summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2007-08-15 14:27:07 (GMT)
committerGeorg Brandl <georg@python.org>2007-08-15 14:27:07 (GMT)
commit739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch)
treef82b450d291927fc1758b96d981aa0610947b529 /Doc/lib
parent2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff)
downloadcpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.zip
cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz
cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.bz2
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/archiving.tex8
-rw-r--r--Doc/lib/asttable.tex280
-rwxr-xr-xDoc/lib/caseless.py60
-rw-r--r--Doc/lib/custominterp.tex13
-rw-r--r--Doc/lib/datatypes.tex10
-rw-r--r--Doc/lib/development.tex13
-rw-r--r--Doc/lib/distutils.tex38
-rw-r--r--Doc/lib/email-dir.py115
-rw-r--r--Doc/lib/email-mime.py32
-rw-r--r--Doc/lib/email-simple.py25
-rw-r--r--Doc/lib/email-unpack.py68
-rw-r--r--Doc/lib/email.tex402
-rw-r--r--Doc/lib/emailcharsets.tex244
-rw-r--r--Doc/lib/emailencoders.tex47
-rw-r--r--Doc/lib/emailexc.tex87
-rw-r--r--Doc/lib/emailgenerator.tex133
-rw-r--r--Doc/lib/emailheaders.tex178
-rw-r--r--Doc/lib/emailiter.tex65
-rw-r--r--Doc/lib/emailmessage.tex561
-rw-r--r--Doc/lib/emailmimebase.tex186
-rw-r--r--Doc/lib/emailparser.tex208
-rw-r--r--Doc/lib/emailutil.tex157
-rw-r--r--Doc/lib/fileformats.tex7
-rw-r--r--Doc/lib/filesys.tex18
-rw-r--r--Doc/lib/frameworks.tex10
-rw-r--r--Doc/lib/i18n.tex11
-rw-r--r--Doc/lib/internet.tex13
-rw-r--r--Doc/lib/ipc.tex14
-rw-r--r--Doc/lib/language.tex10
-rw-r--r--Doc/lib/lib.tex452
-rw-r--r--Doc/lib/libaifc.tex202
-rw-r--r--Doc/lib/liballos.tex9
-rw-r--r--Doc/lib/libanydbm.tex85
-rw-r--r--Doc/lib/libarray.tex241
-rw-r--r--Doc/lib/libascii.tex175
-rw-r--r--Doc/lib/libast.tex57
-rw-r--r--Doc/lib/libasynchat.tex254
-rw-r--r--Doc/lib/libasyncore.tex260
-rw-r--r--Doc/lib/libatexit.tex108
-rw-r--r--Doc/lib/libaudioop.tex258
-rw-r--r--Doc/lib/libbase64.tex169
-rw-r--r--Doc/lib/libbasehttp.tex245
-rw-r--r--Doc/lib/libbinascii.tex147
-rw-r--r--Doc/lib/libbinhex.tex55
-rw-r--r--Doc/lib/libbisect.tex84
-rw-r--r--Doc/lib/libbltin.tex44
-rw-r--r--Doc/lib/libbsddb.tex211
-rw-r--r--Doc/lib/libbz2.tex165
-rw-r--r--Doc/lib/libcalendar.tex304
-rw-r--r--Doc/lib/libcfgparser.tex322
-rw-r--r--Doc/lib/libcgi.tex602
-rw-r--r--Doc/lib/libcgihttp.tex70
-rw-r--r--Doc/lib/libcgitb.tex67
-rw-r--r--Doc/lib/libchunk.tex111
-rw-r--r--Doc/lib/libcmath.tex149
-rw-r--r--Doc/lib/libcmd.tex198
-rw-r--r--Doc/lib/libcmp.tex36
-rw-r--r--Doc/lib/libcmpcache.tex21
-rw-r--r--Doc/lib/libcode.tex173
-rw-r--r--Doc/lib/libcodecs.tex1341
-rw-r--r--Doc/lib/libcodeop.tex103
-rw-r--r--Doc/lib/libcollections.tex402
-rw-r--r--Doc/lib/libcolorsys.tex54
-rw-r--r--Doc/lib/libcommands.tex54
-rw-r--r--Doc/lib/libcompileall.tex63
-rw-r--r--Doc/lib/libconsts.tex33
-rw-r--r--Doc/lib/libcontextlib.tex130
-rw-r--r--Doc/lib/libcookie.tex260
-rw-r--r--Doc/lib/libcookielib.tex720
-rw-r--r--Doc/lib/libcopy.tex97
-rw-r--r--Doc/lib/libcopyreg.tex40
-rw-r--r--Doc/lib/libcrypt.tex60
-rw-r--r--Doc/lib/libcrypto.tex19
-rw-r--r--Doc/lib/libcsv.tex538
-rwxr-xr-xDoc/lib/libctypes.tex2450
-rw-r--r--Doc/lib/libcurses.tex1405
-rw-r--r--Doc/lib/libcursespanel.tex96
-rw-r--r--Doc/lib/libdatetime.tex1441
-rw-r--r--Doc/lib/libdbhash.tex88
-rw-r--r--Doc/lib/libdbm.tex61
-rw-r--r--Doc/lib/libdecimal.tex1313
-rw-r--r--Doc/lib/libdifflib.tex704
-rw-r--r--Doc/lib/libdircache.tex49
-rw-r--r--Doc/lib/libdis.tex674
-rw-r--r--Doc/lib/libdl.tex101
-rw-r--r--Doc/lib/libdoctest.tex1974
-rw-r--r--Doc/lib/libdocxmlrpc.tex109
-rw-r--r--Doc/lib/libdumbdbm.tex63
-rw-r--r--Doc/lib/libdummythread.tex22
-rw-r--r--Doc/lib/libdummythreading.tex22
-rw-r--r--Doc/lib/liberrno.tex149
-rw-r--r--Doc/lib/libetree.tex426
-rw-r--r--Doc/lib/libexcs.tex427
-rw-r--r--Doc/lib/libfcntl.tex174
-rw-r--r--Doc/lib/libfilecmp.tex142
-rw-r--r--Doc/lib/libfileinput.tex192
-rw-r--r--Doc/lib/libfnmatch.tex86
-rw-r--r--Doc/lib/libformatter.tex329
-rw-r--r--Doc/lib/libfpectl.tex127
-rw-r--r--Doc/lib/libfpformat.tex54
-rw-r--r--Doc/lib/libftplib.tex300
-rw-r--r--Doc/lib/libfuncs.tex1125
-rw-r--r--Doc/lib/libfunctools.tex145
-rw-r--r--Doc/lib/libfuture.tex69
-rw-r--r--Doc/lib/libgc.tex196
-rw-r--r--Doc/lib/libgdbm.tex100
-rw-r--r--Doc/lib/libgetopt.tex154
-rw-r--r--Doc/lib/libgetpass.tex36
-rw-r--r--Doc/lib/libgettext.tex773
-rw-r--r--Doc/lib/libglob.tex51
-rw-r--r--Doc/lib/libgrp.tex49
-rw-r--r--Doc/lib/libgzip.tex70
-rw-r--r--Doc/lib/libhashlib.tex114
-rw-r--r--Doc/lib/libheapq.tex225
-rw-r--r--Doc/lib/libhmac.tex54
-rw-r--r--Doc/lib/libhotshot.tex137
-rw-r--r--Doc/lib/libhtmllib.tex181
-rw-r--r--Doc/lib/libhtmlparser.tex173
-rw-r--r--Doc/lib/libhttplib.tex452
-rw-r--r--Doc/lib/libimaplib.tex507
-rw-r--r--Doc/lib/libimghdr.tex60
-rw-r--r--Doc/lib/libimp.tex291
-rw-r--r--Doc/lib/libinspect.tex391
-rw-r--r--Doc/lib/libintro.tex53
-rw-r--r--Doc/lib/libitertools.tex575
-rw-r--r--Doc/lib/libkeyword.tex20
-rw-r--r--Doc/lib/liblinecache.tex50
-rw-r--r--Doc/lib/liblocale.tex527
-rw-r--r--Doc/lib/liblogging.tex1768
-rw-r--r--Doc/lib/libmailbox.tex1443
-rw-r--r--Doc/lib/libmailcap.tex82
-rw-r--r--Doc/lib/libmain.tex16
-rw-r--r--Doc/lib/libmarshal.tex117
-rw-r--r--Doc/lib/libmath.tex209
-rw-r--r--Doc/lib/libmhlib.tex168
-rw-r--r--Doc/lib/libmimetools.tex120
-rw-r--r--Doc/lib/libmimetypes.tex226
-rw-r--r--Doc/lib/libmisc.tex7
-rw-r--r--Doc/lib/libmm.tex8
-rw-r--r--Doc/lib/libmmap.tex171
-rw-r--r--Doc/lib/libmodulefinder.tex51
-rw-r--r--Doc/lib/libmsilib.tex485
-rw-r--r--Doc/lib/libmsvcrt.tex109
-rw-r--r--Doc/lib/libmultifile.tex175
-rw-r--r--Doc/lib/libmutex.tex57
-rw-r--r--Doc/lib/libnetrc.tex68
-rw-r--r--Doc/lib/libnew.tex55
-rw-r--r--Doc/lib/libni.tex63
-rw-r--r--Doc/lib/libnis.tex63
-rw-r--r--Doc/lib/libnntplib.tex355
-rw-r--r--Doc/lib/libobjs.tex24
-rw-r--r--Doc/lib/liboperator.tex530
-rw-r--r--Doc/lib/liboptparse.tex1888
-rw-r--r--Doc/lib/libos.tex1980
-rw-r--r--Doc/lib/libossaudiodev.tex401
-rw-r--r--Doc/lib/libparser.tex712
-rw-r--r--Doc/lib/libpdb.tex464
-rw-r--r--Doc/lib/libpickle.tex888
-rw-r--r--Doc/lib/libpickletools.tex34
-rw-r--r--Doc/lib/libpipes.tex84
-rw-r--r--Doc/lib/libpkgutil.tex45
-rw-r--r--Doc/lib/libplatform.tex238
-rw-r--r--Doc/lib/libpoplib.tex187
-rw-r--r--Doc/lib/libposix.tex97
-rw-r--r--Doc/lib/libposixpath.tex300
-rw-r--r--Doc/lib/libpprint.tex210
-rw-r--r--Doc/lib/libprofile.tex722
-rw-r--r--Doc/lib/libpty.tex44
-rw-r--r--Doc/lib/libpwd.tex57
-rw-r--r--Doc/lib/libpyclbr.tex102
-rw-r--r--Doc/lib/libpycompile.tex53
-rw-r--r--Doc/lib/libpydoc.tex67
-rw-r--r--Doc/lib/libpyexpat.tex766
-rw-r--r--Doc/lib/libpython.tex8
-rw-r--r--Doc/lib/libqueue.tex145
-rw-r--r--Doc/lib/libquopri.tex61
-rw-r--r--Doc/lib/librandom.tex309
-rw-r--r--Doc/lib/libre.tex954
-rw-r--r--Doc/lib/libreadline.tex196
-rw-r--r--Doc/lib/librepr.tex133
-rw-r--r--Doc/lib/libresource.tex215
-rw-r--r--Doc/lib/librfc822.tex336
-rw-r--r--Doc/lib/librlcompleter.tex65
-rw-r--r--Doc/lib/librobotparser.tex66
-rw-r--r--Doc/lib/librunpy.tex76
-rw-r--r--Doc/lib/libsched.tex97
-rw-r--r--Doc/lib/libselect.tex132
-rw-r--r--Doc/lib/libsgmllib.tex271
-rw-r--r--Doc/lib/libshelve.tex174
-rw-r--r--Doc/lib/libshlex.tex279
-rw-r--r--Doc/lib/libshutil.tex152
-rw-r--r--Doc/lib/libsignal.tex173
-rw-r--r--Doc/lib/libsimplehttp.tex86
-rw-r--r--Doc/lib/libsimplexmlrpc.tex235
-rw-r--r--Doc/lib/libsite.tex93
-rw-r--r--Doc/lib/libsmtpd.tex63
-rw-r--r--Doc/lib/libsmtplib.tex344
-rw-r--r--Doc/lib/libsndhdr.tex41
-rw-r--r--Doc/lib/libsocket.tex921
-rw-r--r--Doc/lib/libsocksvr.tex293
-rw-r--r--Doc/lib/libsomeos.tex10
-rw-r--r--Doc/lib/libspwd.tex48
-rw-r--r--Doc/lib/libsqlite3.tex648
-rw-r--r--Doc/lib/libstat.tex157
-rw-r--r--Doc/lib/libstatvfs.tex55
-rw-r--r--Doc/lib/libstdtypes.tex2070
-rw-r--r--Doc/lib/libstring.tex425
-rw-r--r--Doc/lib/libstringio.tex125
-rw-r--r--Doc/lib/libstringprep.tex136
-rw-r--r--Doc/lib/libstrings.tex10
-rw-r--r--Doc/lib/libstruct.tex269
-rw-r--r--Doc/lib/libsubprocess.tex340
-rw-r--r--Doc/lib/libsunau.tex218
-rw-r--r--Doc/lib/libsymbol.tex30
-rw-r--r--Doc/lib/libsys.tex582
-rw-r--r--Doc/lib/libsyslog.tex76
-rw-r--r--Doc/lib/libtabnanny.tex62
-rw-r--r--Doc/lib/libtarfile.tex664
-rw-r--r--Doc/lib/libtelnetlib.tex228
-rw-r--r--Doc/lib/libtempfile.tex214
-rw-r--r--Doc/lib/libtermios.tex112
-rw-r--r--Doc/lib/libtest.tex316
-rw-r--r--Doc/lib/libtextwrap.tex188
-rw-r--r--Doc/lib/libthread.tex173
-rw-r--r--Doc/lib/libthreading.tex728
-rw-r--r--Doc/lib/libtime.tex475
-rw-r--r--Doc/lib/libtimeit.tex249
-rw-r--r--Doc/lib/libtoken.tex44
-rw-r--r--Doc/lib/libtokenize.tex119
-rw-r--r--Doc/lib/libtrace.tex125
-rw-r--r--Doc/lib/libtraceback.tex152
-rw-r--r--Doc/lib/libtty.tex34
-rw-r--r--Doc/lib/libturtle.tex268
-rw-r--r--Doc/lib/libtypes.tex211
-rw-r--r--Doc/lib/libundoc.tex82
-rw-r--r--Doc/lib/libunicodedata.tex160
-rw-r--r--Doc/lib/libunittest.tex978
-rw-r--r--Doc/lib/libunix.tex8
-rw-r--r--Doc/lib/liburllib.tex494
-rw-r--r--Doc/lib/liburllib2.tex872
-rw-r--r--Doc/lib/liburlparse.tex253
-rw-r--r--Doc/lib/libuser.tex71
-rw-r--r--Doc/lib/libuserdict.tex181
-rw-r--r--Doc/lib/libuu.tex58
-rw-r--r--Doc/lib/libuuid.tex233
-rw-r--r--Doc/lib/libwarnings.tex253
-rw-r--r--Doc/lib/libwave.tex171
-rw-r--r--Doc/lib/libweakref.tex336
-rw-r--r--Doc/lib/libwebbrowser.tex173
-rw-r--r--Doc/lib/libwhichdb.tex20
-rw-r--r--Doc/lib/libwinreg.tex414
-rw-r--r--Doc/lib/libwinsound.tex142
-rwxr-xr-xDoc/lib/libwsgiref.tex782
-rw-r--r--Doc/lib/libxdrlib.tex251
-rw-r--r--Doc/lib/libxmlrpclib.tex391
-rw-r--r--Doc/lib/libzipfile.tex371
-rw-r--r--Doc/lib/libzipimport.tex128
-rw-r--r--Doc/lib/libzlib.tex197
-rw-r--r--Doc/lib/markup.tex29
-rw-r--r--Doc/lib/mimelib.tex65
-rw-r--r--Doc/lib/minidom-example.py64
-rw-r--r--Doc/lib/modules.tex9
-rw-r--r--Doc/lib/netdata.tex6
-rw-r--r--Doc/lib/numeric.tex13
-rw-r--r--Doc/lib/persistence.tex15
-rwxr-xr-xDoc/lib/required_1.py20
-rwxr-xr-xDoc/lib/required_2.py41
-rw-r--r--Doc/lib/sqlite3/adapter_datetime.py14
-rw-r--r--Doc/lib/sqlite3/adapter_point_1.py16
-rw-r--r--Doc/lib/sqlite3/adapter_point_2.py17
-rw-r--r--Doc/lib/sqlite3/collation_reverse.py15
-rw-r--r--Doc/lib/sqlite3/complete_statement.py30
-rw-r--r--Doc/lib/sqlite3/connect_db_1.py3
-rw-r--r--Doc/lib/sqlite3/connect_db_2.py3
-rw-r--r--Doc/lib/sqlite3/converter_point.py47
-rw-r--r--Doc/lib/sqlite3/countcursors.py15
-rw-r--r--Doc/lib/sqlite3/createdb.py28
-rw-r--r--Doc/lib/sqlite3/execsql_fetchonerow.py17
-rw-r--r--Doc/lib/sqlite3/execsql_printall_1.py13
-rw-r--r--Doc/lib/sqlite3/execute_1.py11
-rw-r--r--Doc/lib/sqlite3/execute_2.py12
-rw-r--r--Doc/lib/sqlite3/execute_3.py12
-rw-r--r--Doc/lib/sqlite3/executemany_1.py24
-rw-r--r--Doc/lib/sqlite3/executemany_2.py15
-rw-r--r--Doc/lib/sqlite3/executescript.py24
-rw-r--r--Doc/lib/sqlite3/insert_more_people.py16
-rw-r--r--Doc/lib/sqlite3/md5func.py11
-rw-r--r--Doc/lib/sqlite3/mysumaggr.py20
-rw-r--r--Doc/lib/sqlite3/parse_colnames.py8
-rw-r--r--Doc/lib/sqlite3/pysqlite_datetime.py20
-rw-r--r--Doc/lib/sqlite3/row_factory.py13
-rw-r--r--Doc/lib/sqlite3/rowclass.py12
-rw-r--r--Doc/lib/sqlite3/shared_cache.py6
-rw-r--r--Doc/lib/sqlite3/shortcut_methods.py21
-rw-r--r--Doc/lib/sqlite3/simple_tableprinter.py26
-rw-r--r--Doc/lib/sqlite3/text_factory.py42
-rw-r--r--Doc/lib/tkinter.tex1873
-rw-r--r--Doc/lib/tzinfo-examples.py139
-rw-r--r--Doc/lib/windows.tex8
-rw-r--r--Doc/lib/xmldom.tex928
-rw-r--r--Doc/lib/xmldomminidom.tex285
-rw-r--r--Doc/lib/xmldompulldom.tex61
-rw-r--r--Doc/lib/xmletree.tex27
-rw-r--r--Doc/lib/xmlsax.tex143
-rw-r--r--Doc/lib/xmlsaxhandler.tex381
-rw-r--r--Doc/lib/xmlsaxreader.tex351
-rw-r--r--Doc/lib/xmlsaxutils.tex81
307 files changed, 0 insertions, 75014 deletions
diff --git a/Doc/lib/archiving.tex b/Doc/lib/archiving.tex
deleted file mode 100644
index 93f5bf7..0000000
--- a/Doc/lib/archiving.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Data Compression and Archiving}
-\label{archiving}
-
-The modules described in this chapter support data compression
-with the zlib, gzip, and bzip2 algorithms, and
-the creation of ZIP- and tar-format archives.
-
-\localmoduletable
diff --git a/Doc/lib/asttable.tex b/Doc/lib/asttable.tex
deleted file mode 100644
index 326bbbb..0000000
--- a/Doc/lib/asttable.tex
+++ /dev/null
@@ -1,280 +0,0 @@
-\begin{longtableiii}{lll}{class}{Node type}{Attribute}{Value}
-
-\lineiii{Add}{\member{left}}{left operand}
-\lineiii{}{\member{right}}{right operand}
-\hline
-
-\lineiii{And}{\member{nodes}}{list of operands}
-\hline
-
-\lineiii{AssAttr}{}{\emph{attribute as target of assignment}}
-\lineiii{}{\member{expr}}{expression on the left-hand side of the dot}
-\lineiii{}{\member{attrname}}{the attribute name, a string}
-\lineiii{}{\member{flags}}{XXX}
-\hline
-
-\lineiii{AssList}{\member{nodes}}{list of list elements being assigned to}
-\hline
-
-\lineiii{AssName}{\member{name}}{name being assigned to}
-\lineiii{}{\member{flags}}{XXX}
-\hline
-
-\lineiii{AssTuple}{\member{nodes}}{list of tuple elements being assigned to}
-\hline
-
-\lineiii{Assert}{\member{test}}{the expression to be tested}
-\lineiii{}{\member{fail}}{the value of the \exception{AssertionError}}
-\hline
-
-\lineiii{Assign}{\member{nodes}}{a list of assignment targets, one per equal sign}
-\lineiii{}{\member{expr}}{the value being assigned}
-\hline
-
-\lineiii{AugAssign}{\member{node}}{}
-\lineiii{}{\member{op}}{}
-\lineiii{}{\member{expr}}{}
-\hline
-
-\lineiii{Bitand}{\member{nodes}}{}
-\hline
-
-\lineiii{Bitor}{\member{nodes}}{}
-\hline
-
-\lineiii{Bitxor}{\member{nodes}}{}
-\hline
-
-\lineiii{Break}{}{}
-\hline
-
-\lineiii{CallFunc}{\member{node}}{expression for the callee}
-\lineiii{}{\member{args}}{a list of arguments}
-\lineiii{}{\member{star_args}}{the extended *-arg value}
-\lineiii{}{\member{dstar_args}}{the extended **-arg value}
-\hline
-
-\lineiii{Class}{\member{name}}{the name of the class, a string}
-\lineiii{}{\member{bases}}{a list of base classes}
-\lineiii{}{\member{doc}}{doc string, a string or \code{None}}
-\lineiii{}{\member{code}}{the body of the class statement}
-\hline
-
-\lineiii{Compare}{\member{expr}}{}
-\lineiii{}{\member{ops}}{}
-\hline
-
-\lineiii{Const}{\member{value}}{}
-\hline
-
-\lineiii{Continue}{}{}
-\hline
-
-\lineiii{Decorators}{\member{nodes}}{List of function decorator expressions}
-\hline
-
-\lineiii{Dict}{\member{items}}{}
-\hline
-
-\lineiii{Discard}{\member{expr}}{}
-\hline
-
-\lineiii{Div}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Ellipsis}{}{}
-\hline
-
-\lineiii{Expression}{\member{node}}{}
-
-\lineiii{Exec}{\member{expr}}{}
-\lineiii{}{\member{locals}}{}
-\lineiii{}{\member{globals}}{}
-\hline
-
-\lineiii{FloorDiv}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{For}{\member{assign}}{}
-\lineiii{}{\member{list}}{}
-\lineiii{}{\member{body}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{From}{\member{modname}}{}
-\lineiii{}{\member{names}}{}
-\hline
-
-\lineiii{Function}{\member{decorators}}{\class{Decorators} or \code{None}}
-\lineiii{}{\member{name}}{name used in def, a string}
-\lineiii{}{\member{argnames}}{list of argument names, as strings}
-\lineiii{}{\member{defaults}}{list of default values}
-\lineiii{}{\member{flags}}{xxx}
-\lineiii{}{\member{doc}}{doc string, a string or \code{None}}
-\lineiii{}{\member{code}}{the body of the function}
-\hline
-
-\lineiii{GenExpr}{\member{code}}{}
-\hline
-
-\lineiii{GenExprFor}{\member{assign}}{}
-\lineiii{}{\member{iter}}{}
-\lineiii{}{\member{ifs}}{}
-\hline
-
-\lineiii{GenExprIf}{\member{test}}{}
-\hline
-
-\lineiii{GenExprInner}{\member{expr}}{}
-\lineiii{}{\member{quals}}{}
-\hline
-
-\lineiii{Getattr}{\member{expr}}{}
-\lineiii{}{\member{attrname}}{}
-\hline
-
-\lineiii{Global}{\member{names}}{}
-\hline
-
-\lineiii{If}{\member{tests}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{Import}{\member{names}}{}
-\hline
-
-\lineiii{Invert}{\member{expr}}{}
-\hline
-
-\lineiii{Keyword}{\member{name}}{}
-\lineiii{}{\member{expr}}{}
-\hline
-
-\lineiii{Lambda}{\member{argnames}}{}
-\lineiii{}{\member{defaults}}{}
-\lineiii{}{\member{flags}}{}
-\lineiii{}{\member{code}}{}
-\hline
-
-\lineiii{LeftShift}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{List}{\member{nodes}}{}
-\hline
-
-\lineiii{ListComp}{\member{expr}}{}
-\lineiii{}{\member{quals}}{}
-\hline
-
-\lineiii{ListCompFor}{\member{assign}}{}
-\lineiii{}{\member{list}}{}
-\lineiii{}{\member{ifs}}{}
-\hline
-
-\lineiii{ListCompIf}{\member{test}}{}
-\hline
-
-\lineiii{Mod}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Module}{\member{doc}}{doc string, a string or \code{None}}
-\lineiii{}{\member{node}}{body of the module, a \class{Stmt}}
-\hline
-
-\lineiii{Mul}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Name}{\member{name}}{}
-\hline
-
-\lineiii{Not}{\member{expr}}{}
-\hline
-
-\lineiii{Or}{\member{nodes}}{}
-\hline
-
-\lineiii{Pass}{}{}
-\hline
-
-\lineiii{Power}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Print}{\member{nodes}}{}
-\lineiii{}{\member{dest}}{}
-\hline
-
-\lineiii{Printnl}{\member{nodes}}{}
-\lineiii{}{\member{dest}}{}
-\hline
-
-\lineiii{Raise}{\member{expr1}}{}
-\lineiii{}{\member{expr2}}{}
-\lineiii{}{\member{expr3}}{}
-\hline
-
-\lineiii{Return}{\member{value}}{}
-\hline
-
-\lineiii{RightShift}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Slice}{\member{expr}}{}
-\lineiii{}{\member{flags}}{}
-\lineiii{}{\member{lower}}{}
-\lineiii{}{\member{upper}}{}
-\hline
-
-\lineiii{Sliceobj}{\member{nodes}}{list of statements}
-\hline
-
-\lineiii{Stmt}{\member{nodes}}{}
-\hline
-
-\lineiii{Sub}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline
-
-\lineiii{Subscript}{\member{expr}}{}
-\lineiii{}{\member{flags}}{}
-\lineiii{}{\member{subs}}{}
-\hline
-
-\lineiii{TryExcept}{\member{body}}{}
-\lineiii{}{\member{handlers}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{TryFinally}{\member{body}}{}
-\lineiii{}{\member{final}}{}
-\hline
-
-\lineiii{Tuple}{\member{nodes}}{}
-\hline
-
-\lineiii{UnaryAdd}{\member{expr}}{}
-\hline
-
-\lineiii{UnarySub}{\member{expr}}{}
-\hline
-
-\lineiii{While}{\member{test}}{}
-\lineiii{}{\member{body}}{}
-\lineiii{}{\member{else_}}{}
-\hline
-
-\lineiii{With}{\member{expr}}{}
-\lineiii{}{\member{vars}}{}
-\lineiii{}{\member{body}}{}
-\hline
-
-\lineiii{Yield}{\member{value}}{}
-\hline
-
-\end{longtableiii}
diff --git a/Doc/lib/caseless.py b/Doc/lib/caseless.py
deleted file mode 100755
index cae94be..0000000
--- a/Doc/lib/caseless.py
+++ /dev/null
@@ -1,60 +0,0 @@
-from optparse import Option, OptionParser, _match_abbrev
-
-# This case-insensitive option parser relies on having a
-# case-insensitive dictionary type available. Here's one
-# for Python 2.2. Note that a *real* case-insensitive
-# dictionary type would also have to implement __new__(),
-# update(), and setdefault() -- but that's not the point
-# of this exercise.
-
-class caseless_dict (dict):
- def __setitem__ (self, key, value):
- dict.__setitem__(self, key.lower(), value)
-
- def __getitem__ (self, key):
- return dict.__getitem__(self, key.lower())
-
- def get (self, key, default=None):
- return dict.get(self, key.lower())
-
- def has_key (self, key):
- return dict.has_key(self, key.lower())
-
-
-class CaselessOptionParser (OptionParser):
-
- def _create_option_list (self):
- self.option_list = []
- self._short_opt = caseless_dict()
- self._long_opt = caseless_dict()
- self._long_opts = []
- self.defaults = {}
-
- def _match_long_opt (self, opt):
- return _match_abbrev(opt.lower(), self._long_opt.keys())
-
-
-if __name__ == "__main__":
- from optik.errors import OptionConflictError
-
- # test 1: no options to start with
- parser = CaselessOptionParser()
- try:
- parser.add_option("-H", dest="blah")
- except OptionConflictError:
- print "ok: got OptionConflictError for -H"
- else:
- print "not ok: no conflict between -h and -H"
-
- parser.add_option("-f", "--file", dest="file")
- #print repr(parser.get_option("-f"))
- #print repr(parser.get_option("-F"))
- #print repr(parser.get_option("--file"))
- #print repr(parser.get_option("--fIlE"))
- (options, args) = parser.parse_args(["--FiLe", "foo"])
- assert options.file == "foo", options.file
- print "ok: case insensitive long options work"
-
- (options, args) = parser.parse_args(["-F", "bar"])
- assert options.file == "bar", options.file
- print "ok: case insensitive short options work"
diff --git a/Doc/lib/custominterp.tex b/Doc/lib/custominterp.tex
deleted file mode 100644
index 555b888..0000000
--- a/Doc/lib/custominterp.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Custom Python Interpreters}
-\label{custominterp}
-
-The modules described in this chapter allow writing interfaces similar
-to Python's interactive interpreter. If you want a Python interpreter
-that supports some special feature in addition to the Python language,
-you should look at the \module{code} module. (The \module{codeop}
-module is lower-level, used to support compiling a possibly-incomplete
-chunk of Python code.)
-
-The full list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/datatypes.tex b/Doc/lib/datatypes.tex
deleted file mode 100644
index 0fe03c7..0000000
--- a/Doc/lib/datatypes.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Data Types}
-\label{datatypes}
-
-The modules described in this chapter provide a variety of specialized
-data types such as dates and times, fixed-type arrays, heap queues,
-synchronized queues, and sets.
-
-The following modules are documented in this chapter:
-
-\localmoduletable
diff --git a/Doc/lib/development.tex b/Doc/lib/development.tex
deleted file mode 100644
index 4b4fadc..0000000
--- a/Doc/lib/development.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Development Tools}
-\label{development}
-
-The modules described in this chapter help you write software. For
-example, the \module{pydoc} module takes a module and generates
-documentation based on the module's contents. The \module{doctest}
-and \module{unittest} modules contains frameworks for writing unit tests
-that automatically exercise code and verify that the expected output
-is produced.
-
-The list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/distutils.tex b/Doc/lib/distutils.tex
deleted file mode 100644
index 3de9dde..0000000
--- a/Doc/lib/distutils.tex
+++ /dev/null
@@ -1,38 +0,0 @@
-\section{\module{distutils} ---
- Building and installing Python modules}
-
-\declaremodule{standard}{distutils}
-\modulesynopsis{Support for building and installing Python modules
- into an existing Python installation.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{distutils} package provides support for building and
-installing additional modules into a Python installation. The new
-modules may be either 100\%{}-pure Python, or may be extension modules
-written in C, or may be collections of Python packages which include
-modules coded in both Python and C.
-
-This package is discussed in two separate documents which are included
-in the Python documentation package. To learn about distributing new
-modules using the \module{distutils} facilities, read
-\citetitle[../dist/dist.html]{Distributing Python Modules}; this
-includes documentation needed to extend distutils. To learn
-about installing Python modules, whether or not the author made use of
-the \module{distutils} package, read
-\citetitle[../inst/inst.html]{Installing Python Modules}.
-
-
-\begin{seealso}
- \seetitle[../dist/dist.html]{Distributing Python Modules}{The manual
- for developers and packagers of Python modules. This
- describes how to prepare \module{distutils}-based packages
- so that they may be easily installed into an existing
- Python installation.}
-
- \seetitle[../inst/inst.html]{Installing Python Modules}{An
- ``administrators'' manual which includes information on
- installing modules into an existing Python installation.
- You do not need to be a Python programmer to read this
- manual.}
-\end{seealso}
diff --git a/Doc/lib/email-dir.py b/Doc/lib/email-dir.py
deleted file mode 100644
index c04f57d..0000000
--- a/Doc/lib/email-dir.py
+++ /dev/null
@@ -1,115 +0,0 @@
-#!/usr/bin/env python
-
-"""Send the contents of a directory as a MIME message."""
-
-import os
-import sys
-import smtplib
-# For guessing MIME type based on file name extension
-import mimetypes
-
-from optparse import OptionParser
-
-from email import encoders
-from email.message import Message
-from email.mime.audio import MIMEAudio
-from email.mime.base import MIMEBase
-from email.mime.image import MIMEImage
-from email.mime.multipart import MIMEMultipart
-from email.mime.text import MIMEText
-
-COMMASPACE = ', '
-
-
-def main():
- parser = OptionParser(usage="""\
-Send the contents of a directory as a MIME message.
-
-Usage: %prog [options]
-
-Unless the -o option is given, the email is sent by forwarding to your local
-SMTP server, which then does the normal delivery process. Your local machine
-must be running an SMTP server.
-""")
- parser.add_option('-d', '--directory',
- type='string', action='store',
- help="""Mail the contents of the specified directory,
- otherwise use the current directory. Only the regular
- files in the directory are sent, and we don't recurse to
- subdirectories.""")
- parser.add_option('-o', '--output',
- type='string', action='store', metavar='FILE',
- help="""Print the composed message to FILE instead of
- sending the message to the SMTP server.""")
- parser.add_option('-s', '--sender',
- type='string', action='store', metavar='SENDER',
- help='The value of the From: header (required)')
- parser.add_option('-r', '--recipient',
- type='string', action='append', metavar='RECIPIENT',
- default=[], dest='recipients',
- help='A To: header value (at least one required)')
- opts, args = parser.parse_args()
- if not opts.sender or not opts.recipients:
- parser.print_help()
- sys.exit(1)
- directory = opts.directory
- if not directory:
- directory = '.'
- # Create the enclosing (outer) message
- outer = MIMEMultipart()
- outer['Subject'] = 'Contents of directory %s' % os.path.abspath(directory)
- outer['To'] = COMMASPACE.join(opts.recipients)
- outer['From'] = opts.sender
- outer.preamble = 'You will not see this in a MIME-aware mail reader.\n'
-
- for filename in os.listdir(directory):
- path = os.path.join(directory, filename)
- if not os.path.isfile(path):
- continue
- # Guess the content type based on the file's extension. Encoding
- # will be ignored, although we should check for simple things like
- # gzip'd or compressed files.
- ctype, encoding = mimetypes.guess_type(path)
- if ctype is None or encoding is not None:
- # No guess could be made, or the file is encoded (compressed), so
- # use a generic bag-of-bits type.
- ctype = 'application/octet-stream'
- maintype, subtype = ctype.split('/', 1)
- if maintype == 'text':
- fp = open(path)
- # Note: we should handle calculating the charset
- msg = MIMEText(fp.read(), _subtype=subtype)
- fp.close()
- elif maintype == 'image':
- fp = open(path, 'rb')
- msg = MIMEImage(fp.read(), _subtype=subtype)
- fp.close()
- elif maintype == 'audio':
- fp = open(path, 'rb')
- msg = MIMEAudio(fp.read(), _subtype=subtype)
- fp.close()
- else:
- fp = open(path, 'rb')
- msg = MIMEBase(maintype, subtype)
- msg.set_payload(fp.read())
- fp.close()
- # Encode the payload using Base64
- encoders.encode_base64(msg)
- # Set the filename parameter
- msg.add_header('Content-Disposition', 'attachment', filename=filename)
- outer.attach(msg)
- # Now send or store the message
- composed = outer.as_string()
- if opts.output:
- fp = open(opts.output, 'w')
- fp.write(composed)
- fp.close()
- else:
- s = smtplib.SMTP()
- s.connect()
- s.sendmail(opts.sender, opts.recipients, composed)
- s.close()
-
-
-if __name__ == '__main__':
- main()
diff --git a/Doc/lib/email-mime.py b/Doc/lib/email-mime.py
deleted file mode 100644
index 5097253..0000000
--- a/Doc/lib/email-mime.py
+++ /dev/null
@@ -1,32 +0,0 @@
-# Import smtplib for the actual sending function
-import smtplib
-
-# Here are the email package modules we'll need
-from email.mime.image import MIMEImage
-from email.mime.multipart import MIMEMultipart
-
-COMMASPACE = ', '
-
-# Create the container (outer) email message.
-msg = MIMEMultipart()
-msg['Subject'] = 'Our family reunion'
-# me == the sender's email address
-# family = the list of all recipients' email addresses
-msg['From'] = me
-msg['To'] = COMMASPACE.join(family)
-msg.preamble = 'Our family reunion'
-
-# Assume we know that the image files are all in PNG format
-for file in pngfiles:
- # Open the files in binary mode. Let the MIMEImage class automatically
- # guess the specific image type.
- fp = open(file, 'rb')
- img = MIMEImage(fp.read())
- fp.close()
- msg.attach(img)
-
-# Send the email via our own SMTP server.
-s = smtplib.SMTP()
-s.connect()
-s.sendmail(me, family, msg.as_string())
-s.close()
diff --git a/Doc/lib/email-simple.py b/Doc/lib/email-simple.py
deleted file mode 100644
index 44152a4..0000000
--- a/Doc/lib/email-simple.py
+++ /dev/null
@@ -1,25 +0,0 @@
-# Import smtplib for the actual sending function
-import smtplib
-
-# Import the email modules we'll need
-from email.mime.text import MIMEText
-
-# Open a plain text file for reading. For this example, assume that
-# the text file contains only ASCII characters.
-fp = open(textfile, 'rb')
-# Create a text/plain message
-msg = MIMEText(fp.read())
-fp.close()
-
-# me == the sender's email address
-# you == the recipient's email address
-msg['Subject'] = 'The contents of %s' % textfile
-msg['From'] = me
-msg['To'] = you
-
-# Send the message via our own SMTP server, but don't include the
-# envelope header.
-s = smtplib.SMTP()
-s.connect()
-s.sendmail(me, [you], msg.as_string())
-s.close()
diff --git a/Doc/lib/email-unpack.py b/Doc/lib/email-unpack.py
deleted file mode 100644
index e596b98..0000000
--- a/Doc/lib/email-unpack.py
+++ /dev/null
@@ -1,68 +0,0 @@
-#!/usr/bin/env python
-
-"""Unpack a MIME message into a directory of files."""
-
-import os
-import sys
-import email
-import errno
-import mimetypes
-
-from optparse import OptionParser
-
-
-def main():
- parser = OptionParser(usage="""\
-Unpack a MIME message into a directory of files.
-
-Usage: %prog [options] msgfile
-""")
- parser.add_option('-d', '--directory',
- type='string', action='store',
- help="""Unpack the MIME message into the named
- directory, which will be created if it doesn't already
- exist.""")
- opts, args = parser.parse_args()
- if not opts.directory:
- parser.print_help()
- sys.exit(1)
-
- try:
- msgfile = args[0]
- except IndexError:
- parser.print_help()
- sys.exit(1)
-
- try:
- os.mkdir(opts.directory)
- except OSError as e:
- # Ignore directory exists error
- if e.errno != errno.EEXIST:
- raise
-
- fp = open(msgfile)
- msg = email.message_from_file(fp)
- fp.close()
-
- counter = 1
- for part in msg.walk():
- # multipart/* are just containers
- if part.get_content_maintype() == 'multipart':
- continue
- # Applications should really sanitize the given filename so that an
- # email message can't be used to overwrite important files
- filename = part.get_filename()
- if not filename:
- ext = mimetypes.guess_extension(part.get_type())
- if not ext:
- # Use a generic bag-of-bits extension
- ext = '.bin'
- filename = 'part-%03d%s' % (counter, ext)
- counter += 1
- fp = open(os.path.join(opts.directory, filename), 'wb')
- fp.write(part.get_payload(decode=True))
- fp.close()
-
-
-if __name__ == '__main__':
- main()
diff --git a/Doc/lib/email.tex b/Doc/lib/email.tex
deleted file mode 100644
index 3de3df3..0000000
--- a/Doc/lib/email.tex
+++ /dev/null
@@ -1,402 +0,0 @@
-% Copyright (C) 2001-2007 Python Software Foundation
-% Author: barry@python.org (Barry Warsaw)
-
-\section{\module{email} ---
- An email and MIME handling package}
-
-\declaremodule{standard}{email}
-\modulesynopsis{Package supporting the parsing, manipulating, and
- generating email messages, including MIME documents.}
-\moduleauthor{Barry A. Warsaw}{barry@python.org}
-\sectionauthor{Barry A. Warsaw}{barry@python.org}
-
-\versionadded{2.2}
-
-The \module{email} package is a library for managing email messages,
-including MIME and other \rfc{2822}-based message documents. It
-subsumes most of the functionality in several older standard modules
-such as \refmodule{rfc822}, \refmodule{mimetools},
-\refmodule{multifile}, and other non-standard packages such as
-\module{mimecntl}. It is specifically \emph{not} designed to do any
-sending of email messages to SMTP (\rfc{2821}), NNTP, or other servers; those
-are functions of modules such as \refmodule{smtplib} and \refmodule{nntplib}.
-The \module{email} package attempts to be as RFC-compliant as possible,
-supporting in addition to \rfc{2822}, such MIME-related RFCs as
-\rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}.
-
-The primary distinguishing feature of the \module{email} package is
-that it splits the parsing and generating of email messages from the
-internal \emph{object model} representation of email. Applications
-using the \module{email} package deal primarily with objects; you can
-add sub-objects to messages, remove sub-objects from messages,
-completely re-arrange the contents, etc. There is a separate parser
-and a separate generator which handles the transformation from flat
-text to the object model, and then back to flat text again. There
-are also handy subclasses for some common MIME object types, and a few
-miscellaneous utilities that help with such common tasks as extracting
-and parsing message field values, creating RFC-compliant dates, etc.
-
-The following sections describe the functionality of the
-\module{email} package. The ordering follows a progression that
-should be common in applications: an email message is read as flat
-text from a file or other source, the text is parsed to produce the
-object structure of the email message, this structure is manipulated,
-and finally, the object tree is rendered back into flat text.
-
-It is perfectly feasible to create the object structure out of whole
-cloth --- i.e. completely from scratch. From there, a similar
-progression can be taken as above.
-
-Also included are detailed specifications of all the classes and
-modules that the \module{email} package provides, the exception
-classes you might encounter while using the \module{email} package,
-some auxiliary utilities, and a few examples. For users of the older
-\module{mimelib} package, or previous versions of the \module{email}
-package, a section on differences and porting is provided.
-
-\begin{seealso}
- \seemodule{smtplib}{SMTP protocol client}
- \seemodule{nntplib}{NNTP protocol client}
-\end{seealso}
-
-\subsection{Representing an email message}
-\input{emailmessage}
-
-\subsection{Parsing email messages}
-\input{emailparser}
-
-\subsection{Generating MIME documents}
-\input{emailgenerator}
-
-\subsection{Creating email and MIME objects from scratch}
-\input{emailmimebase}
-
-\subsection{Internationalized headers}
-\input{emailheaders}
-
-\subsection{Representing character sets}
-\input{emailcharsets}
-
-\subsection{Encoders}
-\input{emailencoders}
-
-\subsection{Exception and Defect classes}
-\input{emailexc}
-
-\subsection{Miscellaneous utilities}
-\input{emailutil}
-
-\subsection{Iterators}
-\input{emailiter}
-
-\subsection{Package History\label{email-pkg-history}}
-
-This table describes the release history of the email package, corresponding
-to the version of Python that the package was released with. For purposes of
-this document, when you see a note about change or added versions, these refer
-to the Python version the change was made in, \emph{not} the email package
-version. This table also describes the Python compatibility of each version
-of the package.
-
-\begin{tableiii}{l|l|l}{constant}{email version}{distributed with}{compatible with}
-\lineiii{1.x}{Python 2.2.0 to Python 2.2.1}{\emph{no longer supported}}
-\lineiii{2.5}{Python 2.2.2+ and Python 2.3}{Python 2.1 to 2.5}
-\lineiii{3.0}{Python 2.4}{Python 2.3 to 2.5}
-\lineiii{4.0}{Python 2.5}{Python 2.3 to 2.5}
-\end{tableiii}
-
-Here are the major differences between \module{email} version 4 and version 3:
-
-\begin{itemize}
-\item All modules have been renamed according to \pep{8} standards. For
- example, the version 3 module \module{email.Message} was renamed to
- \module{email.message} in version 4.
-
-\item A new subpackage \module{email.mime} was added and all the version 3
- \module{email.MIME*} modules were renamed and situated into the
- \module{email.mime} subpackage. For example, the version 3 module
- \module{email.MIMEText} was renamed to \module{email.mime.text}.
-
- \emph{Note that the version 3 names will continue to work until Python
- 2.6}.
-
-\item The \module{email.mime.application} module was added, which contains the
- \class{MIMEApplication} class.
-
-\item Methods that were deprecated in version 3 have been removed. These
- include \method{Generator.__call__()}, \method{Message.get_type()},
- \method{Message.get_main_type()}, \method{Message.get_subtype()}.
-
-\item Fixes have been added for \rfc{2231} support which can change some of
- the return types for \function{Message.get_param()} and friends. Under
- some circumstances, values which used to return a 3-tuple now return
- simple strings (specifically, if all extended parameter segments were
- unencoded, there is no language and charset designation expected, so the
- return type is now a simple string). Also, \%-decoding used to be done
- for both encoded and unencoded segments; this decoding is now done only
- for encoded segments.
-\end{itemize}
-
-Here are the major differences between \module{email} version 3 and version 2:
-
-\begin{itemize}
-\item The \class{FeedParser} class was introduced, and the \class{Parser}
- class was implemented in terms of the \class{FeedParser}. All parsing
- therefore is non-strict, and parsing will make a best effort never to
- raise an exception. Problems found while parsing messages are stored in
- the message's \var{defect} attribute.
-
-\item All aspects of the API which raised \exception{DeprecationWarning}s in
- version 2 have been removed. These include the \var{_encoder} argument
- to the \class{MIMEText} constructor, the \method{Message.add_payload()}
- method, the \function{Utils.dump_address_pair()} function, and the
- functions \function{Utils.decode()} and \function{Utils.encode()}.
-
-\item New \exception{DeprecationWarning}s have been added to:
- \method{Generator.__call__()}, \method{Message.get_type()},
- \method{Message.get_main_type()}, \method{Message.get_subtype()}, and
- the \var{strict} argument to the \class{Parser} class. These are
- expected to be removed in future versions.
-
-\item Support for Pythons earlier than 2.3 has been removed.
-\end{itemize}
-
-Here are the differences between \module{email} version 2 and version 1:
-
-\begin{itemize}
-\item The \module{email.Header} and \module{email.Charset} modules
- have been added.
-
-\item The pickle format for \class{Message} instances has changed.
- Since this was never (and still isn't) formally defined, this
- isn't considered a backward incompatibility. However if your
- application pickles and unpickles \class{Message} instances, be
- aware that in \module{email} version 2, \class{Message}
- instances now have private variables \var{_charset} and
- \var{_default_type}.
-
-\item Several methods in the \class{Message} class have been
- deprecated, or their signatures changed. Also, many new methods
- have been added. See the documentation for the \class{Message}
- class for details. The changes should be completely backward
- compatible.
-
-\item The object structure has changed in the face of
- \mimetype{message/rfc822} content types. In \module{email}
- version 1, such a type would be represented by a scalar payload,
- i.e. the container message's \method{is_multipart()} returned
- false, \method{get_payload()} was not a list object, but a single
- \class{Message} instance.
-
- This structure was inconsistent with the rest of the package, so
- the object representation for \mimetype{message/rfc822} content
- types was changed. In \module{email} version 2, the container
- \emph{does} return \code{True} from \method{is_multipart()}, and
- \method{get_payload()} returns a list containing a single
- \class{Message} item.
-
- Note that this is one place that backward compatibility could
- not be completely maintained. However, if you're already
- testing the return type of \method{get_payload()}, you should be
- fine. You just need to make sure your code doesn't do a
- \method{set_payload()} with a \class{Message} instance on a
- container with a content type of \mimetype{message/rfc822}.
-
-\item The \class{Parser} constructor's \var{strict} argument was
- added, and its \method{parse()} and \method{parsestr()} methods
- grew a \var{headersonly} argument. The \var{strict} flag was
- also added to functions \function{email.message_from_file()}
- and \function{email.message_from_string()}.
-
-\item \method{Generator.__call__()} is deprecated; use
- \method{Generator.flatten()} instead. The \class{Generator}
- class has also grown the \method{clone()} method.
-
-\item The \class{DecodedGenerator} class in the
- \module{email.Generator} module was added.
-
-\item The intermediate base classes \class{MIMENonMultipart} and
- \class{MIMEMultipart} have been added, and interposed in the
- class hierarchy for most of the other MIME-related derived
- classes.
-
-\item The \var{_encoder} argument to the \class{MIMEText} constructor
- has been deprecated. Encoding now happens implicitly based
- on the \var{_charset} argument.
-
-\item The following functions in the \module{email.Utils} module have
- been deprecated: \function{dump_address_pairs()},
- \function{decode()}, and \function{encode()}. The following
- functions have been added to the module:
- \function{make_msgid()}, \function{decode_rfc2231()},
- \function{encode_rfc2231()}, and \function{decode_params()}.
-
-\item The non-public function \function{email.Iterators._structure()}
- was added.
-\end{itemize}
-
-\subsection{Differences from \module{mimelib}}
-
-The \module{email} package was originally prototyped as a separate
-library called
-\ulink{\texttt{mimelib}}{http://mimelib.sf.net/}.
-Changes have been made so that
-method names are more consistent, and some methods or modules have
-either been added or removed. The semantics of some of the methods
-have also changed. For the most part, any functionality available in
-\module{mimelib} is still available in the \refmodule{email} package,
-albeit often in a different way. Backward compatibility between
-the \module{mimelib} package and the \module{email} package was not a
-priority.
-
-Here is a brief description of the differences between the
-\module{mimelib} and the \refmodule{email} packages, along with hints on
-how to port your applications.
-
-Of course, the most visible difference between the two packages is
-that the package name has been changed to \refmodule{email}. In
-addition, the top-level package has the following differences:
-
-\begin{itemize}
-\item \function{messageFromString()} has been renamed to
- \function{message_from_string()}.
-
-\item \function{messageFromFile()} has been renamed to
- \function{message_from_file()}.
-
-\end{itemize}
-
-The \class{Message} class has the following differences:
-
-\begin{itemize}
-\item The method \method{asString()} was renamed to \method{as_string()}.
-
-\item The method \method{ismultipart()} was renamed to
- \method{is_multipart()}.
-
-\item The \method{get_payload()} method has grown a \var{decode}
- optional argument.
-
-\item The method \method{getall()} was renamed to \method{get_all()}.
-
-\item The method \method{addheader()} was renamed to \method{add_header()}.
-
-\item The method \method{gettype()} was renamed to \method{get_type()}.
-
-\item The method \method{getmaintype()} was renamed to
- \method{get_main_type()}.
-
-\item The method \method{getsubtype()} was renamed to
- \method{get_subtype()}.
-
-\item The method \method{getparams()} was renamed to
- \method{get_params()}.
- Also, whereas \method{getparams()} returned a list of strings,
- \method{get_params()} returns a list of 2-tuples, effectively
- the key/value pairs of the parameters, split on the \character{=}
- sign.
-
-\item The method \method{getparam()} was renamed to \method{get_param()}.
-
-\item The method \method{getcharsets()} was renamed to
- \method{get_charsets()}.
-
-\item The method \method{getfilename()} was renamed to
- \method{get_filename()}.
-
-\item The method \method{getboundary()} was renamed to
- \method{get_boundary()}.
-
-\item The method \method{setboundary()} was renamed to
- \method{set_boundary()}.
-
-\item The method \method{getdecodedpayload()} was removed. To get
- similar functionality, pass the value 1 to the \var{decode} flag
- of the {get_payload()} method.
-
-\item The method \method{getpayloadastext()} was removed. Similar
- functionality
- is supported by the \class{DecodedGenerator} class in the
- \refmodule{email.generator} module.
-
-\item The method \method{getbodyastext()} was removed. You can get
- similar functionality by creating an iterator with
- \function{typed_subpart_iterator()} in the
- \refmodule{email.iterators} module.
-\end{itemize}
-
-The \class{Parser} class has no differences in its public interface.
-It does have some additional smarts to recognize
-\mimetype{message/delivery-status} type messages, which it represents as
-a \class{Message} instance containing separate \class{Message}
-subparts for each header block in the delivery status
-notification\footnote{Delivery Status Notifications (DSN) are defined
-in \rfc{1894}.}.
-
-The \class{Generator} class has no differences in its public
-interface. There is a new class in the \refmodule{email.generator}
-module though, called \class{DecodedGenerator} which provides most of
-the functionality previously available in the
-\method{Message.getpayloadastext()} method.
-
-The following modules and classes have been changed:
-
-\begin{itemize}
-\item The \class{MIMEBase} class constructor arguments \var{_major}
- and \var{_minor} have changed to \var{_maintype} and
- \var{_subtype} respectively.
-
-\item The \code{Image} class/module has been renamed to
- \code{MIMEImage}. The \var{_minor} argument has been renamed to
- \var{_subtype}.
-
-\item The \code{Text} class/module has been renamed to
- \code{MIMEText}. The \var{_minor} argument has been renamed to
- \var{_subtype}.
-
-\item The \code{MessageRFC822} class/module has been renamed to
- \code{MIMEMessage}. Note that an earlier version of
- \module{mimelib} called this class/module \code{RFC822}, but
- that clashed with the Python standard library module
- \refmodule{rfc822} on some case-insensitive file systems.
-
- Also, the \class{MIMEMessage} class now represents any kind of
- MIME message with main type \mimetype{message}. It takes an
- optional argument \var{_subtype} which is used to set the MIME
- subtype. \var{_subtype} defaults to \mimetype{rfc822}.
-\end{itemize}
-
-\module{mimelib} provided some utility functions in its
-\module{address} and \module{date} modules. All of these functions
-have been moved to the \refmodule{email.utils} module.
-
-The \code{MsgReader} class/module has been removed. Its functionality
-is most closely supported in the \function{body_line_iterator()}
-function in the \refmodule{email.iterators} module.
-
-\subsection{Examples}
-
-Here are a few examples of how to use the \module{email} package to
-read, write, and send simple email messages, as well as more complex
-MIME messages.
-
-First, let's see how to create and send a simple text message:
-
-\verbatiminput{email-simple.py}
-
-Here's an example of how to send a MIME message containing a bunch of
-family pictures that may be residing in a directory:
-
-\verbatiminput{email-mime.py}
-
-Here's an example of how to send the entire contents of a directory as
-an email message:
-\footnote{Thanks to Matthew Dixon Cowles for the original inspiration
- and examples.}
-
-\verbatiminput{email-dir.py}
-
-And finally, here's an example of how to unpack a MIME message like
-the one above, into a directory of files:
-
-\verbatiminput{email-unpack.py}
diff --git a/Doc/lib/emailcharsets.tex b/Doc/lib/emailcharsets.tex
deleted file mode 100644
index e0be68a..0000000
--- a/Doc/lib/emailcharsets.tex
+++ /dev/null
@@ -1,244 +0,0 @@
-\declaremodule{standard}{email.charset}
-\modulesynopsis{Character Sets}
-
-This module provides a class \class{Charset} for representing
-character sets and character set conversions in email messages, as
-well as a character set registry and several convenience methods for
-manipulating this registry. Instances of \class{Charset} are used in
-several other modules within the \module{email} package.
-
-Import this class from the \module{email.charset} module.
-
-\versionadded{2.2.2}
-
-\begin{classdesc}{Charset}{\optional{input_charset}}
-Map character sets to their email properties.
-
-This class provides information about the requirements imposed on
-email for a specific character set. It also provides convenience
-routines for converting between character sets, given the availability
-of the applicable codecs. Given a character set, it will do its best
-to provide information on how to use that character set in an email
-message in an RFC-compliant way.
-
-Certain character sets must be encoded with quoted-printable or base64
-when used in email headers or bodies. Certain character sets must be
-converted outright, and are not allowed in email.
-
-Optional \var{input_charset} is as described below; it is always
-coerced to lower case. After being alias normalized it is also used
-as a lookup into the registry of character sets to find out the header
-encoding, body encoding, and output conversion codec to be used for
-the character set. For example, if
-\var{input_charset} is \code{iso-8859-1}, then headers and bodies will
-be encoded using quoted-printable and no output conversion codec is
-necessary. If \var{input_charset} is \code{euc-jp}, then headers will
-be encoded with base64, bodies will not be encoded, but output text
-will be converted from the \code{euc-jp} character set to the
-\code{iso-2022-jp} character set.
-\end{classdesc}
-
-\class{Charset} instances have the following data attributes:
-
-\begin{datadesc}{input_charset}
-The initial character set specified. Common aliases are converted to
-their \emph{official} email names (e.g. \code{latin_1} is converted to
-\code{iso-8859-1}). Defaults to 7-bit \code{us-ascii}.
-\end{datadesc}
-
-\begin{datadesc}{header_encoding}
-If the character set must be encoded before it can be used in an
-email header, this attribute will be set to \code{Charset.QP} (for
-quoted-printable), \code{Charset.BASE64} (for base64 encoding), or
-\code{Charset.SHORTEST} for the shortest of QP or BASE64 encoding.
-Otherwise, it will be \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{body_encoding}
-Same as \var{header_encoding}, but describes the encoding for the
-mail message's body, which indeed may be different than the header
-encoding. \code{Charset.SHORTEST} is not allowed for
-\var{body_encoding}.
-\end{datadesc}
-
-\begin{datadesc}{output_charset}
-Some character sets must be converted before they can be used in
-email headers or bodies. If the \var{input_charset} is one of
-them, this attribute will contain the name of the character set
-output will be converted to. Otherwise, it will be \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{input_codec}
-The name of the Python codec used to convert the \var{input_charset} to
-Unicode. If no conversion codec is necessary, this attribute will be
-\code{None}.
-\end{datadesc}
-
-\begin{datadesc}{output_codec}
-The name of the Python codec used to convert Unicode to the
-\var{output_charset}. If no conversion codec is necessary, this
-attribute will have the same value as the \var{input_codec}.
-\end{datadesc}
-
-\class{Charset} instances also have the following methods:
-
-\begin{methoddesc}[Charset]{get_body_encoding}{}
-Return the content transfer encoding used for body encoding.
-
-This is either the string \samp{quoted-printable} or \samp{base64}
-depending on the encoding used, or it is a function, in which case you
-should call the function with a single argument, the Message object
-being encoded. The function should then set the
-\mailheader{Content-Transfer-Encoding} header itself to whatever is
-appropriate.
-
-Returns the string \samp{quoted-printable} if
-\var{body_encoding} is \code{QP}, returns the string
-\samp{base64} if \var{body_encoding} is \code{BASE64}, and returns the
-string \samp{7bit} otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}{convert}{s}
-Convert the string \var{s} from the \var{input_codec} to the
-\var{output_codec}.
-\end{methoddesc}
-
-\begin{methoddesc}{to_splittable}{s}
-Convert a possibly multibyte string to a safely splittable format.
-\var{s} is the string to split.
-
-Uses the \var{input_codec} to try and convert the string to Unicode,
-so it can be safely split on character boundaries (even for multibyte
-characters).
-
-Returns the string as-is if it isn't known how to convert \var{s} to
-Unicode with the \var{input_charset}.
-
-Characters that could not be converted to Unicode will be replaced
-with the Unicode replacement character \character{U+FFFD}.
-\end{methoddesc}
-
-\begin{methoddesc}{from_splittable}{ustr\optional{, to_output}}
-Convert a splittable string back into an encoded string. \var{ustr}
-is a Unicode string to ``unsplit''.
-
-This method uses the proper codec to try and convert the string from
-Unicode back into an encoded format. Return the string as-is if it is
-not Unicode, or if it could not be converted from Unicode.
-
-Characters that could not be converted from Unicode will be replaced
-with an appropriate character (usually \character{?}).
-
-If \var{to_output} is \code{True} (the default), uses
-\var{output_codec} to convert to an
-encoded format. If \var{to_output} is \code{False}, it uses
-\var{input_codec}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_output_charset}{}
-Return the output character set.
-
-This is the \var{output_charset} attribute if that is not \code{None},
-otherwise it is \var{input_charset}.
-\end{methoddesc}
-
-\begin{methoddesc}{encoded_header_len}{}
-Return the length of the encoded header string, properly calculating
-for quoted-printable or base64 encoding.
-\end{methoddesc}
-
-\begin{methoddesc}{header_encode}{s\optional{, convert}}
-Header-encode the string \var{s}.
-
-If \var{convert} is \code{True}, the string will be converted from the
-input charset to the output charset automatically. This is not useful
-for multibyte character sets, which have line length issues (multibyte
-characters must be split on a character, not a byte boundary); use the
-higher-level \class{Header} class to deal with these issues (see
-\refmodule{email.header}). \var{convert} defaults to \code{False}.
-
-The type of encoding (base64 or quoted-printable) will be based on
-the \var{header_encoding} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}{body_encode}{s\optional{, convert}}
-Body-encode the string \var{s}.
-
-If \var{convert} is \code{True} (the default), the string will be
-converted from the input charset to output charset automatically.
-Unlike \method{header_encode()}, there are no issues with byte
-boundaries and multibyte charsets in email bodies, so this is usually
-pretty safe.
-
-The type of encoding (base64 or quoted-printable) will be based on
-the \var{body_encoding} attribute.
-\end{methoddesc}
-
-The \class{Charset} class also provides a number of methods to support
-standard operations and built-in functions.
-
-\begin{methoddesc}[Charset]{__str__}{}
-Returns \var{input_charset} as a string coerced to lower case.
-\method{__repr__()} is an alias for \method{__str__()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Charset]{__eq__}{other}
-This method allows you to compare two \class{Charset} instances for equality.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__ne__}{other}
-This method allows you to compare two \class{Charset} instances for inequality.
-\end{methoddesc}
-
-The \module{email.charset} module also provides the following
-functions for adding new entries to the global character set, alias,
-and codec registries:
-
-\begin{funcdesc}{add_charset}{charset\optional{, header_enc\optional{,
- body_enc\optional{, output_charset}}}}
-Add character properties to the global registry.
-
-\var{charset} is the input character set, and must be the canonical
-name of a character set.
-
-Optional \var{header_enc} and \var{body_enc} is either
-\code{Charset.QP} for quoted-printable, \code{Charset.BASE64} for
-base64 encoding, \code{Charset.SHORTEST} for the shortest of
-quoted-printable or base64 encoding, or \code{None} for no encoding.
-\code{SHORTEST} is only valid for \var{header_enc}. The default is
-\code{None} for no encoding.
-
-Optional \var{output_charset} is the character set that the output
-should be in. Conversions will proceed from input charset, to
-Unicode, to the output charset when the method
-\method{Charset.convert()} is called. The default is to output in the
-same character set as the input.
-
-Both \var{input_charset} and \var{output_charset} must have Unicode
-codec entries in the module's character set-to-codec mapping; use
-\function{add_codec()} to add codecs the module does
-not know about. See the \refmodule{codecs} module's documentation for
-more information.
-
-The global character set registry is kept in the module global
-dictionary \code{CHARSETS}.
-\end{funcdesc}
-
-\begin{funcdesc}{add_alias}{alias, canonical}
-Add a character set alias. \var{alias} is the alias name,
-e.g. \code{latin-1}. \var{canonical} is the character set's canonical
-name, e.g. \code{iso-8859-1}.
-
-The global charset alias registry is kept in the module global
-dictionary \code{ALIASES}.
-\end{funcdesc}
-
-\begin{funcdesc}{add_codec}{charset, codecname}
-Add a codec that map characters in the given character set to and from
-Unicode.
-
-\var{charset} is the canonical name of a character set.
-\var{codecname} is the name of a Python codec, as appropriate for the
-second argument to the \function{unicode()} built-in, or to the
-\method{encode()} method of a Unicode string.
-\end{funcdesc}
diff --git a/Doc/lib/emailencoders.tex b/Doc/lib/emailencoders.tex
deleted file mode 100644
index 3d05c2a..0000000
--- a/Doc/lib/emailencoders.tex
+++ /dev/null
@@ -1,47 +0,0 @@
-\declaremodule{standard}{email.encoders}
-\modulesynopsis{Encoders for email message payloads.}
-
-When creating \class{Message} objects from scratch, you often need to
-encode the payloads for transport through compliant mail servers.
-This is especially true for \mimetype{image/*} and \mimetype{text/*}
-type messages containing binary data.
-
-The \module{email} package provides some convenient encodings in its
-\module{encoders} module. These encoders are actually used by the
-\class{MIMEAudio} and \class{MIMEImage} class constructors to provide default
-encodings. All encoder functions take exactly one argument, the message
-object to encode. They usually extract the payload, encode it, and reset the
-payload to this newly encoded value. They should also set the
-\mailheader{Content-Transfer-Encoding} header as appropriate.
-
-Here are the encoding functions provided:
-
-\begin{funcdesc}{encode_quopri}{msg}
-Encodes the payload into quoted-printable form and sets the
-\mailheader{Content-Transfer-Encoding} header to
-\code{quoted-printable}\footnote{Note that encoding with
-\method{encode_quopri()} also encodes all tabs and space characters in
-the data.}.
-This is a good encoding to use when most of your payload is normal
-printable data, but contains a few unprintable characters.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_base64}{msg}
-Encodes the payload into base64 form and sets the
-\mailheader{Content-Transfer-Encoding} header to
-\code{base64}. This is a good encoding to use when most of your payload
-is unprintable data since it is a more compact form than
-quoted-printable. The drawback of base64 encoding is that it
-renders the text non-human readable.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_7or8bit}{msg}
-This doesn't actually modify the message's payload, but it does set
-the \mailheader{Content-Transfer-Encoding} header to either \code{7bit} or
-\code{8bit} as appropriate, based on the payload data.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_noop}{msg}
-This does nothing; it doesn't even set the
-\mailheader{Content-Transfer-Encoding} header.
-\end{funcdesc}
diff --git a/Doc/lib/emailexc.tex b/Doc/lib/emailexc.tex
deleted file mode 100644
index 3cef1d5..0000000
--- a/Doc/lib/emailexc.tex
+++ /dev/null
@@ -1,87 +0,0 @@
-\declaremodule{standard}{email.errors}
-\modulesynopsis{The exception classes used by the email package.}
-
-The following exception classes are defined in the
-\module{email.errors} module:
-
-\begin{excclassdesc}{MessageError}{}
-This is the base class for all exceptions that the \module{email}
-package can raise. It is derived from the standard
-\exception{Exception} class and defines no additional methods.
-\end{excclassdesc}
-
-\begin{excclassdesc}{MessageParseError}{}
-This is the base class for exceptions thrown by the \class{Parser}
-class. It is derived from \exception{MessageError}.
-\end{excclassdesc}
-
-\begin{excclassdesc}{HeaderParseError}{}
-Raised under some error conditions when parsing the \rfc{2822} headers of
-a message, this class is derived from \exception{MessageParseError}.
-It can be raised from the \method{Parser.parse()} or
-\method{Parser.parsestr()} methods.
-
-Situations where it can be raised include finding an envelope
-header after the first \rfc{2822} header of the message, finding a
-continuation line before the first \rfc{2822} header is found, or finding
-a line in the headers which is neither a header or a continuation
-line.
-\end{excclassdesc}
-
-\begin{excclassdesc}{BoundaryError}{}
-Raised under some error conditions when parsing the \rfc{2822} headers of
-a message, this class is derived from \exception{MessageParseError}.
-It can be raised from the \method{Parser.parse()} or
-\method{Parser.parsestr()} methods.
-
-Situations where it can be raised include not being able to find the
-starting or terminating boundary in a \mimetype{multipart/*} message
-when strict parsing is used.
-\end{excclassdesc}
-
-\begin{excclassdesc}{MultipartConversionError}{}
-Raised when a payload is added to a \class{Message} object using
-\method{add_payload()}, but the payload is already a scalar and the
-message's \mailheader{Content-Type} main type is not either
-\mimetype{multipart} or missing. \exception{MultipartConversionError}
-multiply inherits from \exception{MessageError} and the built-in
-\exception{TypeError}.
-
-Since \method{Message.add_payload()} is deprecated, this exception is
-rarely raised in practice. However the exception may also be raised
-if the \method{attach()} method is called on an instance of a class
-derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
-\end{excclassdesc}
-
-Here's the list of the defects that the \class{FeedParser} can find while
-parsing messages. Note that the defects are added to the message where the
-problem was found, so for example, if a message nested inside a
-\mimetype{multipart/alternative} had a malformed header, that nested message
-object would have a defect, but the containing messages would not.
-
-All defect classes are subclassed from \class{email.errors.MessageDefect}, but
-this class is \emph{not} an exception!
-
-\versionadded[All the defect classes were added]{2.4}
-
-\begin{itemize}
-\item \class{NoBoundaryInMultipartDefect} -- A message claimed to be a
- multipart, but had no \mimetype{boundary} parameter.
-
-\item \class{StartBoundaryNotFoundDefect} -- The start boundary claimed in the
- \mailheader{Content-Type} header was never found.
-
-\item \class{FirstHeaderLineIsContinuationDefect} -- The message had a
- continuation line as its first header line.
-
-\item \class{MisplacedEnvelopeHeaderDefect} - A ``Unix From'' header was found
- in the middle of a header block.
-
-\item \class{MalformedHeaderDefect} -- A header was found that was missing a
- colon, or was otherwise malformed.
-
-\item \class{MultipartInvariantViolationDefect} -- A message claimed to be a
- \mimetype{multipart}, but no subparts were found. Note that when a
- message has this defect, its \method{is_multipart()} method may return
- false even though its content type claims to be \mimetype{multipart}.
-\end{itemize}
diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex
deleted file mode 100644
index 7ab0a53..0000000
--- a/Doc/lib/emailgenerator.tex
+++ /dev/null
@@ -1,133 +0,0 @@
-\declaremodule{standard}{email.generator}
-\modulesynopsis{Generate flat text email messages from a message structure.}
-
-One of the most common tasks is to generate the flat text of the email
-message represented by a message object structure. You will need to do
-this if you want to send your message via the \refmodule{smtplib}
-module or the \refmodule{nntplib} module, or print the message on the
-console. Taking a message object structure and producing a flat text
-document is the job of the \class{Generator} class.
-
-Again, as with the \refmodule{email.parser} module, you aren't limited
-to the functionality of the bundled generator; you could write one
-from scratch yourself. However the bundled generator knows how to
-generate most email in a standards-compliant way, should handle MIME
-and non-MIME email messages just fine, and is designed so that the
-transformation from flat text, to a message structure via the
-\class{Parser} class, and back to flat text, is idempotent (the input
-is identical to the output).
-
-Here are the public methods of the \class{Generator} class, imported from the
-\module{email.generator} module:
-
-\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{,
- maxheaderlen}}}
-The constructor for the \class{Generator} class takes a file-like
-object called \var{outfp} for an argument. \var{outfp} must support
-the \method{write()} method and be usable as the output file in a
-Python extended print statement.
-
-Optional \var{mangle_from_} is a flag that, when \code{True}, puts a
-\samp{>} character in front of any line in the body that starts exactly as
-\samp{From }, i.e. \code{From} followed by a space at the beginning of the
-line. This is the only guaranteed portable way to avoid having such
-lines be mistaken for a \UNIX{} mailbox format envelope header separator (see
-\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
-{http://www.jwz.org/doc/content-length.html}
-for details). \var{mangle_from_} defaults to \code{True}, but you
-might want to set this to \code{False} if you are not writing \UNIX{}
-mailbox format files.
-
-Optional \var{maxheaderlen} specifies the longest length for a
-non-continued header. When a header line is longer than
-\var{maxheaderlen} (in characters, with tabs expanded to 8 spaces),
-the header will be split as defined in the \module{email.header.Header}
-class. Set to zero to disable header wrapping. The default is 78, as
-recommended (but not required) by \rfc{2822}.
-\end{classdesc}
-
-The other public \class{Generator} methods are:
-
-\begin{methoddesc}[Generator]{flatten}{msg\optional{, unixfrom}}
-Print the textual representation of the message object structure rooted at
-\var{msg} to the output file specified when the \class{Generator}
-instance was created. Subparts are visited depth-first and the
-resulting text will be properly MIME encoded.
-
-Optional \var{unixfrom} is a flag that forces the printing of the
-envelope header delimiter before the first \rfc{2822} header of the
-root message object. If the root object has no envelope header, a
-standard one is crafted. By default, this is set to \code{False} to
-inhibit the printing of the envelope delimiter.
-
-Note that for subparts, no envelope header is ever printed.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Generator]{clone}{fp}
-Return an independent clone of this \class{Generator} instance with
-the exact same options.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Generator]{write}{s}
-Write the string \var{s} to the underlying file object,
-i.e. \var{outfp} passed to \class{Generator}'s constructor. This
-provides just enough file-like API for \class{Generator} instances to
-be used in extended print statements.
-\end{methoddesc}
-
-As a convenience, see the methods \method{Message.as_string()} and
-\code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which
-simplify the generation of a formatted string representation of a
-message object. For more detail, see \refmodule{email.message}.
-
-The \module{email.generator} module also provides a derived class,
-called \class{DecodedGenerator} which is like the \class{Generator}
-base class, except that non-\mimetype{text} parts are substituted with
-a format string representing the part.
-
-\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{,
- maxheaderlen\optional{, fmt}}}}
-
-This class, derived from \class{Generator} walks through all the
-subparts of a message. If the subpart is of main type
-\mimetype{text}, then it prints the decoded payload of the subpart.
-Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the
-\class{Generator} base class.
-
-If the subpart is not of main type \mimetype{text}, optional \var{fmt}
-is a format string that is used instead of the message payload.
-\var{fmt} is expanded with the following keywords, \samp{\%(keyword)s}
-format:
-
-\begin{itemize}
-\item \code{type} -- Full MIME type of the non-\mimetype{text} part
-
-\item \code{maintype} -- Main MIME type of the non-\mimetype{text} part
-
-\item \code{subtype} -- Sub-MIME type of the non-\mimetype{text} part
-
-\item \code{filename} -- Filename of the non-\mimetype{text} part
-
-\item \code{description} -- Description associated with the
- non-\mimetype{text} part
-
-\item \code{encoding} -- Content transfer encoding of the
- non-\mimetype{text} part
-
-\end{itemize}
-
-The default value for \var{fmt} is \code{None}, meaning
-
-\begin{verbatim}
-[Non-text (%(type)s) part of message omitted, filename %(filename)s]
-\end{verbatim}
-
-\versionadded{2.2.2}
-\end{classdesc}
-
-\versionchanged[The previously deprecated method \method{__call__()} was
-removed]{2.5}
diff --git a/Doc/lib/emailheaders.tex b/Doc/lib/emailheaders.tex
deleted file mode 100644
index 524d08c..0000000
--- a/Doc/lib/emailheaders.tex
+++ /dev/null
@@ -1,178 +0,0 @@
-\declaremodule{standard}{email.header}
-\modulesynopsis{Representing non-ASCII headers}
-
-\rfc{2822} is the base standard that describes the format of email
-messages. It derives from the older \rfc{822} standard which came
-into widespread use at a time when most email was composed of \ASCII{}
-characters only. \rfc{2822} is a specification written assuming email
-contains only 7-bit \ASCII{} characters.
-
-Of course, as email has been deployed worldwide, it has become
-internationalized, such that language specific character sets can now
-be used in email messages. The base standard still requires email
-messages to be transferred using only 7-bit \ASCII{} characters, so a
-slew of RFCs have been written describing how to encode email
-containing non-\ASCII{} characters into \rfc{2822}-compliant format.
-These RFCs include \rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}.
-The \module{email} package supports these standards in its
-\module{email.header} and \module{email.charset} modules.
-
-If you want to include non-\ASCII{} characters in your email headers,
-say in the \mailheader{Subject} or \mailheader{To} fields, you should
-use the \class{Header} class and assign the field in the
-\class{Message} object to an instance of \class{Header} instead of
-using a string for the header value. Import the \class{Header} class from the
-\module{email.header} module. For example:
-
-\begin{verbatim}
->>> from email.message import Message
->>> from email.header import Header
->>> msg = Message()
->>> h = Header('p\xf6stal', 'iso-8859-1')
->>> msg['Subject'] = h
->>> print msg.as_string()
-Subject: =?iso-8859-1?q?p=F6stal?=
-
-
-\end{verbatim}
-
-Notice here how we wanted the \mailheader{Subject} field to contain a
-non-\ASCII{} character? We did this by creating a \class{Header}
-instance and passing in the character set that the byte string was
-encoded in. When the subsequent \class{Message} instance was
-flattened, the \mailheader{Subject} field was properly \rfc{2047}
-encoded. MIME-aware mail readers would show this header using the
-embedded ISO-8859-1 character.
-
-\versionadded{2.2.2}
-
-Here is the \class{Header} class description:
-
-\begin{classdesc}{Header}{\optional{s\optional{, charset\optional{,
- maxlinelen\optional{, header_name\optional{, continuation_ws\optional{,
- errors}}}}}}}
-Create a MIME-compliant header that can contain strings in different
-character sets.
-
-Optional \var{s} is the initial header value. If \code{None} (the
-default), the initial header value is not set. You can later append
-to the header with \method{append()} method calls. \var{s} may be a
-byte string or a Unicode string, but see the \method{append()}
-documentation for semantics.
-
-Optional \var{charset} serves two purposes: it has the same meaning as
-the \var{charset} argument to the \method{append()} method. It also
-sets the default character set for all subsequent \method{append()}
-calls that omit the \var{charset} argument. If \var{charset} is not
-provided in the constructor (the default), the \code{us-ascii}
-character set is used both as \var{s}'s initial charset and as the
-default for subsequent \method{append()} calls.
-
-The maximum line length can be specified explicit via
-\var{maxlinelen}. For splitting the first line to a shorter value (to
-account for the field header which isn't included in \var{s},
-e.g. \mailheader{Subject}) pass in the name of the field in
-\var{header_name}. The default \var{maxlinelen} is 76, and the
-default value for \var{header_name} is \code{None}, meaning it is not
-taken into account for the first line of a long, split header.
-
-Optional \var{continuation_ws} must be \rfc{2822}-compliant folding
-whitespace, and is usually either a space or a hard tab character.
-This character will be prepended to continuation lines.
-\end{classdesc}
-
-Optional \var{errors} is passed straight through to the
-\method{append()} method.
-
-\begin{methoddesc}[Header]{append}{s\optional{, charset\optional{, errors}}}
-Append the string \var{s} to the MIME header.
-
-Optional \var{charset}, if given, should be a \class{Charset} instance
-(see \refmodule{email.charset}) or the name of a character set, which
-will be converted to a \class{Charset} instance. A value of
-\code{None} (the default) means that the \var{charset} given in the
-constructor is used.
-
-\var{s} may be a byte string or a Unicode string. If it is a byte
-string (i.e. \code{isinstance(s, str)} is true), then
-\var{charset} is the encoding of that byte string, and a
-\exception{UnicodeError} will be raised if the string cannot be
-decoded with that character set.
-
-If \var{s} is a Unicode string, then \var{charset} is a hint
-specifying the character set of the characters in the string. In this
-case, when producing an \rfc{2822}-compliant header using \rfc{2047}
-rules, the Unicode string will be encoded using the following charsets
-in order: \code{us-ascii}, the \var{charset} hint, \code{utf-8}. The
-first character set to not provoke a \exception{UnicodeError} is used.
-
-Optional \var{errors} is passed through to any \function{unicode()} or
-\function{ustr.encode()} call, and defaults to ``strict''.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{encode}{\optional{splitchars}}
-Encode a message header into an RFC-compliant format, possibly
-wrapping long lines and encapsulating non-\ASCII{} parts in base64 or
-quoted-printable encodings. Optional \var{splitchars} is a string
-containing characters to split long ASCII lines on, in rough support
-of \rfc{2822}'s \emph{highest level syntactic breaks}. This doesn't
-affect \rfc{2047} encoded lines.
-\end{methoddesc}
-
-The \class{Header} class also provides a number of methods to support
-standard operators and built-in functions.
-
-\begin{methoddesc}[Header]{__str__}{}
-A synonym for \method{Header.encode()}. Useful for
-\code{str(aHeader)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__unicode__}{}
-A helper for the built-in \function{unicode()} function. Returns the
-header as a Unicode string.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__eq__}{other}
-This method allows you to compare two \class{Header} instances for equality.
-\end{methoddesc}
-
-\begin{methoddesc}[Header]{__ne__}{other}
-This method allows you to compare two \class{Header} instances for inequality.
-\end{methoddesc}
-
-The \module{email.header} module also provides the following
-convenient functions.
-
-\begin{funcdesc}{decode_header}{header}
-Decode a message header value without converting the character set.
-The header value is in \var{header}.
-
-This function returns a list of \code{(decoded_string, charset)} pairs
-containing each of the decoded parts of the header. \var{charset} is
-\code{None} for non-encoded parts of the header, otherwise a lower
-case string containing the name of the character set specified in the
-encoded string.
-
-Here's an example:
-
-\begin{verbatim}
->>> from email.header import decode_header
->>> decode_header('=?iso-8859-1?q?p=F6stal?=')
-[('p\xf6stal', 'iso-8859-1')]
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{make_header}{decoded_seq\optional{, maxlinelen\optional{,
- header_name\optional{, continuation_ws}}}}
-Create a \class{Header} instance from a sequence of pairs as returned
-by \function{decode_header()}.
-
-\function{decode_header()} takes a header value string and returns a
-sequence of pairs of the format \code{(decoded_string, charset)} where
-\var{charset} is the name of the character set.
-
-This function takes one of those sequence of pairs and returns a
-\class{Header} instance. Optional \var{maxlinelen},
-\var{header_name}, and \var{continuation_ws} are as in the
-\class{Header} constructor.
-\end{funcdesc}
diff --git a/Doc/lib/emailiter.tex b/Doc/lib/emailiter.tex
deleted file mode 100644
index ef8ef6f..0000000
--- a/Doc/lib/emailiter.tex
+++ /dev/null
@@ -1,65 +0,0 @@
-\declaremodule{standard}{email.iterators}
-\modulesynopsis{Iterate over a message object tree.}
-
-Iterating over a message object tree is fairly easy with the
-\method{Message.walk()} method. The \module{email.iterators} module
-provides some useful higher level iterations over message object
-trees.
-
-\begin{funcdesc}{body_line_iterator}{msg\optional{, decode}}
-This iterates over all the payloads in all the subparts of \var{msg},
-returning the string payloads line-by-line. It skips over all the
-subpart headers, and it skips over any subpart with a payload that
-isn't a Python string. This is somewhat equivalent to reading the
-flat text representation of the message from a file using
-\method{readline()}, skipping over all the intervening headers.
-
-Optional \var{decode} is passed through to \method{Message.get_payload()}.
-\end{funcdesc}
-
-\begin{funcdesc}{typed_subpart_iterator}{msg\optional{,
- maintype\optional{, subtype}}}
-This iterates over all the subparts of \var{msg}, returning only those
-subparts that match the MIME type specified by \var{maintype} and
-\var{subtype}.
-
-Note that \var{subtype} is optional; if omitted, then subpart MIME
-type matching is done only with the main type. \var{maintype} is
-optional too; it defaults to \mimetype{text}.
-
-Thus, by default \function{typed_subpart_iterator()} returns each
-subpart that has a MIME type of \mimetype{text/*}.
-\end{funcdesc}
-
-The following function has been added as a useful debugging tool. It
-should \emph{not} be considered part of the supported public interface
-for the package.
-
-\begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}}
-Prints an indented representation of the content types of the
-message object structure. For example:
-
-\begin{verbatim}
->>> msg = email.message_from_file(somefile)
->>> _structure(msg)
-multipart/mixed
- text/plain
- text/plain
- multipart/digest
- message/rfc822
- text/plain
- message/rfc822
- text/plain
- message/rfc822
- text/plain
- message/rfc822
- text/plain
- message/rfc822
- text/plain
- text/plain
-\end{verbatim}
-
-Optional \var{fp} is a file-like object to print the output to. It
-must be suitable for Python's extended print statement. \var{level}
-is used internally.
-\end{funcdesc}
diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex
deleted file mode 100644
index 7bd7dd8..0000000
--- a/Doc/lib/emailmessage.tex
+++ /dev/null
@@ -1,561 +0,0 @@
-\declaremodule{standard}{email.message}
-\modulesynopsis{The base class representing email messages.}
-
-The central class in the \module{email} package is the
-\class{Message} class, imported from the \module{email.message} module. It is
-the base class for the \module{email} object model. \class{Message} provides
-the core functionality for setting and querying header fields, and for
-accessing message bodies.
-
-Conceptually, a \class{Message} object consists of \emph{headers} and
-\emph{payloads}. Headers are \rfc{2822} style field names and
-values where the field name and value are separated by a colon. The
-colon is not part of either the field name or the field value.
-
-Headers are stored and returned in case-preserving form but are
-matched case-insensitively. There may also be a single envelope
-header, also known as the \emph{Unix-From} header or the
-\code{From_} header. The payload is either a string in the case of
-simple message objects or a list of \class{Message} objects for
-MIME container documents (e.g. \mimetype{multipart/*} and
-\mimetype{message/rfc822}).
-
-\class{Message} objects provide a mapping style interface for
-accessing the message headers, and an explicit interface for accessing
-both the headers and the payload. It provides convenience methods for
-generating a flat text representation of the message object tree, for
-accessing commonly used header parameters, and for recursively walking
-over the object tree.
-
-Here are the methods of the \class{Message} class:
-
-\begin{classdesc}{Message}{}
-The constructor takes no arguments.
-\end{classdesc}
-
-\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}}
-Return the entire message flatten as a string. When optional
-\var{unixfrom} is \code{True}, the envelope header is included in the
-returned string. \var{unixfrom} defaults to \code{False}.
-
-Note that this method is provided as a convenience and may not always format
-the message the way you want. For example, by default it mangles lines that
-begin with \code{From }. For more flexibility, instantiate a
-\class{Generator} instance and use its
-\method{flatten()} method directly. For example:
-
-\begin{verbatim}
-from cStringIO import StringIO
-from email.generator import Generator
-fp = StringIO()
-g = Generator(fp, mangle_from_=False, maxheaderlen=60)
-g.flatten(msg)
-text = fp.getvalue()
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__str__}{}
-Equivalent to \method{as_string(unixfrom=True)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{is_multipart}{}
-Return \code{True} if the message's payload is a list of
-sub-\class{Message} objects, otherwise return \code{False}. When
-\method{is_multipart()} returns False, the payload should be a string
-object.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_unixfrom}{unixfrom}
-Set the message's envelope header to \var{unixfrom}, which should be a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_unixfrom}{}
-Return the message's envelope header. Defaults to \code{None} if the
-envelope header was never set.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{attach}{payload}
-Add the given \var{payload} to the current payload, which must be
-\code{None} or a list of \class{Message} objects before the call.
-After the call, the payload will always be a list of \class{Message}
-objects. If you want to set the payload to a scalar object (e.g. a
-string), use \method{set_payload()} instead.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_payload}{\optional{i\optional{, decode}}}
-Return a reference the current payload, which will be a list of
-\class{Message} objects when \method{is_multipart()} is \code{True}, or a
-string when \method{is_multipart()} is \code{False}. If the
-payload is a list and you mutate the list object, you modify the
-message's payload in place.
-
-With optional argument \var{i}, \method{get_payload()} will return the
-\var{i}-th element of the payload, counting from zero, if
-\method{is_multipart()} is \code{True}. An \exception{IndexError}
-will be raised if \var{i} is less than 0 or greater than or equal to
-the number of items in the payload. If the payload is a string
-(i.e. \method{is_multipart()} is \code{False}) and \var{i} is given, a
-\exception{TypeError} is raised.
-
-Optional \var{decode} is a flag indicating whether the payload should be
-decoded or not, according to the \mailheader{Content-Transfer-Encoding} header.
-When \code{True} and the message is not a multipart, the payload will be
-decoded if this header's value is \samp{quoted-printable} or
-\samp{base64}. If some other encoding is used, or
-\mailheader{Content-Transfer-Encoding} header is
-missing, or if the payload has bogus base64 data, the payload is
-returned as-is (undecoded). If the message is a multipart and the
-\var{decode} flag is \code{True}, then \code{None} is returned. The
-default for \var{decode} is \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}}
-Set the entire message object's payload to \var{payload}. It is the
-client's responsibility to ensure the payload invariants. Optional
-\var{charset} sets the message's default character set; see
-\method{set_charset()} for details.
-
-\versionchanged[\var{charset} argument added]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_charset}{charset}
-Set the character set of the payload to \var{charset}, which can
-either be a \class{Charset} instance (see \refmodule{email.charset}), a
-string naming a character set,
-or \code{None}. If it is a string, it will be converted to a
-\class{Charset} instance. If \var{charset} is \code{None}, the
-\code{charset} parameter will be removed from the
-\mailheader{Content-Type} header. Anything else will generate a
-\exception{TypeError}.
-
-The message will be assumed to be of type \mimetype{text/*} encoded with
-\var{charset.input_charset}. It will be converted to
-\var{charset.output_charset}
-and encoded properly, if needed, when generating the plain text
-representation of the message. MIME headers
-(\mailheader{MIME-Version}, \mailheader{Content-Type},
-\mailheader{Content-Transfer-Encoding}) will be added as needed.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_charset}{}
-Return the \class{Charset} instance associated with the message's payload.
-\versionadded{2.2.2}
-\end{methoddesc}
-
-The following methods implement a mapping-like interface for accessing
-the message's \rfc{2822} headers. Note that there are some
-semantic differences between these methods and a normal mapping
-(i.e. dictionary) interface. For example, in a dictionary there are
-no duplicate keys, but here there may be duplicate message headers. Also,
-in dictionaries there is no guaranteed order to the keys returned by
-\method{keys()}, but in a \class{Message} object, headers are always
-returned in the order they appeared in the original message, or were
-added to the message later. Any header deleted and then re-added are
-always appended to the end of the header list.
-
-These semantic differences are intentional and are biased toward
-maximal convenience.
-
-Note that in all cases, any envelope header present in the message is
-not included in the mapping interface.
-
-\begin{methoddesc}[Message]{__len__}{}
-Return the total number of headers, including duplicates.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__contains__}{name}
-Return true if the message object has a field named \var{name}.
-Matching is done case-insensitively and \var{name} should not include the
-trailing colon. Used for the \code{in} operator,
-e.g.:
-
-\begin{verbatim}
-if 'message-id' in myMessage:
- print 'Message-ID:', myMessage['message-id']
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__getitem__}{name}
-Return the value of the named header field. \var{name} should not
-include the colon field separator. If the header is missing,
-\code{None} is returned; a \exception{KeyError} is never raised.
-
-Note that if the named field appears more than once in the message's
-headers, exactly which of those field values will be returned is
-undefined. Use the \method{get_all()} method to get the values of all
-the extant named headers.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__setitem__}{name, val}
-Add a header to the message with field name \var{name} and value
-\var{val}. The field is appended to the end of the message's existing
-fields.
-
-Note that this does \emph{not} overwrite or delete any existing header
-with the same name. If you want to ensure that the new header is the
-only one present in the message with field name
-\var{name}, delete the field first, e.g.:
-
-\begin{verbatim}
-del msg['subject']
-msg['subject'] = 'Python roolz!'
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__delitem__}{name}
-Delete all occurrences of the field with name \var{name} from the
-message's headers. No exception is raised if the named field isn't
-present in the headers.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{has_key}{name}
-Return true if the message contains a header field named \var{name},
-otherwise return false.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{keys}{}
-Return a list of all the message's header field names.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{values}{}
-Return a list of all the message's field values.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{items}{}
-Return a list of 2-tuples containing all the message's field headers
-and values.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get}{name\optional{, failobj}}
-Return the value of the named header field. This is identical to
-\method{__getitem__()} except that optional \var{failobj} is returned
-if the named header is missing (defaults to \code{None}).
-\end{methoddesc}
-
-Here are some additional useful methods:
-
-\begin{methoddesc}[Message]{get_all}{name\optional{, failobj}}
-Return a list of all the values for the field named \var{name}.
-If there are no such named headers in the message, \var{failobj} is
-returned (defaults to \code{None}).
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{add_header}{_name, _value, **_params}
-Extended header setting. This method is similar to
-\method{__setitem__()} except that additional header parameters can be
-provided as keyword arguments. \var{_name} is the header field to add
-and \var{_value} is the \emph{primary} value for the header.
-
-For each item in the keyword argument dictionary \var{_params}, the
-key is taken as the parameter name, with underscores converted to
-dashes (since dashes are illegal in Python identifiers). Normally,
-the parameter will be added as \code{key="value"} unless the value is
-\code{None}, in which case only the key will be added.
-
-Here's an example:
-
-\begin{verbatim}
-msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
-\end{verbatim}
-
-This will add a header that looks like
-
-\begin{verbatim}
-Content-Disposition: attachment; filename="bud.gif"
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{replace_header}{_name, _value}
-Replace a header. Replace the first header found in the message that
-matches \var{_name}, retaining header order and field name case. If
-no matching header was found, a \exception{KeyError} is raised.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_type}{}
-Return the message's content type. The returned string is coerced to
-lower case of the form \mimetype{maintype/subtype}. If there was no
-\mailheader{Content-Type} header in the message the default type as
-given by \method{get_default_type()} will be returned. Since
-according to \rfc{2045}, messages always have a default type,
-\method{get_content_type()} will always return a value.
-
-\rfc{2045} defines a message's default type to be
-\mimetype{text/plain} unless it appears inside a
-\mimetype{multipart/digest} container, in which case it would be
-\mimetype{message/rfc822}. If the \mailheader{Content-Type} header
-has an invalid type specification, \rfc{2045} mandates that the
-default type be \mimetype{text/plain}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_maintype}{}
-Return the message's main content type. This is the
-\mimetype{maintype} part of the string returned by
-\method{get_content_type()}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_subtype}{}
-Return the message's sub-content type. This is the \mimetype{subtype}
-part of the string returned by \method{get_content_type()}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_default_type}{}
-Return the default content type. Most messages have a default content
-type of \mimetype{text/plain}, except for messages that are subparts
-of \mimetype{multipart/digest} containers. Such subparts have a
-default content type of \mimetype{message/rfc822}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_default_type}{ctype}
-Set the default content type. \var{ctype} should either be
-\mimetype{text/plain} or \mimetype{message/rfc822}, although this is
-not enforced. The default content type is not stored in the
-\mailheader{Content-Type} header.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{,
- header\optional{, unquote}}}}
-Return the message's \mailheader{Content-Type} parameters, as a list. The
-elements of the returned list are 2-tuples of key/value pairs, as
-split on the \character{=} sign. The left hand side of the
-\character{=} is the key, while the right hand side is the value. If
-there is no \character{=} sign in the parameter the value is the empty
-string, otherwise the value is as described in \method{get_param()} and is
-unquoted if optional \var{unquote} is \code{True} (the default).
-
-Optional \var{failobj} is the object to return if there is no
-\mailheader{Content-Type} header. Optional \var{header} is the header to
-search instead of \mailheader{Content-Type}.
-
-\versionchanged[\var{unquote} argument added]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_param}{param\optional{,
- failobj\optional{, header\optional{, unquote}}}}
-Return the value of the \mailheader{Content-Type} header's parameter
-\var{param} as a string. If the message has no \mailheader{Content-Type}
-header or if there is no such parameter, then \var{failobj} is
-returned (defaults to \code{None}).
-
-Optional \var{header} if given, specifies the message header to use
-instead of \mailheader{Content-Type}.
-
-Parameter keys are always compared case insensitively. The return
-value can either be a string, or a 3-tuple if the parameter was
-\rfc{2231} encoded. When it's a 3-tuple, the elements of the value are of
-the form \code{(CHARSET, LANGUAGE, VALUE)}. Note that both \code{CHARSET} and
-\code{LANGUAGE} can be \code{None}, in which case you should consider
-\code{VALUE} to be encoded in the \code{us-ascii} charset. You can
-usually ignore \code{LANGUAGE}.
-
-If your application doesn't care whether the parameter was encoded as in
-\rfc{2231}, you can collapse the parameter value by calling
-\function{email.Utils.collapse_rfc2231_value()}, passing in the return value
-from \method{get_param()}. This will return a suitably decoded Unicode string
-whn the value is a tuple, or the original string unquoted if it isn't. For
-example:
-
-\begin{verbatim}
-rawparam = msg.get_param('foo')
-param = email.Utils.collapse_rfc2231_value(rawparam)
-\end{verbatim}
-
-In any case, the parameter value (either the returned string, or the
-\code{VALUE} item in the 3-tuple) is always unquoted, unless
-\var{unquote} is set to \code{False}.
-
-\versionchanged[\var{unquote} argument added, and 3-tuple return value
-possible]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_param}{param, value\optional{,
- header\optional{, requote\optional{, charset\optional{, language}}}}}
-
-Set a parameter in the \mailheader{Content-Type} header. If the
-parameter already exists in the header, its value will be replaced
-with \var{value}. If the \mailheader{Content-Type} header as not yet
-been defined for this message, it will be set to \mimetype{text/plain}
-and the new parameter value will be appended as per \rfc{2045}.
-
-Optional \var{header} specifies an alternative header to
-\mailheader{Content-Type}, and all parameters will be quoted as
-necessary unless optional \var{requote} is \code{False} (the default
-is \code{True}).
-
-If optional \var{charset} is specified, the parameter will be encoded
-according to \rfc{2231}. Optional \var{language} specifies the RFC
-2231 language, defaulting to the empty string. Both \var{charset} and
-\var{language} should be strings.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{del_param}{param\optional{, header\optional{,
- requote}}}
-Remove the given parameter completely from the
-\mailheader{Content-Type} header. The header will be re-written in
-place without the parameter or its value. All values will be quoted
-as necessary unless \var{requote} is \code{False} (the default is
-\code{True}). Optional \var{header} specifies an alternative to
-\mailheader{Content-Type}.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_type}{type\optional{, header}\optional{,
- requote}}
-Set the main type and subtype for the \mailheader{Content-Type}
-header. \var{type} must be a string in the form
-\mimetype{maintype/subtype}, otherwise a \exception{ValueError} is
-raised.
-
-This method replaces the \mailheader{Content-Type} header, keeping all
-the parameters in place. If \var{requote} is \code{False}, this
-leaves the existing header's quoting as is, otherwise the parameters
-will be quoted (the default).
-
-An alternative header can be specified in the \var{header} argument.
-When the \mailheader{Content-Type} header is set a
-\mailheader{MIME-Version} header is also added.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_filename}{\optional{failobj}}
-Return the value of the \code{filename} parameter of the
-\mailheader{Content-Disposition} header of the message. If the header does
-not have a \code{filename} parameter, this method falls back to looking for
-the \code{name} parameter. If neither is found, or the header is missing,
-then \var{failobj} is returned. The returned string will always be unquoted
-as per \method{Utils.unquote()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}}
-Return the value of the \code{boundary} parameter of the
-\mailheader{Content-Type} header of the message, or \var{failobj} if either
-the header is missing, or has no \code{boundary} parameter. The
-returned string will always be unquoted as per
-\method{Utils.unquote()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_boundary}{boundary}
-Set the \code{boundary} parameter of the \mailheader{Content-Type}
-header to \var{boundary}. \method{set_boundary()} will always quote
-\var{boundary} if necessary. A \exception{HeaderParseError} is raised
-if the message object has no \mailheader{Content-Type} header.
-
-Note that using this method is subtly different than deleting the old
-\mailheader{Content-Type} header and adding a new one with the new boundary
-via \method{add_header()}, because \method{set_boundary()} preserves the
-order of the \mailheader{Content-Type} header in the list of headers.
-However, it does \emph{not} preserve any continuation lines which may
-have been present in the original \mailheader{Content-Type} header.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_content_charset}{\optional{failobj}}
-Return the \code{charset} parameter of the \mailheader{Content-Type}
-header, coerced to lower case. If there is no
-\mailheader{Content-Type} header, or if that header has no
-\code{charset} parameter, \var{failobj} is returned.
-
-Note that this method differs from \method{get_charset()} which
-returns the \class{Charset} instance for the default encoding of the
-message body.
-
-\versionadded{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}}
-Return a list containing the character set names in the message. If
-the message is a \mimetype{multipart}, then the list will contain one
-element for each subpart in the payload, otherwise, it will be a list
-of length 1.
-
-Each item in the list will be a string which is the value of the
-\code{charset} parameter in the \mailheader{Content-Type} header for the
-represented subpart. However, if the subpart has no
-\mailheader{Content-Type} header, no \code{charset} parameter, or is not of
-the \mimetype{text} main MIME type, then that item in the returned list
-will be \var{failobj}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{walk}{}
-The \method{walk()} method is an all-purpose generator which can be
-used to iterate over all the parts and subparts of a message object
-tree, in depth-first traversal order. You will typically use
-\method{walk()} as the iterator in a \code{for} loop; each
-iteration returns the next subpart.
-
-Here's an example that prints the MIME type of every part of a
-multipart message structure:
-
-\begin{verbatim}
->>> for part in msg.walk():
-... print part.get_content_type()
-multipart/report
-text/plain
-message/delivery-status
-text/plain
-text/plain
-message/rfc822
-\end{verbatim}
-\end{methoddesc}
-
-\versionchanged[The previously deprecated methods \method{get_type()},
-\method{get_main_type()}, and \method{get_subtype()} were removed]{2.5}
-
-\class{Message} objects can also optionally contain two instance
-attributes, which can be used when generating the plain text of a MIME
-message.
-
-\begin{datadesc}{preamble}
-The format of a MIME document allows for some text between the blank
-line following the headers, and the first multipart boundary string.
-Normally, this text is never visible in a MIME-aware mail reader
-because it falls outside the standard MIME armor. However, when
-viewing the raw text of the message, or when viewing the message in a
-non-MIME aware reader, this text can become visible.
-
-The \var{preamble} attribute contains this leading extra-armor text
-for MIME documents. When the \class{Parser} discovers some text after
-the headers but before the first boundary string, it assigns this text
-to the message's \var{preamble} attribute. When the \class{Generator}
-is writing out the plain text representation of a MIME message, and it
-finds the message has a \var{preamble} attribute, it will write this
-text in the area between the headers and the first boundary. See
-\refmodule{email.parser} and \refmodule{email.generator} for details.
-
-Note that if the message object has no preamble, the
-\var{preamble} attribute will be \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{epilogue}
-The \var{epilogue} attribute acts the same way as the \var{preamble}
-attribute, except that it contains text that appears between the last
-boundary and the end of the message.
-
-\versionchanged[You do not need to set the epilogue to the empty string in
-order for the \class{Generator} to print a newline at the end of the
-file]{2.5}
-\end{datadesc}
-
-\begin{datadesc}{defects}
-The \var{defects} attribute contains a list of all the problems found when
-parsing this message. See \refmodule{email.errors} for a detailed description
-of the possible parsing defects.
-
-\versionadded{2.4}
-\end{datadesc}
diff --git a/Doc/lib/emailmimebase.tex b/Doc/lib/emailmimebase.tex
deleted file mode 100644
index 4735be3..0000000
--- a/Doc/lib/emailmimebase.tex
+++ /dev/null
@@ -1,186 +0,0 @@
-\declaremodule{standard}{email.mime}
-\declaremodule{standard}{email.mime.base}
-\declaremodule{standard}{email.mime.nonmultipart}
-\declaremodule{standard}{email.mime.multipart}
-\declaremodule{standard}{email.mime.audio}
-\declaremodule{standard}{email.mime.image}
-\declaremodule{standard}{email.mime.message}
-\declaremodule{standard}{email.mime.text}
-Ordinarily, you get a message object structure by passing a file or
-some text to a parser, which parses the text and returns the root
-message object. However you can also build a complete message
-structure from scratch, or even individual \class{Message} objects by
-hand. In fact, you can also take an existing structure and add new
-\class{Message} objects, move them around, etc. This makes a very
-convenient interface for slicing-and-dicing MIME messages.
-
-You can create a new object structure by creating \class{Message} instances,
-adding attachments and all the appropriate headers manually. For MIME
-messages though, the \module{email} package provides some convenient
-subclasses to make things easier.
-
-Here are the classes:
-
-\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
-Module: \module{email.mime.base}
-
-This is the base class for all the MIME-specific subclasses of
-\class{Message}. Ordinarily you won't create instances specifically
-of \class{MIMEBase}, although you could. \class{MIMEBase} is provided
-primarily as a convenient base class for more specific MIME-aware
-subclasses.
-
-\var{_maintype} is the \mailheader{Content-Type} major type
-(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
-\mailheader{Content-Type} minor type
-(e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter
-key/value dictionary and is passed directly to
-\method{Message.add_header()}.
-
-The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
-(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a
-\mailheader{MIME-Version} header (always set to \code{1.0}).
-\end{classdesc}
-
-\begin{classdesc}{MIMENonMultipart}{}
-Module: \module{email.mime.nonmultipart}
-
-A subclass of \class{MIMEBase}, this is an intermediate base class for
-MIME messages that are not \mimetype{multipart}. The primary purpose
-of this class is to prevent the use of the \method{attach()} method,
-which only makes sense for \mimetype{multipart} messages. If
-\method{attach()} is called, a \exception{MultipartConversionError}
-exception is raised.
-
-\versionadded{2.2.2}
-\end{classdesc}
-
-\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
- boundary\optional{, _subparts\optional{, _params}}}}}
-Module: \module{email.mime.multipart}
-
-A subclass of \class{MIMEBase}, this is an intermediate base class for
-MIME messages that are \mimetype{multipart}. Optional \var{_subtype}
-defaults to \mimetype{mixed}, but can be used to specify the subtype
-of the message. A \mailheader{Content-Type} header of
-\mimetype{multipart/}\var{_subtype} will be added to the message
-object. A \mailheader{MIME-Version} header will also be added.
-
-Optional \var{boundary} is the multipart boundary string. When
-\code{None} (the default), the boundary is calculated when needed.
-
-\var{_subparts} is a sequence of initial subparts for the payload. It
-must be possible to convert this sequence to a list. You can always
-attach new subparts to the message by using the
-\method{Message.attach()} method.
-
-Additional parameters for the \mailheader{Content-Type} header are
-taken from the keyword arguments, or passed into the \var{_params}
-argument, which is a keyword dictionary.
-
-\versionadded{2.2.2}
-\end{classdesc}
-
-\begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{,
- _encoder\optional{, **_params}}}}
-Module: \module{email.mime.application}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class is
-used to represent MIME message objects of major type \mimetype{application}.
-\var{_data} is a string containing the raw byte data. Optional \var{_subtype}
-specifies the MIME subtype and defaults to \mimetype{octet-stream}.
-
-Optional \var{_encoder} is a callable (i.e. function) which will
-perform the actual encoding of the data for transport. This
-callable takes one argument, which is the \class{MIMEApplication} instance.
-It should use \method{get_payload()} and \method{set_payload()} to
-change the payload to encoded form. It should also add any
-\mailheader{Content-Transfer-Encoding} or other headers to the message
-object as necessary. The default encoding is base64. See the
-\refmodule{email.encoders} module for a list of the built-in encoders.
-
-\var{_params} are passed straight through to the base class constructor.
-\versionadded{2.5}
-\end{classdesc}
-
-\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
- _encoder\optional{, **_params}}}}
-Module: \module{email.mime.audio}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
-is used to create MIME message objects of major type \mimetype{audio}.
-\var{_audiodata} is a string containing the raw audio data. If this
-data can be decoded by the standard Python module \refmodule{sndhdr},
-then the subtype will be automatically included in the
-\mailheader{Content-Type} header. Otherwise you can explicitly specify the
-audio subtype via the \var{_subtype} parameter. If the minor type could
-not be guessed and \var{_subtype} was not given, then \exception{TypeError}
-is raised.
-
-Optional \var{_encoder} is a callable (i.e. function) which will
-perform the actual encoding of the audio data for transport. This
-callable takes one argument, which is the \class{MIMEAudio} instance.
-It should use \method{get_payload()} and \method{set_payload()} to
-change the payload to encoded form. It should also add any
-\mailheader{Content-Transfer-Encoding} or other headers to the message
-object as necessary. The default encoding is base64. See the
-\refmodule{email.encoders} module for a list of the built-in encoders.
-
-\var{_params} are passed straight through to the base class constructor.
-\end{classdesc}
-
-\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
- _encoder\optional{, **_params}}}}
-Module: \module{email.mime.image}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
-used to create MIME message objects of major type \mimetype{image}.
-\var{_imagedata} is a string containing the raw image data. If this
-data can be decoded by the standard Python module \refmodule{imghdr},
-then the subtype will be automatically included in the
-\mailheader{Content-Type} header. Otherwise you can explicitly specify the
-image subtype via the \var{_subtype} parameter. If the minor type could
-not be guessed and \var{_subtype} was not given, then \exception{TypeError}
-is raised.
-
-Optional \var{_encoder} is a callable (i.e. function) which will
-perform the actual encoding of the image data for transport. This
-callable takes one argument, which is the \class{MIMEImage} instance.
-It should use \method{get_payload()} and \method{set_payload()} to
-change the payload to encoded form. It should also add any
-\mailheader{Content-Transfer-Encoding} or other headers to the message
-object as necessary. The default encoding is base64. See the
-\refmodule{email.encoders} module for a list of the built-in encoders.
-
-\var{_params} are passed straight through to the \class{MIMEBase}
-constructor.
-\end{classdesc}
-
-\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
-Module: \module{email.mime.message}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class
-is used to create MIME objects of main type \mimetype{message}.
-\var{_msg} is used as the payload, and must be an instance of class
-\class{Message} (or a subclass thereof), otherwise a
-\exception{TypeError} is raised.
-
-Optional \var{_subtype} sets the subtype of the message; it defaults
-to \mimetype{rfc822}.
-\end{classdesc}
-
-\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}}
-Module: \module{email.mime.text}
-
-A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
-used to create MIME objects of major type \mimetype{text}.
-\var{_text} is the string for the payload. \var{_subtype} is the
-minor type and defaults to \mimetype{plain}. \var{_charset} is the
-character set of the text and is passed as a parameter to the
-\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No
-guessing or encoding is performed on the text data.
-
-\versionchanged[The previously deprecated \var{_encoding} argument has
-been removed. Encoding happens implicitly based on the \var{_charset}
-argument]{2.4}
-\end{classdesc}
diff --git a/Doc/lib/emailparser.tex b/Doc/lib/emailparser.tex
deleted file mode 100644
index 609fa40..0000000
--- a/Doc/lib/emailparser.tex
+++ /dev/null
@@ -1,208 +0,0 @@
-\declaremodule{standard}{email.parser}
-\modulesynopsis{Parse flat text email messages to produce a message
- object structure.}
-
-Message object structures can be created in one of two ways: they can be
-created from whole cloth by instantiating \class{Message} objects and
-stringing them together via \method{attach()} and
-\method{set_payload()} calls, or they can be created by parsing a flat text
-representation of the email message.
-
-The \module{email} package provides a standard parser that understands
-most email document structures, including MIME documents. You can
-pass the parser a string or a file object, and the parser will return
-to you the root \class{Message} instance of the object structure. For
-simple, non-MIME messages the payload of this root object will likely
-be a string containing the text of the message. For MIME
-messages, the root object will return \code{True} from its
-\method{is_multipart()} method, and the subparts can be accessed via
-the \method{get_payload()} and \method{walk()} methods.
-
-There are actually two parser interfaces available for use, the classic
-\class{Parser} API and the incremental \class{FeedParser} API. The classic
-\class{Parser} API is fine if you have the entire text of the message in
-memory as a string, or if the entire message lives in a file on the file
-system. \class{FeedParser} is more appropriate for when you're reading the
-message from a stream which might block waiting for more input (e.g. reading
-an email message from a socket). The \class{FeedParser} can consume and parse
-the message incrementally, and only returns the root object when you close the
-parser\footnote{As of email package version 3.0, introduced in
-Python 2.4, the classic \class{Parser} was re-implemented in terms of the
-\class{FeedParser}, so the semantics and results are identical between the two
-parsers.}.
-
-Note that the parser can be extended in limited ways, and of course
-you can implement your own parser completely from scratch. There is
-no magical connection between the \module{email} package's bundled
-parser and the \class{Message} class, so your custom parser can create
-message object trees any way it finds necessary.
-
-\subsubsection{FeedParser API}
-
-\versionadded{2.4}
-
-The \class{FeedParser}, imported from the \module{email.feedparser} module,
-provides an API that is conducive to incremental parsing of email messages,
-such as would be necessary when reading the text of an email message from a
-source that can block (e.g. a socket). The
-\class{FeedParser} can of course be used to parse an email message fully
-contained in a string or a file, but the classic \class{Parser} API may be
-more convenient for such use cases. The semantics and results of the two
-parser APIs are identical.
-
-The \class{FeedParser}'s API is simple; you create an instance, feed it a
-bunch of text until there's no more to feed it, then close the parser to
-retrieve the root message object. The \class{FeedParser} is extremely
-accurate when parsing standards-compliant messages, and it does a very good
-job of parsing non-compliant messages, providing information about how a
-message was deemed broken. It will populate a message object's \var{defects}
-attribute with a list of any problems it found in a message. See the
-\refmodule{email.errors} module for the list of defects that it can find.
-
-Here is the API for the \class{FeedParser}:
-
-\begin{classdesc}{FeedParser}{\optional{_factory}}
-Create a \class{FeedParser} instance. Optional \var{_factory} is a
-no-argument callable that will be called whenever a new message object is
-needed. It defaults to the \class{email.message.Message} class.
-\end{classdesc}
-
-\begin{methoddesc}[FeedParser]{feed}{data}
-Feed the \class{FeedParser} some more data. \var{data} should be a
-string containing one or more lines. The lines can be partial and the
-\class{FeedParser} will stitch such partial lines together properly. The
-lines in the string can have any of the common three line endings, carriage
-return, newline, or carriage return and newline (they can even be mixed).
-\end{methoddesc}
-
-\begin{methoddesc}[FeedParser]{close}{}
-Closing a \class{FeedParser} completes the parsing of all previously fed data,
-and returns the root message object. It is undefined what happens if you feed
-more data to a closed \class{FeedParser}.
-\end{methoddesc}
-
-\subsubsection{Parser class API}
-
-The \class{Parser} class, imported from the \module{email.parser} module,
-provides an API that can be used to parse a message when the complete contents
-of the message are available in a string or file. The
-\module{email.parser} module also provides a second class, called
-\class{HeaderParser} which can be used if you're only interested in
-the headers of the message. \class{HeaderParser} can be much faster in
-these situations, since it does not attempt to parse the message body,
-instead setting the payload to the raw body as a string.
-\class{HeaderParser} has the same API as the \class{Parser} class.
-
-\begin{classdesc}{Parser}{\optional{_class}}
-The constructor for the \class{Parser} class takes an optional
-argument \var{_class}. This must be a callable factory (such as a
-function or a class), and it is used whenever a sub-message object
-needs to be created. It defaults to \class{Message} (see
-\refmodule{email.message}). The factory will be called without
-arguments.
-
-The optional \var{strict} flag is ignored. \deprecated{2.4}{Because the
-\class{Parser} class is a backward compatible API wrapper around the
-new-in-Python 2.4 \class{FeedParser}, \emph{all} parsing is effectively
-non-strict. You should simply stop passing a \var{strict} flag to the
-\class{Parser} constructor.}
-
-\versionchanged[The \var{strict} flag was added]{2.2.2}
-\versionchanged[The \var{strict} flag was deprecated]{2.4}
-\end{classdesc}
-
-The other public \class{Parser} methods are:
-
-\begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}}
-Read all the data from the file-like object \var{fp}, parse the
-resulting text, and return the root message object. \var{fp} must
-support both the \method{readline()} and the \method{read()} methods
-on file-like objects.
-
-The text contained in \var{fp} must be formatted as a block of \rfc{2822}
-style headers and header continuation lines, optionally preceded by a
-envelope header. The header block is terminated either by the
-end of the data or by a blank line. Following the header block is the
-body of the message (which may contain MIME-encoded subparts).
-
-Optional \var{headersonly} is as with the \method{parse()} method.
-
-\versionchanged[The \var{headersonly} flag was added]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}}
-Similar to the \method{parse()} method, except it takes a string
-object instead of a file-like object. Calling this method on a string
-is exactly equivalent to wrapping \var{text} in a \class{StringIO}
-instance first and calling \method{parse()}.
-
-Optional \var{headersonly} is a flag specifying whether to stop
-parsing after reading the headers or not. The default is \code{False},
-meaning it parses the entire contents of the file.
-
-\versionchanged[The \var{headersonly} flag was added]{2.2.2}
-\end{methoddesc}
-
-Since creating a message object structure from a string or a file
-object is such a common task, two functions are provided as a
-convenience. They are available in the top-level \module{email}
-package namespace.
-
-\begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}}
-Return a message object structure from a string. This is exactly
-equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} and
-\var{strict} are interpreted as with the \class{Parser} class constructor.
-
-\versionchanged[The \var{strict} flag was added]{2.2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}}
-Return a message object structure tree from an open file object. This
-is exactly equivalent to \code{Parser().parse(fp)}. Optional
-\var{_class} and \var{strict} are interpreted as with the
-\class{Parser} class constructor.
-
-\versionchanged[The \var{strict} flag was added]{2.2.2}
-\end{funcdesc}
-
-Here's an example of how you might use this at an interactive Python
-prompt:
-
-\begin{verbatim}
->>> import email
->>> msg = email.message_from_string(myString)
-\end{verbatim}
-
-\subsubsection{Additional notes}
-
-Here are some notes on the parsing semantics:
-
-\begin{itemize}
-\item Most non-\mimetype{multipart} type messages are parsed as a single
- message object with a string payload. These objects will return
- \code{False} for \method{is_multipart()}. Their
- \method{get_payload()} method will return a string object.
-
-\item All \mimetype{multipart} type messages will be parsed as a
- container message object with a list of sub-message objects for
- their payload. The outer container message will return
- \code{True} for \method{is_multipart()} and their
- \method{get_payload()} method will return the list of
- \class{Message} subparts.
-
-\item Most messages with a content type of \mimetype{message/*}
- (e.g. \mimetype{message/delivery-status} and
- \mimetype{message/rfc822}) will also be parsed as container
- object containing a list payload of length 1. Their
- \method{is_multipart()} method will return \code{True}. The
- single element in the list payload will be a sub-message object.
-
-\item Some non-standards compliant messages may not be internally consistent
- about their \mimetype{multipart}-edness. Such messages may have a
- \mailheader{Content-Type} header of type \mimetype{multipart}, but their
- \method{is_multipart()} method may return \code{False}. If such
- messages were parsed with the \class{FeedParser}, they will have an
- instance of the \class{MultipartInvariantViolationDefect} class in their
- \var{defects} attribute list. See \refmodule{email.errors} for
- details.
-\end{itemize}
diff --git a/Doc/lib/emailutil.tex b/Doc/lib/emailutil.tex
deleted file mode 100644
index f9fe2d4..0000000
--- a/Doc/lib/emailutil.tex
+++ /dev/null
@@ -1,157 +0,0 @@
-\declaremodule{standard}{email.utils}
-\modulesynopsis{Miscellaneous email package utilities.}
-
-There are several useful utilities provided in the \module{email.utils}
-module:
-
-\begin{funcdesc}{quote}{str}
-Return a new string with backslashes in \var{str} replaced by two
-backslashes, and double quotes replaced by backslash-double quote.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote}{str}
-Return a new string which is an \emph{unquoted} version of \var{str}.
-If \var{str} ends and begins with double quotes, they are stripped
-off. Likewise if \var{str} ends and begins with angle brackets, they
-are stripped off.
-\end{funcdesc}
-
-\begin{funcdesc}{parseaddr}{address}
-Parse address -- which should be the value of some address-containing
-field such as \mailheader{To} or \mailheader{Cc} -- into its constituent
-\emph{realname} and \emph{email address} parts. Returns a tuple of that
-information, unless the parse fails, in which case a 2-tuple of
-\code{('', '')} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{formataddr}{pair}
-The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
-\code{(realname, email_address)} and returns the string value suitable
-for a \mailheader{To} or \mailheader{Cc} header. If the first element of
-\var{pair} is false, then the second element is returned unmodified.
-\end{funcdesc}
-
-\begin{funcdesc}{getaddresses}{fieldvalues}
-This method returns a list of 2-tuples of the form returned by
-\code{parseaddr()}. \var{fieldvalues} is a sequence of header field
-values as might be returned by \method{Message.get_all()}. Here's a
-simple example that gets all the recipients of a message:
-
-\begin{verbatim}
-from email.utils import getaddresses
-
-tos = msg.get_all('to', [])
-ccs = msg.get_all('cc', [])
-resent_tos = msg.get_all('resent-to', [])
-resent_ccs = msg.get_all('resent-cc', [])
-all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{parsedate}{date}
-Attempts to parse a date according to the rules in \rfc{2822}.
-however, some mailers don't follow that format as specified, so
-\function{parsedate()} tries to guess correctly in such cases.
-\var{date} is a string containing an \rfc{2822} date, such as
-\code{"Mon, 20 Nov 1995 19:12:08 -0500"}. If it succeeds in parsing
-the date, \function{parsedate()} returns a 9-tuple that can be passed
-directly to \function{time.mktime()}; otherwise \code{None} will be
-returned. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{parsedate_tz}{date}
-Performs the same function as \function{parsedate()}, but returns
-either \code{None} or a 10-tuple; the first 9 elements make up a tuple
-that can be passed directly to \function{time.mktime()}, and the tenth
-is the offset of the date's timezone from UTC (which is the official
-term for Greenwich Mean Time)\footnote{Note that the sign of the timezone
-offset is the opposite of the sign of the \code{time.timezone}
-variable for the same timezone; the latter variable follows the
-\POSIX{} standard while this module follows \rfc{2822}.}. If the input
-string has no timezone, the last element of the tuple returned is
-\code{None}. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{mktime_tz}{tuple}
-Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
-timestamp. It the timezone item in the tuple is \code{None}, assume
-local time. Minor deficiency: \function{mktime_tz()} interprets the
-first 8 elements of \var{tuple} as a local time and then compensates
-for the timezone difference. This may yield a slight error around
-changes in daylight savings time, though not worth worrying about for
-common use.
-\end{funcdesc}
-
-\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}\optional{, usegmt}}}
-Returns a date string as per \rfc{2822}, e.g.:
-
-\begin{verbatim}
-Fri, 09 Nov 2001 01:08:47 -0000
-\end{verbatim}
-
-Optional \var{timeval} if given is a floating point time value as
-accepted by \function{time.gmtime()} and \function{time.localtime()},
-otherwise the current time is used.
-
-Optional \var{localtime} is a flag that when \code{True}, interprets
-\var{timeval}, and returns a date relative to the local timezone
-instead of UTC, properly taking daylight savings time into account.
-The default is \code{False} meaning UTC is used.
-
-Optional \var{usegmt} is a flag that when \code{True}, outputs a
-date string with the timezone as an ascii string \code{GMT}, rather
-than a numeric \code{-0000}. This is needed for some protocols (such
-as HTTP). This only applies when \var{localtime} is \code{False}.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{make_msgid}{\optional{idstring}}
-Returns a string suitable for an \rfc{2822}-compliant
-\mailheader{Message-ID} header. Optional \var{idstring} if given, is
-a string used to strengthen the uniqueness of the message id.
-\end{funcdesc}
-
-\begin{funcdesc}{decode_rfc2231}{s}
-Decode the string \var{s} according to \rfc{2231}.
-\end{funcdesc}
-
-\begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}}
-Encode the string \var{s} according to \rfc{2231}. Optional
-\var{charset} and \var{language}, if given is the character set name
-and language name to use. If neither is given, \var{s} is returned
-as-is. If \var{charset} is given but \var{language} is not, the
-string is encoded using the empty string for \var{language}.
-\end{funcdesc}
-
-\begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{,
- fallback_charset}}}
-When a header parameter is encoded in \rfc{2231} format,
-\method{Message.get_param()} may return a 3-tuple containing the character
-set, language, and value. \function{collapse_rfc2231_value()} turns this into
-a unicode string. Optional \var{errors} is passed to the \var{errors}
-argument of the built-in \function{unicode()} function; it defaults to
-\code{replace}. Optional \var{fallback_charset} specifies the character set
-to use if the one in the \rfc{2231} header is not known by Python; it defaults
-to \code{us-ascii}.
-
-For convenience, if the \var{value} passed to
-\function{collapse_rfc2231_value()} is not a tuple, it should be a string and
-it is returned unquoted.
-\end{funcdesc}
-
-\begin{funcdesc}{decode_params}{params}
-Decode parameters list according to \rfc{2231}. \var{params} is a
-sequence of 2-tuples containing elements of the form
-\code{(content-type, string-value)}.
-\end{funcdesc}
-
-\versionchanged[The \function{dump_address_pair()} function has been removed;
-use \function{formataddr()} instead]{2.4}
-
-\versionchanged[The \function{decode()} function has been removed; use the
-\method{Header.decode_header()} method instead]{2.4}
-
-\versionchanged[The \function{encode()} function has been removed; use the
-\method{Header.encode()} method instead]{2.4}
diff --git a/Doc/lib/fileformats.tex b/Doc/lib/fileformats.tex
deleted file mode 100644
index 9f9c116..0000000
--- a/Doc/lib/fileformats.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-\chapter{File Formats}
-\label{fileformats}
-
-The modules described in this chapter parse various miscellaneous file
-formats that aren't markup languages or are related to e-mail.
-
-\localmoduletable
diff --git a/Doc/lib/filesys.tex b/Doc/lib/filesys.tex
deleted file mode 100644
index 0c682c8..0000000
--- a/Doc/lib/filesys.tex
+++ /dev/null
@@ -1,18 +0,0 @@
-\chapter{File and Directory Access}
-\label{filesys}
-
-The modules described in this chapter deal with disk files and
-directories. For example, there are modules for reading the
-properties of files, manipulating paths in a portable way, and
-creating temporary files. The full list of modules in this chapter is:
-
-\localmoduletable
-
-% XXX can this be included in the seealso environment? --amk
-Also see section \ref{bltin-file-objects} for a description
-of Python's built-in file objects.
-
-\begin{seealso}
- \seemodule{os}{Operating system interfaces, including functions to
- work with files at a lower level than the built-in file object.}
-\end{seealso}
diff --git a/Doc/lib/frameworks.tex b/Doc/lib/frameworks.tex
deleted file mode 100644
index ffe300e..0000000
--- a/Doc/lib/frameworks.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Program Frameworks}
-\label{frameworks}
-
-The modules described in this chapter are frameworks that will largely
-dictate the structure of your program. Currently the modules described
-here are all oriented toward writing command-line interfaces.
-
-The full list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/i18n.tex b/Doc/lib/i18n.tex
deleted file mode 100644
index 699a60c..0000000
--- a/Doc/lib/i18n.tex
+++ /dev/null
@@ -1,11 +0,0 @@
-\chapter{Internationalization}
-\label{i18n}
-
-The modules described in this chapter help you write
-software that is independent of language and locale
-by providing mechanisms for selecting a language to be used in
-program messages or by tailoring output to match local conventions.
-
-The list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/internet.tex b/Doc/lib/internet.tex
deleted file mode 100644
index 72ac4b3..0000000
--- a/Doc/lib/internet.tex
+++ /dev/null
@@ -1,13 +0,0 @@
-\chapter{Internet Protocols and Support \label{internet}}
-
-\index{WWW}
-\index{Internet}
-\index{World Wide Web}
-
-The modules described in this chapter implement Internet protocols and
-support for related technology. They are all implemented in Python.
-Most of these modules require the presence of the system-dependent
-module \refmodule{socket}\refbimodindex{socket}, which is currently
-supported on most popular platforms. Here is an overview:
-
-\localmoduletable
diff --git a/Doc/lib/ipc.tex b/Doc/lib/ipc.tex
deleted file mode 100644
index cd95056..0000000
--- a/Doc/lib/ipc.tex
+++ /dev/null
@@ -1,14 +0,0 @@
-\chapter{Interprocess Communication and Networking}
-\label{ipc}
-
-The modules described in this chapter provide mechanisms for different
-processes to communicate.
-
-Some modules only work for two processes that are on the same machine,
-e.g. \module{signal} and \module{subprocess}. Other modules support
-networking protocols that two or more processes can used to
-communicate across machines.
-
-The list of modules described in this chapter is:
-
-\localmoduletable
diff --git a/Doc/lib/language.tex b/Doc/lib/language.tex
deleted file mode 100644
index 5cdb113..0000000
--- a/Doc/lib/language.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Python Language Services
- \label{language}}
-
-Python provides a number of modules to assist in working with the
-Python language. These modules support tokenizing, parsing, syntax
-analysis, bytecode disassembly, and various other facilities.
-
-These modules include:
-
-\localmoduletable
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
deleted file mode 100644
index 445ac55..0000000
--- a/Doc/lib/lib.tex
+++ /dev/null
@@ -1,452 +0,0 @@
-\documentclass{manual}
-
-% NOTE: this file controls which chapters/sections of the library
-% manual are actually printed. It is easy to customize your manual
-% by commenting out sections that you're not interested in.
-
-\title{Python Library Reference}
-
-\input{boilerplate}
-
-\makeindex % tell \index to actually write the
- % .idx file
-\makemodindex % ... and the module index as well.
-
-
-\begin{document}
-
-\maketitle
-
-\ifhtml
-\chapter*{Front Matter\label{front}}
-\fi
-
-\input{copyright}
-
-\begin{abstract}
-
-\noindent
-Python is an extensible, interpreted, object-oriented programming
-language. It supports a wide range of applications, from simple text
-processing scripts to interactive Web browsers.
-
-While the \citetitle[../ref/ref.html]{Python Reference Manual}
-describes the exact syntax and semantics of the language, it does not
-describe the standard library that is distributed with the language,
-and which greatly enhances its immediate usability. This library
-contains built-in modules (written in C) that provide access to system
-functionality such as file I/O that would otherwise be inaccessible to
-Python programmers, as well as modules written in Python that provide
-standardized solutions for many problems that occur in everyday
-programming. Some of these modules are explicitly designed to
-encourage and enhance the portability of Python programs.
-
-This library reference manual documents Python's standard library, as
-well as many optional library modules (which may or may not be
-available, depending on whether the underlying platform supports them
-and on the configuration choices made at compile time). It also
-documents the standard types of the language and its built-in
-functions and exceptions, many of which are not or incompletely
-documented in the Reference Manual.
-
-This manual assumes basic knowledge about the Python language. For an
-informal introduction to Python, see the
-\citetitle[../tut/tut.html]{Python Tutorial}; the
-\citetitle[../ref/ref.html]{Python Reference Manual} remains the
-highest authority on syntactic and semantic questions. Finally, the
-manual entitled \citetitle[../ext/ext.html]{Extending and Embedding
-the Python Interpreter} describes how to add new extensions to Python
-and how to embed it in other applications.
-
-\end{abstract}
-
-\tableofcontents
-
- % Chapter title:
-
-\input{libintro} % Introduction
-
-
-% =============
-% BUILT-INs
-% =============
-
-\input{libobjs} % Built-in Exceptions and Functions
-\input{libfuncs}
-\input{libexcs}
-\input{libconsts}
-
-\input{libstdtypes} % Built-in types
-
-
-% =============
-% BASIC/GENERAL-PURPOSE OBJECTS
-% =============
-
-% Strings
-\input{libstrings} % String Services
-\input{libstring}
-\input{libre}
-\input{libstruct} % XXX also/better in File Formats?
-\input{libdifflib}
-\input{libstringio}
-\input{libtextwrap}
-\input{libcodecs}
-\input{libunicodedata}
-\input{libstringprep}
-\input{libfpformat}
-
-
-\input{datatypes} % Data types and structures
-\input{libdatetime}
-\input{libcalendar}
-\input{libcollections}
-\input{libheapq}
-\input{libbisect}
-\input{libarray}
-\input{libsched}
-\input{libmutex}
-\input{libqueue}
-\input{libweakref}
-\input{libuserdict}
-
-% General object services
-% XXX intro
-\input{libtypes}
-\input{libnew}
-\input{libcopy}
-\input{libpprint}
-\input{librepr}
-
-
-\input{numeric} % Numeric/Mathematical modules
-\input{libmath}
-\input{libcmath}
-\input{libdecimal}
-\input{librandom}
-
-% Functions, Functional, Generators and Iterators
-% XXX intro functional
-\input{libitertools}
-\input{libfunctools}
-\input{liboperator} % from runtime - better with itertools and functools
-
-
-% =============
-% DATA FORMATS
-% =============
-
-% Big move - include all the markup and internet formats here
-
-% MIME & email stuff
-\input{netdata} % Internet Data Handling
-\input{email}
-\input{libmailcap}
-\input{libmailbox}
-\input{libmhlib}
-\input{libmimetools}
-\input{libmimetypes}
-\input{libmultifile}
-\input{librfc822}
-
-% encoding stuff
-\input{libbase64}
-\input{libbinhex}
-\input{libbinascii}
-\input{libquopri}
-\input{libuu}
-
-\input{markup} % Structured Markup Processing Tools
-\input{libhtmlparser}
-\input{libsgmllib}
-\input{libhtmllib}
-\input{libpyexpat}
-\input{xmldom}
-\input{xmldomminidom}
-\input{xmldompulldom}
-\input{xmlsax}
-\input{xmlsaxhandler}
-\input{xmlsaxutils}
-\input{xmlsaxreader}
-\input{libetree}
-
-\input{fileformats} % Miscellaneous file formats
-\input{libcsv}
-\input{libcfgparser}
-\input{librobotparser}
-\input{libnetrc}
-\input{libxdrlib}
-
-\input{libcrypto} % Cryptographic Services
-\input{libhashlib}
-\input{libhmac}
-
-% =============
-% FILE & DATABASE STORAGE
-% =============
-
-\input{filesys} % File/directory support
-\input{libposixpath} % os.path
-\input{libfileinput}
-\input{libstat}
-\input{libstatvfs}
-\input{libfilecmp}
-\input{libtempfile}
-\input{libglob}
-\input{libfnmatch}
-\input{liblinecache}
-\input{libshutil}
-\input{libdircache}
-
-
-\input{archiving} % Data compression and archiving
-\input{libzlib}
-\input{libgzip}
-\input{libbz2}
-\input{libzipfile}
-\input{libtarfile}
-
-
-\input{persistence} % Persistent storage
-\input{libpickle}
-\input{libcopyreg} % really copy_reg % from runtime...
-\input{libshelve}
-\input{libmarshal}
-\input{libanydbm}
-\input{libwhichdb}
-\input{libdbm}
-\input{libgdbm}
-\input{libdbhash}
-\input{libbsddb}
-\input{libdumbdbm}
-\input{libsqlite3}
-
-
-% =============
-% OS
-% =============
-
-
-\input{liballos} % Generic Operating System Services
-\input{libos}
-\input{libtime}
-\input{liboptparse}
-\input{libgetopt}
-\input{liblogging}
-\input{libgetpass}
-\input{libcurses}
-\input{libascii} % curses.ascii
-\input{libcursespanel}
-\input{libplatform}
-\input{liberrno}
-\input{libctypes}
-
-\input{libsomeos} % Optional Operating System Services
-\input{libselect}
-\input{libthread}
-\input{libthreading}
-\input{libdummythread}
-\input{libdummythreading}
-\input{libmmap}
-\input{libreadline}
-\input{librlcompleter}
-
-\input{libunix} % UNIX Specific Services
-\input{libposix}
-\input{libpwd}
-\input{libspwd}
-\input{libgrp}
-\input{libcrypt}
-\input{libdl}
-\input{libtermios}
-\input{libtty}
-\input{libpty}
-\input{libfcntl}
-\input{libpipes}
-\input{libresource}
-\input{libnis}
-\input{libsyslog}
-\input{libcommands}
-
-
-% =============
-% NETWORK & COMMUNICATIONS
-% =============
-
-\input{ipc} % Interprocess communication/networking
-\input{libsubprocess}
-\input{libsocket}
-\input{libsignal}
-\input{libasyncore}
-\input{libasynchat}
-
-\input{internet} % Internet Protocols
-\input{libwebbrowser}
-\input{libcgi}
-\input{libcgitb}
-\input{libwsgiref}
-\input{liburllib}
-\input{liburllib2}
-\input{libhttplib}
-\input{libftplib}
-\input{libpoplib}
-\input{libimaplib}
-\input{libnntplib}
-\input{libsmtplib}
-\input{libsmtpd}
-\input{libtelnetlib}
-\input{libuuid}
-\input{liburlparse}
-\input{libsocksvr}
-\input{libbasehttp}
-\input{libsimplehttp}
-\input{libcgihttp}
-\input{libcookielib}
-\input{libcookie}
-\input{libxmlrpclib}
-\input{libsimplexmlrpc}
-\input{libdocxmlrpc}
-
-% =============
-% MULTIMEDIA
-% =============
-
-\input{libmm} % Multimedia Services
-\input{libaudioop}
-\input{libaifc}
-\input{libsunau}
-\input{libwave}
-\input{libchunk}
-\input{libcolorsys}
-\input{libimghdr}
-\input{libsndhdr}
-\input{libossaudiodev}
-
-% Tkinter is a chapter in its own right.
-\input{tkinter}
-
-% % Internationalization
-\input{i18n}
-\input{libgettext}
-\input{liblocale}
-
-% =============
-% PROGRAM FRAMEWORKS
-% =============
-\input{frameworks}
-\input{libcmd}
-\input{libshlex}
-
-
-% =============
-% DEVELOPMENT TOOLS
-% =============
-% % Software development support
-\input{development}
-\input{libpydoc}
-\input{libdoctest}
-\input{libunittest}
-\input{libtest}
-
-\input{libpdb} % The Python Debugger
-
-\input{libprofile} % The Python Profiler
-\input{libhotshot} % unmaintained C profiler
-\input{libtimeit}
-\input{libtrace}
-
-% =============
-% PYTHON ENGINE
-% =============
-
-% Runtime services
-\input{libpython} % Python Runtime Services
-\input{libsys}
-\input{libbltin} % really __builtin__
-\input{libmain} % really __main__
-\input{libwarnings}
-\input{libcontextlib}
-\input{libatexit}
-\input{libtraceback}
-\input{libfuture} % really __future__
-\input{libgc}
-\input{libinspect}
-\input{libsite}
-\input{libuser}
-\input{libfpectl}
-
-
-\input{custominterp} % Custom interpreter
-\input{libcode}
-\input{libcodeop}
-
-
-\input{modules} % Importing Modules
-\input{libimp}
-\input{libzipimport}
-\input{libpkgutil}
-\input{libmodulefinder}
-\input{librunpy}
-
-
-% =============
-% PYTHON LANGUAGE & COMPILER
-% =============
-
-\input{language} % Python Language Services
-\input{libparser}
-\input{libsymbol}
-\input{libtoken}
-\input{libkeyword}
-\input{libtokenize}
-\input{libtabnanny}
-\input{libpyclbr}
-\input{libpycompile} % really py_compile
-\input{libcompileall}
-\input{libdis}
-\input{libpickletools}
-\input{distutils}
-
-\input{libast}
-
-\input{libmisc} % Miscellaneous Services
-\input{libformatter}
-
-% =============
-% OTHER PLATFORM-SPECIFIC STUFF
-% =============
-
-\input{windows} % MS Windows ONLY
-\input{libmsilib}
-\input{libmsvcrt}
-\input{libwinreg}
-\input{libwinsound}
-
-\appendix
-\input{libundoc}
-
-%\chapter{Obsolete Modules}
-
-\chapter{Reporting Bugs}
-\input{reportingbugs}
-
-\chapter{History and License}
-\input{license}
-
-%
-% The ugly "%begin{latexonly}" pseudo-environments are really just to
-% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
-% not really valuable.
-%
-
-%begin{latexonly}
-\renewcommand{\indexname}{Module Index}
-%end{latexonly}
-\input{modlib.ind} % Module Index
-
-%begin{latexonly}
-\renewcommand{\indexname}{Index}
-%end{latexonly}
-\input{lib.ind} % Index
-
-\end{document}
diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex
deleted file mode 100644
index 65abe84..0000000
--- a/Doc/lib/libaifc.tex
+++ /dev/null
@@ -1,202 +0,0 @@
-\section{\module{aifc} ---
- Read and write AIFF and AIFC files}
-
-\declaremodule{standard}{aifc}
-\modulesynopsis{Read and write audio files in AIFF or AIFC format.}
-
-
-This module provides support for reading and writing AIFF and AIFF-C
-files. AIFF is Audio Interchange File Format, a format for storing
-digital audio samples in a file. AIFF-C is a newer version of the
-format that includes the ability to compress the audio data.
-\index{Audio Interchange File Format}
-\index{AIFF}
-\index{AIFF-C}
-
-\strong{Caveat:} Some operations may only work under IRIX; these will
-raise \exception{ImportError} when attempting to import the
-\module{cl} module, which is only available on IRIX.
-
-Audio files have a number of parameters that describe the audio data.
-The sampling rate or frame rate is the number of times per second the
-sound is sampled. The number of channels indicate if the audio is
-mono, stereo, or quadro. Each frame consists of one sample per
-channel. The sample size is the size in bytes of each sample. Thus a
-frame consists of \var{nchannels}*\var{samplesize} bytes, and a
-second's worth of audio consists of
-\var{nchannels}*\var{samplesize}*\var{framerate} bytes.
-
-For example, CD quality audio has a sample size of two bytes (16
-bits), uses two channels (stereo) and has a frame rate of 44,100
-frames/second. This gives a frame size of 4 bytes (2*2), and a
-second's worth occupies 2*2*44100 bytes (176,400 bytes).
-
-Module \module{aifc} defines the following function:
-
-\begin{funcdesc}{open}{file\optional{, mode}}
-Open an AIFF or AIFF-C file and return an object instance with
-methods that are described below. The argument \var{file} is either a
-string naming a file or a file object. \var{mode} must be \code{'r'}
-or \code{'rb'} when the file must be opened for reading, or \code{'w'}
-or \code{'wb'} when the file must be opened for writing. If omitted,
-\code{\var{file}.mode} is used if it exists, otherwise \code{'rb'} is
-used. When used for writing, the file object should be seekable,
-unless you know ahead of time how many samples you are going to write
-in total and use \method{writeframesraw()} and \method{setnframes()}.
-\end{funcdesc}
-
-Objects returned by \function{open()} when a file is opened for
-reading have the following methods:
-
-\begin{methoddesc}[aifc]{getnchannels}{}
-Return the number of audio channels (1 for mono, 2 for stereo).
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getsampwidth}{}
-Return the size in bytes of individual samples.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getframerate}{}
-Return the sampling rate (number of audio frames per second).
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getnframes}{}
-Return the number of audio frames in the file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getcomptype}{}
-Return a four-character string describing the type of compression used
-in the audio file. For AIFF files, the returned value is
-\code{'NONE'}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getcompname}{}
-Return a human-readable description of the type of compression used in
-the audio file. For AIFF files, the returned value is \code{'not
-compressed'}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getparams}{}
-Return a tuple consisting of all of the above values in the above
-order.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getmarkers}{}
-Return a list of markers in the audio file. A marker consists of a
-tuple of three elements. The first is the mark ID (an integer), the
-second is the mark position in frames from the beginning of the data
-(an integer), the third is the name of the mark (a string).
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{getmark}{id}
-Return the tuple as described in \method{getmarkers()} for the mark
-with the given \var{id}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{readframes}{nframes}
-Read and return the next \var{nframes} frames from the audio file. The
-returned data is a string containing for each frame the uncompressed
-samples of all channels.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{rewind}{}
-Rewind the read pointer. The next \method{readframes()} will start from
-the beginning.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setpos}{pos}
-Seek to the specified frame number.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{tell}{}
-Return the current frame number.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{close}{}
-Close the AIFF file. After calling this method, the object can no
-longer be used.
-\end{methoddesc}
-
-Objects returned by \function{open()} when a file is opened for
-writing have all the above methods, except for \method{readframes()} and
-\method{setpos()}. In addition the following methods exist. The
-\method{get*()} methods can only be called after the corresponding
-\method{set*()} methods have been called. Before the first
-\method{writeframes()} or \method{writeframesraw()}, all parameters
-except for the number of frames must be filled in.
-
-\begin{methoddesc}[aifc]{aiff}{}
-Create an AIFF file. The default is that an AIFF-C file is created,
-unless the name of the file ends in \code{'.aiff'} in which case the
-default is an AIFF file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{aifc}{}
-Create an AIFF-C file. The default is that an AIFF-C file is created,
-unless the name of the file ends in \code{'.aiff'} in which case the
-default is an AIFF file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setnchannels}{nchannels}
-Specify the number of channels in the audio file.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setsampwidth}{width}
-Specify the size in bytes of audio samples.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setframerate}{rate}
-Specify the sampling frequency in frames per second.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setnframes}{nframes}
-Specify the number of frames that are to be written to the audio file.
-If this parameter is not set, or not set correctly, the file needs to
-support seeking.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setcomptype}{type, name}
-Specify the compression type. If not specified, the audio data will
-not be compressed. In AIFF files, compression is not possible. The
-name parameter should be a human-readable description of the
-compression type, the type parameter should be a four-character
-string. Currently the following compression types are supported:
-NONE, ULAW, ALAW, G722.
-\index{u-LAW}
-\index{A-LAW}
-\index{G.722}
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
-Set all the above parameters at once. The argument is a tuple
-consisting of the various parameters. This means that it is possible
-to use the result of a \method{getparams()} call as argument to
-\method{setparams()}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{setmark}{id, pos, name}
-Add a mark with the given id (larger than 0), and the given name at
-the given position. This method can be called at any time before
-\method{close()}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{tell}{}
-Return the current write position in the output file. Useful in
-combination with \method{setmark()}.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{writeframes}{data}
-Write data to the output file. This method can only be called after
-the audio file parameters have been set.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{writeframesraw}{data}
-Like \method{writeframes()}, except that the header of the audio file
-is not updated.
-\end{methoddesc}
-
-\begin{methoddesc}[aifc]{close}{}
-Close the AIFF file. The header of the file is updated to reflect the
-actual size of the audio data. After calling this method, the object
-can no longer be used.
-\end{methoddesc}
diff --git a/Doc/lib/liballos.tex b/Doc/lib/liballos.tex
deleted file mode 100644
index dd046c9..0000000
--- a/Doc/lib/liballos.tex
+++ /dev/null
@@ -1,9 +0,0 @@
-\chapter{Generic Operating System Services \label{allos}}
-
-The modules described in this chapter provide interfaces to operating
-system features that are available on (almost) all operating systems,
-such as files and a clock. The interfaces are generally modeled
-after the \UNIX{} or C interfaces, but they are available on most
-other systems as well. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libanydbm.tex b/Doc/lib/libanydbm.tex
deleted file mode 100644
index badc6ec..0000000
--- a/Doc/lib/libanydbm.tex
+++ /dev/null
@@ -1,85 +0,0 @@
-\section{\module{anydbm} ---
- Generic access to DBM-style databases}
-
-\declaremodule{standard}{anydbm}
-\modulesynopsis{Generic interface to DBM-style database modules.}
-
-
-\module{anydbm} is a generic interface to variants of the DBM
-database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires
-\refmodule{bsddb}\refbimodindex{bsddb}),
-\refmodule{gdbm}\refbimodindex{gdbm}, or
-\refmodule{dbm}\refbimodindex{dbm}. If none of these modules is
-installed, the slow-but-simple implementation in module
-\refmodule{dumbdbm}\refstmodindex{dumbdbm} will be used.
-
-\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
-Open the database file \var{filename} and return a corresponding object.
-
-If the database file already exists, the \refmodule{whichdb} module is
-used to determine its type and the appropriate module is used; if it
-does not exist, the first module listed above that can be imported is
-used.
-
-The optional \var{flag} argument can be
-\code{'r'} to open an existing database for reading only,
-\code{'w'} to open an existing database for reading and writing,
-\code{'c'} to create the database if it doesn't exist, or
-\code{'n'}, which will always create a new empty database. If not
-specified, the default value is \code{'r'}.
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666} (and will be modified by the prevailing umask).
-\end{funcdesc}
-
-\begin{excdesc}{error}
-A tuple containing the exceptions that can be raised by each of the
-supported modules, with a unique exception \exception{anydbm.error} as
-the first item --- the latter is used when \exception{anydbm.error} is
-raised.
-\end{excdesc}
-
-The object returned by \function{open()} supports most of the same
-functionality as dictionaries; keys and their corresponding values can
-be stored, retrieved, and deleted, and the \method{has_key()} and
-\method{keys()} methods are available. Keys and values must always be
-strings.
-
-The following example records some hostnames and a corresponding title,
-and then prints out the contents of the database:
-
-\begin{verbatim}
-import anydbm
-
-# Open database, creating it if necessary.
-db = anydbm.open('cache', 'c')
-
-# Record some values
-db['www.python.org'] = 'Python Website'
-db['www.cnn.com'] = 'Cable News Network'
-
-# Loop through contents. Other dictionary methods
-# such as .keys(), .values() also work.
-for k, v in db.iteritems():
- print k, '\t', v
-
-# Storing a non-string key or value will raise an exception (most
-# likely a TypeError).
-db['www.yahoo.com'] = 4
-
-# Close when done.
-db.close()
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule{dbhash}{BSD \code{db} database interface.}
- \seemodule{dbm}{Standard \UNIX{} database interface.}
- \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
- \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
- \seemodule{shelve}{General object persistence built on top of
- the Python \code{dbm} interface.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
deleted file mode 100644
index eaf5888..0000000
--- a/Doc/lib/libarray.tex
+++ /dev/null
@@ -1,241 +0,0 @@
-\section{\module{array} ---
- Efficient arrays of numeric values}
-
-\declaremodule{builtin}{array}
-\modulesynopsis{Efficient arrays of uniformly typed numeric values.}
-
-
-This module defines an object type which can efficiently represent
-an array of basic values: characters, integers, floating point
-numbers. Arrays\index{arrays} are sequence types and behave very much
-like lists, except that the type of objects stored in them is
-constrained. The type is specified at object creation time by using a
-\dfn{type code}, which is a single character. The following type
-codes are defined:
-
-\begin{tableiv}{c|l|l|c}{code}{Type code}{C Type}{Python Type}{Minimum size in bytes}
- \lineiv{'c'}{char} {character} {1}
- \lineiv{'b'}{signed char} {int} {1}
- \lineiv{'B'}{unsigned char} {int} {1}
- \lineiv{'u'}{Py_UNICODE} {Unicode character}{2}
- \lineiv{'h'}{signed short} {int} {2}
- \lineiv{'H'}{unsigned short}{int} {2}
- \lineiv{'i'}{signed int} {int} {2}
- \lineiv{'I'}{unsigned int} {long} {2}
- \lineiv{'l'}{signed long} {int} {4}
- \lineiv{'L'}{unsigned long} {long} {4}
- \lineiv{'f'}{float} {float} {4}
- \lineiv{'d'}{double} {float} {8}
-\end{tableiv}
-
-The actual representation of values is determined by the machine
-architecture (strictly speaking, by the C implementation). The actual
-size can be accessed through the \member{itemsize} attribute. The values
-stored for \code{'L'} and \code{'I'} items will be represented as
-Python long integers when retrieved, because Python's plain integer
-type cannot represent the full range of C's unsigned (long) integers.
-
-
-The module defines the following type:
-
-\begin{funcdesc}{array}{typecode\optional{, initializer}}
-Return a new array whose items are restricted by \var{typecode},
-and initialized from the optional \var{initializer} value, which
-must be a list, string, or iterable over elements of the
-appropriate type.
-\versionchanged[Formerly, only lists or strings were accepted]{2.4}
-If given a list or string, the initializer is passed to the
-new array's \method{fromlist()}, \method{fromstring()}, or
-\method{fromunicode()} method (see below) to add initial items to
-the array. Otherwise, the iterable initializer is passed to the
-\method{extend()} method.
-\end{funcdesc}
-
-\begin{datadesc}{ArrayType}
-Obsolete alias for \function{array}.
-\end{datadesc}
-
-
-Array objects support the ordinary sequence operations of
-indexing, slicing, concatenation, and multiplication. When using
-slice assignment, the assigned value must be an array object with the
-same type code; in all other cases, \exception{TypeError} is raised.
-Array objects also implement the buffer interface, and may be used
-wherever buffer objects are supported.
-
-The following data items and methods are also supported:
-
-\begin{memberdesc}[array]{typecode}
-The typecode character used to create the array.
-\end{memberdesc}
-
-\begin{memberdesc}[array]{itemsize}
-The length in bytes of one array item in the internal representation.
-\end{memberdesc}
-
-
-\begin{methoddesc}[array]{append}{x}
-Append a new item with value \var{x} to the end of the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{buffer_info}{}
-Return a tuple \code{(\var{address}, \var{length})} giving the current
-memory address and the length in elements of the buffer used to hold
-array's contents. The size of the memory buffer in bytes can be
-computed as \code{\var{array}.buffer_info()[1] *
-\var{array}.itemsize}. This is occasionally useful when working with
-low-level (and inherently unsafe) I/O interfaces that require memory
-addresses, such as certain \cfunction{ioctl()} operations. The
-returned numbers are valid as long as the array exists and no
-length-changing operations are applied to it.
-
-\note{When using array objects from code written in C or
-\Cpp{} (the only way to effectively make use of this information), it
-makes more sense to use the buffer interface supported by array
-objects. This method is maintained for backward compatibility and
-should be avoided in new code. The buffer interface is documented in
-the \citetitle[../api/newTypes.html]{Python/C API Reference Manual}.}
-\end{methoddesc}
-
-\begin{methoddesc}[array]{byteswap}{}
-``Byteswap'' all items of the array. This is only supported for
-values which are 1, 2, 4, or 8 bytes in size; for other types of
-values, \exception{RuntimeError} is raised. It is useful when reading
-data from a file written on a machine with a different byte order.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{count}{x}
-Return the number of occurrences of \var{x} in the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{extend}{iterable}
-Append items from \var{iterable} to the end of the array. If
-\var{iterable} is another array, it must have \emph{exactly} the same
-type code; if not, \exception{TypeError} will be raised. If
-\var{iterable} is not an array, it must be iterable and its
-elements must be the right type to be appended to the array.
-\versionchanged[Formerly, the argument could only be another array]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromfile}{f, n}
-Read \var{n} items (as machine values) from the file object \var{f}
-and append them to the end of the array. If less than \var{n} items
-are available, \exception{EOFError} is raised, but the items that were
-available are still inserted into the array. \var{f} must be a real
-built-in file object; something else with a \method{read()} method won't
-do.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromlist}{list}
-Append items from the list. This is equivalent to
-\samp{for x in \var{list}:\ a.append(x)}
-except that if there is a type error, the array is unchanged.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromstring}{s}
-Appends items from the string, interpreting the string as an
-array of machine values (as if it had been read from a
-file using the \method{fromfile()} method).
-\end{methoddesc}
-
-\begin{methoddesc}[array]{fromunicode}{s}
-Extends this array with data from the given unicode string. The array
-must be a type \code{'u'} array; otherwise a \exception{ValueError}
-is raised. Use \samp{array.fromstring(ustr.decode(enc))} to
-append Unicode data to an array of some other type.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{index}{x}
-Return the smallest \var{i} such that \var{i} is the index of
-the first occurrence of \var{x} in the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{insert}{i, x}
-Insert a new item with value \var{x} in the array before position
-\var{i}. Negative values are treated as being relative to the end
-of the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{pop}{\optional{i}}
-Removes the item with the index \var{i} from the array and returns
-it. The optional argument defaults to \code{-1}, so that by default
-the last item is removed and returned.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{read}{f, n}
-\deprecated {1.5.1}
- {Use the \method{fromfile()} method.}
-Read \var{n} items (as machine values) from the file object \var{f}
-and append them to the end of the array. If less than \var{n} items
-are available, \exception{EOFError} is raised, but the items that were
-available are still inserted into the array. \var{f} must be a real
-built-in file object; something else with a \method{read()} method won't
-do.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{remove}{x}
-Remove the first occurrence of \var{x} from the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{reverse}{}
-Reverse the order of the items in the array.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tofile}{f}
-Write all items (as machine values) to the file object \var{f}.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tolist}{}
-Convert the array to an ordinary list with the same items.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tostring}{}
-Convert the array to an array of machine values and return the
-string representation (the same sequence of bytes that would
-be written to a file by the \method{tofile()} method.)
-\end{methoddesc}
-
-\begin{methoddesc}[array]{tounicode}{}
-Convert the array to a unicode string. The array must be
-a type \code{'u'} array; otherwise a \exception{ValueError} is raised.
-Use \samp{array.tostring().decode(enc)} to obtain a unicode string
-from an array of some other type.
-\end{methoddesc}
-
-\begin{methoddesc}[array]{write}{f}
-\deprecated {1.5.1}
- {Use the \method{tofile()} method.}
-Write all items (as machine values) to the file object \var{f}.
-\end{methoddesc}
-
-When an array object is printed or converted to a string, it is
-represented as \code{array(\var{typecode}, \var{initializer})}. The
-\var{initializer} is omitted if the array is empty, otherwise it is a
-string if the \var{typecode} is \code{'c'}, otherwise it is a list of
-numbers. The string is guaranteed to be able to be converted back to
-an array with the same type and value using reverse quotes
-(\code{``}), so long as the \function{array()} function has been
-imported using \code{from array import array}. Examples:
-
-\begin{verbatim}
-array('l')
-array('c', 'hello world')
-array('u', u'hello \textbackslash u2641')
-array('l', [1, 2, 3, 4, 5])
-array('d', [1.0, 2.0, 3.14])
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule{struct}{Packing and unpacking of heterogeneous binary data.}
- \seemodule{xdrlib}{Packing and unpacking of External Data
- Representation (XDR) data as used in some remote
- procedure call systems.}
- \seetitle[http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm]{The
- Numerical Python Manual}{The Numeric Python extension
- (NumPy) defines another array type; see
- \url{http://numpy.sourceforge.net/} for further information
- about Numerical Python. (A PDF version of the NumPy manual
- is available at
- \url{http://numpy.sourceforge.net/numdoc/numdoc.pdf}).}
-\end{seealso}
diff --git a/Doc/lib/libascii.tex b/Doc/lib/libascii.tex
deleted file mode 100644
index 003bd95..0000000
--- a/Doc/lib/libascii.tex
+++ /dev/null
@@ -1,175 +0,0 @@
-\section{\module{curses.ascii} ---
- Utilities for ASCII characters}
-
-\declaremodule{standard}{curses.ascii}
-\modulesynopsis{Constants and set-membership functions for
- \ASCII\ characters.}
-\moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
-\sectionauthor{Eric S. Raymond}{esr@thyrsus.com}
-
-\versionadded{1.6}
-
-The \module{curses.ascii} module supplies name constants for
-\ASCII{} characters and functions to test membership in various
-\ASCII{} character classes. The constants supplied are names for
-control characters as follows:
-
-\begin{tableii}{l|l}{constant}{Name}{Meaning}
- \lineii{NUL}{}
- \lineii{SOH}{Start of heading, console interrupt}
- \lineii{STX}{Start of text}
- \lineii{ETX}{End of text}
- \lineii{EOT}{End of transmission}
- \lineii{ENQ}{Enquiry, goes with \constant{ACK} flow control}
- \lineii{ACK}{Acknowledgement}
- \lineii{BEL}{Bell}
- \lineii{BS}{Backspace}
- \lineii{TAB}{Tab}
- \lineii{HT}{Alias for \constant{TAB}: ``Horizontal tab''}
- \lineii{LF}{Line feed}
- \lineii{NL}{Alias for \constant{LF}: ``New line''}
- \lineii{VT}{Vertical tab}
- \lineii{FF}{Form feed}
- \lineii{CR}{Carriage return}
- \lineii{SO}{Shift-out, begin alternate character set}
- \lineii{SI}{Shift-in, resume default character set}
- \lineii{DLE}{Data-link escape}
- \lineii{DC1}{XON, for flow control}
- \lineii{DC2}{Device control 2, block-mode flow control}
- \lineii{DC3}{XOFF, for flow control}
- \lineii{DC4}{Device control 4}
- \lineii{NAK}{Negative acknowledgement}
- \lineii{SYN}{Synchronous idle}
- \lineii{ETB}{End transmission block}
- \lineii{CAN}{Cancel}
- \lineii{EM}{End of medium}
- \lineii{SUB}{Substitute}
- \lineii{ESC}{Escape}
- \lineii{FS}{File separator}
- \lineii{GS}{Group separator}
- \lineii{RS}{Record separator, block-mode terminator}
- \lineii{US}{Unit separator}
- \lineii{SP}{Space}
- \lineii{DEL}{Delete}
-\end{tableii}
-
-Note that many of these have little practical significance in modern
-usage. The mnemonics derive from teleprinter conventions that predate
-digital computers.
-
-The module supplies the following functions, patterned on those in the
-standard C library:
-
-
-\begin{funcdesc}{isalnum}{c}
-Checks for an \ASCII{} alphanumeric character; it is equivalent to
-\samp{isalpha(\var{c}) or isdigit(\var{c})}.
-\end{funcdesc}
-
-\begin{funcdesc}{isalpha}{c}
-Checks for an \ASCII{} alphabetic character; it is equivalent to
-\samp{isupper(\var{c}) or islower(\var{c})}.
-\end{funcdesc}
-
-\begin{funcdesc}{isascii}{c}
-Checks for a character value that fits in the 7-bit \ASCII{} set.
-\end{funcdesc}
-
-\begin{funcdesc}{isblank}{c}
-Checks for an \ASCII{} whitespace character.
-\end{funcdesc}
-
-\begin{funcdesc}{iscntrl}{c}
-Checks for an \ASCII{} control character (in the range 0x00 to 0x1f).
-\end{funcdesc}
-
-\begin{funcdesc}{isdigit}{c}
-Checks for an \ASCII{} decimal digit, \character{0} through
-\character{9}. This is equivalent to \samp{\var{c} in string.digits}.
-\end{funcdesc}
-
-\begin{funcdesc}{isgraph}{c}
-Checks for \ASCII{} any printable character except space.
-\end{funcdesc}
-
-\begin{funcdesc}{islower}{c}
-Checks for an \ASCII{} lower-case character.
-\end{funcdesc}
-
-\begin{funcdesc}{isprint}{c}
-Checks for any \ASCII{} printable character including space.
-\end{funcdesc}
-
-\begin{funcdesc}{ispunct}{c}
-Checks for any printable \ASCII{} character which is not a space or an
-alphanumeric character.
-\end{funcdesc}
-
-\begin{funcdesc}{isspace}{c}
-Checks for \ASCII{} white-space characters; space, line feed,
-carriage return, form feed, horizontal tab, vertical tab.
-\end{funcdesc}
-
-\begin{funcdesc}{isupper}{c}
-Checks for an \ASCII{} uppercase letter.
-\end{funcdesc}
-
-\begin{funcdesc}{isxdigit}{c}
-Checks for an \ASCII{} hexadecimal digit. This is equivalent to
-\samp{\var{c} in string.hexdigits}.
-\end{funcdesc}
-
-\begin{funcdesc}{isctrl}{c}
-Checks for an \ASCII{} control character (ordinal values 0 to 31).
-\end{funcdesc}
-
-\begin{funcdesc}{ismeta}{c}
-Checks for a non-\ASCII{} character (ordinal values 0x80 and above).
-\end{funcdesc}
-
-These functions accept either integers or strings; when the argument
-is a string, it is first converted using the built-in function
-\function{ord()}.
-
-Note that all these functions check ordinal bit values derived from the
-first character of the string you pass in; they do not actually know
-anything about the host machine's character encoding. For functions
-that know about the character encoding (and handle
-internationalization properly) see the \refmodule{string} module.
-
-The following two functions take either a single-character string or
-integer byte value; they return a value of the same type.
-
-\begin{funcdesc}{ascii}{c}
-Return the ASCII value corresponding to the low 7 bits of \var{c}.
-\end{funcdesc}
-
-\begin{funcdesc}{ctrl}{c}
-Return the control character corresponding to the given character
-(the character bit value is bitwise-anded with 0x1f).
-\end{funcdesc}
-
-\begin{funcdesc}{alt}{c}
-Return the 8-bit character corresponding to the given ASCII character
-(the character bit value is bitwise-ored with 0x80).
-\end{funcdesc}
-
-The following function takes either a single-character string or
-integer value; it returns a string.
-
-\begin{funcdesc}{unctrl}{c}
-Return a string representation of the \ASCII{} character \var{c}. If
-\var{c} is printable, this string is the character itself. If the
-character is a control character (0x00-0x1f) the string consists of a
-caret (\character{\^}) followed by the corresponding uppercase letter.
-If the character is an \ASCII{} delete (0x7f) the string is
-\code{'\^{}?'}. If the character has its meta bit (0x80) set, the meta
-bit is stripped, the preceding rules applied, and
-\character{!} prepended to the result.
-\end{funcdesc}
-
-\begin{datadesc}{controlnames}
-A 33-element string array that contains the \ASCII{} mnemonics for the
-thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f (US), in
-order, plus the mnemonic \samp{SP} for the space character.
-\end{datadesc}
diff --git a/Doc/lib/libast.tex b/Doc/lib/libast.tex
deleted file mode 100644
index b2956ae..0000000
--- a/Doc/lib/libast.tex
+++ /dev/null
@@ -1,57 +0,0 @@
-% XXX Label can't be _ast?
-% XXX Where should this section/chapter go?
-\chapter{Abstract Syntax Trees\label{ast}}
-
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.5}
-
-The \code{_ast} module helps Python applications to process
-trees of the Python abstract syntax grammar. The Python compiler
-currently provides read-only access to such trees, meaning that
-applications can only create a tree for a given piece of Python
-source code; generating byte code from a (potentially modified)
-tree is not supported. The abstract syntax itself might change with
-each Python release; this module helps to find out programmatically
-what the current grammar looks like.
-
-An abstract syntax tree can be generated by passing \code{_ast.PyCF_ONLY_AST}
-as a flag to the \function{compile} builtin function. The result will be a tree
-of objects whose classes all inherit from \code{_ast.AST}.
-
-The actual classes are derived from the \code{Parser/Python.asdl} file,
-which is reproduced below. There is one class defined for each left-hand
-side symbol in the abstract grammar (for example, \code{_ast.stmt} or \code{_ast.expr}).
-In addition, there is one class defined for each constructor on the
-right-hand side; these classes inherit from the classes for the left-hand
-side trees. For example, \code{_ast.BinOp} inherits from \code{_ast.expr}.
-For production rules with alternatives (aka "sums"), the left-hand side
-class is abstract: only instances of specific constructor nodes are ever
-created.
-
-Each concrete class has an attribute \code{_fields} which gives the
-names of all child nodes.
-
-Each instance of a concrete class has one attribute for each child node,
-of the type as defined in the grammar. For example, \code{_ast.BinOp}
-instances have an attribute \code{left} of type \code{_ast.expr}.
-Instances of \code{_ast.expr} and \code{_ast.stmt} subclasses also
-have lineno and col_offset attributes. The lineno is the line number
-of source text (1 indexed so the first line is line 1) and the
-col_offset is the utf8 byte offset of the first token that generated
-the node. The utf8 offset is recorded because the parser uses utf8
-internally.
-
-If these attributes are marked as optional in the grammar (using a
-question mark), the value might be \code{None}. If the attributes
-can have zero-or-more values (marked with an asterisk), the
-values are represented as Python lists.
-
-\section{Abstract Grammar}
-
-The module defines a string constant \code{__version__} which
-is the decimal subversion revision number of the file shown below.
-
-The abstract grammar is currently defined as follows:
-
-\verbatiminput{../../Parser/Python.asdl}
diff --git a/Doc/lib/libasynchat.tex b/Doc/lib/libasynchat.tex
deleted file mode 100644
index 223bfed7..0000000
--- a/Doc/lib/libasynchat.tex
+++ /dev/null
@@ -1,254 +0,0 @@
-\section{\module{asynchat} ---
- Asynchronous socket command/response handler}
-
-\declaremodule{standard}{asynchat}
-\modulesynopsis{Support for asynchronous command/response protocols.}
-\moduleauthor{Sam Rushing}{rushing@nightmare.com}
-\sectionauthor{Steve Holden}{sholden@holdenweb.com}
-
-This module builds on the \refmodule{asyncore} infrastructure,
-simplifying asynchronous clients and servers and making it easier to
-handle protocols whose elements are terminated by arbitrary strings, or
-are of variable length. \refmodule{asynchat} defines the abstract class
-\class{async_chat} that you subclass, providing implementations of the
-\method{collect_incoming_data()} and \method{found_terminator()}
-methods. It uses the same asynchronous loop as \refmodule{asyncore}, and
-the two types of channel, \class{asyncore.dispatcher} and
-\class{asynchat.async_chat}, can freely be mixed in the channel map.
-Typically an \class{asyncore.dispatcher} server channel generates new
-\class{asynchat.async_chat} channel objects as it receives incoming
-connection requests.
-
-\begin{classdesc}{async_chat}{}
- This class is an abstract subclass of \class{asyncore.dispatcher}. To make
- practical use of the code you must subclass \class{async_chat}, providing
- meaningful \method{collect_incoming_data()} and \method{found_terminator()}
- methods. The \class{asyncore.dispatcher} methods can be
- used, although not all make sense in a message/response context.
-
- Like \class{asyncore.dispatcher}, \class{async_chat} defines a set of events
- that are generated by an analysis of socket conditions after a
- \cfunction{select()} call. Once the polling loop has been started the
- \class{async_chat} object's methods are called by the event-processing
- framework with no action on the part of the programmer.
-
- Unlike \class{asyncore.dispatcher}, \class{async_chat} allows you to define
- a first-in-first-out queue (fifo) of \emph{producers}. A producer need have
- only one method, \method{more()}, which should return data to be transmitted
- on the channel. The producer indicates exhaustion (\emph{i.e.} that it contains
- no more data) by having its \method{more()} method return the empty string. At
- this point the \class{async_chat} object removes the producer from the fifo
- and starts using the next producer, if any. When the producer fifo is empty
- the \method{handle_write()} method does nothing. You use the channel object's
- \method{set_terminator()} method to describe how to recognize the end
- of, or an important breakpoint in, an incoming transmission from the
- remote endpoint.
-
- To build a functioning \class{async_chat} subclass your
- input methods \method{collect_incoming_data()} and
- \method{found_terminator()} must handle the data that the channel receives
- asynchronously. The methods are described below.
-\end{classdesc}
-
-\begin{methoddesc}{close_when_done}{}
- Pushes a \code{None} on to the producer fifo. When this producer is
- popped off the fifo it causes the channel to be closed.
-\end{methoddesc}
-
-\begin{methoddesc}{collect_incoming_data}{data}
- Called with \var{data} holding an arbitrary amount of received data.
- The default method, which must be overridden, raises a \exception{NotImplementedError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}{discard_buffers}{}
- In emergencies this method will discard any data held in the input and/or
- output buffers and the producer fifo.
-\end{methoddesc}
-
-\begin{methoddesc}{found_terminator}{}
- Called when the incoming data stream matches the termination condition
- set by \method{set_terminator}. The default method, which must be overridden,
- raises a \exception{NotImplementedError} exception. The buffered input data should
- be available via an instance attribute.
-\end{methoddesc}
-
-\begin{methoddesc}{get_terminator}{}
- Returns the current terminator for the channel.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_close}{}
- Called when the channel is closed. The default method silently closes
- the channel's socket.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_read}{}
- Called when a read event fires on the channel's socket in the
- asynchronous loop. The default method checks for the termination
- condition established by \method{set_terminator()}, which can be either
- the appearance of a particular string in the input stream or the receipt
- of a particular number of characters. When the terminator is found,
- \method{handle_read} calls the \method{found_terminator()} method after
- calling \method{collect_incoming_data()} with any data preceding the
- terminating condition.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_write}{}
- Called when the application may write data to the channel.
- The default method calls the \method{initiate_send()} method, which in turn
- will call \method{refill_buffer()} to collect data from the producer
- fifo associated with the channel.
-\end{methoddesc}
-
-\begin{methoddesc}{push}{data}
- Creates a \class{simple_producer} object (\emph{see below}) containing the data and
- pushes it on to the channel's \code{producer_fifo} to ensure its
- transmission. This is all you need to do to have the channel write
- the data out to the network, although it is possible to use your
- own producers in more complex schemes to implement encryption and
- chunking, for example.
-\end{methoddesc}
-
-\begin{methoddesc}{push_with_producer}{producer}
- Takes a producer object and adds it to the producer fifo associated with
- the channel. When all currently-pushed producers have been exhausted
- the channel will consume this producer's data by calling its
- \method{more()} method and send the data to the remote endpoint.
-\end{methoddesc}
-
-\begin{methoddesc}{readable}{}
- Should return \code{True} for the channel to be included in the set of
- channels tested by the \cfunction{select()} loop for readability.
-\end{methoddesc}
-
-\begin{methoddesc}{refill_buffer}{}
- Refills the output buffer by calling the \method{more()} method of the
- producer at the head of the fifo. If it is exhausted then the
- producer is popped off the fifo and the next producer is activated.
- If the current producer is, or becomes, \code{None} then the channel
- is closed.
-\end{methoddesc}
-
-\begin{methoddesc}{set_terminator}{term}
- Sets the terminating condition to be recognised on the channel. \code{term}
- may be any of three types of value, corresponding to three different ways
- to handle incoming protocol data.
-
- \begin{tableii}{l|l}{}{term}{Description}
- \lineii{\emph{string}}{Will call \method{found_terminator()} when the
- string is found in the input stream}
- \lineii{\emph{integer}}{Will call \method{found_terminator()} when the
- indicated number of characters have been received}
- \lineii{\code{None}}{The channel continues to collect data forever}
- \end{tableii}
-
- Note that any data following the terminator will be available for reading by
- the channel after \method{found_terminator()} is called.
-\end{methoddesc}
-
-\begin{methoddesc}{writable}{}
- Should return \code{True} as long as items remain on the producer fifo,
- or the channel is connected and the channel's output buffer is non-empty.
-\end{methoddesc}
-
-\subsection{asynchat - Auxiliary Classes and Functions}
-
-\begin{classdesc}{simple_producer}{data\optional{, buffer_size=512}}
- A \class{simple_producer} takes a chunk of data and an optional buffer size.
- Repeated calls to its \method{more()} method yield successive chunks of the
- data no larger than \var{buffer_size}.
-\end{classdesc}
-
-\begin{methoddesc}{more}{}
- Produces the next chunk of information from the producer, or returns the empty string.
-\end{methoddesc}
-
-\begin{classdesc}{fifo}{\optional{list=None}}
- Each channel maintains a \class{fifo} holding data which has been pushed by the
- application but not yet popped for writing to the channel.
- A \class{fifo} is a list used to hold data and/or producers until they are required.
- If the \var{list} argument is provided then it should contain producers or
- data items to be written to the channel.
-\end{classdesc}
-
-\begin{methoddesc}{is_empty}{}
- Returns \code{True} iff the fifo is empty.
-\end{methoddesc}
-
-\begin{methoddesc}{first}{}
- Returns the least-recently \method{push()}ed item from the fifo.
-\end{methoddesc}
-
-\begin{methoddesc}{push}{data}
- Adds the given data (which may be a string or a producer object) to the
- producer fifo.
-\end{methoddesc}
-
-\begin{methoddesc}{pop}{}
- If the fifo is not empty, returns \code{True, first()}, deleting the popped
- item. Returns \code{False, None} for an empty fifo.
-\end{methoddesc}
-
-The \module{asynchat} module also defines one utility function, which may be
-of use in network and textual analysis operations.
-
-\begin{funcdesc}{find_prefix_at_end}{haystack, needle}
- Returns \code{True} if string \var{haystack} ends with any non-empty
- prefix of string \var{needle}.
-\end{funcdesc}
-
-\subsection{asynchat Example \label{asynchat-example}}
-
-The following partial example shows how HTTP requests can be read with
-\class{async_chat}. A web server might create an \class{http_request_handler} object for
-each incoming client connection. Notice that initially the
-channel terminator is set to match the blank line at the end of the HTTP
-headers, and a flag indicates that the headers are being read.
-
-Once the headers have been read, if the request is of type POST
-(indicating that further data are present in the input stream) then the
-\code{Content-Length:} header is used to set a numeric terminator to
-read the right amount of data from the channel.
-
-The \method{handle_request()} method is called once all relevant input
-has been marshalled, after setting the channel terminator to \code{None}
-to ensure that any extraneous data sent by the web client are ignored.
-
-\begin{verbatim}
-class http_request_handler(asynchat.async_chat):
-
- def __init__(self, conn, addr, sessions, log):
- asynchat.async_chat.__init__(self, conn=conn)
- self.addr = addr
- self.sessions = sessions
- self.ibuffer = []
- self.obuffer = ""
- self.set_terminator("\r\n\r\n")
- self.reading_headers = True
- self.handling = False
- self.cgi_data = None
- self.log = log
-
- def collect_incoming_data(self, data):
- """Buffer the data"""
- self.ibuffer.append(data)
-
- def found_terminator(self):
- if self.reading_headers:
- self.reading_headers = False
- self.parse_headers("".join(self.ibuffer))
- self.ibuffer = []
- if self.op.upper() == "POST":
- clen = self.headers.getheader("content-length")
- self.set_terminator(int(clen))
- else:
- self.handling = True
- self.set_terminator(None)
- self.handle_request()
- elif not self.handling:
- self.set_terminator(None) # browsers sometimes over-send
- self.cgi_data = parse(self.headers, "".join(self.ibuffer))
- self.handling = True
- self.ibuffer = []
- self.handle_request()
-\end{verbatim}
-
diff --git a/Doc/lib/libasyncore.tex b/Doc/lib/libasyncore.tex
deleted file mode 100644
index 0552896..0000000
--- a/Doc/lib/libasyncore.tex
+++ /dev/null
@@ -1,260 +0,0 @@
-\section{\module{asyncore} ---
- Asynchronous socket handler}
-
-\declaremodule{builtin}{asyncore}
-\modulesynopsis{A base class for developing asynchronous socket
- handling services.}
-\moduleauthor{Sam Rushing}{rushing@nightmare.com}
-\sectionauthor{Christopher Petrilli}{petrilli@amber.org}
-\sectionauthor{Steve Holden}{sholden@holdenweb.com}
-% Heavily adapted from original documentation by Sam Rushing.
-
-This module provides the basic infrastructure for writing asynchronous
-socket service clients and servers.
-
-There are only two ways to have a program on a single processor do
-``more than one thing at a time.'' Multi-threaded programming is the
-simplest and most popular way to do it, but there is another very
-different technique, that lets you have nearly all the advantages of
-multi-threading, without actually using multiple threads. It's really
-only practical if your program is largely I/O bound. If your program
-is processor bound, then pre-emptive scheduled threads are probably what
-you really need. Network servers are rarely processor bound, however.
-
-If your operating system supports the \cfunction{select()} system call
-in its I/O library (and nearly all do), then you can use it to juggle
-multiple communication channels at once; doing other work while your
-I/O is taking place in the ``background.'' Although this strategy can
-seem strange and complex, especially at first, it is in many ways
-easier to understand and control than multi-threaded programming.
-The \module{asyncore} module solves many of the difficult problems for
-you, making the task of building sophisticated high-performance
-network servers and clients a snap. For ``conversational'' applications
-and protocols the companion \refmodule{asynchat} module is invaluable.
-
-The basic idea behind both modules is to create one or more network
-\emph{channels}, instances of class \class{asyncore.dispatcher} and
-\class{asynchat.async_chat}. Creating the channels adds them to a global
-map, used by the \function{loop()} function if you do not provide it
-with your own \var{map}.
-
-Once the initial channel(s) is(are) created, calling the \function{loop()}
-function activates channel service, which continues until the last
-channel (including any that have been added to the map during asynchronous
-service) is closed.
-
-\begin{funcdesc}{loop}{\optional{timeout\optional{, use_poll\optional{,
- map\optional{,count}}}}}
- Enter a polling loop that terminates after count passes or all open
- channels have been closed. All arguments are optional. The \var{count}
- parameter defaults to None, resulting in the loop terminating only
- when all channels have been closed. The \var{timeout} argument sets the
- timeout parameter for the appropriate \function{select()} or
- \function{poll()} call, measured in seconds; the default is 30 seconds.
- The \var{use_poll} parameter, if true, indicates that \function{poll()}
- should be used in preference to \function{select()} (the default is
- \code{False}).
-
- The \var{map} parameter is a dictionary whose items are
- the channels to watch. As channels are closed they are deleted from their
- map. If \var{map} is omitted, a global map is used.
- Channels (instances of \class{asyncore.dispatcher}, \class{asynchat.async_chat}
- and subclasses thereof) can freely be mixed in the map.
-\end{funcdesc}
-
-\begin{classdesc}{dispatcher}{}
- The \class{dispatcher} class is a thin wrapper around a low-level socket object.
- To make it more useful, it has a few methods for event-handling which are called
- from the asynchronous loop.
- Otherwise, it can be treated as a normal non-blocking socket object.
-
- Two class attributes can be modified, to improve performance,
- or possibly even to conserve memory.
-
- \begin{datadesc}{ac_in_buffer_size}
- The asynchronous input buffer size (default \code{4096}).
- \end{datadesc}
-
- \begin{datadesc}{ac_out_buffer_size}
- The asynchronous output buffer size (default \code{4096}).
- \end{datadesc}
-
- The firing of low-level events at certain times or in certain connection
- states tells the asynchronous loop that certain higher-level events have
- taken place. For example, if we have asked for a socket to connect to
- another host, we know that the connection has been made when the socket
- becomes writable for the first time (at this point you know that you may
- write to it with the expectation of success). The implied higher-level
- events are:
-
- \begin{tableii}{l|l}{code}{Event}{Description}
- \lineii{handle_connect()}{Implied by the first write event}
- \lineii{handle_close()}{Implied by a read event with no data available}
- \lineii{handle_accept()}{Implied by a read event on a listening socket}
- \end{tableii}
-
- During asynchronous processing, each mapped channel's \method{readable()}
- and \method{writable()} methods are used to determine whether the channel's
- socket should be added to the list of channels \cfunction{select()}ed or
- \cfunction{poll()}ed for read and write events.
-
-\end{classdesc}
-
-Thus, the set of channel events is larger than the basic socket events.
-The full set of methods that can be overridden in your subclass follows:
-
-\begin{methoddesc}{handle_read}{}
- Called when the asynchronous loop detects that a \method{read()}
- call on the channel's socket will succeed.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_write}{}
- Called when the asynchronous loop detects that a writable socket
- can be written.
- Often this method will implement the necessary buffering for
- performance. For example:
-
-\begin{verbatim}
-def handle_write(self):
- sent = self.send(self.buffer)
- self.buffer = self.buffer[sent:]
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{handle_expt}{}
- Called when there is out of band (OOB) data for a socket
- connection. This will almost never happen, as OOB is
- tenuously supported and rarely used.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_connect}{}
- Called when the active opener's socket actually makes a connection.
- Might send a ``welcome'' banner, or initiate a protocol
- negotiation with the remote endpoint, for example.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_close}{}
- Called when the socket is closed.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_error}{}
- Called when an exception is raised and not otherwise handled. The default
- version prints a condensed traceback.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_accept}{}
- Called on listening channels (passive openers) when a
- connection can be established with a new remote endpoint that
- has issued a \method{connect()} call for the local endpoint.
-\end{methoddesc}
-
-\begin{methoddesc}{readable}{}
- Called each time around the asynchronous loop to determine whether a
- channel's socket should be added to the list on which read events can
- occur. The default method simply returns \code{True},
- indicating that by default, all channels will be interested in
- read events.
-\end{methoddesc}
-
-\begin{methoddesc}{writable}{}
- Called each time around the asynchronous loop to determine whether a
- channel's socket should be added to the list on which write events can
- occur. The default method simply returns \code{True},
- indicating that by default, all channels will be interested in
- write events.
-\end{methoddesc}
-
-In addition, each channel delegates or extends many of the socket methods.
-Most of these are nearly identical to their socket partners.
-
-\begin{methoddesc}{create_socket}{family, type}
- This is identical to the creation of a normal socket, and
- will use the same options for creation. Refer to the
- \refmodule{socket} documentation for information on creating
- sockets.
-\end{methoddesc}
-
-\begin{methoddesc}{connect}{address}
- As with the normal socket object, \var{address} is a
- tuple with the first element the host to connect to, and the
- second the port number.
-\end{methoddesc}
-
-\begin{methoddesc}{send}{data}
- Send \var{data} to the remote end-point of the socket.
-\end{methoddesc}
-
-\begin{methoddesc}{recv}{buffer_size}
- Read at most \var{buffer_size} bytes from the socket's remote end-point.
- An empty string implies that the channel has been closed from the other
- end.
-\end{methoddesc}
-
-\begin{methoddesc}{listen}{backlog}
- Listen for connections made to the socket. The \var{backlog}
- argument specifies the maximum number of queued connections
- and should be at least 1; the maximum value is
- system-dependent (usually 5).
-\end{methoddesc}
-
-\begin{methoddesc}{bind}{address}
- Bind the socket to \var{address}. The socket must not already be
- bound. (The format of \var{address} depends on the address family
- --- see above.) To mark the socket as re-usable (setting the
- \constant{SO_REUSEADDR} option), call the \class{dispatcher}
- object's \method{set_reuse_addr()} method.
-\end{methoddesc}
-
-\begin{methoddesc}{accept}{}
- Accept a connection. The socket must be bound to an address
- and listening for connections. The return value is a pair
- \code{(\var{conn}, \var{address})} where \var{conn} is a
- \emph{new} socket object usable to send and receive data on
- the connection, and \var{address} is the address bound to the
- socket on the other end of the connection.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
- Close the socket. All future operations on the socket object
- will fail. The remote end-point will receive no more data (after
- queued data is flushed). Sockets are automatically closed
- when they are garbage-collected.
-\end{methoddesc}
-
-
-\subsection{asyncore Example basic HTTP client \label{asyncore-example}}
-
-Here is a very basic HTTP client that uses the \class{dispatcher}
-class to implement its socket handling:
-
-\begin{verbatim}
-import asyncore, socket
-
-class http_client(asyncore.dispatcher):
-
- def __init__(self, host, path):
- asyncore.dispatcher.__init__(self)
- self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
- self.connect( (host, 80) )
- self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
-
- def handle_connect(self):
- pass
-
- def handle_close(self):
- self.close()
-
- def handle_read(self):
- print self.recv(8192)
-
- def writable(self):
- return (len(self.buffer) > 0)
-
- def handle_write(self):
- sent = self.send(self.buffer)
- self.buffer = self.buffer[sent:]
-
-c = http_client('www.python.org', '/')
-
-asyncore.loop()
-\end{verbatim}
diff --git a/Doc/lib/libatexit.tex b/Doc/lib/libatexit.tex
deleted file mode 100644
index 04f1d49..0000000
--- a/Doc/lib/libatexit.tex
+++ /dev/null
@@ -1,108 +0,0 @@
-\section{\module{atexit} ---
- Exit handlers}
-
-\declaremodule{builtin}{atexit}
-\moduleauthor{Skip Montanaro}{skip@mojam.com}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-\modulesynopsis{Register and execute cleanup functions.}
-
-\versionadded{2.0}
-
-
-The \module{atexit} module defines functions to register and
-unregister cleanup functions. Functions thus registered are
-automatically executed upon normal interpreter termination.
-
-Note: the functions registered via this module are not called when
-the program is killed by a signal, when a Python fatal internal
-error is detected, or when \function{os._exit()} is called.
-
-\begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}}
-Register \var{func} as a function to be executed at termination. Any
-optional arguments that are to be passed to \var{func} must be passed
-as arguments to \function{register()}.
-
-At normal program termination (for instance, if
-\function{sys.exit()} is called or the main module's execution
-completes), all functions registered are called in last in, first out
-order. The assumption is that lower level modules will normally be
-imported before higher level modules and thus must be cleaned up
-later.
-
-If an exception is raised during execution of the exit handlers, a
-traceback is printed (unless \exception{SystemExit} is raised) and the
-exception information is saved. After all exit handlers have had a
-chance to run the last exception to be raised is re-raised.
-
-\versionchanged[This function now returns \var{func} which makes it
- possible to use it as a decorator without binding the
- original name to \code{None}]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{unregister}{func}
-Remove a function \var{func} from the list of functions to be run at
-interpreter-shutdown. After calling \function{unregister()},
-\var{func} is guaranteed not to be called when the interpreter
-shuts down.
-
-\versionadded{3.0}
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{readline}{Useful example of \module{atexit} to read and
- write \refmodule{readline} history files.}
-\end{seealso}
-
-
-\subsection{\module{atexit} Example \label{atexit-example}}
-
-The following simple example demonstrates how a module can initialize
-a counter from a file when it is imported and save the counter's
-updated value automatically when the program terminates without
-relying on the application making an explicit call into this module at
-termination.
-
-\begin{verbatim}
-try:
- _count = int(open("/tmp/counter").read())
-except IOError:
- _count = 0
-
-def incrcounter(n):
- global _count
- _count = _count + n
-
-def savecounter():
- open("/tmp/counter", "w").write("%d" % _count)
-
-import atexit
-atexit.register(savecounter)
-\end{verbatim}
-
-Positional and keyword arguments may also be passed to
-\function{register()} to be passed along to the registered function
-when it is called:
-
-\begin{verbatim}
-def goodbye(name, adjective):
- print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
-
-import atexit
-atexit.register(goodbye, 'Donny', 'nice')
-
-# or:
-atexit.register(goodbye, adjective='nice', name='Donny')
-\end{verbatim}
-
-Usage as a decorator:
-
-\begin{verbatim}
-import atexit
-
-@atexit.register
-def goodbye():
- print "You are now leaving the Python sector."
-\end{verbatim}
-
-This obviously only works with functions that don't take arguments.
diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex
deleted file mode 100644
index e827e76..0000000
--- a/Doc/lib/libaudioop.tex
+++ /dev/null
@@ -1,258 +0,0 @@
-\section{\module{audioop} ---
- Manipulate raw audio data}
-
-\declaremodule{builtin}{audioop}
-\modulesynopsis{Manipulate raw audio data.}
-
-
-The \module{audioop} module contains some useful operations on sound
-fragments. It operates on sound fragments consisting of signed
-integer samples 8, 16 or 32 bits wide, stored in Python strings.
-All scalar items are integers, unless specified otherwise.
-
-% This para is mostly here to provide an excuse for the index entries...
-This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
-\index{Intel/DVI ADPCM}
-\index{ADPCM, Intel/DVI}
-\index{a-LAW}
-\index{u-LAW}
-
-A few of the more complicated operations only take 16-bit samples,
-otherwise the sample size (in bytes) is always a parameter of the
-operation.
-
-The module defines the following variables and functions:
-
-\begin{excdesc}{error}
-This exception is raised on all errors, such as unknown number of bytes
-per sample, etc.
-\end{excdesc}
-
-\begin{funcdesc}{add}{fragment1, fragment2, width}
-Return a fragment which is the addition of the two samples passed as
-parameters. \var{width} is the sample width in bytes, either
-\code{1}, \code{2} or \code{4}. Both fragments should have the same
-length.
-\end{funcdesc}
-
-\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
-Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
-the description of \function{lin2adpcm()} for details on ADPCM coding.
-Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
-has the width specified in \var{width}.
-\end{funcdesc}
-
-\begin{funcdesc}{alaw2lin}{fragment, width}
-Convert sound fragments in a-LAW encoding to linearly encoded sound
-fragments. a-LAW encoding always uses 8 bits samples, so \var{width}
-refers only to the sample width of the output fragment here.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{avg}{fragment, width}
-Return the average over all samples in the fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{avgpp}{fragment, width}
-Return the average peak-peak value over all samples in the fragment.
-No filtering is done, so the usefulness of this routine is
-questionable.
-\end{funcdesc}
-
-\begin{funcdesc}{bias}{fragment, width, bias}
-Return a fragment that is the original fragment with a bias added to
-each sample.
-\end{funcdesc}
-
-\begin{funcdesc}{cross}{fragment, width}
-Return the number of zero crossings in the fragment passed as an
-argument.
-\end{funcdesc}
-
-\begin{funcdesc}{findfactor}{fragment, reference}
-Return a factor \var{F} such that
-\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
-minimal, i.e., return the factor with which you should multiply
-\var{reference} to make it match as well as possible to
-\var{fragment}. The fragments should both contain 2-byte samples.
-
-The time taken by this routine is proportional to
-\code{len(\var{fragment})}.
-\end{funcdesc}
-
-\begin{funcdesc}{findfit}{fragment, reference}
-Try to match \var{reference} as well as possible to a portion of
-\var{fragment} (which should be the longer fragment). This is
-(conceptually) done by taking slices out of \var{fragment}, using
-\function{findfactor()} to compute the best match, and minimizing the
-result. The fragments should both contain 2-byte samples. Return a
-tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
-(integer) offset into \var{fragment} where the optimal match started
-and \var{factor} is the (floating-point) factor as per
-\function{findfactor()}.
-\end{funcdesc}
-
-\begin{funcdesc}{findmax}{fragment, length}
-Search \var{fragment} for a slice of length \var{length} samples (not
-bytes!)\ with maximum energy, i.e., return \var{i} for which
-\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
-should both contain 2-byte samples.
-
-The routine takes time proportional to \code{len(\var{fragment})}.
-\end{funcdesc}
-
-\begin{funcdesc}{getsample}{fragment, width, index}
-Return the value of sample \var{index} from the fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{lin2adpcm}{fragment, width, state}
-Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an
-adaptive coding scheme, whereby each 4 bit number is the difference
-between one sample and the next, divided by a (varying) step. The
-Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
-may well become a standard.
-
-\var{state} is a tuple containing the state of the coder. The coder
-returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
-\var{newstate} should be passed to the next call of
-\function{lin2adpcm()}. In the initial call, \code{None} can be
-passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
-packed 2 4-bit values per byte.
-\end{funcdesc}
-
-\begin{funcdesc}{lin2alaw}{fragment, width}
-Convert samples in the audio fragment to a-LAW encoding and return
-this as a Python string. a-LAW is an audio encoding format whereby
-you get a dynamic range of about 13 bits using only 8 bit samples. It
-is used by the Sun audio hardware, among others.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{lin2lin}{fragment, width, newwidth}
-Convert samples between 1-, 2- and 4-byte formats.
-\end{funcdesc}
-
-\begin{funcdesc}{lin2ulaw}{fragment, width}
-Convert samples in the audio fragment to u-LAW encoding and return
-this as a Python string. u-LAW is an audio encoding format whereby
-you get a dynamic range of about 14 bits using only 8 bit samples. It
-is used by the Sun audio hardware, among others.
-\end{funcdesc}
-
-\begin{funcdesc}{minmax}{fragment, width}
-Return a tuple consisting of the minimum and maximum values of all
-samples in the sound fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{max}{fragment, width}
-Return the maximum of the \emph{absolute value} of all samples in a
-fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{maxpp}{fragment, width}
-Return the maximum peak-peak value in the sound fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{mul}{fragment, width, factor}
-Return a fragment that has all samples in the original fragment
-multiplied by the floating-point value \var{factor}. Overflow is
-silently ignored.
-\end{funcdesc}
-
-\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
- state\optional{, weightA\optional{, weightB}}}
-Convert the frame rate of the input fragment.
-
-\var{state} is a tuple containing the state of the converter. The
-converter returns a tuple \code{(\var{newfragment}, \var{newstate})},
-and \var{newstate} should be passed to the next call of
-\function{ratecv()}. The initial call should pass \code{None}
-as the state.
-
-The \var{weightA} and \var{weightB} arguments are parameters for a
-simple digital filter and default to \code{1} and \code{0} respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{reverse}{fragment, width}
-Reverse the samples in a fragment and returns the modified fragment.
-\end{funcdesc}
-
-\begin{funcdesc}{rms}{fragment, width}
-Return the root-mean-square of the fragment, i.e.
-\begin{displaymath}
-\catcode`_=8
-\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
-\end{displaymath}
-This is a measure of the power in an audio signal.
-\end{funcdesc}
-
-\begin{funcdesc}{tomono}{fragment, width, lfactor, rfactor}
-Convert a stereo fragment to a mono fragment. The left channel is
-multiplied by \var{lfactor} and the right channel by \var{rfactor}
-before adding the two channels to give a mono signal.
-\end{funcdesc}
-
-\begin{funcdesc}{tostereo}{fragment, width, lfactor, rfactor}
-Generate a stereo fragment from a mono fragment. Each pair of samples
-in the stereo fragment are computed from the mono sample, whereby left
-channel samples are multiplied by \var{lfactor} and right channel
-samples by \var{rfactor}.
-\end{funcdesc}
-
-\begin{funcdesc}{ulaw2lin}{fragment, width}
-Convert sound fragments in u-LAW encoding to linearly encoded sound
-fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
-refers only to the sample width of the output fragment here.
-\end{funcdesc}
-
-Note that operations such as \function{mul()} or \function{max()} make
-no distinction between mono and stereo fragments, i.e.\ all samples
-are treated equal. If this is a problem the stereo fragment should be
-split into two mono fragments first and recombined later. Here is an
-example of how to do that:
-
-\begin{verbatim}
-def mul_stereo(sample, width, lfactor, rfactor):
- lsample = audioop.tomono(sample, width, 1, 0)
- rsample = audioop.tomono(sample, width, 0, 1)
- lsample = audioop.mul(sample, width, lfactor)
- rsample = audioop.mul(sample, width, rfactor)
- lsample = audioop.tostereo(lsample, width, 1, 0)
- rsample = audioop.tostereo(rsample, width, 0, 1)
- return audioop.add(lsample, rsample, width)
-\end{verbatim}
-
-If you use the ADPCM coder to build network packets and you want your
-protocol to be stateless (i.e.\ to be able to tolerate packet loss)
-you should not only transmit the data but also the state. Note that
-you should send the \var{initial} state (the one you passed to
-\function{lin2adpcm()}) along to the decoder, not the final state (as
-returned by the coder). If you want to use \function{struct.struct()}
-to store the state in binary you can code the first element (the
-predicted value) in 16 bits and the second (the delta index) in 8.
-
-The ADPCM coders have never been tried against other ADPCM coders,
-only against themselves. It could well be that I misinterpreted the
-standards in which case they will not be interoperable with the
-respective standards.
-
-The \function{find*()} routines might look a bit funny at first sight.
-They are primarily meant to do echo cancellation. A reasonably
-fast way to do this is to pick the most energetic piece of the output
-sample, locate that in the input sample and subtract the whole output
-sample from the input sample:
-
-\begin{verbatim}
-def echocancel(outputdata, inputdata):
- pos = audioop.findmax(outputdata, 800) # one tenth second
- out_test = outputdata[pos*2:]
- in_test = inputdata[pos*2:]
- ipos, factor = audioop.findfit(in_test, out_test)
- # Optional (for better cancellation):
- # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
- # out_test)
- prefill = '\0'*(pos+ipos)*2
- postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
- outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
- return audioop.add(inputdata, outputdata, 2)
-\end{verbatim}
diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex
deleted file mode 100644
index 23b74f0..0000000
--- a/Doc/lib/libbase64.tex
+++ /dev/null
@@ -1,169 +0,0 @@
-\section{\module{base64} ---
- RFC 3548: Base16, Base32, Base64 Data Encodings}
-
-\declaremodule{standard}{base64}
-\modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
-
-
-\indexii{base64}{encoding}
-\index{MIME!base64 encoding}
-
-This module provides data encoding and decoding as specified in
-\rfc{3548}. This standard defines the Base16, Base32, and Base64
-algorithms for encoding and decoding arbitrary binary strings into
-text strings that can be safely sent by email, used as parts of URLs,
-or included as part of an HTTP POST request. The encoding algorithm is
-not the same as the \program{uuencode} program.
-
-There are two interfaces provided by this module. The modern
-interface supports encoding and decoding string objects using all
-three alphabets. The legacy interface provides for encoding and
-decoding to and from file-like objects as well as strings, but only
-using the Base64 standard alphabet.
-
-The modern interface, which was introduced in Python 2.4, provides:
-
-\begin{funcdesc}{b64encode}{s\optional{, altchars}}
-Encode a string use Base64.
-
-\var{s} is the string to encode. Optional \var{altchars} must be a
-string of at least length 2 (additional characters are ignored) which
-specifies an alternative alphabet for the \code{+} and \code{/}
-characters. This allows an application to e.g. generate URL or
-filesystem safe Base64 strings. The default is \code{None}, for which
-the standard Base64 alphabet is used.
-
-The encoded string is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{b64decode}{s\optional{, altchars}}
-Decode a Base64 encoded string.
-
-\var{s} is the string to decode. Optional \var{altchars} must be a
-string of at least length 2 (additional characters are ignored) which
-specifies the alternative alphabet used instead of the \code{+} and
-\code{/} characters.
-
-The decoded string is returned. A \exception{TypeError} is raised if
-\var{s} were incorrectly padded or if there are non-alphabet
-characters present in the string.
-\end{funcdesc}
-
-\begin{funcdesc}{standard_b64encode}{s}
-Encode string \var{s} using the standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{standard_b64decode}{s}
-Decode string \var{s} using the standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{urlsafe_b64encode}{s}
-Encode string \var{s} using a URL-safe alphabet, which substitutes
-\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
-standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{urlsafe_b64decode}{s}
-Decode string \var{s} using a URL-safe alphabet, which substitutes
-\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
-standard Base64 alphabet.
-\end{funcdesc}
-
-\begin{funcdesc}{b32encode}{s}
-Encode a string using Base32. \var{s} is the string to encode. The
-encoded string is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
-Decode a Base32 encoded string.
-
-\var{s} is the string to decode. Optional \var{casefold} is a flag
-specifying whether a lowercase alphabet is acceptable as input. For
-security purposes, the default is \code{False}.
-
-\rfc{3548} allows for optional mapping of the digit 0 (zero) to the
-letter O (oh), and for optional mapping of the digit 1 (one) to either
-the letter I (eye) or letter L (el). The optional argument
-\var{map01} when not \code{None}, specifies which letter the digit 1 should
-be mapped to (when \var{map01} is not \code{None}, the digit 0 is always
-mapped to the letter O). For security purposes the default is
-\code{None}, so that 0 and 1 are not allowed in the input.
-
-The decoded string is returned. A \exception{TypeError} is raised if
-\var{s} were incorrectly padded or if there are non-alphabet characters
-present in the string.
-\end{funcdesc}
-
-\begin{funcdesc}{b16encode}{s}
-Encode a string using Base16.
-
-\var{s} is the string to encode. The encoded string is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{b16decode}{s\optional{, casefold}}
-Decode a Base16 encoded string.
-
-\var{s} is the string to decode. Optional \var{casefold} is a flag
-specifying whether a lowercase alphabet is acceptable as input. For
-security purposes, the default is \code{False}.
-
-The decoded string is returned. A \exception{TypeError} is raised if
-\var{s} were incorrectly padded or if there are non-alphabet
-characters present in the string.
-\end{funcdesc}
-
-The legacy interface:
-
-\begin{funcdesc}{decode}{input, output}
-Decode the contents of the \var{input} file and write the resulting
-binary data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.read()} returns an empty string.
-\end{funcdesc}
-
-\begin{funcdesc}{decodestring}{s}
-Decode the string \var{s}, which must contain one or more lines of
-base64 encoded data, and return a string containing the resulting
-binary data.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{input, output}
-Encode the contents of the \var{input} file and write the resulting
-base64 encoded data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.read()} returns an empty string. \function{encode()}
-returns the encoded data plus a trailing newline character
-(\code{'\e n'}).
-\end{funcdesc}
-
-\begin{funcdesc}{encodestring}{s}
-Encode the string \var{s}, which can contain arbitrary binary data,
-and return a string containing one or more lines of
-base64-encoded data. \function{encodestring()} returns a
-string containing one or more lines of base64-encoded data
-always including an extra trailing newline (\code{'\e n'}).
-\end{funcdesc}
-
-An example usage of the module:
-
-\begin{verbatim}
->>> import base64
->>> encoded = base64.b64encode('data to be encoded')
->>> encoded
-'ZGF0YSB0byBiZSBlbmNvZGVk'
->>> data = base64.b64decode(encoded)
->>> data
-'data to be encoded'
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{binascii}{Support module containing \ASCII-to-binary
- and binary-to-\ASCII{} conversions.}
- \seerfc{1521}{MIME (Multipurpose Internet Mail Extensions) Part One:
- Mechanisms for Specifying and Describing the Format of
- Internet Message Bodies}{Section 5.2, ``Base64
- Content-Transfer-Encoding,'' provides the definition of the
- base64 encoding.}
-\end{seealso}
diff --git a/Doc/lib/libbasehttp.tex b/Doc/lib/libbasehttp.tex
deleted file mode 100644
index 64c069f..0000000
--- a/Doc/lib/libbasehttp.tex
+++ /dev/null
@@ -1,245 +0,0 @@
-\section{\module{BaseHTTPServer} ---
- Basic HTTP server}
-
-\declaremodule{standard}{BaseHTTPServer}
-\modulesynopsis{Basic HTTP server (base class for
- \class{SimpleHTTPServer} and \class{CGIHTTPServer}).}
-
-
-\indexii{WWW}{server}
-\indexii{HTTP}{protocol}
-\index{URL}
-\index{httpd}
-
-This module defines two classes for implementing HTTP servers
-(Web servers). Usually, this module isn't used directly, but is used
-as a basis for building functioning Web servers. See the
-\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and
-\refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules.
-
-The first class, \class{HTTPServer}, is a
-\class{SocketServer.TCPServer} subclass. It creates and listens at the
-HTTP socket, dispatching the requests to a handler. Code to create and
-run the server looks like this:
-
-\begin{verbatim}
-def run(server_class=BaseHTTPServer.HTTPServer,
- handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
- server_address = ('', 8000)
- httpd = server_class(server_address, handler_class)
- httpd.serve_forever()
-\end{verbatim}
-
-\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
-This class builds on the \class{TCPServer} class by
-storing the server address as instance
-variables named \member{server_name} and \member{server_port}. The
-server is accessible by the handler, typically through the handler's
-\member{server} instance variable.
-\end{classdesc}
-
-\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
-This class is used
-to handle the HTTP requests that arrive at the server. By itself,
-it cannot respond to any actual HTTP requests; it must be subclassed
-to handle each request method (e.g. GET or POST).
-\class{BaseHTTPRequestHandler} provides a number of class and instance
-variables, and methods for use by subclasses.
-
-The handler will parse the request and the headers, then call a
-method specific to the request type. The method name is constructed
-from the request. For example, for the request method \samp{SPAM}, the
-\method{do_SPAM()} method will be called with no arguments. All of
-the relevant information is stored in instance variables of the
-handler. Subclasses should not need to override or extend the
-\method{__init__()} method.
-\end{classdesc}
-
-
-\class{BaseHTTPRequestHandler} has the following instance variables:
-
-\begin{memberdesc}{client_address}
-Contains a tuple of the form \code{(\var{host}, \var{port})} referring
-to the client's address.
-\end{memberdesc}
-
-\begin{memberdesc}{command}
-Contains the command (request type). For example, \code{'GET'}.
-\end{memberdesc}
-
-\begin{memberdesc}{path}
-Contains the request path.
-\end{memberdesc}
-
-\begin{memberdesc}{request_version}
-Contains the version string from the request. For example,
-\code{'HTTP/1.0'}.
-\end{memberdesc}
-
-\begin{memberdesc}{headers}
-Holds an instance of the class specified by the \member{MessageClass}
-class variable. This instance parses and manages the headers in
-the HTTP request.
-\end{memberdesc}
-
-\begin{memberdesc}{rfile}
-Contains an input stream, positioned at the start of the optional
-input data.
-\end{memberdesc}
-
-\begin{memberdesc}{wfile}
-Contains the output stream for writing a response back to the client.
-Proper adherence to the HTTP protocol must be used when writing
-to this stream.
-\end{memberdesc}
-
-
-\class{BaseHTTPRequestHandler} has the following class variables:
-
-\begin{memberdesc}{server_version}
-Specifies the server software version. You may want to override
-this.
-The format is multiple whitespace-separated strings,
-where each string is of the form name[/version].
-For example, \code{'BaseHTTP/0.2'}.
-\end{memberdesc}
-
-\begin{memberdesc}{sys_version}
-Contains the Python system version, in a form usable by the
-\member{version_string} method and the \member{server_version} class
-variable. For example, \code{'Python/1.4'}.
-\end{memberdesc}
-
-\begin{memberdesc}{error_message_format}
-Specifies a format string for building an error response to the
-client. It uses parenthesized, keyed format specifiers, so the
-format operand must be a dictionary. The \var{code} key should
-be an integer, specifying the numeric HTTP error code value.
-\var{message} should be a string containing a (detailed) error
-message of what occurred, and \var{explain} should be an
-explanation of the error code number. Default \var{message}
-and \var{explain} values can found in the \var{responses}
-class variable.
-\end{memberdesc}
-
-\begin{memberdesc}{protocol_version}
-This specifies the HTTP protocol version used in responses. If set
-to \code{'HTTP/1.1'}, the server will permit HTTP persistent
-connections; however, your server \emph{must} then include an
-accurate \code{Content-Length} header (using \method{send_header()})
-in all of its responses to clients. For backwards compatibility,
-the setting defaults to \code{'HTTP/1.0'}.
-\end{memberdesc}
-
-\begin{memberdesc}{MessageClass}
-Specifies a \class{rfc822.Message}-like class to parse HTTP
-headers. Typically, this is not overridden, and it defaults to
-\class{mimetools.Message}.
-\withsubitem{(in module mimetools)}{\ttindex{Message}}
-\end{memberdesc}
-
-\begin{memberdesc}{responses}
-This variable contains a mapping of error code integers to two-element
-tuples containing a short and long message. For example,
-\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
-\var{shortmessage} is usually used as the \var{message} key in an
-error response, and \var{longmessage} as the \var{explain} key
-(see the \member{error_message_format} class variable).
-\end{memberdesc}
-
-
-A \class{BaseHTTPRequestHandler} instance has the following methods:
-
-\begin{methoddesc}{handle}{}
-Calls \method{handle_one_request()} once (or, if persistent connections
-are enabled, multiple times) to handle incoming HTTP requests.
-You should never need to override it; instead, implement appropriate
-\method{do_*()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_one_request}{}
-This method will parse and dispatch
-the request to the appropriate \method{do_*()} method. You should
-never need to override it.
-\end{methoddesc}
-
-\begin{methoddesc}{send_error}{code\optional{, message}}
-Sends and logs a complete error reply to the client. The numeric
-\var{code} specifies the HTTP error code, with \var{message} as
-optional, more specific text. A complete set of headers is sent,
-followed by text composed using the \member{error_message_format}
-class variable.
-\end{methoddesc}
-
-\begin{methoddesc}{send_response}{code\optional{, message}}
-Sends a response header and logs the accepted request. The HTTP
-response line is sent, followed by \emph{Server} and \emph{Date}
-headers. The values for these two headers are picked up from the
-\method{version_string()} and \method{date_time_string()} methods,
-respectively.
-\end{methoddesc}
-
-\begin{methoddesc}{send_header}{keyword, value}
-Writes a specific HTTP header to the output stream. \var{keyword}
-should specify the header keyword, with \var{value} specifying
-its value.
-\end{methoddesc}
-
-\begin{methoddesc}{end_headers}{}
-Sends a blank line, indicating the end of the HTTP headers in
-the response.
-\end{methoddesc}
-
-\begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
-Logs an accepted (successful) request. \var{code} should specify
-the numeric HTTP code associated with the response. If a size of
-the response is available, then it should be passed as the
-\var{size} parameter.
-\end{methoddesc}
-
-\begin{methoddesc}{log_error}{...}
-Logs an error when a request cannot be fulfilled. By default,
-it passes the message to \method{log_message()}, so it takes the
-same arguments (\var{format} and additional values).
-\end{methoddesc}
-
-\begin{methoddesc}{log_message}{format, ...}
-Logs an arbitrary message to \code{sys.stderr}. This is typically
-overridden to create custom error logging mechanisms. The
-\var{format} argument is a standard printf-style format string,
-where the additional arguments to \method{log_message()} are applied
-as inputs to the formatting. The client address and current date
-and time are prefixed to every message logged.
-\end{methoddesc}
-
-\begin{methoddesc}{version_string}{}
-Returns the server software's version string. This is a combination
-of the \member{server_version} and \member{sys_version} class variables.
-\end{methoddesc}
-
-\begin{methoddesc}{date_time_string}{\optional{timestamp}}
-Returns the date and time given by \var{timestamp} (which must be in the
-format returned by \function{time.time()}), formatted for a message header.
-If \var{timestamp} is omitted, it uses the current date and time.
-
-The result looks like \code{'Sun, 06 Nov 1994 08:49:37 GMT'}.
-\versionadded[The \var{timestamp} parameter]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{log_date_time_string}{}
-Returns the current date and time, formatted for logging.
-\end{methoddesc}
-
-\begin{methoddesc}{address_string}{}
-Returns the client address, formatted for logging. A name lookup
-is performed on the client's IP address.
-\end{methoddesc}
-
-
-\begin{seealso}
- \seemodule{CGIHTTPServer}{Extended request handler that supports CGI
- scripts.}
-
- \seemodule{SimpleHTTPServer}{Basic request handler that limits response
- to files actually under the document root.}
-\end{seealso}
diff --git a/Doc/lib/libbinascii.tex b/Doc/lib/libbinascii.tex
deleted file mode 100644
index 84d29c6..0000000
--- a/Doc/lib/libbinascii.tex
+++ /dev/null
@@ -1,147 +0,0 @@
-\section{\module{binascii} ---
- Convert between binary and \ASCII}
-
-\declaremodule{builtin}{binascii}
-\modulesynopsis{Tools for converting between binary and various
- \ASCII-encoded binary representations.}
-
-
-The \module{binascii} module contains a number of methods to convert
-between binary and various \ASCII-encoded binary
-representations. Normally, you will not use these functions directly
-but use wrapper modules like \refmodule{uu}\refstmodindex{uu},
-\refmodule{base64}\refstmodindex{base64}, or
-\refmodule{binhex}\refstmodindex{binhex} instead. The \module{binascii} module
-contains low-level functions written in C for greater speed
-that are used by the higher-level modules.
-
-The \module{binascii} module defines the following functions:
-
-\begin{funcdesc}{a2b_uu}{string}
-Convert a single line of uuencoded data back to binary and return the
-binary data. Lines normally contain 45 (binary) bytes, except for the
-last line. Line data may be followed by whitespace.
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_uu}{data}
-Convert binary data to a line of \ASCII{} characters, the return value
-is the converted line, including a newline char. The length of
-\var{data} should be at most 45.
-\end{funcdesc}
-
-\begin{funcdesc}{a2b_base64}{string}
-Convert a block of base64 data back to binary and return the
-binary data. More than one line may be passed at a time.
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_base64}{data}
-Convert binary data to a line of \ASCII{} characters in base64 coding.
-The return value is the converted line, including a newline char.
-The length of \var{data} should be at most 57 to adhere to the base64
-standard.
-\end{funcdesc}
-
-\begin{funcdesc}{a2b_qp}{string\optional{, header}}
-Convert a block of quoted-printable data back to binary and return the
-binary data. More than one line may be passed at a time.
-If the optional argument \var{header} is present and true, underscores
-will be decoded as spaces.
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_qp}{data\optional{, quotetabs, istext, header}}
-Convert binary data to a line(s) of \ASCII{} characters in
-quoted-printable encoding. The return value is the converted line(s).
-If the optional argument \var{quotetabs} is present and true, all tabs
-and spaces will be encoded.
-If the optional argument \var{istext} is present and true,
-newlines are not encoded but trailing whitespace will be encoded.
-If the optional argument \var{header} is
-present and true, spaces will be encoded as underscores per RFC1522.
-If the optional argument \var{header} is present and false, newline
-characters will be encoded as well; otherwise linefeed conversion might
-corrupt the binary data stream.
-\end{funcdesc}
-
-\begin{funcdesc}{a2b_hqx}{string}
-Convert binhex4 formatted \ASCII{} data to binary, without doing
-RLE-decompression. The string should contain a complete number of
-binary bytes, or (in case of the last portion of the binhex4 data)
-have the remaining bits zero.
-\end{funcdesc}
-
-\begin{funcdesc}{rledecode_hqx}{data}
-Perform RLE-decompression on the data, as per the binhex4
-standard. The algorithm uses \code{0x90} after a byte as a repeat
-indicator, followed by a count. A count of \code{0} specifies a byte
-value of \code{0x90}. The routine returns the decompressed data,
-unless data input data ends in an orphaned repeat indicator, in which
-case the \exception{Incomplete} exception is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{rlecode_hqx}{data}
-Perform binhex4 style RLE-compression on \var{data} and return the
-result.
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_hqx}{data}
-Perform hexbin4 binary-to-\ASCII{} translation and return the
-resulting string. The argument should already be RLE-coded, and have a
-length divisible by 3 (except possibly the last fragment).
-\end{funcdesc}
-
-\begin{funcdesc}{crc_hqx}{data, crc}
-Compute the binhex4 crc value of \var{data}, starting with an initial
-\var{crc} and returning the result.
-\end{funcdesc}
-
-\begin{funcdesc}{crc32}{data\optional{, crc}}
-Compute CRC-32, the 32-bit checksum of data, starting with an initial
-crc. This is consistent with the ZIP file checksum. Since the
-algorithm is designed for use as a checksum algorithm, it is not
-suitable for use as a general hash algorithm. Use as follows:
-\begin{verbatim}
- print binascii.crc32("hello world")
- # Or, in two pieces:
- crc = binascii.crc32("hello")
- crc = binascii.crc32(" world", crc)
- print crc
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{b2a_hex}{data}
-\funcline{hexlify}{data}
-Return the hexadecimal representation of the binary \var{data}. Every
-byte of \var{data} is converted into the corresponding 2-digit hex
-representation. The resulting string is therefore twice as long as
-the length of \var{data}.
-\end{funcdesc}
-
-\begin{funcdesc}{a2b_hex}{hexstr}
-\funcline{unhexlify}{hexstr}
-Return the binary data represented by the hexadecimal string
-\var{hexstr}. This function is the inverse of \function{b2a_hex()}.
-\var{hexstr} must contain an even number of hexadecimal digits (which
-can be upper or lower case), otherwise a \exception{TypeError} is
-raised.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-Exception raised on errors. These are usually programming errors.
-\end{excdesc}
-
-\begin{excdesc}{Incomplete}
-Exception raised on incomplete data. These are usually not programming
-errors, but may be handled by reading a little more data and trying
-again.
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{base64}{Support for base64 encoding used in MIME email messages.}
-
- \seemodule{binhex}{Support for the binhex format used on the Macintosh.}
-
- \seemodule{uu}{Support for UU encoding used on \UNIX.}
-
- \seemodule{quopri}{Support for quoted-printable encoding used in MIME email messages. }
-\end{seealso}
diff --git a/Doc/lib/libbinhex.tex b/Doc/lib/libbinhex.tex
deleted file mode 100644
index d30f2b4..0000000
--- a/Doc/lib/libbinhex.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\section{\module{binhex} ---
- Encode and decode binhex4 files}
-
-\declaremodule{standard}{binhex}
-\modulesynopsis{Encode and decode files in binhex4 format.}
-
-
-This module encodes and decodes files in binhex4 format, a format
-allowing representation of Macintosh files in \ASCII. On the Macintosh,
-both forks of a file and the finder information are encoded (or
-decoded), on other platforms only the data fork is handled.
-
-The \module{binhex} module defines the following functions:
-
-\begin{funcdesc}{binhex}{input, output}
-Convert a binary file with filename \var{input} to binhex file
-\var{output}. The \var{output} parameter can either be a filename or a
-file-like object (any object supporting a \method{write()} and
-\method{close()} method).
-\end{funcdesc}
-
-\begin{funcdesc}{hexbin}{input\optional{, output}}
-Decode a binhex file \var{input}. \var{input} may be a filename or a
-file-like object supporting \method{read()} and \method{close()} methods.
-The resulting file is written to a file named \var{output}, unless the
-argument is omitted in which case the output filename is read from the
-binhex file.
-\end{funcdesc}
-
-The following exception is also defined:
-
-\begin{excdesc}{Error}
-Exception raised when something can't be encoded using the binhex
-format (for example, a filename is too long to fit in the filename
-field), or when input is not properly encoded binhex data.
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{binascii}{Support module containing \ASCII-to-binary
- and binary-to-\ASCII{} conversions.}
-\end{seealso}
-
-
-\subsection{Notes \label{binhex-notes}}
-
-There is an alternative, more powerful interface to the coder and
-decoder, see the source for details.
-
-If you code or decode textfiles on non-Macintosh platforms they will
-still use the Macintosh newline convention (carriage-return as end of
-line).
-
-As of this writing, \function{hexbin()} appears to not work in all
-cases.
diff --git a/Doc/lib/libbisect.tex b/Doc/lib/libbisect.tex
deleted file mode 100644
index 516e5cf..0000000
--- a/Doc/lib/libbisect.tex
+++ /dev/null
@@ -1,84 +0,0 @@
-\section{\module{bisect} ---
- Array bisection algorithm}
-
-\declaremodule{standard}{bisect}
-\modulesynopsis{Array bisection algorithms for binary searching.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-% LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
-% example based on the PyModules FAQ entry by Aaron Watters
-% <arw@pythonpros.com>.
-
-
-This module provides support for maintaining a list in sorted order
-without having to sort the list after each insertion. For long lists
-of items with expensive comparison operations, this can be an
-improvement over the more common approach. The module is called
-\module{bisect} because it uses a basic bisection algorithm to do its
-work. The source code may be most useful as a working example of the
-algorithm (the boundary conditions are already right!).
-
-The following functions are provided:
-
-\begin{funcdesc}{bisect_left}{list, item\optional{, lo\optional{, hi}}}
- Locate the proper insertion point for \var{item} in \var{list} to
- maintain sorted order. The parameters \var{lo} and \var{hi} may be
- used to specify a subset of the list which should be considered; by
- default the entire list is used. If \var{item} is already present
- in \var{list}, the insertion point will be before (to the left of)
- any existing entries. The return value is suitable for use as the
- first parameter to \code{\var{list}.insert()}. This assumes that
- \var{list} is already sorted.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{bisect_right}{list, item\optional{, lo\optional{, hi}}}
- Similar to \function{bisect_left()}, but returns an insertion point
- which comes after (to the right of) any existing entries of
- \var{item} in \var{list}.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{bisect}{\unspecified}
- Alias for \function{bisect_right()}.
-\end{funcdesc}
-
-\begin{funcdesc}{insort_left}{list, item\optional{, lo\optional{, hi}}}
- Insert \var{item} in \var{list} in sorted order. This is equivalent
- to \code{\var{list}.insert(bisect.bisect_left(\var{list}, \var{item},
- \var{lo}, \var{hi}), \var{item})}. This assumes that \var{list} is
- already sorted.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{insort_right}{list, item\optional{, lo\optional{, hi}}}
- Similar to \function{insort_left()}, but inserting \var{item} in
- \var{list} after any existing entries of \var{item}.
-\versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{insort}{\unspecified}
- Alias for \function{insort_right()}.
-\end{funcdesc}
-
-
-\subsection{Examples}
-\nodename{bisect-example}
-
-The \function{bisect()} function is generally useful for categorizing
-numeric data. This example uses \function{bisect()} to look up a
-letter grade for an exam total (say) based on a set of ordered numeric
-breakpoints: 85 and up is an `A', 75..84 is a `B', etc.
-
-\begin{verbatim}
->>> grades = "FEDCBA"
->>> breakpoints = [30, 44, 66, 75, 85]
->>> from bisect import bisect
->>> def grade(total):
-... return grades[bisect(breakpoints, total)]
-...
->>> grade(66)
-'C'
->>> map(grade, [33, 99, 77, 44, 12, 88])
-['E', 'A', 'B', 'D', 'F', 'A']
-
-\end{verbatim}
diff --git a/Doc/lib/libbltin.tex b/Doc/lib/libbltin.tex
deleted file mode 100644
index f6abe25..0000000
--- a/Doc/lib/libbltin.tex
+++ /dev/null
@@ -1,44 +0,0 @@
-\section{\module{__builtin__} ---
- Built-in objects}
-
-\declaremodule[builtin]{builtin}{__builtin__}
-\modulesynopsis{The module that provides the built-in namespace.}
-
-
-This module provides direct access to all `built-in' identifiers of
-Python; for example, \code{__builtin__.open} is the full name for the
-built-in function \function{open()}. See chapter~\ref{builtin},
-``Built-in Objects.''
-
-This module is not normally accessed explicitly by most applications,
-but can be useful in modules that provide objects with the same name
-as a built-in value, but in which the built-in of that name is also
-needed. For example, in a module that wants to implement an
-\function{open()} function that wraps the built-in \function{open()},
-this module can be used directly:
-
-\begin{verbatim}
-import __builtin__
-
-def open(path):
- f = __builtin__.open(path, 'r')
- return UpperCaser(f)
-
-class UpperCaser:
- '''Wrapper around a file that converts output to upper-case.'''
-
- def __init__(self, f):
- self._f = f
-
- def read(self, count=-1):
- return self._f.read(count).upper()
-
- # ...
-\end{verbatim}
-
-As an implementation detail, most modules have the name
-\code{__builtins__} (note the \character{s}) made available as part of
-their globals. The value of \code{__builtins__} is normally either
-this module or the value of this modules's \member{__dict__}
-attribute. Since this is an implementation detail, it may not be used
-by alternate implementations of Python.
diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex
deleted file mode 100644
index 8f23324..0000000
--- a/Doc/lib/libbsddb.tex
+++ /dev/null
@@ -1,211 +0,0 @@
-\section{\module{bsddb} ---
- Interface to Berkeley DB library}
-
-\declaremodule{extension}{bsddb}
-\modulesynopsis{Interface to Berkeley DB database library}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-
-The \module{bsddb} module provides an interface to the Berkeley DB
-library. Users can create hash, btree or record based library files
-using the appropriate open call. Bsddb objects behave generally like
-dictionaries. Keys and values must be strings, however, so to use
-other objects as keys or to store other kinds of objects the user must
-serialize them somehow, typically using \function{marshal.dumps()} or
-\function{pickle.dumps()}.
-
-The \module{bsddb} module requires a Berkeley DB library version from
-3.3 thru 4.5.
-
-\begin{seealso}
- \seeurl{http://pybsddb.sourceforge.net/}
- {The website with documentation for the \module{bsddb.db}
- Python Berkeley DB interface that closely mirrors the object
- oriented interface provided in Berkeley DB 3 and 4.}
-
- \seeurl{http://www.oracle.com/database/berkeley-db/}
- {The Berkeley DB library.}
-\end{seealso}
-
-A more modern DB, DBEnv and DBSequence object interface is available in the
-\module{bsddb.db} module which closely matches the Berkeley DB C API
-documented at the above URLs. Additional features provided by the
-\module{bsddb.db} API include fine tuning, transactions, logging, and
-multiprocess concurrent database access.
-
-The following is a description of the legacy \module{bsddb} interface
-compatible with the old Python bsddb module. Starting in Python 2.5 this
-interface should be safe for multithreaded access. The \module{bsddb.db}
-API is recommended for threading users as it provides better control.
-
-The \module{bsddb} module defines the following functions that create
-objects that access the appropriate type of Berkeley DB file. The
-first two arguments of each function are the same. For ease of
-portability, only the first two arguments should be used in most
-instances.
-
-\begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
- mode\optional{, pgsize\optional{,
- ffactor\optional{, nelem\optional{,
- cachesize\optional{, lorder\optional{,
- hflags}}}}}}}}}
-Open the hash format file named \var{filename}. Files never intended
-to be preserved on disk may be created by passing \code{None} as the
-\var{filename}. The optional
-\var{flag} identifies the mode used to open the file. It may be
-\character{r} (read only), \character{w} (read-write) ,
-\character{c} (read-write - create if necessary; the default) or
-\character{n} (read-write - truncate to zero length). The other
-arguments are rarely used and are just passed to the low-level
-\cfunction{dbopen()} function. Consult the Berkeley DB documentation
-for their use and interpretation.
-\end{funcdesc}
-
-\begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
-mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
-minkeypage\optional{, pgsize\optional{, lorder}}}}}}}}}
-
-Open the btree format file named \var{filename}. Files never intended
-to be preserved on disk may be created by passing \code{None} as the
-\var{filename}. The optional
-\var{flag} identifies the mode used to open the file. It may be
-\character{r} (read only), \character{w} (read-write),
-\character{c} (read-write - create if necessary; the default) or
-\character{n} (read-write - truncate to zero length). The other
-arguments are rarely used and are just passed to the low-level dbopen
-function. Consult the Berkeley DB documentation for their use and
-interpretation.
-\end{funcdesc}
-
-\begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
-rnflags\optional{, cachesize\optional{, pgsize\optional{, lorder\optional{,
-rlen\optional{, delim\optional{, source\optional{, pad}}}}}}}}}}}
-
-Open a DB record format file named \var{filename}. Files never intended
-to be preserved on disk may be created by passing \code{None} as the
-\var{filename}. The optional
-\var{flag} identifies the mode used to open the file. It may be
-\character{r} (read only), \character{w} (read-write),
-\character{c} (read-write - create if necessary; the default) or
-\character{n} (read-write - truncate to zero length). The other
-arguments are rarely used and are just passed to the low-level dbopen
-function. Consult the Berkeley DB documentation for their use and
-interpretation.
-\end{funcdesc}
-
-\begin{classdesc}{StringKeys}{db}
- Wrapper class around a DB object that supports string keys
- (rather than bytes). All keys are encoded as UTF-8, then passed
- to the underlying object. \versionadded{3.0}
-\end{classdesc}
-
-\begin{classdesc}{StringValues}{db}
- Wrapper class around a DB object that supports string values
- (rather than bytes). All values are encoded as UTF-8, then passed
- to the underlying object. \versionadded{3.0}
-\end{classdesc}
-
-\begin{seealso}
- \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
-\end{seealso}
-
-\subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
-
-Once instantiated, hash, btree and record objects support
-the same methods as dictionaries. In addition, they support
-the methods listed below.
-\versionchanged[Added dictionary methods]{2.3.1}
-
-\begin{methoddesc}[bsddbobject]{close}{}
-Close the underlying file. The object can no longer be accessed. Since
-there is no open \method{open} method for these objects, to open the file
-again a new \module{bsddb} module open function must be called.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{keys}{}
-Return the list of keys contained in the DB file. The order of the list is
-unspecified and should not be relied on. In particular, the order of the
-list returned is different for different file formats.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{has_key}{key}
-Return \code{1} if the DB file contains the argument as a key.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{set_location}{key}
-Set the cursor to the item indicated by \var{key} and return a tuple
-containing the key and its value. For binary tree databases (opened
-using \function{btopen()}), if \var{key} does not actually exist in
-the database, the cursor will point to the next item in sorted order
-and return that key and value. For other databases,
-\exception{KeyError} will be raised if \var{key} is not found in the
-database.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{first}{}
-Set the cursor to the first item in the DB file and return it. The order of
-keys in the file is unspecified, except in the case of B-Tree databases.
-This method raises \exception{bsddb.error} if the database is empty.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{next}{}
-Set the cursor to the next item in the DB file and return it. The order of
-keys in the file is unspecified, except in the case of B-Tree databases.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{previous}{}
-Set the cursor to the previous item in the DB file and return it. The
-order of keys in the file is unspecified, except in the case of B-Tree
-databases. This is not supported on hashtable databases (those opened
-with \function{hashopen()}).
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{last}{}
-Set the cursor to the last item in the DB file and return it. The
-order of keys in the file is unspecified. This is not supported on
-hashtable databases (those opened with \function{hashopen()}).
-This method raises \exception{bsddb.error} if the database is empty.
-\end{methoddesc}
-
-\begin{methoddesc}[bsddbobject]{sync}{}
-Synchronize the database on disk.
-\end{methoddesc}
-
-Example:
-
-\begin{verbatim}
->>> import bsddb
->>> db = bsddb.btopen('/tmp/spam.db', 'c')
->>> for i in range(10): db['%d'%i] = '%d'% (i*i)
-...
->>> db['3']
-'9'
->>> db.keys()
-['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
->>> db.first()
-('0', '0')
->>> db.next()
-('1', '1')
->>> db.last()
-('9', '81')
->>> db.set_location('2')
-('2', '4')
->>> db.previous()
-('1', '1')
->>> for k, v in db.iteritems():
-... print k, v
-0 0
-1 1
-2 4
-3 9
-4 16
-5 25
-6 36
-7 49
-8 64
-9 81
->>> '8' in db
-True
->>> db.sync()
-0
-\end{verbatim}
diff --git a/Doc/lib/libbz2.tex b/Doc/lib/libbz2.tex
deleted file mode 100644
index 36bc0d2..0000000
--- a/Doc/lib/libbz2.tex
+++ /dev/null
@@ -1,165 +0,0 @@
-\section{\module{bz2} ---
- Compression compatible with \program{bzip2}}
-
-\declaremodule{builtin}{bz2}
-\modulesynopsis{Interface to compression and decompression
- routines compatible with \program{bzip2}.}
-\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
-\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
-
-\versionadded{2.3}
-
-This module provides a comprehensive interface for the bz2 compression library.
-It implements a complete file interface, one-shot (de)compression functions,
-and types for sequential (de)compression.
-
-Here is a resume of the features offered by the bz2 module:
-
-\begin{itemize}
-\item \class{BZ2File} class implements a complete file interface, including
- \method{readline()}, \method{readlines()},
- \method{writelines()}, \method{seek()}, etc;
-\item \class{BZ2File} class implements emulated \method{seek()} support;
-\item \class{BZ2File} class implements universal newline support;
-\item \class{BZ2File} class offers an optimized line iteration using
- the readahead algorithm borrowed from file objects;
-\item Sequential (de)compression supported by \class{BZ2Compressor} and
- \class{BZ2Decompressor} classes;
-\item One-shot (de)compression supported by \function{compress()} and
- \function{decompress()} functions;
-\item Thread safety uses individual locking mechanism;
-\item Complete inline documentation;
-\end{itemize}
-
-
-\subsection{(De)compression of files}
-
-Handling of compressed files is offered by the \class{BZ2File} class.
-
-\begin{classdesc}{BZ2File}{filename\optional{, mode\optional{,
- buffering\optional{, compresslevel}}}}
-Open a bz2 file. Mode can be either \code{'r'} or \code{'w'}, for reading
-(default) or writing. When opened for writing, the file will be created if
-it doesn't exist, and truncated otherwise. If \var{buffering} is given,
-\code{0} means unbuffered, and larger numbers specify the buffer size;
-the default is \code{0}. If
-\var{compresslevel} is given, it must be a number between \code{1} and
-\code{9}; the default is \code{9}.
-Add a \character{U} to mode to open the file for input with universal newline
-support. Any line ending in the input file will be seen as a
-\character{\e n} in Python. Also, a file so opened gains the
-attribute \member{newlines}; the value for this attribute is one of
-\code{None} (no newline read yet), \code{'\e r'}, \code{'\e n'},
-\code{'\e r\e n'} or a tuple containing all the newline types
-seen. Universal newlines are available only when reading.
-Instances support iteration in the same way as normal \class{file}
-instances.
-\end{classdesc}
-
-\begin{methoddesc}[BZ2File]{close}{}
-Close the file. Sets data attribute \member{closed} to true. A closed file
-cannot be used for further I/O operations. \method{close()} may be called
-more than once without error.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{read}{\optional{size}}
-Read at most \var{size} uncompressed bytes, returned as a string. If the
-\var{size} argument is negative or omitted, read until EOF is reached.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{readline}{\optional{size}}
-Return the next line from the file, as a string, retaining newline.
-A non-negative \var{size} argument limits the maximum number of bytes to
-return (an incomplete line may be returned then). Return an empty
-string at EOF.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{readlines}{\optional{size}}
-Return a list of lines read. The optional \var{size} argument, if given,
-is an approximate bound on the total number of bytes in the lines returned.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{seek}{offset\optional{, whence}}
-Move to new file position. Argument \var{offset} is a byte count. Optional
-argument \var{whence} defaults to \code{os.SEEK_SET} or \code{0} (offset from start of file;
-offset should be \code{>= 0}); other values are \code{os.SEEK_CUR} or \code{1} (move relative to
-current position; offset can be positive or negative), and \code{os.SEEK_END} or \code{2} (move relative to end
-of file; offset is usually negative, although many platforms allow seeking beyond
-the end of a file).
-
-Note that seeking of bz2 files is emulated, and depending on the parameters
-the operation may be extremely slow.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{tell}{}
-Return the current file position, an integer (may be a long integer).
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{write}{data}
-Write string \var{data} to file. Note that due to buffering, \method{close()}
-may be needed before the file on disk reflects the data written.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2File]{writelines}{sequence_of_strings}
-Write the sequence of strings to the file. Note that newlines are not added.
-The sequence can be any iterable object producing strings. This is equivalent
-to calling write() for each string.
-\end{methoddesc}
-
-
-\subsection{Sequential (de)compression}
-
-Sequential compression and decompression is done using the classes
-\class{BZ2Compressor} and \class{BZ2Decompressor}.
-
-\begin{classdesc}{BZ2Compressor}{\optional{compresslevel}}
-Create a new compressor object. This object may be used to compress
-data sequentially. If you want to compress data in one shot, use the
-\function{compress()} function instead. The \var{compresslevel} parameter,
-if given, must be a number between \code{1} and \code{9}; the default
-is \code{9}.
-\end{classdesc}
-
-\begin{methoddesc}[BZ2Compressor]{compress}{data}
-Provide more data to the compressor object. It will return chunks of compressed
-data whenever possible. When you've finished providing data to compress, call
-the \method{flush()} method to finish the compression process, and return what
-is left in internal buffers.
-\end{methoddesc}
-
-\begin{methoddesc}[BZ2Compressor]{flush}{}
-Finish the compression process and return what is left in internal buffers. You
-must not use the compressor object after calling this method.
-\end{methoddesc}
-
-\begin{classdesc}{BZ2Decompressor}{}
-Create a new decompressor object. This object may be used to decompress
-data sequentially. If you want to decompress data in one shot, use the
-\function{decompress()} function instead.
-\end{classdesc}
-
-\begin{methoddesc}[BZ2Decompressor]{decompress}{data}
-Provide more data to the decompressor object. It will return chunks of
-decompressed data whenever possible. If you try to decompress data after the
-end of stream is found, \exception{EOFError} will be raised. If any data was
-found after the end of stream, it'll be ignored and saved in
-\member{unused\_data} attribute.
-\end{methoddesc}
-
-
-\subsection{One-shot (de)compression}
-
-One-shot compression and decompression is provided through the
-\function{compress()} and \function{decompress()} functions.
-
-\begin{funcdesc}{compress}{data\optional{, compresslevel}}
-Compress \var{data} in one shot. If you want to compress data sequentially,
-use an instance of \class{BZ2Compressor} instead. The \var{compresslevel}
-parameter, if given, must be a number between \code{1} and \code{9};
-the default is \code{9}.
-\end{funcdesc}
-
-\begin{funcdesc}{decompress}{data}
-Decompress \var{data} in one shot. If you want to decompress data
-sequentially, use an instance of \class{BZ2Decompressor} instead.
-\end{funcdesc}
diff --git a/Doc/lib/libcalendar.tex b/Doc/lib/libcalendar.tex
deleted file mode 100644
index acfd2da..0000000
--- a/Doc/lib/libcalendar.tex
+++ /dev/null
@@ -1,304 +0,0 @@
-\section{\module{calendar} ---
- General calendar-related functions}
-
-\declaremodule{standard}{calendar}
-\modulesynopsis{Functions for working with calendars,
- including some emulation of the \UNIX\ \program{cal}
- program.}
-\sectionauthor{Drew Csillag}{drew_csillag@geocities.com}
-
-This module allows you to output calendars like the \UNIX{}
-\program{cal} program, and provides additional useful functions
-related to the calendar. By default, these calendars have Monday as
-the first day of the week, and Sunday as the last (the European
-convention). Use \function{setfirstweekday()} to set the first day of the
-week to Sunday (6) or to any other weekday. Parameters that specify
-dates are given as integers.
-
-Most of these functions and classses rely on the \module{datetime}
-module which uses an idealized calendar, the current Gregorian
-calendar indefinitely extended in both directions. This matches
-the definition of the "proleptic Gregorian" calendar in Dershowitz
-and Reingold's book "Calendrical Calculations", where it's the
-base calendar for all computations.
-
-\begin{classdesc}{Calendar}{\optional{firstweekday}}
-Creates a \class{Calendar} object. \var{firstweekday} is an integer
-specifying the first day of the week. \code{0} is Monday (the default),
-\code{6} is Sunday.
-
-A \class{Calendar} object provides several methods that can
-be used for preparing the calendar data for formatting. This
-class doesn't do any formatting itself. This is the job of
-subclasses.
-\versionadded{2.5}
-\end{classdesc}
-
-\class{Calendar} instances have the following methods:
-
-\begin{methoddesc}{iterweekdays}{weekday}
-Return an iterator for the week day numbers that will be used
-for one week. The first number from the iterator will be the
-same as the number returned by \method{firstweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{itermonthdates}{year, month}
-Return an iterator for the month \var{month} (1-12) in the
-year \var{year}. This iterator will return all days (as
-\class{datetime.date} objects) for the month and all days
-before the start of the month or after the end of the month
-that are required to get a complete week.
-\end{methoddesc}
-
-\begin{methoddesc}{itermonthdays2}{year, month}
-Return an iterator for the month \var{month} in the year
-\var{year} similar to \method{itermonthdates()}. Days returned
-will be tuples consisting of a day number and a week day
-number.
-\end{methoddesc}
-
-\begin{methoddesc}{itermonthdays}{year, month}
-Return an iterator for the month \var{month} in the year
-\var{year} similar to \method{itermonthdates()}. Days returned
-will simply be day numbers.
-\end{methoddesc}
-
-\begin{methoddesc}{monthdatescalendar}{year, month}
-Return a list of the weeks in the month \var{month} of
-the \var{year} as full weeks. Weeks are lists of seven
-\class{datetime.date} objects.
-\end{methoddesc}
-
-\begin{methoddesc}{monthdays2calendar}{year, month}
-Return a list of the weeks in the month \var{month} of
-the \var{year} as full weeks. Weeks are lists of seven
-tuples of day numbers and weekday numbers.
-\end{methoddesc}
-
-\begin{methoddesc}{monthdayscalendar}{year, month}
-Return a list of the weeks in the month \var{month} of
-the \var{year} as full weeks. Weeks are lists of seven
-day numbers.
-\end{methoddesc}
-
-\begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}}
-Return the data for the specified year ready for formatting. The return
-value is a list of month rows. Each month row contains up to \var{width}
-months (defaulting to 3). Each month contains between 4 and 6 weeks and
-each week contains 1--7 days. Days are \class{datetime.date} objects.
-\end{methoddesc}
-
-\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}}
-Return the data for the specified year ready for formatting (similar to
-\method{yeardatescalendar()}). Entries in the week lists are tuples of
-day numbers and weekday numbers. Day numbers outside this month are zero.
-\end{methoddesc}
-
-\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}}
-Return the data for the specified year ready for formatting (similar to
-\method{yeardatescalendar()}). Entries in the week lists are day numbers.
-Day numbers outside this month are zero.
-\end{methoddesc}
-
-
-\begin{classdesc}{TextCalendar}{\optional{firstweekday}}
-This class can be used to generate plain text calendars.
-
-\versionadded{2.5}
-\end{classdesc}
-
-\class{TextCalendar} instances have the following methods:
-
-\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}}
-Return a month's calendar in a multi-line string. If \var{w} is
-provided, it specifies the width of the date columns, which are
-centered. If \var{l} is given, it specifies the number of lines that
-each week will use. Depends on the first weekday as set by
-\function{setfirstweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
-Print a month's calendar as returned by \method{formatmonth()}.
-\end{methoddesc}
-
-\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{,
- l\optional{, c\optional{, m}}}}}
-Return a \var{m}-column calendar for an entire year as a multi-line string.
-Optional parameters \var{w}, \var{l}, and \var{c} are for date column
-width, lines per week, and number of spaces between month columns,
-respectively. Depends on the first weekday as set by
-\method{setfirstweekday()}. The earliest year for which a calendar can
-be generated is platform-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{,
- c\optional{, m}}}}}
-Print the calendar for an entire year as returned by \method{formatyear()}.
-\end{methoddesc}
-
-
-\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}}
-This class can be used to generate HTML calendars.
-
-\versionadded{2.5}
-\end{classdesc}
-
-\class{HTMLCalendar} instances have the following methods:
-
-\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}}
-Return a month's calendar as an HTML table. If \var{withyear} is
-true the year will be included in the header, otherwise just the
-month name will be used.
-\end{methoddesc}
-
-\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}}
-Return a year's calendar as an HTML table. \var{width} (defaulting to 3)
-specifies the number of months per row.
-\end{methoddesc}
-
-\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{,
- width\optional{, css\optional{, encoding}}}}
-Return a year's calendar as a complete HTML page. \var{width}
-(defaulting to 3) specifies the number of months per row. \var{css}
-is the name for the cascading style sheet to be used. \constant{None}
-can be passed if no style sheet should be used. \var{encoding}
-specifies the encoding to be used for the output (defaulting
-to the system default encoding).
-\end{methoddesc}
-
-
-\begin{classdesc}{LocaleTextCalendar}{\optional{firstweekday\optional{, locale}}}
-This subclass of \class{TextCalendar} can be passed a locale name in the
-constructor and will return month and weekday names in the specified locale.
-If this locale includes an encoding all strings containing month and weekday
-names will be returned as unicode.
-\versionadded{2.5}
-\end{classdesc}
-
-
-\begin{classdesc}{LocaleHTMLCalendar}{\optional{firstweekday\optional{, locale}}}
-This subclass of \class{HTMLCalendar} can be passed a locale name in the
-constructor and will return month and weekday names in the specified locale.
-If this locale includes an encoding all strings containing month and weekday
-names will be returned as unicode.
-\versionadded{2.5}
-\end{classdesc}
-
-
-For simple text calendars this module provides the following functions.
-
-\begin{funcdesc}{setfirstweekday}{weekday}
-Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start
-each week. The values \constant{MONDAY}, \constant{TUESDAY},
-\constant{WEDNESDAY}, \constant{THURSDAY}, \constant{FRIDAY},
-\constant{SATURDAY}, and \constant{SUNDAY} are provided for
-convenience. For example, to set the first weekday to Sunday:
-
-\begin{verbatim}
-import calendar
-calendar.setfirstweekday(calendar.SUNDAY)
-\end{verbatim}
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{firstweekday}{}
-Returns the current setting for the weekday to start each week.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{isleap}{year}
-Returns \constant{True} if \var{year} is a leap year, otherwise
-\constant{False}.
-\end{funcdesc}
-
-\begin{funcdesc}{leapdays}{y1, y2}
-Returns the number of leap years in the range
-[\var{y1}\ldots\var{y2}), where \var{y1} and \var{y2} are years.
-\versionchanged[This function didn't work for ranges spanning
- a century change in Python 1.5.2]{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{weekday}{year, month, day}
-Returns the day of the week (\code{0} is Monday) for \var{year}
-(\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day}
-(\code{1}--\code{31}).
-\end{funcdesc}
-
-\begin{funcdesc}{weekheader}{n}
-Return a header containing abbreviated weekday names. \var{n} specifies
-the width in characters for one weekday.
-\end{funcdesc}
-
-\begin{funcdesc}{monthrange}{year, month}
-Returns weekday of first day of the month and number of days in month,
-for the specified \var{year} and \var{month}.
-\end{funcdesc}
-
-\begin{funcdesc}{monthcalendar}{year, month}
-Returns a matrix representing a month's calendar. Each row represents
-a week; days outside of the month a represented by zeros.
-Each week begins with Monday unless set by \function{setfirstweekday()}.
-\end{funcdesc}
-
-\begin{funcdesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
-Prints a month's calendar as returned by \function{month()}.
-\end{funcdesc}
-
-\begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}}
-Returns a month's calendar in a multi-line string using the
-\method{formatmonth} of the \class{TextCalendar} class.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{prcal}{year\optional{, w\optional{, l\optional{c}}}}
-Prints the calendar for an entire year as returned by
-\function{calendar()}.
-\end{funcdesc}
-
-\begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}}
-Returns a 3-column calendar for an entire year as a multi-line string
-using the \method{formatyear} of the \class{TextCalendar} class.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{timegm}{tuple}
-An unrelated but handy function that takes a time tuple such as
-returned by the \function{gmtime()} function in the \refmodule{time}
-module, and returns the corresponding \UNIX{} timestamp value, assuming
-an epoch of 1970, and the POSIX encoding. In fact,
-\function{time.gmtime()} and \function{timegm()} are each others' inverse.
-\versionadded{2.0}
-\end{funcdesc}
-
-The \module{calendar} module exports the following data attributes:
-
-\begin{datadesc}{day_name}
-An array that represents the days of the week in the
-current locale.
-\end{datadesc}
-
-\begin{datadesc}{day_abbr}
-An array that represents the abbreviated days of the week
-in the current locale.
-\end{datadesc}
-
-\begin{datadesc}{month_name}
-An array that represents the months of the year in the
-current locale. This follows normal convention
-of January being month number 1, so it has a length of 13 and
-\code{month_name[0]} is the empty string.
-\end{datadesc}
-
-\begin{datadesc}{month_abbr}
-An array that represents the abbreviated months of the year
-in the current locale. This follows normal convention
-of January being month number 1, so it has a length of 13 and
-\code{month_abbr[0]} is the empty string.
-\end{datadesc}
-
-\begin{seealso}
- \seemodule{datetime}{Object-oriented interface to dates and times
- with similar functionality to the
- \refmodule{time} module.}
- \seemodule{time}{Low-level time related functions.}
-\end{seealso}
diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex
deleted file mode 100644
index a41aee1..0000000
--- a/Doc/lib/libcfgparser.tex
+++ /dev/null
@@ -1,322 +0,0 @@
-\section{\module{ConfigParser} ---
- Configuration file parser}
-
-\declaremodule{standard}{ConfigParser}
-\modulesynopsis{Configuration file parser.}
-\moduleauthor{Ken Manheimer}{klm@zope.com}
-\moduleauthor{Barry Warsaw}{bwarsaw@python.org}
-\moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
-\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
-
-This module defines the class \class{ConfigParser}.
-\indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
-\index{Windows ini file}
-The \class{ConfigParser} class implements a basic configuration file
-parser language which provides a structure similar to what you would
-find on Microsoft Windows INI files. You can use this to write Python
-programs which can be customized by end users easily.
-
-\begin{notice}[warning]
- This library does \emph{not} interpret or write the value-type
- prefixes used in the Windows Registry extended version of INI syntax.
-\end{notice}
-
-The configuration file consists of sections, led by a
-\samp{[section]} header and followed by \samp{name: value} entries,
-with continuations in the style of \rfc{822}; \samp{name=value} is
-also accepted. Note that leading whitespace is removed from values.
-The optional values can contain format strings which refer to other
-values in the same section, or values in a special
-\code{DEFAULT} section. Additional defaults can be provided on
-initialization and retrieval. Lines beginning with \character{\#} or
-\character{;} are ignored and may be used to provide comments.
-
-For example:
-
-\begin{verbatim}
-[My Section]
-foodir: %(dir)s/whatever
-dir=frob
-\end{verbatim}
-
-would resolve the \samp{\%(dir)s} to the value of
-\samp{dir} (\samp{frob} in this case). All reference expansions are
-done on demand.
-
-Default values can be specified by passing them into the
-\class{ConfigParser} constructor as a dictionary. Additional defaults
-may be passed into the \method{get()} method which will override all
-others.
-
-Sections are normally stored in a builtin dictionary. An alternative
-dictionary type can be passed to the \class{ConfigParser} constructor.
-For example, if a dictionary type is passed that sorts its keys,
-the sections will be sorted on write-back, as will be the keys within
-each section.
-
-\begin{classdesc}{RawConfigParser}{\optional{defaults\optional{, dict_type}}}
-The basic configuration object. When \var{defaults} is given, it is
-initialized into the dictionary of intrinsic defaults. When \var{dict_type}
-is given, it will be used to create the dictionary objects for the list
-of sections, for the options within a section, and for the default values.
-This class does not support the magical interpolation behavior.
-\versionadded{2.3}
-\versionchanged[\var{dict_type} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{ConfigParser}{\optional{defaults}}
-Derived class of \class{RawConfigParser} that implements the magical
-interpolation feature and adds optional arguments to the \method{get()}
-and \method{items()} methods. The values in \var{defaults} must be
-appropriate for the \samp{\%()s} string interpolation. Note that
-\var{__name__} is an intrinsic default; its value is the section name,
-and will override any value provided in \var{defaults}.
-
-All option names used in interpolation will be passed through the
-\method{optionxform()} method just like any other option name
-reference. For example, using the default implementation of
-\method{optionxform()} (which converts option names to lower case),
-the values \samp{foo \%(bar)s} and \samp{foo \%(BAR)s} are
-equivalent.
-\end{classdesc}
-
-\begin{classdesc}{SafeConfigParser}{\optional{defaults}}
-Derived class of \class{ConfigParser} that implements a more-sane
-variant of the magical interpolation feature. This implementation is
-more predictable as well.
-% XXX Need to explain what's safer/more predictable about it.
-New applications should prefer this version if they don't need to be
-compatible with older versions of Python.
-\versionadded{2.3}
-\end{classdesc}
-
-\begin{excdesc}{NoSectionError}
-Exception raised when a specified section is not found.
-\end{excdesc}
-
-\begin{excdesc}{DuplicateSectionError}
-Exception raised if \method{add_section()} is called with the name of
-a section that is already present.
-\end{excdesc}
-
-\begin{excdesc}{NoOptionError}
-Exception raised when a specified option is not found in the specified
-section.
-\end{excdesc}
-
-\begin{excdesc}{InterpolationError}
-Base class for exceptions raised when problems occur performing string
-interpolation.
-\end{excdesc}
-
-\begin{excdesc}{InterpolationDepthError}
-Exception raised when string interpolation cannot be completed because
-the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
-Subclass of \exception{InterpolationError}.
-\end{excdesc}
-
-\begin{excdesc}{InterpolationMissingOptionError}
-Exception raised when an option referenced from a value does not exist.
-Subclass of \exception{InterpolationError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{InterpolationSyntaxError}
-Exception raised when the source text into which substitutions are
-made does not conform to the required syntax.
-Subclass of \exception{InterpolationError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{MissingSectionHeaderError}
-Exception raised when attempting to parse a file which has no section
-headers.
-\end{excdesc}
-
-\begin{excdesc}{ParsingError}
-Exception raised when errors occur attempting to parse a file.
-\end{excdesc}
-
-\begin{datadesc}{MAX_INTERPOLATION_DEPTH}
-The maximum depth for recursive interpolation for \method{get()} when
-the \var{raw} parameter is false. This is relevant only for the
-\class{ConfigParser} class.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{shlex}{Support for a creating \UNIX{} shell-like
- mini-languages which can be used as an alternate
- format for application configuration files.}
-\end{seealso}
-
-
-\subsection{RawConfigParser Objects \label{RawConfigParser-objects}}
-
-\class{RawConfigParser} instances have the following methods:
-
-\begin{methoddesc}[RawConfigParser]{defaults}{}
-Return a dictionary containing the instance-wide defaults.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{sections}{}
-Return a list of the sections available; \code{DEFAULT} is not
-included in the list.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{add_section}{section}
-Add a section named \var{section} to the instance. If a section by
-the given name already exists, \exception{DuplicateSectionError} is
-raised.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{has_section}{section}
-Indicates whether the named section is present in the
-configuration. The \code{DEFAULT} section is not acknowledged.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{options}{section}
-Returns a list of options available in the specified \var{section}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{has_option}{section, option}
-If the given section exists, and contains the given option,
-return \constant{True}; otherwise return \constant{False}.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{read}{filenames}
-Attempt to read and parse a list of filenames, returning a list of filenames
-which were successfully parsed. If \var{filenames} is a string or
-Unicode string, it is treated as a single filename.
-If a file named in \var{filenames} cannot be opened, that file will be
-ignored. This is designed so that you can specify a list of potential
-configuration file locations (for example, the current directory, the
-user's home directory, and some system-wide directory), and all
-existing configuration files in the list will be read. If none of the
-named files exist, the \class{ConfigParser} instance will contain an
-empty dataset. An application which requires initial values to be
-loaded from a file should load the required file or files using
-\method{readfp()} before calling \method{read()} for any optional
-files:
-
-\begin{verbatim}
-import ConfigParser, os
-
-config = ConfigParser.ConfigParser()
-config.readfp(open('defaults.cfg'))
-config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
-\end{verbatim}
-\versionchanged[Returns list of successfully parsed filenames]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{readfp}{fp\optional{, filename}}
-Read and parse configuration data from the file or file-like object in
-\var{fp} (only the \method{readline()} method is used). If
-\var{filename} is omitted and \var{fp} has a \member{name} attribute,
-that is used for \var{filename}; the default is \samp{<???>}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{get}{section, option}
-Get an \var{option} value for the named \var{section}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{getint}{section, option}
-A convenience method which coerces the \var{option} in the specified
-\var{section} to an integer.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{getfloat}{section, option}
-A convenience method which coerces the \var{option} in the specified
-\var{section} to a floating point number.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{getboolean}{section, option}
-A convenience method which coerces the \var{option} in the specified
-\var{section} to a Boolean value. Note that the accepted values
-for the option are \code{"1"}, \code{"yes"}, \code{"true"}, and \code{"on"},
-which cause this method to return \code{True}, and \code{"0"}, \code{"no"},
-\code{"false"}, and \code{"off"}, which cause it to return \code{False}. These
-string values are checked in a case-insensitive manner. Any other value will
-cause it to raise \exception{ValueError}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{items}{section}
-Return a list of \code{(\var{name}, \var{value})} pairs for each
-option in the given \var{section}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{set}{section, option, value}
-If the given section exists, set the given option to the specified
-value; otherwise raise \exception{NoSectionError}. While it is
-possible to use \class{RawConfigParser} (or \class{ConfigParser} with
-\var{raw} parameters set to true) for \emph{internal} storage of
-non-string values, full functionality (including interpolation and
-output to files) can only be achieved using string values.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{write}{fileobject}
-Write a representation of the configuration to the specified file
-object. This representation can be parsed by a future \method{read()}
-call.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{remove_option}{section, option}
-Remove the specified \var{option} from the specified \var{section}.
-If the section does not exist, raise \exception{NoSectionError}.
-If the option existed to be removed, return \constant{True};
-otherwise return \constant{False}.
-\versionadded{1.6}
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{remove_section}{section}
-Remove the specified \var{section} from the configuration.
-If the section in fact existed, return \code{True}.
-Otherwise return \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[RawConfigParser]{optionxform}{option}
-Transforms the option name \var{option} as found in an input file or
-as passed in by client code to the form that should be used in the
-internal structures. The default implementation returns a lower-case
-version of \var{option}; subclasses may override this or client code
-can set an attribute of this name on instances to affect this
-behavior. Setting this to \function{str()}, for example, would make
-option names case sensitive.
-\end{methoddesc}
-
-
-\subsection{ConfigParser Objects \label{ConfigParser-objects}}
-
-The \class{ConfigParser} class extends some methods of the
-\class{RawConfigParser} interface, adding some optional arguments.
-
-\begin{methoddesc}[ConfigParser]{get}{section, option\optional{, raw\optional{, vars}}}
-Get an \var{option} value for the named \var{section}. All the
-\character{\%} interpolations are expanded in the return values, based
-on the defaults passed into the constructor, as well as the options
-\var{vars} provided, unless the \var{raw} argument is true.
-\end{methoddesc}
-
-\begin{methoddesc}[ConfigParser]{items}{section\optional{, raw\optional{, vars}}}
-Return a list of \code{(\var{name}, \var{value})} pairs for each
-option in the given \var{section}. Optional arguments have the
-same meaning as for the \method{get()} method.
-\versionadded{2.3}
-\end{methoddesc}
-
-
-\subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}}
-
-The \class{SafeConfigParser} class implements the same extended
-interface as \class{ConfigParser}, with the following addition:
-
-\begin{methoddesc}[SafeConfigParser]{set}{section, option, value}
-If the given section exists, set the given option to the specified
-value; otherwise raise \exception{NoSectionError}. \var{value} must
-be a string (\class{str} or \class{unicode}); if not,
-\exception{TypeError} is raised.
-\versionadded{2.4}
-\end{methoddesc}
diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex
deleted file mode 100644
index 1dd7e03..0000000
--- a/Doc/lib/libcgi.tex
+++ /dev/null
@@ -1,602 +0,0 @@
-\section{\module{cgi} ---
- Common Gateway Interface support.}
-\declaremodule{standard}{cgi}
-
-\modulesynopsis{Common Gateway Interface support, used to interpret
-forms in server-side scripts.}
-
-\indexii{WWW}{server}
-\indexii{CGI}{protocol}
-\indexii{HTTP}{protocol}
-\indexii{MIME}{headers}
-\index{URL}
-
-
-Support module for Common Gateway Interface (CGI) scripts.%
-\index{Common Gateway Interface}
-
-This module defines a number of utilities for use by CGI scripts
-written in Python.
-
-\subsection{Introduction}
-\nodename{cgi-intro}
-
-A CGI script is invoked by an HTTP server, usually to process user
-input submitted through an HTML \code{<FORM>} or \code{<ISINDEX>} element.
-
-Most often, CGI scripts live in the server's special \file{cgi-bin}
-directory. The HTTP server places all sorts of information about the
-request (such as the client's hostname, the requested URL, the query
-string, and lots of other goodies) in the script's shell environment,
-executes the script, and sends the script's output back to the client.
-
-The script's input is connected to the client too, and sometimes the
-form data is read this way; at other times the form data is passed via
-the ``query string'' part of the URL. This module is intended
-to take care of the different cases and provide a simpler interface to
-the Python script. It also provides a number of utilities that help
-in debugging scripts, and the latest addition is support for file
-uploads from a form (if your browser supports it).
-
-The output of a CGI script should consist of two sections, separated
-by a blank line. The first section contains a number of headers,
-telling the client what kind of data is following. Python code to
-generate a minimal header section looks like this:
-
-\begin{verbatim}
-print "Content-Type: text/html" # HTML is following
-print # blank line, end of headers
-\end{verbatim}
-
-The second section is usually HTML, which allows the client software
-to display nicely formatted text with header, in-line images, etc.
-Here's Python code that prints a simple piece of HTML:
-
-\begin{verbatim}
-print "<TITLE>CGI script output</TITLE>"
-print "<H1>This is my first CGI script</H1>"
-print "Hello, world!"
-\end{verbatim}
-
-\subsection{Using the cgi module}
-\nodename{Using the cgi module}
-
-Begin by writing \samp{import cgi}. Do not use \samp{from cgi import
-*} --- the module defines all sorts of names for its own use or for
-backward compatibility that you don't want in your namespace.
-
-When you write a new script, consider adding the line:
-
-\begin{verbatim}
-import cgitb; cgitb.enable()
-\end{verbatim}
-
-This activates a special exception handler that will display detailed
-reports in the Web browser if any errors occur. If you'd rather not
-show the guts of your program to users of your script, you can have
-the reports saved to files instead, with a line like this:
-
-\begin{verbatim}
-import cgitb; cgitb.enable(display=0, logdir="/tmp")
-\end{verbatim}
-
-It's very helpful to use this feature during script development.
-The reports produced by \refmodule{cgitb} provide information that
-can save you a lot of time in tracking down bugs. You can always
-remove the \code{cgitb} line later when you have tested your script
-and are confident that it works correctly.
-
-To get at submitted form data,
-it's best to use the \class{FieldStorage} class. The other classes
-defined in this module are provided mostly for backward compatibility.
-Instantiate it exactly once, without arguments. This reads the form
-contents from standard input or the environment (depending on the
-value of various environment variables set according to the CGI
-standard). Since it may consume standard input, it should be
-instantiated only once.
-
-The \class{FieldStorage} instance can be indexed like a Python
-dictionary, and also supports the standard dictionary methods
-\method{has_key()} and \method{keys()}. The built-in \function{len()}
-is also supported. Form fields containing empty strings are ignored
-and do not appear in the dictionary; to keep such values, provide
-a true value for the optional \var{keep_blank_values} keyword
-parameter when creating the \class{FieldStorage} instance.
-
-For instance, the following code (which assumes that the
-\mailheader{Content-Type} header and blank line have already been
-printed) checks that the fields \code{name} and \code{addr} are both
-set to a non-empty string:
-
-\begin{verbatim}
-form = cgi.FieldStorage()
-if not (form.has_key("name") and form.has_key("addr")):
- print "<H1>Error</H1>"
- print "Please fill in the name and addr fields."
- return
-print "<p>name:", form["name"].value
-print "<p>addr:", form["addr"].value
-...further form processing here...
-\end{verbatim}
-
-Here the fields, accessed through \samp{form[\var{key}]}, are
-themselves instances of \class{FieldStorage} (or
-\class{MiniFieldStorage}, depending on the form encoding).
-The \member{value} attribute of the instance yields the string value
-of the field. The \method{getvalue()} method returns this string value
-directly; it also accepts an optional second argument as a default to
-return if the requested key is not present.
-
-If the submitted form data contains more than one field with the same
-name, the object retrieved by \samp{form[\var{key}]} is not a
-\class{FieldStorage} or \class{MiniFieldStorage}
-instance but a list of such instances. Similarly, in this situation,
-\samp{form.getvalue(\var{key})} would return a list of strings.
-If you expect this possibility
-(when your HTML form contains multiple fields with the same name), use
-the \function{getlist()} function, which always returns a list of values (so that you
-do not need to special-case the single item case). For example, this
-code concatenates any number of username fields, separated by
-commas:
-
-\begin{verbatim}
-value = form.getlist("username")
-usernames = ",".join(value)
-\end{verbatim}
-
-If a field represents an uploaded file, accessing the value via the
-\member{value} attribute or the \function{getvalue()} method reads the
-entire file in memory as a string. This may not be what you want.
-You can test for an uploaded file by testing either the \member{filename}
-attribute or the \member{file} attribute. You can then read the data at
-leisure from the \member{file} attribute:
-
-\begin{verbatim}
-fileitem = form["userfile"]
-if fileitem.file:
- # It's an uploaded file; count lines
- linecount = 0
- while 1:
- line = fileitem.file.readline()
- if not line: break
- linecount = linecount + 1
-\end{verbatim}
-
-The file upload draft standard entertains the possibility of uploading
-multiple files from one field (using a recursive
-\mimetype{multipart/*} encoding). When this occurs, the item will be
-a dictionary-like \class{FieldStorage} item. This can be determined
-by testing its \member{type} attribute, which should be
-\mimetype{multipart/form-data} (or perhaps another MIME type matching
-\mimetype{multipart/*}). In this case, it can be iterated over
-recursively just like the top-level form object.
-
-When a form is submitted in the ``old'' format (as the query string or
-as a single data part of type
-\mimetype{application/x-www-form-urlencoded}), the items will actually
-be instances of the class \class{MiniFieldStorage}. In this case, the
-\member{list}, \member{file}, and \member{filename} attributes are
-always \code{None}.
-
-
-\subsection{Higher Level Interface}
-
-\versionadded{2.2} % XXX: Is this true ?
-
-The previous section explains how to read CGI form data using the
-\class{FieldStorage} class. This section describes a higher level
-interface which was added to this class to allow one to do it in a
-more readable and intuitive way. The interface doesn't make the
-techniques described in previous sections obsolete --- they are still
-useful to process file uploads efficiently, for example.
-
-The interface consists of two simple methods. Using the methods
-you can process form data in a generic way, without the need to worry
-whether only one or more values were posted under one name.
-
-In the previous section, you learned to write following code anytime
-you expected a user to post more than one value under one name:
-
-\begin{verbatim}
-item = form.getvalue("item")
-if isinstance(item, list):
- # The user is requesting more than one item.
-else:
- # The user is requesting only one item.
-\end{verbatim}
-
-This situation is common for example when a form contains a group of
-multiple checkboxes with the same name:
-
-\begin{verbatim}
-<input type="checkbox" name="item" value="1" />
-<input type="checkbox" name="item" value="2" />
-\end{verbatim}
-
-In most situations, however, there's only one form control with a
-particular name in a form and then you expect and need only one value
-associated with this name. So you write a script containing for
-example this code:
-
-\begin{verbatim}
-user = form.getvalue("user").upper()
-\end{verbatim}
-
-The problem with the code is that you should never expect that a
-client will provide valid input to your scripts. For example, if a
-curious user appends another \samp{user=foo} pair to the query string,
-then the script would crash, because in this situation the
-\code{getvalue("user")} method call returns a list instead of a
-string. Calling the \method{toupper()} method on a list is not valid
-(since lists do not have a method of this name) and results in an
-\exception{AttributeError} exception.
-
-Therefore, the appropriate way to read form data values was to always
-use the code which checks whether the obtained value is a single value
-or a list of values. That's annoying and leads to less readable
-scripts.
-
-A more convenient approach is to use the methods \method{getfirst()}
-and \method{getlist()} provided by this higher level interface.
-
-\begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}}
- This method always returns only one value associated with form field
- \var{name}. The method returns only the first value in case that
- more values were posted under such name. Please note that the order
- in which the values are received may vary from browser to browser
- and should not be counted on.\footnote{Note that some recent
- versions of the HTML specification do state what order the
- field values should be supplied in, but knowing whether a
- request was received from a conforming browser, or even from a
- browser at all, is tedious and error-prone.} If no such form
- field or value exists then the method returns the value specified by
- the optional parameter \var{default}. This parameter defaults to
- \code{None} if not specified.
-\end{methoddesc}
-
-\begin{methoddesc}[FieldStorage]{getlist}{name}
- This method always returns a list of values associated with form
- field \var{name}. The method returns an empty list if no such form
- field or value exists for \var{name}. It returns a list consisting
- of one item if only one such value exists.
-\end{methoddesc}
-
-Using these methods you can write nice compact code:
-
-\begin{verbatim}
-import cgi
-form = cgi.FieldStorage()
-user = form.getfirst("user", "").upper() # This way it's safe.
-for item in form.getlist("item"):
- do_something(item)
-\end{verbatim}
-
-
-\subsection{Old classes}
-
-These classes, present in earlier versions of the \module{cgi} module,
-are still supported for backward compatibility. New applications
-should use the \class{FieldStorage} class.
-
-\class{SvFormContentDict} stores single value form content as
-dictionary; it assumes each field name occurs in the form only once.
-
-\class{FormContentDict} stores multiple value form content as a
-dictionary (the form items are lists of values). Useful if your form
-contains multiple fields with the same name.
-
-Other classes (\class{FormContent}, \class{InterpFormContentDict}) are
-present for backwards compatibility with really old applications only.
-If you still use these and would be inconvenienced when they
-disappeared from a next version of this module, drop me a note.
-
-
-\subsection{Functions}
-\nodename{Functions in cgi module}
-
-These are useful if you want more control, or if you want to employ
-some of the algorithms implemented in this module in other
-circumstances.
-
-\begin{funcdesc}{parse}{fp\optional{, keep_blank_values\optional{,
- strict_parsing}}}
- Parse a query in the environment or from a file (the file defaults
- to \code{sys.stdin}). The \var{keep_blank_values} and
- \var{strict_parsing} parameters are passed to \function{parse_qs()}
- unchanged.
-\end{funcdesc}
-
-\begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{,
- strict_parsing}}}
-Parse a query string given as a string argument (data of type
-\mimetype{application/x-www-form-urlencoded}). Data are
-returned as a dictionary. The dictionary keys are the unique query
-variable names and the values are lists of values for each name.
-
-The optional argument \var{keep_blank_values} is
-a flag indicating whether blank values in
-URL encoded queries should be treated as blank strings.
-A true value indicates that blanks should be retained as
-blank strings. The default false value indicates that
-blank values are to be ignored and treated as if they were
-not included.
-
-The optional argument \var{strict_parsing} is a flag indicating what
-to do with parsing errors. If false (the default), errors
-are silently ignored. If true, errors raise a \exception{ValueError}
-exception.
-
-Use the \function{\refmodule{urllib}.urlencode()} function to convert
-such dictionaries into query strings.
-
-\end{funcdesc}
-
-\begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{,
- strict_parsing}}}
-Parse a query string given as a string argument (data of type
-\mimetype{application/x-www-form-urlencoded}). Data are
-returned as a list of name, value pairs.
-
-The optional argument \var{keep_blank_values} is
-a flag indicating whether blank values in
-URL encoded queries should be treated as blank strings.
-A true value indicates that blanks should be retained as
-blank strings. The default false value indicates that
-blank values are to be ignored and treated as if they were
-not included.
-
-The optional argument \var{strict_parsing} is a flag indicating what
-to do with parsing errors. If false (the default), errors
-are silently ignored. If true, errors raise a \exception{ValueError}
-exception.
-
-Use the \function{\refmodule{urllib}.urlencode()} function to convert
-such lists of pairs into query strings.
-\end{funcdesc}
-
-\begin{funcdesc}{parse_multipart}{fp, pdict}
-Parse input of type \mimetype{multipart/form-data} (for
-file uploads). Arguments are \var{fp} for the input file and
-\var{pdict} for a dictionary containing other parameters in
-the \mailheader{Content-Type} header.
-
-Returns a dictionary just like \function{parse_qs()} keys are the
-field names, each value is a list of values for that field. This is
-easy to use but not much good if you are expecting megabytes to be
-uploaded --- in that case, use the \class{FieldStorage} class instead
-which is much more flexible.
-
-Note that this does not parse nested multipart parts --- use
-\class{FieldStorage} for that.
-\end{funcdesc}
-
-\begin{funcdesc}{parse_header}{string}
-Parse a MIME header (such as \mailheader{Content-Type}) into a main
-value and a dictionary of parameters.
-\end{funcdesc}
-
-\begin{funcdesc}{test}{}
-Robust test CGI script, usable as main program.
-Writes minimal HTTP headers and formats all information provided to
-the script in HTML form.
-\end{funcdesc}
-
-\begin{funcdesc}{print_environ}{}
-Format the shell environment in HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{print_form}{form}
-Format a form in HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{print_directory}{}
-Format the current directory in HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{print_environ_usage}{}
-Print a list of useful (used by CGI) environment variables in
-HTML.
-\end{funcdesc}
-
-\begin{funcdesc}{escape}{s\optional{, quote}}
-Convert the characters
-\character{\&}, \character{<} and \character{>} in string \var{s} to
-HTML-safe sequences. Use this if you need to display text that might
-contain such characters in HTML. If the optional flag \var{quote} is
-true, the quotation mark character (\character{"}) is also translated;
-this helps for inclusion in an HTML attribute value, as in \code{<A
-HREF="...">}. If the value to be quoted might include single- or
-double-quote characters, or both, consider using the
-\function{quoteattr()} function in the \refmodule{xml.sax.saxutils}
-module instead.
-\end{funcdesc}
-
-
-\subsection{Caring about security \label{cgi-security}}
-
-\indexii{CGI}{security}
-
-There's one important rule: if you invoke an external program (via the
-\function{os.system()} or \function{os.popen()} functions. or others
-with similar functionality), make very sure you don't pass arbitrary
-strings received from the client to the shell. This is a well-known
-security hole whereby clever hackers anywhere on the Web can exploit a
-gullible CGI script to invoke arbitrary shell commands. Even parts of
-the URL or field names cannot be trusted, since the request doesn't
-have to come from your form!
-
-To be on the safe side, if you must pass a string gotten from a form
-to a shell command, you should make sure the string contains only
-alphanumeric characters, dashes, underscores, and periods.
-
-
-\subsection{Installing your CGI script on a \UNIX\ system}
-
-Read the documentation for your HTTP server and check with your local
-system administrator to find the directory where CGI scripts should be
-installed; usually this is in a directory \file{cgi-bin} in the server tree.
-
-Make sure that your script is readable and executable by ``others''; the
-\UNIX{} file mode should be \code{0755} octal (use \samp{chmod 0755
-\var{filename}}). Make sure that the first line of the script contains
-\code{\#!} starting in column 1 followed by the pathname of the Python
-interpreter, for instance:
-
-\begin{verbatim}
-#!/usr/local/bin/python
-\end{verbatim}
-
-Make sure the Python interpreter exists and is executable by ``others''.
-
-Make sure that any files your script needs to read or write are
-readable or writable, respectively, by ``others'' --- their mode
-should be \code{0644} for readable and \code{0666} for writable. This
-is because, for security reasons, the HTTP server executes your script
-as user ``nobody'', without any special privileges. It can only read
-(write, execute) files that everybody can read (write, execute). The
-current directory at execution time is also different (it is usually
-the server's cgi-bin directory) and the set of environment variables
-is also different from what you get when you log in. In particular, don't
-count on the shell's search path for executables (\envvar{PATH}) or
-the Python module search path (\envvar{PYTHONPATH}) to be set to
-anything interesting.
-
-If you need to load modules from a directory which is not on Python's
-default module search path, you can change the path in your script,
-before importing other modules. For example:
-
-\begin{verbatim}
-import sys
-sys.path.insert(0, "/usr/home/joe/lib/python")
-sys.path.insert(0, "/usr/local/lib/python")
-\end{verbatim}
-
-(This way, the directory inserted last will be searched first!)
-
-Instructions for non-\UNIX{} systems will vary; check your HTTP server's
-documentation (it will usually have a section on CGI scripts).
-
-
-\subsection{Testing your CGI script}
-
-Unfortunately, a CGI script will generally not run when you try it
-from the command line, and a script that works perfectly from the
-command line may fail mysteriously when run from the server. There's
-one reason why you should still test your script from the command
-line: if it contains a syntax error, the Python interpreter won't
-execute it at all, and the HTTP server will most likely send a cryptic
-error to the client.
-
-Assuming your script has no syntax errors, yet it does not work, you
-have no choice but to read the next section.
-
-
-\subsection{Debugging CGI scripts} \indexii{CGI}{debugging}
-
-First of all, check for trivial installation errors --- reading the
-section above on installing your CGI script carefully can save you a
-lot of time. If you wonder whether you have understood the
-installation procedure correctly, try installing a copy of this module
-file (\file{cgi.py}) as a CGI script. When invoked as a script, the file
-will dump its environment and the contents of the form in HTML form.
-Give it the right mode etc, and send it a request. If it's installed
-in the standard \file{cgi-bin} directory, it should be possible to send it a
-request by entering a URL into your browser of the form:
-
-\begin{verbatim}
-http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
-\end{verbatim}
-
-If this gives an error of type 404, the server cannot find the script
--- perhaps you need to install it in a different directory. If it
-gives another error, there's an installation problem that
-you should fix before trying to go any further. If you get a nicely
-formatted listing of the environment and form content (in this
-example, the fields should be listed as ``addr'' with value ``At Home''
-and ``name'' with value ``Joe Blow''), the \file{cgi.py} script has been
-installed correctly. If you follow the same procedure for your own
-script, you should now be able to debug it.
-
-The next step could be to call the \module{cgi} module's
-\function{test()} function from your script: replace its main code
-with the single statement
-
-\begin{verbatim}
-cgi.test()
-\end{verbatim}
-
-This should produce the same results as those gotten from installing
-the \file{cgi.py} file itself.
-
-When an ordinary Python script raises an unhandled exception (for
-whatever reason: of a typo in a module name, a file that can't be
-opened, etc.), the Python interpreter prints a nice traceback and
-exits. While the Python interpreter will still do this when your CGI
-script raises an exception, most likely the traceback will end up in
-one of the HTTP server's log files, or be discarded altogether.
-
-Fortunately, once you have managed to get your script to execute
-\emph{some} code, you can easily send tracebacks to the Web browser
-using the \refmodule{cgitb} module. If you haven't done so already,
-just add the line:
-
-\begin{verbatim}
-import cgitb; cgitb.enable()
-\end{verbatim}
-
-to the top of your script. Then try running it again; when a
-problem occurs, you should see a detailed report that will
-likely make apparent the cause of the crash.
-
-If you suspect that there may be a problem in importing the
-\refmodule{cgitb} module, you can use an even more robust approach
-(which only uses built-in modules):
-
-\begin{verbatim}
-import sys
-sys.stderr = sys.stdout
-print "Content-Type: text/plain"
-print
-...your code here...
-\end{verbatim}
-
-This relies on the Python interpreter to print the traceback. The
-content type of the output is set to plain text, which disables all
-HTML processing. If your script works, the raw HTML will be displayed
-by your client. If it raises an exception, most likely after the
-first two lines have been printed, a traceback will be displayed.
-Because no HTML interpretation is going on, the traceback will be
-readable.
-
-
-\subsection{Common problems and solutions}
-
-\begin{itemize}
-\item Most HTTP servers buffer the output from CGI scripts until the
-script is completed. This means that it is not possible to display a
-progress report on the client's display while the script is running.
-
-\item Check the installation instructions above.
-
-\item Check the HTTP server's log files. (\samp{tail -f logfile} in a
-separate window may be useful!)
-
-\item Always check a script for syntax errors first, by doing something
-like \samp{python script.py}.
-
-\item If your script does not have any syntax errors, try adding
-\samp{import cgitb; cgitb.enable()} to the top of the script.
-
-\item When invoking external programs, make sure they can be found.
-Usually, this means using absolute path names --- \envvar{PATH} is
-usually not set to a very useful value in a CGI script.
-
-\item When reading or writing external files, make sure they can be read
-or written by the userid under which your CGI script will be running:
-this is typically the userid under which the web server is running, or some
-explicitly specified userid for a web server's \samp{suexec} feature.
-
-\item Don't try to give a CGI script a set-uid mode. This doesn't work on
-most systems, and is a security liability as well.
-\end{itemize}
-
diff --git a/Doc/lib/libcgihttp.tex b/Doc/lib/libcgihttp.tex
deleted file mode 100644
index df0728e..0000000
--- a/Doc/lib/libcgihttp.tex
+++ /dev/null
@@ -1,70 +0,0 @@
-\section{\module{CGIHTTPServer} ---
- CGI-capable HTTP request handler}
-
-
-\declaremodule{standard}{CGIHTTPServer}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{This module provides a request handler for HTTP servers
- which can run CGI scripts.}
-
-
-The \module{CGIHTTPServer} module defines a request-handler class,
-interface compatible with
-\class{BaseHTTPServer.BaseHTTPRequestHandler} and inherits behavior
-from \class{SimpleHTTPServer.SimpleHTTPRequestHandler} but can also
-run CGI scripts.
-
-\note{This module can run CGI scripts on \UNIX{} and Windows systems;
-on Mac OS it will only be able to run Python scripts within the same
-process as itself.}
-
-\note{CGI scripts run by the \class{CGIHTTPRequestHandler} class cannot execute
-redirects (HTTP code 302), because code 200 (script output follows)
-is sent prior to execution of the CGI script. This pre-empts the status
-code.}
-
-The \module{CGIHTTPServer} module defines the following class:
-
-\begin{classdesc}{CGIHTTPRequestHandler}{request, client_address, server}
-This class is used to serve either files or output of CGI scripts from
-the current directory and below. Note that mapping HTTP hierarchic
-structure to local directory structure is exactly as in
-\class{SimpleHTTPServer.SimpleHTTPRequestHandler}.
-
-The class will however, run the CGI script, instead of serving it as a
-file, if it guesses it to be a CGI script. Only directory-based CGI
-are used --- the other common server configuration is to treat special
-extensions as denoting CGI scripts.
-
-The \function{do_GET()} and \function{do_HEAD()} functions are
-modified to run CGI scripts and serve the output, instead of serving
-files, if the request leads to somewhere below the
-\code{cgi_directories} path.
-\end{classdesc}
-
-The \class{CGIHTTPRequestHandler} defines the following data member:
-
-\begin{memberdesc}{cgi_directories}
-This defaults to \code{['/cgi-bin', '/htbin']} and describes
-directories to treat as containing CGI scripts.
-\end{memberdesc}
-
-The \class{CGIHTTPRequestHandler} defines the following methods:
-
-\begin{methoddesc}{do_POST}{}
-This method serves the \code{'POST'} request type, only allowed for
-CGI scripts. Error 501, "Can only POST to CGI scripts", is output
-when trying to POST to a non-CGI url.
-\end{methoddesc}
-
-Note that CGI scripts will be run with UID of user nobody, for security
-reasons. Problems with the CGI script will be translated to error 403.
-
-For example usage, see the implementation of the \function{test()}
-function.
-
-
-\begin{seealso}
- \seemodule{BaseHTTPServer}{Base class implementation for Web server
- and request handler.}
-\end{seealso}
diff --git a/Doc/lib/libcgitb.tex b/Doc/lib/libcgitb.tex
deleted file mode 100644
index ca9959f..0000000
--- a/Doc/lib/libcgitb.tex
+++ /dev/null
@@ -1,67 +0,0 @@
-\section{\module{cgitb} ---
- Traceback manager for CGI scripts}
-
-\declaremodule{standard}{cgitb}
-\modulesynopsis{Configurable traceback handler for CGI scripts.}
-\moduleauthor{Ka-Ping Yee}{ping@lfw.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{2.2}
-\index{CGI!exceptions}
-\index{CGI!tracebacks}
-\index{exceptions!in CGI scripts}
-\index{tracebacks!in CGI scripts}
-
-The \module{cgitb} module provides a special exception handler for Python
-scripts. (Its name is a bit misleading. It was originally designed to
-display extensive traceback information in HTML for CGI scripts. It was
-later generalized to also display this information in plain text.) After
-this module is activated, if an uncaught exception occurs, a detailed,
-formatted report will be displayed. The report
-includes a traceback showing excerpts of the source code for each level,
-as well as the values of the arguments and local variables to currently
-running functions, to help you debug the problem. Optionally, you can
-save this information to a file instead of sending it to the browser.
-
-To enable this feature, simply add one line to the top of your CGI script:
-
-\begin{verbatim}
-import cgitb; cgitb.enable()
-\end{verbatim}
-
-The options to the \function{enable()} function control whether the
-report is displayed in the browser and whether the report is logged
-to a file for later analysis.
-
-
-\begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
- context\optional{, format}}}}}
- This function causes the \module{cgitb} module to take over the
- interpreter's default handling for exceptions by setting the
- value of \member{\refmodule{sys}.excepthook}.
- \withsubitem{(in module sys)}{\ttindex{excepthook()}}
-
- The optional argument \var{display} defaults to \code{1} and can be set
- to \code{0} to suppress sending the traceback to the browser.
- If the argument \var{logdir} is present, the traceback reports are
- written to files. The value of \var{logdir} should be a directory
- where these files will be placed.
- The optional argument \var{context} is the number of lines of
- context to display around the current line of source code in the
- traceback; this defaults to \code{5}.
- If the optional argument \var{format} is \code{"html"}, the output is
- formatted as HTML. Any other value forces plain text output. The default
- value is \code{"html"}.
-\end{funcdesc}
-
-\begin{funcdesc}{handler}{\optional{info}}
- This function handles an exception using the default settings
- (that is, show a report in the browser, but don't log to a file).
- This can be used when you've caught an exception and want to
- report it using \module{cgitb}. The optional \var{info} argument
- should be a 3-tuple containing an exception type, exception
- value, and traceback object, exactly like the tuple returned by
- \function{\refmodule{sys}.exc_info()}. If the \var{info} argument
- is not supplied, the current exception is obtained from
- \function{\refmodule{sys}.exc_info()}.
-\end{funcdesc}
diff --git a/Doc/lib/libchunk.tex b/Doc/lib/libchunk.tex
deleted file mode 100644
index 8e2a494..0000000
--- a/Doc/lib/libchunk.tex
+++ /dev/null
@@ -1,111 +0,0 @@
-\section{\module{chunk} ---
- Read IFF chunked data}
-
-\declaremodule{standard}{chunk}
-\modulesynopsis{Module to read IFF chunks.}
-\moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
-\sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
-
-
-
-This module provides an interface for reading files that use EA IFF 85
-chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
-Jerry Morrison, Electronic Arts, January 1985.} This format is used
-in at least the Audio\index{Audio Interchange File
-Format}\index{AIFF}\index{AIFF-C} Interchange File Format
-(AIFF/AIFF-C) and the Real\index{Real Media File Format} Media File
-Format\index{RMFF} (RMFF). The WAVE audio file format is closely
-related and can also be read using this module.
-
-A chunk has the following structure:
-
-\begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
- \lineiii{0}{4}{Chunk ID}
- \lineiii{4}{4}{Size of chunk in big-endian byte order, not including the
- header}
- \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
- the preceding field}
- \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and
- chunk alignment is used}
-\end{tableiii}
-
-The ID is a 4-byte string which identifies the type of chunk.
-
-The size field (a 32-bit value, encoded using big-endian byte order)
-gives the size of the chunk data, not including the 8-byte header.
-
-Usually an IFF-type file consists of one or more chunks. The proposed
-usage of the \class{Chunk} class defined here is to instantiate an
-instance at the start of each chunk and read from the instance until
-it reaches the end, after which a new instance can be instantiated.
-At the end of the file, creating a new instance will fail with a
-\exception{EOFError} exception.
-
-\begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}}
-Class which represents a chunk. The \var{file} argument is expected
-to be a file-like object. An instance of this class is specifically
-allowed. The only method that is needed is \method{read()}. If the
-methods \method{seek()} and \method{tell()} are present and don't
-raise an exception, they are also used. If these methods are present
-and raise an exception, they are expected to not have altered the
-object. If the optional argument \var{align} is true, chunks are
-assumed to be aligned on 2-byte boundaries. If \var{align} is
-false, no alignment is assumed. The default value is true. If the
-optional argument \var{bigendian} is false, the chunk size is assumed
-to be in little-endian order. This is needed for WAVE audio files.
-The default value is true. If the optional argument \var{inclheader}
-is true, the size given in the chunk header includes the size of the
-header. The default value is false.
-\end{classdesc}
-
-A \class{Chunk} object supports the following methods:
-
-\begin{methoddesc}{getname}{}
-Returns the name (ID) of the chunk. This is the first 4 bytes of the
-chunk.
-\end{methoddesc}
-
-\begin{methoddesc}{getsize}{}
-Returns the size of the chunk.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Close and skip to the end of the chunk. This does not close the
-underlying file.
-\end{methoddesc}
-
-The remaining methods will raise \exception{IOError} if called after
-the \method{close()} method has been called.
-
-\begin{methoddesc}{isatty}{}
-Returns \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}{seek}{pos\optional{, whence}}
-Set the chunk's current position. The \var{whence} argument is
-optional and defaults to \code{0} (absolute file positioning); other
-values are \code{1} (seek relative to the current position) and
-\code{2} (seek relative to the file's end). There is no return value.
-If the underlying file does not allow seek, only forward seeks are
-allowed.
-\end{methoddesc}
-
-\begin{methoddesc}{tell}{}
-Return the current position into the chunk.
-\end{methoddesc}
-
-\begin{methoddesc}{read}{\optional{size}}
-Read at most \var{size} bytes from the chunk (less if the read hits
-the end of the chunk before obtaining \var{size} bytes). If the
-\var{size} argument is negative or omitted, read all data until the
-end of the chunk. The bytes are returned as a string object. An
-empty string is returned when the end of the chunk is encountered
-immediately.
-\end{methoddesc}
-
-\begin{methoddesc}{skip}{}
-Skip to the end of the chunk. All further calls to \method{read()}
-for the chunk will return \code{''}. If you are not interested in the
-contents of the chunk, this method should be called so that the file
-points to the start of the next chunk.
-\end{methoddesc}
diff --git a/Doc/lib/libcmath.tex b/Doc/lib/libcmath.tex
deleted file mode 100644
index f8aa45b..0000000
--- a/Doc/lib/libcmath.tex
+++ /dev/null
@@ -1,149 +0,0 @@
-\section{\module{cmath} ---
- Mathematical functions for complex numbers}
-
-\declaremodule{builtin}{cmath}
-\modulesynopsis{Mathematical functions for complex numbers.}
-
-This module is always available. It provides access to mathematical
-functions for complex numbers. The functions in this module accept
-integers, floating-point numbers or complex numbers as arguments.
-They will also accept any Python object that has either a
-\method{__complex__} or a \method{__float__} method: these methods are
-used to convert the object to a complex or floating-point number, respectively, and
-the function is then applied to the result of the conversion.
-
-The functions are:
-
-\begin{funcdesc}{acos}{x}
-Return the arc cosine of \var{x}.
-There are two branch cuts:
-One extends right from 1 along the real axis to \infinity, continuous
-from below.
-The other extends left from -1 along the real axis to -\infinity,
-continuous from above.
-\end{funcdesc}
-
-\begin{funcdesc}{acosh}{x}
-Return the hyperbolic arc cosine of \var{x}.
-There is one branch cut, extending left from 1 along the real axis
-to -\infinity, continuous from above.
-\end{funcdesc}
-
-\begin{funcdesc}{asin}{x}
-Return the arc sine of \var{x}.
-This has the same branch cuts as \function{acos()}.
-\end{funcdesc}
-
-\begin{funcdesc}{asinh}{x}
-Return the hyperbolic arc sine of \var{x}.
-There are two branch cuts, extending left from \plusminus\code{1j} to
-\plusminus-\infinity\code{j}, both continuous from above.
-These branch cuts should be considered a bug to be corrected in a
-future release.
-The correct branch cuts should extend along the imaginary axis,
-one from \code{1j} up to \infinity\code{j} and continuous from the
-right, and one from -\code{1j} down to -\infinity\code{j} and
-continuous from the left.
-\end{funcdesc}
-
-\begin{funcdesc}{atan}{x}
-Return the arc tangent of \var{x}.
-There are two branch cuts:
-One extends from \code{1j} along the imaginary axis to
-\infinity\code{j}, continuous from the left.
-The other extends from -\code{1j} along the imaginary axis to
--\infinity\code{j}, continuous from the left.
-(This should probably be changed so the upper cut becomes continuous
-from the other side.)
-\end{funcdesc}
-
-\begin{funcdesc}{atanh}{x}
-Return the hyperbolic arc tangent of \var{x}.
-There are two branch cuts:
-One extends from 1 along the real axis to \infinity, continuous
-from above.
-The other extends from -1 along the real axis to -\infinity,
-continuous from above.
-(This should probably be changed so the right cut becomes continuous from
-the other side.)
-\end{funcdesc}
-
-\begin{funcdesc}{cos}{x}
-Return the cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{cosh}{x}
-Return the hyperbolic cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{exp}{x}
-Return the exponential value \code{e**\var{x}}.
-\end{funcdesc}
-
-\begin{funcdesc}{log}{x\optional{, base}}
-Returns the logarithm of \var{x} to the given \var{base}.
-If the \var{base} is not specified, returns the natural logarithm of \var{x}.
-There is one branch cut, from 0 along the negative real axis to
--\infinity, continuous from above.
-\versionchanged[\var{base} argument added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{log10}{x}
-Return the base-10 logarithm of \var{x}.
-This has the same branch cut as \function{log()}.
-\end{funcdesc}
-
-\begin{funcdesc}{sin}{x}
-Return the sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{sinh}{x}
-Return the hyperbolic sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{sqrt}{x}
-Return the square root of \var{x}.
-This has the same branch cut as \function{log()}.
-\end{funcdesc}
-
-\begin{funcdesc}{tan}{x}
-Return the tangent of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{tanh}{x}
-Return the hyperbolic tangent of \var{x}.
-\end{funcdesc}
-
-The module also defines two mathematical constants:
-
-\begin{datadesc}{pi}
-The mathematical constant \emph{pi}, as a real.
-\end{datadesc}
-
-\begin{datadesc}{e}
-The mathematical constant \emph{e}, as a real.
-\end{datadesc}
-
-Note that the selection of functions is similar, but not identical, to
-that in module \refmodule{math}\refbimodindex{math}. The reason for having
-two modules is that some users aren't interested in complex numbers,
-and perhaps don't even know what they are. They would rather have
-\code{math.sqrt(-1)} raise an exception than return a complex number.
-Also note that the functions defined in \module{cmath} always return a
-complex number, even if the answer can be expressed as a real number
-(in which case the complex number has an imaginary part of zero).
-
-A note on branch cuts: They are curves along which the given function
-fails to be continuous. They are a necessary feature of many complex
-functions. It is assumed that if you need to compute with complex
-functions, you will understand about branch cuts. Consult almost any
-(not too elementary) book on complex variables for enlightenment. For
-information of the proper choice of branch cuts for numerical
-purposes, a good reference should be the following:
-
-\begin{seealso}
- \seetext{Kahan, W: Branch cuts for complex elementary functions;
- or, Much ado about nothing's sign bit. In Iserles, A.,
- and Powell, M. (eds.), \citetitle{The state of the art in
- numerical analysis}. Clarendon Press (1987) pp165-211.}
-\end{seealso}
diff --git a/Doc/lib/libcmd.tex b/Doc/lib/libcmd.tex
deleted file mode 100644
index 810f19c..0000000
--- a/Doc/lib/libcmd.tex
+++ /dev/null
@@ -1,198 +0,0 @@
-\section{\module{cmd} ---
- Support for line-oriented command interpreters}
-
-\declaremodule{standard}{cmd}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\modulesynopsis{Build line-oriented command interpreters.}
-
-
-The \class{Cmd} class provides a simple framework for writing
-line-oriented command interpreters. These are often useful for
-test harnesses, administrative tools, and prototypes that will
-later be wrapped in a more sophisticated interface.
-
-\begin{classdesc}{Cmd}{\optional{completekey\optional{,
- stdin\optional{, stdout}}}}
-A \class{Cmd} instance or subclass instance is a line-oriented
-interpreter framework. There is no good reason to instantiate
-\class{Cmd} itself; rather, it's useful as a superclass of an
-interpreter class you define yourself in order to inherit
-\class{Cmd}'s methods and encapsulate action methods.
-
-The optional argument \var{completekey} is the \refmodule{readline} name
-of a completion key; it defaults to \kbd{Tab}. If \var{completekey} is
-not \constant{None} and \refmodule{readline} is available, command completion
-is done automatically.
-
-The optional arguments \var{stdin} and \var{stdout} specify the
-input and output file objects that the Cmd instance or subclass
-instance will use for input and output. If not specified, they
-will default to \var{sys.stdin} and \var{sys.stdout}.
-
-\versionchanged[The \var{stdin} and \var{stdout} parameters were added]{2.3}
-\end{classdesc}
-
-\subsection{Cmd Objects}
-\label{Cmd-objects}
-
-A \class{Cmd} instance has the following methods:
-
-\begin{methoddesc}[Cmd]{cmdloop}{\optional{intro}}
-Repeatedly issue a prompt, accept input, parse an initial prefix off
-the received input, and dispatch to action methods, passing them the
-remainder of the line as argument.
-
-The optional argument is a banner or intro string to be issued before the
-first prompt (this overrides the \member{intro} class member).
-
-If the \refmodule{readline} module is loaded, input will automatically
-inherit \program{bash}-like history-list editing (e.g. \kbd{Control-P}
-scrolls back to the last command, \kbd{Control-N} forward to the next
-one, \kbd{Control-F} moves the cursor to the right non-destructively,
-\kbd{Control-B} moves the cursor to the left non-destructively, etc.).
-
-An end-of-file on input is passed back as the string \code{'EOF'}.
-
-An interpreter instance will recognize a command name \samp{foo} if
-and only if it has a method \method{do_foo()}. As a special case,
-a line beginning with the character \character{?} is dispatched to
-the method \method{do_help()}. As another special case, a line
-beginning with the character \character{!} is dispatched to the
-method \method{do_shell()} (if such a method is defined).
-
-This method will return when the \method{postcmd()} method returns a
-true value. The \var{stop} argument to \method{postcmd()} is the
-return value from the command's corresponding \method{do_*()} method.
-
-If completion is enabled, completing commands will be done
-automatically, and completing of commands args is done by calling
-\method{complete_foo()} with arguments \var{text}, \var{line},
-\var{begidx}, and \var{endidx}. \var{text} is the string prefix we
-are attempting to match: all returned matches must begin with it.
-\var{line} is the current input line with leading whitespace removed,
-\var{begidx} and \var{endidx} are the beginning and ending indexes
-of the prefix text, which could be used to provide different
-completion depending upon which position the argument is in.
-
-All subclasses of \class{Cmd} inherit a predefined \method{do_help()}.
-This method, called with an argument \code{'bar'}, invokes the
-corresponding method \method{help_bar()}. With no argument,
-\method{do_help()} lists all available help topics (that is, all
-commands with corresponding \method{help_*()} methods), and also lists
-any undocumented commands.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{onecmd}{str}
-Interpret the argument as though it had been typed in response to the
-prompt. This may be overridden, but should not normally need to be;
-see the \method{precmd()} and \method{postcmd()} methods for useful
-execution hooks. The return value is a flag indicating whether
-interpretation of commands by the interpreter should stop. If there
-is a \method{do_*()} method for the command \var{str}, the return
-value of that method is returned, otherwise the return value from the
-\method{default()} method is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{emptyline}{}
-Method called when an empty line is entered in response to the prompt.
-If this method is not overridden, it repeats the last nonempty command
-entered.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{default}{line}
-Method called on an input line when the command prefix is not
-recognized. If this method is not overridden, it prints an
-error message and returns.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{completedefault}{text, line, begidx, endidx}
-Method called to complete an input line when no command-specific
-\method{complete_*()} method is available. By default, it returns an
-empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{precmd}{line}
-Hook method executed just before the command line \var{line} is
-interpreted, but after the input prompt is generated and issued. This
-method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses. The return value is used as the command which will be
-executed by the \method{onecmd()} method; the \method{precmd()}
-implementation may re-write the command or simply return \var{line}
-unchanged.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{postcmd}{stop, line}
-Hook method executed just after a command dispatch is finished. This
-method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses. \var{line} is the command line which was executed, and
-\var{stop} is a flag which indicates whether execution will be
-terminated after the call to \method{postcmd()}; this will be the
-return value of the \method{onecmd()} method. The return value of
-this method will be used as the new value for the internal flag which
-corresponds to \var{stop}; returning false will cause interpretation
-to continue.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{preloop}{}
-Hook method executed once when \method{cmdloop()} is called. This
-method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses.
-\end{methoddesc}
-
-\begin{methoddesc}[Cmd]{postloop}{}
-Hook method executed once when \method{cmdloop()} is about to return.
-This method is a stub in \class{Cmd}; it exists to be overridden by
-subclasses.
-\end{methoddesc}
-
-Instances of \class{Cmd} subclasses have some public instance variables:
-
-\begin{memberdesc}[Cmd]{prompt}
-The prompt issued to solicit input.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{identchars}
-The string of characters accepted for the command prefix.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{lastcmd}
-The last nonempty command prefix seen.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{intro}
-A string to issue as an intro or banner. May be overridden by giving
-the \method{cmdloop()} method an argument.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{doc_header}
-The header to issue if the help output has a section for documented
-commands.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{misc_header}
-The header to issue if the help output has a section for miscellaneous
-help topics (that is, there are \method{help_*()} methods without
-corresponding \method{do_*()} methods).
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{undoc_header}
-The header to issue if the help output has a section for undocumented
-commands (that is, there are \method{do_*()} methods without
-corresponding \method{help_*()} methods).
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{ruler}
-The character used to draw separator lines under the help-message
-headers. If empty, no ruler line is drawn. It defaults to
-\character{=}.
-\end{memberdesc}
-
-\begin{memberdesc}[Cmd]{use_rawinput}
-A flag, defaulting to true. If true, \method{cmdloop()} uses
-\function{input()} to display a prompt and read the next command;
-if false, \method{sys.stdout.write()} and
-\method{sys.stdin.readline()} are used. (This means that by
-importing \refmodule{readline}, on systems that support it, the
-interpreter will automatically support \program{Emacs}-like line editing
-and command-history keystrokes.)
-\end{memberdesc}
diff --git a/Doc/lib/libcmp.tex b/Doc/lib/libcmp.tex
deleted file mode 100644
index 489efee..0000000
--- a/Doc/lib/libcmp.tex
+++ /dev/null
@@ -1,36 +0,0 @@
-\section{\module{cmp} ---
- File comparisons}
-
-\declaremodule{standard}{cmp}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Compare files very efficiently.}
-
-\deprecated{1.6}{Use the \refmodule{filecmp} module instead.}
-
-The \module{cmp} module defines a function to compare files, taking all
-sort of short-cuts to make it a highly efficient operation.
-
-The \module{cmp} module defines the following function:
-
-\begin{funcdesc}{cmp}{f1, f2}
-Compare two files given as names. The following tricks are used to
-optimize the comparisons:
-
-\begin{itemize}
- \item Files with identical type, size and mtime are assumed equal.
- \item Files with different type or size are never equal.
- \item The module only compares files it already compared if their
- signature (type, size and mtime) changed.
- \item No external programs are called.
-\end{itemize}
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import cmp
->>> cmp.cmp('libundoc.tex', 'libundoc.tex')
-1
->>> cmp.cmp('libundoc.tex', 'lib.tex')
-0
-\end{verbatim}
diff --git a/Doc/lib/libcmpcache.tex b/Doc/lib/libcmpcache.tex
deleted file mode 100644
index 8991477..0000000
--- a/Doc/lib/libcmpcache.tex
+++ /dev/null
@@ -1,21 +0,0 @@
-\section{\module{cmpcache} ---
- Efficient file comparisons}
-
-\declaremodule{standard}{cmpcache}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Compare files very efficiently.}
-
-\deprecated{1.6}{Use the \refmodule{filecmp} module instead.}
-
-The \module{cmpcache} module provides an identical interface and similar
-functionality as the \refmodule{cmp} module, but can be a bit more efficient
-as it uses \function{statcache.stat()} instead of \function{os.stat()}
-(see the \refmodule{statcache} module for information on the
-difference).
-
-\note{Using the \refmodule{statcache} module to provide
-\function{stat()} information results in trashing the cache
-invalidation mechanism: results are not as reliable. To ensure
-``current'' results, use \function{cmp.cmp()} instead of the version
-defined in this module, or use \function{statcache.forget()} to
-invalidate the appropriate entries.}
diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex
deleted file mode 100644
index 8e14b02..0000000
--- a/Doc/lib/libcode.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{code} ---
- Interpreter base classes}
-\declaremodule{standard}{code}
-
-\modulesynopsis{Base classes for interactive Python interpreters.}
-
-
-The \code{code} module provides facilities to implement
-read-eval-print loops in Python. Two classes and convenience
-functions are included which can be used to build applications which
-provide an interactive interpreter prompt.
-
-
-\begin{classdesc}{InteractiveInterpreter}{\optional{locals}}
-This class deals with parsing and interpreter state (the user's
-namespace); it does not deal with input buffering or prompting or
-input file naming (the filename is always passed in explicitly).
-The optional \var{locals} argument specifies the dictionary in
-which code will be executed; it defaults to a newly created
-dictionary with key \code{'__name__'} set to \code{'__console__'}
-and key \code{'__doc__'} set to \code{None}.
-\end{classdesc}
-
-\begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}}
-Closely emulate the behavior of the interactive Python interpreter.
-This class builds on \class{InteractiveInterpreter} and adds
-prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and
-input buffering.
-\end{classdesc}
-
-
-\begin{funcdesc}{interact}{\optional{banner\optional{,
- readfunc\optional{, local}}}}
-Convenience function to run a read-eval-print loop. This creates a
-new instance of \class{InteractiveConsole} and sets \var{readfunc}
-to be used as the \method{raw_input()} method, if provided. If
-\var{local} is provided, it is passed to the
-\class{InteractiveConsole} constructor for use as the default
-namespace for the interpreter loop. The \method{interact()} method
-of the instance is then run with \var{banner} passed as the banner
-to use, if provided. The console object is discarded after use.
-\end{funcdesc}
-
-\begin{funcdesc}{compile_command}{source\optional{,
- filename\optional{, symbol}}}
-This function is useful for programs that want to emulate Python's
-interpreter main loop (a.k.a. the read-eval-print loop). The tricky
-part is to determine when the user has entered an incomplete command
-that can be completed by entering more text (as opposed to a
-complete command or a syntax error). This function
-\emph{almost} always makes the same decision as the real interpreter
-main loop.
-
-\var{source} is the source string; \var{filename} is the optional
-filename from which source was read, defaulting to \code{'<input>'};
-and \var{symbol} is the optional grammar start symbol, which should
-be either \code{'single'} (the default) or \code{'eval'}.
-
-Returns a code object (the same as \code{compile(\var{source},
-\var{filename}, \var{symbol})}) if the command is complete and
-valid; \code{None} if the command is incomplete; raises
-\exception{SyntaxError} if the command is complete and contains a
-syntax error, or raises \exception{OverflowError} or
-\exception{ValueError} if the command contains an invalid literal.
-\end{funcdesc}
-
-
-\subsection{Interactive Interpreter Objects
- \label{interpreter-objects}}
-
-\begin{methoddesc}[InteractiveInterpreter]{runsource}{source\optional{, filename\optional{, symbol}}}
-Compile and run some source in the interpreter.
-Arguments are the same as for \function{compile_command()}; the
-default for \var{filename} is \code{'<input>'}, and for
-\var{symbol} is \code{'single'}. One several things can happen:
-
-\begin{itemize}
-\item
-The input is incorrect; \function{compile_command()} raised an
-exception (\exception{SyntaxError} or \exception{OverflowError}). A
-syntax traceback will be printed by calling the
-\method{showsyntaxerror()} method. \method{runsource()} returns
-\code{False}.
-
-\item
-The input is incomplete, and more input is required;
-\function{compile_command()} returned \code{None}.
-\method{runsource()} returns \code{True}.
-
-\item
-The input is complete; \function{compile_command()} returned a code
-object. The code is executed by calling the \method{runcode()} (which
-also handles run-time exceptions, except for \exception{SystemExit}).
-\method{runsource()} returns \code{False}.
-\end{itemize}
-
-The return value can be used to decide whether to use
-\code{sys.ps1} or \code{sys.ps2} to prompt the next line.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{runcode}{code}
-Execute a code object.
-When an exception occurs, \method{showtraceback()} is called to
-display a traceback. All exceptions are caught except
-\exception{SystemExit}, which is allowed to propagate.
-
-A note about \exception{KeyboardInterrupt}: this exception may occur
-elsewhere in this code, and may not always be caught. The caller
-should be prepared to deal with it.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{showsyntaxerror}{\optional{filename}}
-Display the syntax error that just occurred. This does not display
-a stack trace because there isn't one for syntax errors.
-If \var{filename} is given, it is stuffed into the exception instead
-of the default filename provided by Python's parser, because it
-always uses \code{'<string>'} when reading from a string.
-The output is written by the \method{write()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{showtraceback}{}
-Display the exception that just occurred. We remove the first stack
-item because it is within the interpreter object implementation.
-The output is written by the \method{write()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveInterpreter]{write}{data}
-Write a string to the standard error stream (\code{sys.stderr}).
-Derived classes should override this to provide the appropriate output
-handling as needed.
-\end{methoddesc}
-
-
-\subsection{Interactive Console Objects
- \label{console-objects}}
-
-The \class{InteractiveConsole} class is a subclass of
-\class{InteractiveInterpreter}, and so offers all the methods of the
-interpreter objects as well as the following additions.
-
-\begin{methoddesc}[InteractiveConsole]{interact}{\optional{banner}}
-Closely emulate the interactive Python console.
-The optional banner argument specify the banner to print before the
-first interaction; by default it prints a banner similar to the one
-printed by the standard Python interpreter, followed by the class
-name of the console object in parentheses (so as not to confuse this
-with the real interpreter -- since it's so close!).
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveConsole]{push}{line}
-Push a line of source text to the interpreter.
-The line should not have a trailing newline; it may have internal
-newlines. The line is appended to a buffer and the interpreter's
-\method{runsource()} method is called with the concatenated contents
-of the buffer as source. If this indicates that the command was
-executed or invalid, the buffer is reset; otherwise, the command is
-incomplete, and the buffer is left as it was after the line was
-appended. The return value is \code{True} if more input is required,
-\code{False} if the line was dealt with in some way (this is the same as
-\method{runsource()}).
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveConsole]{resetbuffer}{}
-Remove any unhandled source text from the input buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[InteractiveConsole]{raw_input}{\optional{prompt}}
-Write a prompt and read a line. The returned line does not include
-the trailing newline. When the user enters the \EOF{} key sequence,
-\exception{EOFError} is raised. The base implementation reads from
-\code{sys.stdin}; a subclass may replace this
-with a different implementation.
-\end{methoddesc}
diff --git a/Doc/lib/libcodecs.tex b/Doc/lib/libcodecs.tex
deleted file mode 100644
index ee141d9..0000000
--- a/Doc/lib/libcodecs.tex
+++ /dev/null
@@ -1,1341 +0,0 @@
-\section{\module{codecs} ---
- Codec registry and base classes}
-
-\declaremodule{standard}{codecs}
-\modulesynopsis{Encode and decode data and streams.}
-\moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\index{Unicode}
-\index{Codecs}
-\indexii{Codecs}{encode}
-\indexii{Codecs}{decode}
-\index{streams}
-\indexii{stackable}{streams}
-
-
-This module defines base classes for standard Python codecs (encoders
-and decoders) and provides access to the internal Python codec
-registry which manages the codec and error handling lookup process.
-
-It defines the following functions:
-
-\begin{funcdesc}{register}{search_function}
-Register a codec search function. Search functions are expected to
-take one argument, the encoding name in all lower case letters, and
-return a \class{CodecInfo} object having the following attributes:
-
-\begin{itemize}
- \item \code{name} The name of the encoding;
- \item \code{encoder} The stateless encoding function;
- \item \code{decoder} The stateless decoding function;
- \item \code{incrementalencoder} An incremental encoder class or factory function;
- \item \code{incrementaldecoder} An incremental decoder class or factory function;
- \item \code{streamwriter} A stream writer class or factory function;
- \item \code{streamreader} A stream reader class or factory function.
-\end{itemize}
-
-The various functions or classes take the following arguments:
-
- \var{encoder} and \var{decoder}: These must be functions or methods
- which have the same interface as the
- \method{encode()}/\method{decode()} methods of Codec instances (see
- Codec Interface). The functions/methods are expected to work in a
- stateless mode.
-
- \var{incrementalencoder} and \var{incrementalencoder}: These have to be
- factory functions providing the following interface:
-
- \code{factory(\var{errors}='strict')}
-
- The factory functions must return objects providing the interfaces
- defined by the base classes \class{IncrementalEncoder} and
- \class{IncrementalEncoder}, respectively. Incremental codecs can maintain
- state.
-
- \var{streamreader} and \var{streamwriter}: These have to be
- factory functions providing the following interface:
-
- \code{factory(\var{stream}, \var{errors}='strict')}
-
- The factory functions must return objects providing the interfaces
- defined by the base classes \class{StreamWriter} and
- \class{StreamReader}, respectively. Stream codecs can maintain
- state.
-
- Possible values for errors are \code{'strict'} (raise an exception
- in case of an encoding error), \code{'replace'} (replace malformed
- data with a suitable replacement marker, such as \character{?}),
- \code{'ignore'} (ignore malformed data and continue without further
- notice), \code{'xmlcharrefreplace'} (replace with the appropriate XML
- character reference (for encoding only)) and \code{'backslashreplace'}
- (replace with backslashed escape sequences (for encoding only)) as
- well as any other error handling name defined via
- \function{register_error()}.
-
-In case a search function cannot find a given encoding, it should
-return \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{lookup}{encoding}
-Looks up the codec info in the Python codec registry and returns a
-\class{CodecInfo} object as defined above.
-
-Encodings are first looked up in the registry's cache. If not found,
-the list of registered search functions is scanned. If no \class{CodecInfo}
-object is found, a \exception{LookupError} is raised. Otherwise, the
-\class{CodecInfo} object is stored in the cache and returned to the caller.
-\end{funcdesc}
-
-To simplify access to the various codecs, the module provides these
-additional functions which use \function{lookup()} for the codec
-lookup:
-
-\begin{funcdesc}{getencoder}{encoding}
-Look up the codec for the given encoding and return its encoder
-function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getdecoder}{encoding}
-Look up the codec for the given encoding and return its decoder
-function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getincrementalencoder}{encoding}
-Look up the codec for the given encoding and return its incremental encoder
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found or the
-codec doesn't support an incremental encoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{getincrementaldecoder}{encoding}
-Look up the codec for the given encoding and return its incremental decoder
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found or the
-codec doesn't support an incremental decoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{getreader}{encoding}
-Look up the codec for the given encoding and return its StreamReader
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getwriter}{encoding}
-Look up the codec for the given encoding and return its StreamWriter
-class or factory function.
-
-Raises a \exception{LookupError} in case the encoding cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{register_error}{name, error_handler}
-Register the error handling function \var{error_handler} under the
-name \var{name}. \var{error_handler} will be called during encoding
-and decoding in case of an error, when \var{name} is specified as the
-errors parameter.
-
-For encoding \var{error_handler} will be called with a
-\exception{UnicodeEncodeError} instance, which contains information about
-the location of the error. The error handler must either raise this or
-a different exception or return a tuple with a replacement for the
-unencodable part of the input and a position where encoding should
-continue. The encoder will encode the replacement and continue encoding
-the original input at the specified position. Negative position values
-will be treated as being relative to the end of the input string. If the
-resulting position is out of bound an \exception{IndexError} will be raised.
-
-Decoding and translating works similar, except \exception{UnicodeDecodeError}
-or \exception{UnicodeTranslateError} will be passed to the handler and
-that the replacement from the error handler will be put into the output
-directly.
-\end{funcdesc}
-
-\begin{funcdesc}{lookup_error}{name}
-Return the error handler previously registered under the name \var{name}.
-
-Raises a \exception{LookupError} in case the handler cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{strict_errors}{exception}
-Implements the \code{strict} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{replace_errors}{exception}
-Implements the \code{replace} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{ignore_errors}{exception}
-Implements the \code{ignore} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{xmlcharrefreplace_errors_errors}{exception}
-Implements the \code{xmlcharrefreplace} error handling.
-\end{funcdesc}
-
-\begin{funcdesc}{backslashreplace_errors_errors}{exception}
-Implements the \code{backslashreplace} error handling.
-\end{funcdesc}
-
-To simplify working with encoded files or stream, the module
-also defines these utility functions:
-
-\begin{funcdesc}{open}{filename, mode\optional{, encoding\optional{,
- errors\optional{, buffering}}}}
-Open an encoded file using the given \var{mode} and return
-a wrapped version providing transparent encoding/decoding.
-
-\note{The wrapped version will only accept the object format
-defined by the codecs, i.e.\ Unicode objects for most built-in
-codecs. Output is also codec-dependent and will usually be Unicode as
-well.}
-
-\var{encoding} specifies the encoding which is to be used for the
-file.
-
-\var{errors} may be given to define the error handling. It defaults
-to \code{'strict'} which causes a \exception{ValueError} to be raised
-in case an encoding error occurs.
-
-\var{buffering} has the same meaning as for the built-in
-\function{open()} function. It defaults to line buffered.
-\end{funcdesc}
-
-\begin{funcdesc}{EncodedFile}{file, input\optional{,
- output\optional{, errors}}}
-Return a wrapped version of file which provides transparent
-encoding translation.
-
-Strings written to the wrapped file are interpreted according to the
-given \var{input} encoding and then written to the original file as
-strings using the \var{output} encoding. The intermediate encoding will
-usually be Unicode but depends on the specified codecs.
-
-If \var{output} is not given, it defaults to \var{input}.
-
-\var{errors} may be given to define the error handling. It defaults to
-\code{'strict'}, which causes \exception{ValueError} to be raised in case
-an encoding error occurs.
-\end{funcdesc}
-
-\begin{funcdesc}{iterencode}{iterable, encoding\optional{, errors}}
-Uses an incremental encoder to iteratively encode the input provided by
-\var{iterable}. This function is a generator. \var{errors} (as well as
-any other keyword argument) is passed through to the incremental encoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{iterdecode}{iterable, encoding\optional{, errors}}
-Uses an incremental decoder to iteratively decode the input provided by
-\var{iterable}. This function is a generator. \var{errors} (as well as
-any other keyword argument) is passed through to the incremental decoder.
-\versionadded{2.5}
-\end{funcdesc}
-
-The module also provides the following constants which are useful
-for reading and writing to platform dependent files:
-
-\begin{datadesc}{BOM}
-\dataline{BOM_BE}
-\dataline{BOM_LE}
-\dataline{BOM_UTF8}
-\dataline{BOM_UTF16}
-\dataline{BOM_UTF16_BE}
-\dataline{BOM_UTF16_LE}
-\dataline{BOM_UTF32}
-\dataline{BOM_UTF32_BE}
-\dataline{BOM_UTF32_LE}
-These constants define various encodings of the Unicode byte order mark
-(BOM) used in UTF-16 and UTF-32 data streams to indicate the byte order
-used in the stream or file and in UTF-8 as a Unicode signature.
-\constant{BOM_UTF16} is either \constant{BOM_UTF16_BE} or
-\constant{BOM_UTF16_LE} depending on the platform's native byte order,
-\constant{BOM} is an alias for \constant{BOM_UTF16}, \constant{BOM_LE}
-for \constant{BOM_UTF16_LE} and \constant{BOM_BE} for \constant{BOM_UTF16_BE}.
-The others represent the BOM in UTF-8 and UTF-32 encodings.
-\end{datadesc}
-
-
-\subsection{Codec Base Classes \label{codec-base-classes}}
-
-The \module{codecs} module defines a set of base classes which define the
-interface and can also be used to easily write you own codecs for use
-in Python.
-
-Each codec has to define four interfaces to make it usable as codec in
-Python: stateless encoder, stateless decoder, stream reader and stream
-writer. The stream reader and writers typically reuse the stateless
-encoder/decoder to implement the file protocols.
-
-The \class{Codec} class defines the interface for stateless
-encoders/decoders.
-
-To simplify and standardize error handling, the \method{encode()} and
-\method{decode()} methods may implement different error handling
-schemes by providing the \var{errors} string argument. The following
-string values are defined and implemented by all standard Python
-codecs:
-
-\begin{tableii}{l|l}{code}{Value}{Meaning}
- \lineii{'strict'}{Raise \exception{UnicodeError} (or a subclass);
- this is the default.}
- \lineii{'ignore'}{Ignore the character and continue with the next.}
- \lineii{'replace'}{Replace with a suitable replacement character;
- Python will use the official U+FFFD REPLACEMENT
- CHARACTER for the built-in Unicode codecs on
- decoding and '?' on encoding.}
- \lineii{'xmlcharrefreplace'}{Replace with the appropriate XML
- character reference (only for encoding).}
- \lineii{'backslashreplace'}{Replace with backslashed escape sequences
- (only for encoding).}
-\end{tableii}
-
-The set of allowed values can be extended via \method{register_error}.
-
-
-\subsubsection{Codec Objects \label{codec-objects}}
-
-The \class{Codec} class defines these methods which also define the
-function interfaces of the stateless encoder and decoder:
-
-\begin{methoddesc}[Codec]{encode}{input\optional{, errors}}
- Encodes the object \var{input} and returns a tuple (output object,
- length consumed). While codecs are not restricted to use with Unicode, in
- a Unicode context, encoding converts a Unicode object to a plain string
- using a particular character set encoding (e.g., \code{cp1252} or
- \code{iso-8859-1}).
-
- \var{errors} defines the error handling to apply. It defaults to
- \code{'strict'} handling.
-
- The method may not store state in the \class{Codec} instance. Use
- \class{StreamCodec} for codecs which have to keep state in order to
- make encoding/decoding efficient.
-
- The encoder must be able to handle zero length input and return an
- empty object of the output object type in this situation.
-\end{methoddesc}
-
-\begin{methoddesc}[Codec]{decode}{input\optional{, errors}}
- Decodes the object \var{input} and returns a tuple (output object,
- length consumed). In a Unicode context, decoding converts a plain string
- encoded using a particular character set encoding to a Unicode object.
-
- \var{input} must be an object which provides the \code{bf_getreadbuf}
- buffer slot. Python strings, buffer objects and memory mapped files
- are examples of objects providing this slot.
-
- \var{errors} defines the error handling to apply. It defaults to
- \code{'strict'} handling.
-
- The method may not store state in the \class{Codec} instance. Use
- \class{StreamCodec} for codecs which have to keep state in order to
- make encoding/decoding efficient.
-
- The decoder must be able to handle zero length input and return an
- empty object of the output object type in this situation.
-\end{methoddesc}
-
-The \class{IncrementalEncoder} and \class{IncrementalDecoder} classes provide
-the basic interface for incremental encoding and decoding. Encoding/decoding the
-input isn't done with one call to the stateless encoder/decoder function,
-but with multiple calls to the \method{encode}/\method{decode} method of the
-incremental encoder/decoder. The incremental encoder/decoder keeps track of
-the encoding/decoding process during method calls.
-
-The joined output of calls to the \method{encode}/\method{decode} method is the
-same as if all the single inputs were joined into one, and this input was
-encoded/decoded with the stateless encoder/decoder.
-
-
-\subsubsection{IncrementalEncoder Objects \label{incremental-encoder-objects}}
-
-\versionadded{2.5}
-
-The \class{IncrementalEncoder} class is used for encoding an input in multiple
-steps. It defines the following methods which every incremental encoder must
-define in order to be compatible with the Python codec registry.
-
-\begin{classdesc}{IncrementalEncoder}{\optional{errors}}
- Constructor for an \class{IncrementalEncoder} instance.
-
- All incremental encoders must provide this constructor interface. They are
- free to add additional keyword arguments, but only the ones defined
- here are used by the Python codec registry.
-
- The \class{IncrementalEncoder} may implement different error handling
- schemes by providing the \var{errors} keyword argument. These
- parameters are predefined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character
- \item \code{'xmlcharrefreplace'} Replace with the appropriate XML
- character reference
- \item \code{'backslashreplace'} Replace with backslashed escape sequences.
- \end{itemize}
-
- The \var{errors} argument will be assigned to an attribute of the
- same name. Assigning to this attribute makes it possible to switch
- between different error handling strategies during the lifetime
- of the \class{IncrementalEncoder} object.
-
- The set of allowed values for the \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{encode}{object\optional{, final}}
- Encodes \var{object} (taking the current state of the encoder into account)
- and returns the resulting encoded object. If this is the last call to
- \method{encode} \var{final} must be true (the default is false).
-\end{methoddesc}
-
-\begin{methoddesc}{reset}{}
- Reset the encoder to the initial state.
-\end{methoddesc}
-
-\begin{methoddesc}{getstate}{}
- Return the current state of the encoder which must be an integer.
- The implementation should make sure that \code{0} is the most common state.
- (States that are more complicated than integers can be converted into an
- integer by marshaling/pickling the state and encoding the bytes of the
- resulting string into an integer).
- \versionadded{3.0}
-\end{methoddesc}
-
-\begin{methoddesc}{setstate}{state}
- Set the state of the encoder to \var{state}. \var{state} must be an
- encoder state returned by \method{getstate}.
- \versionadded{3.0}
-\end{methoddesc}
-
-
-\subsubsection{IncrementalDecoder Objects \label{incremental-decoder-objects}}
-
-The \class{IncrementalDecoder} class is used for decoding an input in multiple
-steps. It defines the following methods which every incremental decoder must
-define in order to be compatible with the Python codec registry.
-
-\begin{classdesc}{IncrementalDecoder}{\optional{errors}}
- Constructor for an \class{IncrementalDecoder} instance.
-
- All incremental decoders must provide this constructor interface. They are
- free to add additional keyword arguments, but only the ones defined
- here are used by the Python codec registry.
-
- The \class{IncrementalDecoder} may implement different error handling
- schemes by providing the \var{errors} keyword argument. These
- parameters are predefined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character.
- \end{itemize}
-
- The \var{errors} argument will be assigned to an attribute of the
- same name. Assigning to this attribute makes it possible to switch
- between different error handling strategies during the lifetime
- of the \class{IncrementalEncoder} object.
-
- The set of allowed values for the \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{decode}{object\optional{, final}}
- Decodes \var{object} (taking the current state of the decoder into account)
- and returns the resulting decoded object. If this is the last call to
- \method{decode} \var{final} must be true (the default is false).
- If \var{final} is true the decoder must decode the input completely and must
- flush all buffers. If this isn't possible (e.g. because of incomplete byte
- sequences at the end of the input) it must initiate error handling just like
- in the stateless case (which might raise an exception).
-\end{methoddesc}
-
-\begin{methoddesc}{reset}{}
- Reset the decoder to the initial state.
-\end{methoddesc}
-
-\begin{methoddesc}{getstate}{}
- Return the current state of the decoder. This must be a tuple with two
- items, the first must be the buffer containing the still undecoded input.
- The second must be an integer and can be additional state info.
- (The implementation should make sure that \code{0} is the most common
- additional state info.) If this additional state info is \code{0} it must
- be possible to set the decoder to the state which has no input buffered
- and \code{0} as the additional state info, so that feeding the previously
- buffered input to the decoder returns it to the previous state without
- producing any output. (Additional state info that is more complicated
- than integers can be converted into an integer by marshaling/pickling
- the info and encoding the bytes of the resulting string into an integer.)
- \versionadded{3.0}
-\end{methoddesc}
-
-\begin{methoddesc}{setstate}{state}
- Set the state of the encoder to \var{state}. \var{state} must be a
- decoder state returned by \method{getstate}.
- \versionadded{3.0}
-\end{methoddesc}
-
-
-The \class{StreamWriter} and \class{StreamReader} classes provide
-generic working interfaces which can be used to implement new
-encoding submodules very easily. See \module{encodings.utf_8} for an
-example of how this is done.
-
-
-\subsubsection{StreamWriter Objects \label{stream-writer-objects}}
-
-The \class{StreamWriter} class is a subclass of \class{Codec} and
-defines the following methods which every stream writer must define in
-order to be compatible with the Python codec registry.
-
-\begin{classdesc}{StreamWriter}{stream\optional{, errors}}
- Constructor for a \class{StreamWriter} instance.
-
- All stream writers must provide this constructor interface. They are
- free to add additional keyword arguments, but only the ones defined
- here are used by the Python codec registry.
-
- \var{stream} must be a file-like object open for writing binary
- data.
-
- The \class{StreamWriter} may implement different error handling
- schemes by providing the \var{errors} keyword argument. These
- parameters are predefined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character
- \item \code{'xmlcharrefreplace'} Replace with the appropriate XML
- character reference
- \item \code{'backslashreplace'} Replace with backslashed escape sequences.
- \end{itemize}
-
- The \var{errors} argument will be assigned to an attribute of the
- same name. Assigning to this attribute makes it possible to switch
- between different error handling strategies during the lifetime
- of the \class{StreamWriter} object.
-
- The set of allowed values for the \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{write}{object}
- Writes the object's contents encoded to the stream.
-\end{methoddesc}
-
-\begin{methoddesc}{writelines}{list}
- Writes the concatenated list of strings to the stream (possibly by
- reusing the \method{write()} method).
-\end{methoddesc}
-
-\begin{methoddesc}{reset}{}
- Flushes and resets the codec buffers used for keeping state.
-
- Calling this method should ensure that the data on the output is put
- into a clean state that allows appending of new fresh data without
- having to rescan the whole stream to recover state.
-\end{methoddesc}
-
-In addition to the above methods, the \class{StreamWriter} must also
-inherit all other methods and attributes from the underlying stream.
-
-
-\subsubsection{StreamReader Objects \label{stream-reader-objects}}
-
-The \class{StreamReader} class is a subclass of \class{Codec} and
-defines the following methods which every stream reader must define in
-order to be compatible with the Python codec registry.
-
-\begin{classdesc}{StreamReader}{stream\optional{, errors}}
- Constructor for a \class{StreamReader} instance.
-
- All stream readers must provide this constructor interface. They are
- free to add additional keyword arguments, but only the ones defined
- here are used by the Python codec registry.
-
- \var{stream} must be a file-like object open for reading (binary)
- data.
-
- The \class{StreamReader} may implement different error handling
- schemes by providing the \var{errors} keyword argument. These
- parameters are defined:
-
- \begin{itemize}
- \item \code{'strict'} Raise \exception{ValueError} (or a subclass);
- this is the default.
- \item \code{'ignore'} Ignore the character and continue with the next.
- \item \code{'replace'} Replace with a suitable replacement character.
- \end{itemize}
-
- The \var{errors} argument will be assigned to an attribute of the
- same name. Assigning to this attribute makes it possible to switch
- between different error handling strategies during the lifetime
- of the \class{StreamReader} object.
-
- The set of allowed values for the \var{errors} argument can
- be extended with \function{register_error()}.
-\end{classdesc}
-
-\begin{methoddesc}{read}{\optional{size\optional{, chars, \optional{firstline}}}}
- Decodes data from the stream and returns the resulting object.
-
- \var{chars} indicates the number of characters to read from the
- stream. \function{read()} will never return more than \var{chars}
- characters, but it might return less, if there are not enough
- characters available.
-
- \var{size} indicates the approximate maximum number of bytes to read
- from the stream for decoding purposes. The decoder can modify this
- setting as appropriate. The default value -1 indicates to read and
- decode as much as possible. \var{size} is intended to prevent having
- to decode huge files in one step.
-
- \var{firstline} indicates that it would be sufficient to only return
- the first line, if there are decoding errors on later lines.
-
- The method should use a greedy read strategy meaning that it should
- read as much data as is allowed within the definition of the encoding
- and the given size, e.g. if optional encoding endings or state
- markers are available on the stream, these should be read too.
-
- \versionchanged[\var{chars} argument added]{2.4}
- \versionchanged[\var{firstline} argument added]{2.4.2}
-\end{methoddesc}
-
-\begin{methoddesc}{readline}{\optional{size\optional{, keepends}}}
- Read one line from the input stream and return the
- decoded data.
-
- \var{size}, if given, is passed as size argument to the stream's
- \method{readline()} method.
-
- If \var{keepends} is false line-endings will be stripped from the
- lines returned.
-
- \versionchanged[\var{keepends} argument added]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}{readlines}{\optional{sizehint\optional{, keepends}}}
- Read all lines available on the input stream and return them as a list
- of lines.
-
- Line-endings are implemented using the codec's decoder method and are
- included in the list entries if \var{keepends} is true.
-
- \var{sizehint}, if given, is passed as the \var{size} argument to the
- stream's \method{read()} method.
-\end{methoddesc}
-
-\begin{methoddesc}{reset}{}
- Resets the codec buffers used for keeping state.
-
- Note that no stream repositioning should take place. This method is
- primarily intended to be able to recover from decoding errors.
-\end{methoddesc}
-
-In addition to the above methods, the \class{StreamReader} must also
-inherit all other methods and attributes from the underlying stream.
-
-The next two base classes are included for convenience. They are not
-needed by the codec registry, but may provide useful in practice.
-
-
-\subsubsection{StreamReaderWriter Objects \label{stream-reader-writer}}
-
-The \class{StreamReaderWriter} allows wrapping streams which work in
-both read and write modes.
-
-The design is such that one can use the factory functions returned by
-the \function{lookup()} function to construct the instance.
-
-\begin{classdesc}{StreamReaderWriter}{stream, Reader, Writer, errors}
- Creates a \class{StreamReaderWriter} instance.
- \var{stream} must be a file-like object.
- \var{Reader} and \var{Writer} must be factory functions or classes
- providing the \class{StreamReader} and \class{StreamWriter} interface
- resp.
- Error handling is done in the same way as defined for the
- stream readers and writers.
-\end{classdesc}
-
-\class{StreamReaderWriter} instances define the combined interfaces of
-\class{StreamReader} and \class{StreamWriter} classes. They inherit
-all other methods and attributes from the underlying stream.
-
-
-\subsubsection{StreamRecoder Objects \label{stream-recoder-objects}}
-
-The \class{StreamRecoder} provide a frontend - backend view of
-encoding data which is sometimes useful when dealing with different
-encoding environments.
-
-The design is such that one can use the factory functions returned by
-the \function{lookup()} function to construct the instance.
-
-\begin{classdesc}{StreamRecoder}{stream, encode, decode,
- Reader, Writer, errors}
- Creates a \class{StreamRecoder} instance which implements a two-way
- conversion: \var{encode} and \var{decode} work on the frontend (the
- input to \method{read()} and output of \method{write()}) while
- \var{Reader} and \var{Writer} work on the backend (reading and
- writing to the stream).
-
- You can use these objects to do transparent direct recodings from
- e.g.\ Latin-1 to UTF-8 and back.
-
- \var{stream} must be a file-like object.
-
- \var{encode}, \var{decode} must adhere to the \class{Codec}
- interface. \var{Reader}, \var{Writer} must be factory functions or
- classes providing objects of the \class{StreamReader} and
- \class{StreamWriter} interface respectively.
-
- \var{encode} and \var{decode} are needed for the frontend
- translation, \var{Reader} and \var{Writer} for the backend
- translation. The intermediate format used is determined by the two
- sets of codecs, e.g. the Unicode codecs will use Unicode as the
- intermediate encoding.
-
- Error handling is done in the same way as defined for the
- stream readers and writers.
-\end{classdesc}
-
-\class{StreamRecoder} instances define the combined interfaces of
-\class{StreamReader} and \class{StreamWriter} classes. They inherit
-all other methods and attributes from the underlying stream.
-
-\subsection{Encodings and Unicode\label{encodings-overview}}
-
-Unicode strings are stored internally as sequences of codepoints (to
-be precise as \ctype{Py_UNICODE} arrays). Depending on the way Python is
-compiled (either via \longprogramopt{enable-unicode=ucs2} or
-\longprogramopt{enable-unicode=ucs4}, with the former being the default)
-\ctype{Py_UNICODE} is either a 16-bit or
-32-bit data type. Once a Unicode object is used outside of CPU and
-memory, CPU endianness and how these arrays are stored as bytes become
-an issue. Transforming a unicode object into a sequence of bytes is
-called encoding and recreating the unicode object from the sequence of
-bytes is known as decoding. There are many different methods for how this
-transformation can be done (these methods are also called encodings).
-The simplest method is to map the codepoints 0-255 to the bytes
-\code{0x0}-\code{0xff}. This means that a unicode object that contains
-codepoints above \code{U+00FF} can't be encoded with this method (which
-is called \code{'latin-1'} or \code{'iso-8859-1'}).
-\function{unicode.encode()} will raise a \exception{UnicodeEncodeError}
-that looks like this: \samp{UnicodeEncodeError: 'latin-1' codec can't
-encode character u'\e u1234' in position 3: ordinal not in range(256)}.
-
-There's another group of encodings (the so called charmap encodings)
-that choose a different subset of all unicode code points and how
-these codepoints are mapped to the bytes \code{0x0}-\code{0xff.}
-To see how this is done simply open e.g. \file{encodings/cp1252.py}
-(which is an encoding that is used primarily on Windows).
-There's a string constant with 256 characters that shows you which
-character is mapped to which byte value.
-
-All of these encodings can only encode 256 of the 65536 (or 1114111)
-codepoints defined in unicode. A simple and straightforward way that
-can store each Unicode code point, is to store each codepoint as two
-consecutive bytes. There are two possibilities: Store the bytes in big
-endian or in little endian order. These two encodings are called
-UTF-16-BE and UTF-16-LE respectively. Their disadvantage is that if
-e.g. you use UTF-16-BE on a little endian machine you will always have
-to swap bytes on encoding and decoding. UTF-16 avoids this problem:
-Bytes will always be in natural endianness. When these bytes are read
-by a CPU with a different endianness, then bytes have to be swapped
-though. To be able to detect the endianness of a UTF-16 byte sequence,
-there's the so called BOM (the "Byte Order Mark"). This is the Unicode
-character \code{U+FEFF}. This character will be prepended to every UTF-16
-byte sequence. The byte swapped version of this character (\code{0xFFFE}) is
-an illegal character that may not appear in a Unicode text. So when
-the first character in an UTF-16 byte sequence appears to be a \code{U+FFFE}
-the bytes have to be swapped on decoding. Unfortunately upto Unicode
-4.0 the character \code{U+FEFF} had a second purpose as a \samp{ZERO WIDTH
-NO-BREAK SPACE}: A character that has no width and doesn't allow a
-word to be split. It can e.g. be used to give hints to a ligature
-algorithm. With Unicode 4.0 using \code{U+FEFF} as a \samp{ZERO WIDTH NO-BREAK
-SPACE} has been deprecated (with \code{U+2060} (\samp{WORD JOINER}) assuming
-this role). Nevertheless Unicode software still must be able to handle
-\code{U+FEFF} in both roles: As a BOM it's a device to determine the storage
-layout of the encoded bytes, and vanishes once the byte sequence has
-been decoded into a Unicode string; as a \samp{ZERO WIDTH NO-BREAK SPACE}
-it's a normal character that will be decoded like any other.
-
-There's another encoding that is able to encoding the full range of
-Unicode characters: UTF-8. UTF-8 is an 8-bit encoding, which means
-there are no issues with byte order in UTF-8. Each byte in a UTF-8
-byte sequence consists of two parts: Marker bits (the most significant
-bits) and payload bits. The marker bits are a sequence of zero to six
-1 bits followed by a 0 bit. Unicode characters are encoded like this
-(with x being payload bits, which when concatenated give the Unicode
-character):
-
-\begin{tableii}{l|l}{textrm}{Range}{Encoding}
-\lineii{\code{U-00000000} ... \code{U-0000007F}}{0xxxxxxx}
-\lineii{\code{U-00000080} ... \code{U-000007FF}}{110xxxxx 10xxxxxx}
-\lineii{\code{U-00000800} ... \code{U-0000FFFF}}{1110xxxx 10xxxxxx 10xxxxxx}
-\lineii{\code{U-00010000} ... \code{U-001FFFFF}}{11110xxx 10xxxxxx 10xxxxxx 10xxxxxx}
-\lineii{\code{U-00200000} ... \code{U-03FFFFFF}}{111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx}
-\lineii{\code{U-04000000} ... \code{U-7FFFFFFF}}{1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx}
-\end{tableii}
-
-The least significant bit of the Unicode character is the rightmost x
-bit.
-
-As UTF-8 is an 8-bit encoding no BOM is required and any \code{U+FEFF}
-character in the decoded Unicode string (even if it's the first
-character) is treated as a \samp{ZERO WIDTH NO-BREAK SPACE}.
-
-Without external information it's impossible to reliably determine
-which encoding was used for encoding a Unicode string. Each charmap
-encoding can decode any random byte sequence. However that's not
-possible with UTF-8, as UTF-8 byte sequences have a structure that
-doesn't allow arbitrary byte sequence. To increase the reliability
-with which a UTF-8 encoding can be detected, Microsoft invented a
-variant of UTF-8 (that Python 2.5 calls \code{"utf-8-sig"}) for its Notepad
-program: Before any of the Unicode characters is written to the file,
-a UTF-8 encoded BOM (which looks like this as a byte sequence: \code{0xef},
-\code{0xbb}, \code{0xbf}) is written. As it's rather improbable that any
-charmap encoded file starts with these byte values (which would e.g. map to
-
- LATIN SMALL LETTER I WITH DIAERESIS \\
- RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK \\
- INVERTED QUESTION MARK
-
-in iso-8859-1), this increases the probability that a utf-8-sig
-encoding can be correctly guessed from the byte sequence. So here the
-BOM is not used to be able to determine the byte order used for
-generating the byte sequence, but as a signature that helps in
-guessing the encoding. On encoding the utf-8-sig codec will write
-\code{0xef}, \code{0xbb}, \code{0xbf} as the first three bytes to the file.
-On decoding utf-8-sig will skip those three bytes if they appear as the
-first three bytes in the file.
-
-
-\subsection{Standard Encodings\label{standard-encodings}}
-
-Python comes with a number of codecs built-in, either implemented as C
-functions or with dictionaries as mapping tables. The following table
-lists the codecs by name, together with a few common aliases, and the
-languages for which the encoding is likely used. Neither the list of
-aliases nor the list of languages is meant to be exhaustive. Notice
-that spelling alternatives that only differ in case or use a hyphen
-instead of an underscore are also valid aliases.
-
-Many of the character sets support the same languages. They vary in
-individual characters (e.g. whether the EURO SIGN is supported or
-not), and in the assignment of characters to code positions. For the
-European languages in particular, the following variants typically
-exist:
-
-\begin{itemize}
-\item an ISO 8859 codeset
-\item a Microsoft Windows code page, which is typically derived from
- a 8859 codeset, but replaces control characters with additional
- graphic characters
-\item an IBM EBCDIC code page
-\item an IBM PC code page, which is \ASCII{} compatible
-\end{itemize}
-
-\begin{longtableiii}{l|l|l}{textrm}{Codec}{Aliases}{Languages}
-
-\lineiii{ascii}
- {646, us-ascii}
- {English}
-
-\lineiii{big5}
- {big5-tw, csbig5}
- {Traditional Chinese}
-
-\lineiii{big5hkscs}
- {big5-hkscs, hkscs}
- {Traditional Chinese}
-
-\lineiii{cp037}
- {IBM037, IBM039}
- {English}
-
-\lineiii{cp424}
- {EBCDIC-CP-HE, IBM424}
- {Hebrew}
-
-\lineiii{cp437}
- {437, IBM437}
- {English}
-
-\lineiii{cp500}
- {EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500}
- {Western Europe}
-
-\lineiii{cp737}
- {}
- {Greek}
-
-\lineiii{cp775}
- {IBM775}
- {Baltic languages}
-
-\lineiii{cp850}
- {850, IBM850}
- {Western Europe}
-
-\lineiii{cp852}
- {852, IBM852}
- {Central and Eastern Europe}
-
-\lineiii{cp855}
- {855, IBM855}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{cp856}
- {}
- {Hebrew}
-
-\lineiii{cp857}
- {857, IBM857}
- {Turkish}
-
-\lineiii{cp860}
- {860, IBM860}
- {Portuguese}
-
-\lineiii{cp861}
- {861, CP-IS, IBM861}
- {Icelandic}
-
-\lineiii{cp862}
- {862, IBM862}
- {Hebrew}
-
-\lineiii{cp863}
- {863, IBM863}
- {Canadian}
-
-\lineiii{cp864}
- {IBM864}
- {Arabic}
-
-\lineiii{cp865}
- {865, IBM865}
- {Danish, Norwegian}
-
-\lineiii{cp866}
- {866, IBM866}
- {Russian}
-
-\lineiii{cp869}
- {869, CP-GR, IBM869}
- {Greek}
-
-\lineiii{cp874}
- {}
- {Thai}
-
-\lineiii{cp875}
- {}
- {Greek}
-
-\lineiii{cp932}
- {932, ms932, mskanji, ms-kanji}
- {Japanese}
-
-\lineiii{cp949}
- {949, ms949, uhc}
- {Korean}
-
-\lineiii{cp950}
- {950, ms950}
- {Traditional Chinese}
-
-\lineiii{cp1006}
- {}
- {Urdu}
-
-\lineiii{cp1026}
- {ibm1026}
- {Turkish}
-
-\lineiii{cp1140}
- {ibm1140}
- {Western Europe}
-
-\lineiii{cp1250}
- {windows-1250}
- {Central and Eastern Europe}
-
-\lineiii{cp1251}
- {windows-1251}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{cp1252}
- {windows-1252}
- {Western Europe}
-
-\lineiii{cp1253}
- {windows-1253}
- {Greek}
-
-\lineiii{cp1254}
- {windows-1254}
- {Turkish}
-
-\lineiii{cp1255}
- {windows-1255}
- {Hebrew}
-
-\lineiii{cp1256}
- {windows1256}
- {Arabic}
-
-\lineiii{cp1257}
- {windows-1257}
- {Baltic languages}
-
-\lineiii{cp1258}
- {windows-1258}
- {Vietnamese}
-
-\lineiii{euc_jp}
- {eucjp, ujis, u-jis}
- {Japanese}
-
-\lineiii{euc_jis_2004}
- {jisx0213, eucjis2004}
- {Japanese}
-
-\lineiii{euc_jisx0213}
- {eucjisx0213}
- {Japanese}
-
-\lineiii{euc_kr}
- {euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001}
- {Korean}
-
-\lineiii{gb2312}
- {chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980,
- gb2312-80, iso-ir-58}
- {Simplified Chinese}
-
-\lineiii{gbk}
- {936, cp936, ms936}
- {Unified Chinese}
-
-\lineiii{gb18030}
- {gb18030-2000}
- {Unified Chinese}
-
-\lineiii{hz}
- {hzgb, hz-gb, hz-gb-2312}
- {Simplified Chinese}
-
-\lineiii{iso2022_jp}
- {csiso2022jp, iso2022jp, iso-2022-jp}
- {Japanese}
-
-\lineiii{iso2022_jp_1}
- {iso2022jp-1, iso-2022-jp-1}
- {Japanese}
-
-\lineiii{iso2022_jp_2}
- {iso2022jp-2, iso-2022-jp-2}
- {Japanese, Korean, Simplified Chinese, Western Europe, Greek}
-
-\lineiii{iso2022_jp_2004}
- {iso2022jp-2004, iso-2022-jp-2004}
- {Japanese}
-
-\lineiii{iso2022_jp_3}
- {iso2022jp-3, iso-2022-jp-3}
- {Japanese}
-
-\lineiii{iso2022_jp_ext}
- {iso2022jp-ext, iso-2022-jp-ext}
- {Japanese}
-
-\lineiii{iso2022_kr}
- {csiso2022kr, iso2022kr, iso-2022-kr}
- {Korean}
-
-\lineiii{latin_1}
- {iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1}
- {West Europe}
-
-\lineiii{iso8859_2}
- {iso-8859-2, latin2, L2}
- {Central and Eastern Europe}
-
-\lineiii{iso8859_3}
- {iso-8859-3, latin3, L3}
- {Esperanto, Maltese}
-
-\lineiii{iso8859_4}
- {iso-8859-4, latin4, L4}
- {Baltic languagues}
-
-\lineiii{iso8859_5}
- {iso-8859-5, cyrillic}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{iso8859_6}
- {iso-8859-6, arabic}
- {Arabic}
-
-\lineiii{iso8859_7}
- {iso-8859-7, greek, greek8}
- {Greek}
-
-\lineiii{iso8859_8}
- {iso-8859-8, hebrew}
- {Hebrew}
-
-\lineiii{iso8859_9}
- {iso-8859-9, latin5, L5}
- {Turkish}
-
-\lineiii{iso8859_10}
- {iso-8859-10, latin6, L6}
- {Nordic languages}
-
-\lineiii{iso8859_13}
- {iso-8859-13}
- {Baltic languages}
-
-\lineiii{iso8859_14}
- {iso-8859-14, latin8, L8}
- {Celtic languages}
-
-\lineiii{iso8859_15}
- {iso-8859-15}
- {Western Europe}
-
-\lineiii{johab}
- {cp1361, ms1361}
- {Korean}
-
-\lineiii{koi8_r}
- {}
- {Russian}
-
-\lineiii{koi8_u}
- {}
- {Ukrainian}
-
-\lineiii{mac_cyrillic}
- {maccyrillic}
- {Bulgarian, Byelorussian, Macedonian, Russian, Serbian}
-
-\lineiii{mac_greek}
- {macgreek}
- {Greek}
-
-\lineiii{mac_iceland}
- {maciceland}
- {Icelandic}
-
-\lineiii{mac_latin2}
- {maclatin2, maccentraleurope}
- {Central and Eastern Europe}
-
-\lineiii{mac_roman}
- {macroman}
- {Western Europe}
-
-\lineiii{mac_turkish}
- {macturkish}
- {Turkish}
-
-\lineiii{ptcp154}
- {csptcp154, pt154, cp154, cyrillic-asian}
- {Kazakh}
-
-\lineiii{shift_jis}
- {csshiftjis, shiftjis, sjis, s_jis}
- {Japanese}
-
-\lineiii{shift_jis_2004}
- {shiftjis2004, sjis_2004, sjis2004}
- {Japanese}
-
-\lineiii{shift_jisx0213}
- {shiftjisx0213, sjisx0213, s_jisx0213}
- {Japanese}
-
-\lineiii{utf_16}
- {U16, utf16}
- {all languages}
-
-\lineiii{utf_16_be}
- {UTF-16BE}
- {all languages (BMP only)}
-
-\lineiii{utf_16_le}
- {UTF-16LE}
- {all languages (BMP only)}
-
-\lineiii{utf_7}
- {U7, unicode-1-1-utf-7}
- {all languages}
-
-\lineiii{utf_8}
- {U8, UTF, utf8}
- {all languages}
-
-\lineiii{utf_8_sig}
- {}
- {all languages}
-
-\end{longtableiii}
-
-A number of codecs are specific to Python, so their codec names have
-no meaning outside Python. Some of them don't convert from Unicode
-strings to byte strings, but instead use the property of the Python
-codecs machinery that any bijective function with one argument can be
-considered as an encoding.
-
-For the codecs listed below, the result in the ``encoding'' direction
-is always a byte string. The result of the ``decoding'' direction is
-listed as operand type in the table.
-
-\begin{tableiv}{l|l|l|l}{textrm}{Codec}{Aliases}{Operand type}{Purpose}
-
-\lineiv{idna}
- {}
- {Unicode string}
- {Implements \rfc{3490},
- see also \refmodule{encodings.idna}}
-
-\lineiv{mbcs}
- {dbcs}
- {Unicode string}
- {Windows only: Encode operand according to the ANSI codepage (CP_ACP)}
-
-\lineiv{palmos}
- {}
- {Unicode string}
- {Encoding of PalmOS 3.5}
-
-\lineiv{punycode}
- {}
- {Unicode string}
- {Implements \rfc{3492}}
-
-\lineiv{raw_unicode_escape}
- {}
- {Unicode string}
- {Produce a string that is suitable as raw Unicode literal in
- Python source code}
-
-\lineiv{undefined}
- {}
- {any}
- {Raise an exception for all conversions. Can be used as the
- system encoding if no automatic coercion between byte and
- Unicode strings is desired.}
-
-\lineiv{unicode_escape}
- {}
- {Unicode string}
- {Produce a string that is suitable as Unicode literal in
- Python source code}
-
-\lineiv{unicode_internal}
- {}
- {Unicode string}
- {Return the internal representation of the operand}
-\end{tableiv}
-
-\versionadded[The \code{idna} and \code{punycode} encodings]{2.3}
-
-\subsection{\module{encodings.idna} ---
- Internationalized Domain Names in Applications}
-
-\declaremodule{standard}{encodings.idna}
-\modulesynopsis{Internationalized Domain Names implementation}
-% XXX The next line triggers a formatting bug, so it's commented out
-% until that can be fixed.
-%\moduleauthor{Martin v. L\"owis}
-
-\versionadded{2.3}
-
-This module implements \rfc{3490} (Internationalized Domain Names in
-Applications) and \rfc{3492} (Nameprep: A Stringprep Profile for
-Internationalized Domain Names (IDN)). It builds upon the
-\code{punycode} encoding and \refmodule{stringprep}.
-
-These RFCs together define a protocol to support non-\ASCII{} characters
-in domain names. A domain name containing non-\ASCII{} characters (such
-as ``www.Alliancefran\c caise.nu'') is converted into an
-\ASCII-compatible encoding (ACE, such as
-``www.xn--alliancefranaise-npb.nu''). The ACE form of the domain name
-is then used in all places where arbitrary characters are not allowed
-by the protocol, such as DNS queries, HTTP \mailheader{Host} fields, and so
-on. This conversion is carried out in the application; if possible
-invisible to the user: The application should transparently convert
-Unicode domain labels to IDNA on the wire, and convert back ACE labels
-to Unicode before presenting them to the user.
-
-Python supports this conversion in several ways: The \code{idna} codec
-allows to convert between Unicode and the ACE. Furthermore, the
-\refmodule{socket} module transparently converts Unicode host names to
-ACE, so that applications need not be concerned about converting host
-names themselves when they pass them to the socket module. On top of
-that, modules that have host names as function parameters, such as
-\refmodule{httplib} and \refmodule{ftplib}, accept Unicode host names
-(\refmodule{httplib} then also transparently sends an IDNA hostname in
-the \mailheader{Host} field if it sends that field at all).
-
-When receiving host names from the wire (such as in reverse name
-lookup), no automatic conversion to Unicode is performed: Applications
-wishing to present such host names to the user should decode them to
-Unicode.
-
-The module \module{encodings.idna} also implements the nameprep
-procedure, which performs certain normalizations on host names, to
-achieve case-insensitivity of international domain names, and to unify
-similar characters. The nameprep functions can be used directly if
-desired.
-
-\begin{funcdesc}{nameprep}{label}
-Return the nameprepped version of \var{label}. The implementation
-currently assumes query strings, so \code{AllowUnassigned} is
-true.
-\end{funcdesc}
-
-\begin{funcdesc}{ToASCII}{label}
-Convert a label to \ASCII, as specified in \rfc{3490}.
-\code{UseSTD3ASCIIRules} is assumed to be false.
-\end{funcdesc}
-
-\begin{funcdesc}{ToUnicode}{label}
-Convert a label to Unicode, as specified in \rfc{3490}.
-\end{funcdesc}
-
- \subsection{\module{encodings.utf_8_sig} ---
- UTF-8 codec with BOM signature}
-\declaremodule{standard}{encodings.utf-8-sig} % XXX utf_8_sig gives TeX errors
-\modulesynopsis{UTF-8 codec with BOM signature}
-\moduleauthor{Walter D\"orwald}{}
-
-\versionadded{2.5}
-
-This module implements a variant of the UTF-8 codec: On encoding a
-UTF-8 encoded BOM will be prepended to the UTF-8 encoded bytes. For
-the stateful encoder this is only done once (on the first write to the
-byte stream). For decoding an optional UTF-8 encoded BOM at the start
-of the data will be skipped.
diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex
deleted file mode 100644
index 6972b6f..0000000
--- a/Doc/lib/libcodeop.tex
+++ /dev/null
@@ -1,103 +0,0 @@
-\section{\module{codeop} ---
- Compile Python code}
-
-% LaTeXed from excellent doc-string.
-
-\declaremodule{standard}{codeop}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\sectionauthor{Michael Hudson}{mwh@python.net}
-\modulesynopsis{Compile (possibly incomplete) Python code.}
-
-The \module{codeop} module provides utilities upon which the Python
-read-eval-print loop can be emulated, as is done in the
-\refmodule{code} module. As a result, you probably don't want to use
-the module directly; if you want to include such a loop in your
-program you probably want to use the \refmodule{code} module instead.
-
-There are two parts to this job:
-
-\begin{enumerate}
- \item Being able to tell if a line of input completes a Python
- statement: in short, telling whether to print
- `\code{>>>~}' or `\code{...~}' next.
- \item Remembering which future statements the user has entered, so
- subsequent input can be compiled with these in effect.
-\end{enumerate}
-
-The \module{codeop} module provides a way of doing each of these
-things, and a way of doing them both.
-
-To do just the former:
-
-\begin{funcdesc}{compile_command}
- {source\optional{, filename\optional{, symbol}}}
-Tries to compile \var{source}, which should be a string of Python
-code and return a code object if \var{source} is valid
-Python code. In that case, the filename attribute of the code object
-will be \var{filename}, which defaults to \code{'<input>'}.
-Returns \code{None} if \var{source} is \emph{not} valid Python
-code, but is a prefix of valid Python code.
-
-If there is a problem with \var{source}, an exception will be raised.
-\exception{SyntaxError} is raised if there is invalid Python syntax,
-and \exception{OverflowError} or \exception{ValueError} if there is an
-invalid literal.
-
-The \var{symbol} argument determines whether \var{source} is compiled
-as a statement (\code{'single'}, the default) or as an expression
-(\code{'eval'}). Any other value will cause \exception{ValueError} to
-be raised.
-
-\strong{Caveat:}
-It is possible (but not likely) that the parser stops parsing
-with a successful outcome before reaching the end of the source;
-in this case, trailing symbols may be ignored instead of causing an
-error. For example, a backslash followed by two newlines may be
-followed by arbitrary garbage. This will be fixed once the API
-for the parser is better.
-\end{funcdesc}
-
-\begin{classdesc}{Compile}{}
-Instances of this class have \method{__call__()} methods identical in
-signature to the built-in function \function{compile()}, but with the
-difference that if the instance compiles program text containing a
-\module{__future__} statement, the instance 'remembers' and compiles
-all subsequent program texts with the statement in force.
-\end{classdesc}
-
-\begin{classdesc}{CommandCompiler}{}
-Instances of this class have \method{__call__()} methods identical in
-signature to \function{compile_command()}; the difference is that if
-the instance compiles program text containing a \code{__future__}
-statement, the instance 'remembers' and compiles all subsequent
-program texts with the statement in force.
-\end{classdesc}
-
-A note on version compatibility: the \class{Compile} and
-\class{CommandCompiler} are new in Python 2.2. If you want to enable
-the future-tracking features of 2.2 but also retain compatibility with
-2.1 and earlier versions of Python you can either write
-
-\begin{verbatim}
-try:
- from codeop import CommandCompiler
- compile_command = CommandCompiler()
- del CommandCompiler
-except ImportError:
- from codeop import compile_command
-\end{verbatim}
-
-which is a low-impact change, but introduces possibly unwanted global
-state into your program, or you can write:
-
-\begin{verbatim}
-try:
- from codeop import CommandCompiler
-except ImportError:
- def CommandCompiler():
- from codeop import compile_command
- return compile_command
-\end{verbatim}
-
-and then call \code{CommandCompiler} every time you need a fresh
-compiler object.
diff --git a/Doc/lib/libcollections.tex b/Doc/lib/libcollections.tex
deleted file mode 100644
index fc44e01..0000000
--- a/Doc/lib/libcollections.tex
+++ /dev/null
@@ -1,402 +0,0 @@
-\section{\module{collections} ---
- High-performance container datatypes}
-
-\declaremodule{standard}{collections}
-\modulesynopsis{High-performance datatypes}
-\moduleauthor{Raymond Hettinger}{python@rcn.com}
-\sectionauthor{Raymond Hettinger}{python@rcn.com}
-\versionadded{2.4}
-
-
-This module implements high-performance container datatypes. Currently,
-there are two datatypes, deque and defaultdict, and one datatype factory
-function, \function{NamedTuple}.
-Future additions may include balanced trees and ordered dictionaries.
-\versionchanged[Added defaultdict]{2.5}
-\versionchanged[Added NamedTuple]{2.6}
-
-\subsection{\class{deque} objects \label{deque-objects}}
-
-\begin{classdesc}{deque}{\optional{iterable}}
- Returns a new deque object initialized left-to-right (using
- \method{append()}) with data from \var{iterable}. If \var{iterable}
- is not specified, the new deque is empty.
-
- Deques are a generalization of stacks and queues (the name is pronounced
- ``deck'' and is short for ``double-ended queue''). Deques support
- thread-safe, memory efficient appends and pops from either side of the deque
- with approximately the same \code{O(1)} performance in either direction.
-
- Though \class{list} objects support similar operations, they are optimized
- for fast fixed-length operations and incur \code{O(n)} memory movement costs
- for \samp{pop(0)} and \samp{insert(0, v)} operations which change both the
- size and position of the underlying data representation.
- \versionadded{2.4}
-\end{classdesc}
-
-Deque objects support the following methods:
-
-\begin{methoddesc}{append}{x}
- Add \var{x} to the right side of the deque.
-\end{methoddesc}
-
-\begin{methoddesc}{appendleft}{x}
- Add \var{x} to the left side of the deque.
-\end{methoddesc}
-
-\begin{methoddesc}{clear}{}
- Remove all elements from the deque leaving it with length 0.
-\end{methoddesc}
-
-\begin{methoddesc}{extend}{iterable}
- Extend the right side of the deque by appending elements from
- the iterable argument.
-\end{methoddesc}
-
-\begin{methoddesc}{extendleft}{iterable}
- Extend the left side of the deque by appending elements from
- \var{iterable}. Note, the series of left appends results in
- reversing the order of elements in the iterable argument.
-\end{methoddesc}
-
-\begin{methoddesc}{pop}{}
- Remove and return an element from the right side of the deque.
- If no elements are present, raises an \exception{IndexError}.
-\end{methoddesc}
-
-\begin{methoddesc}{popleft}{}
- Remove and return an element from the left side of the deque.
- If no elements are present, raises an \exception{IndexError}.
-\end{methoddesc}
-
-\begin{methoddesc}{remove}{value}
- Removed the first occurrence of \var{value}. If not found,
- raises a \exception{ValueError}.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{rotate}{n}
- Rotate the deque \var{n} steps to the right. If \var{n} is
- negative, rotate to the left. Rotating one step to the right
- is equivalent to: \samp{d.appendleft(d.pop())}.
-\end{methoddesc}
-
-In addition to the above, deques support iteration, pickling, \samp{len(d)},
-\samp{reversed(d)}, \samp{copy.copy(d)}, \samp{copy.deepcopy(d)},
-membership testing with the \keyword{in} operator, and subscript references
-such as \samp{d[-1]}.
-
-Example:
-
-\begin{verbatim}
->>> from collections import deque
->>> d = deque('ghi') # make a new deque with three items
->>> for elem in d: # iterate over the deque's elements
-... print elem.upper()
-G
-H
-I
-
->>> d.append('j') # add a new entry to the right side
->>> d.appendleft('f') # add a new entry to the left side
->>> d # show the representation of the deque
-deque(['f', 'g', 'h', 'i', 'j'])
-
->>> d.pop() # return and remove the rightmost item
-'j'
->>> d.popleft() # return and remove the leftmost item
-'f'
->>> list(d) # list the contents of the deque
-['g', 'h', 'i']
->>> d[0] # peek at leftmost item
-'g'
->>> d[-1] # peek at rightmost item
-'i'
-
->>> list(reversed(d)) # list the contents of a deque in reverse
-['i', 'h', 'g']
->>> 'h' in d # search the deque
-True
->>> d.extend('jkl') # add multiple elements at once
->>> d
-deque(['g', 'h', 'i', 'j', 'k', 'l'])
->>> d.rotate(1) # right rotation
->>> d
-deque(['l', 'g', 'h', 'i', 'j', 'k'])
->>> d.rotate(-1) # left rotation
->>> d
-deque(['g', 'h', 'i', 'j', 'k', 'l'])
-
->>> deque(reversed(d)) # make a new deque in reverse order
-deque(['l', 'k', 'j', 'i', 'h', 'g'])
->>> d.clear() # empty the deque
->>> d.pop() # cannot pop from an empty deque
-Traceback (most recent call last):
- File "<pyshell#6>", line 1, in -toplevel-
- d.pop()
-IndexError: pop from an empty deque
-
->>> d.extendleft('abc') # extendleft() reverses the input order
->>> d
-deque(['c', 'b', 'a'])
-\end{verbatim}
-
-\subsubsection{Recipes \label{deque-recipes}}
-
-This section shows various approaches to working with deques.
-
-The \method{rotate()} method provides a way to implement \class{deque}
-slicing and deletion. For example, a pure python implementation of
-\code{del d[n]} relies on the \method{rotate()} method to position
-elements to be popped:
-
-\begin{verbatim}
-def delete_nth(d, n):
- d.rotate(-n)
- d.popleft()
- d.rotate(n)
-\end{verbatim}
-
-To implement \class{deque} slicing, use a similar approach applying
-\method{rotate()} to bring a target element to the left side of the deque.
-Remove old entries with \method{popleft()}, add new entries with
-\method{extend()}, and then reverse the rotation.
-
-With minor variations on that approach, it is easy to implement Forth style
-stack manipulations such as \code{dup}, \code{drop}, \code{swap}, \code{over},
-\code{pick}, \code{rot}, and \code{roll}.
-
-A roundrobin task server can be built from a \class{deque} using
-\method{popleft()} to select the current task and \method{append()}
-to add it back to the tasklist if the input stream is not exhausted:
-
-\begin{verbatim}
-def roundrobin(*iterables):
- pending = deque(iter(i) for i in iterables)
- while pending:
- task = pending.popleft()
- try:
- yield next(task)
- except StopIteration:
- continue
- pending.append(task)
-
->>> for value in roundrobin('abc', 'd', 'efgh'):
-... print value
-
-a
-d
-e
-b
-f
-c
-g
-h
-
-\end{verbatim}
-
-
-Multi-pass data reduction algorithms can be succinctly expressed and
-efficiently coded by extracting elements with multiple calls to
-\method{popleft()}, applying the reduction function, and calling
-\method{append()} to add the result back to the queue.
-
-For example, building a balanced binary tree of nested lists entails
-reducing two adjacent nodes into one by grouping them in a list:
-
-\begin{verbatim}
-def maketree(iterable):
- d = deque(iterable)
- while len(d) > 1:
- pair = [d.popleft(), d.popleft()]
- d.append(pair)
- return list(d)
-
->>> print maketree('abcdefgh')
-[[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]]
-
-\end{verbatim}
-
-
-
-\subsection{\class{defaultdict} objects \label{defaultdict-objects}}
-
-\begin{classdesc}{defaultdict}{\optional{default_factory\optional{, ...}}}
- Returns a new dictionary-like object. \class{defaultdict} is a subclass
- of the builtin \class{dict} class. It overrides one method and adds one
- writable instance variable. The remaining functionality is the same as
- for the \class{dict} class and is not documented here.
-
- The first argument provides the initial value for the
- \member{default_factory} attribute; it defaults to \code{None}.
- All remaining arguments are treated the same as if they were
- passed to the \class{dict} constructor, including keyword arguments.
-
- \versionadded{2.5}
-\end{classdesc}
-
-\class{defaultdict} objects support the following method in addition to
-the standard \class{dict} operations:
-
-\begin{methoddesc}{__missing__}{key}
- If the \member{default_factory} attribute is \code{None}, this raises
- an \exception{KeyError} exception with the \var{key} as argument.
-
- If \member{default_factory} is not \code{None}, it is called without
- arguments to provide a default value for the given \var{key}, this
- value is inserted in the dictionary for the \var{key}, and returned.
-
- If calling \member{default_factory} raises an exception this exception
- is propagated unchanged.
-
- This method is called by the \method{__getitem__} method of the
- \class{dict} class when the requested key is not found; whatever it
- returns or raises is then returned or raised by \method{__getitem__}.
-\end{methoddesc}
-
-\class{defaultdict} objects support the following instance variable:
-
-\begin{memberdesc}{default_factory}
- This attribute is used by the \method{__missing__} method; it is initialized
- from the first argument to the constructor, if present, or to \code{None},
- if absent.
-\end{memberdesc}
-
-
-\subsubsection{\class{defaultdict} Examples \label{defaultdict-examples}}
-
-Using \class{list} as the \member{default_factory}, it is easy to group
-a sequence of key-value pairs into a dictionary of lists:
-
-\begin{verbatim}
->>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
->>> d = defaultdict(list)
->>> for k, v in s:
- d[k].append(v)
-
->>> d.items()
-[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
-\end{verbatim}
-
-When each key is encountered for the first time, it is not already in the
-mapping; so an entry is automatically created using the
-\member{default_factory} function which returns an empty \class{list}. The
-\method{list.append()} operation then attaches the value to the new list. When
-keys are encountered again, the look-up proceeds normally (returning the list
-for that key) and the \method{list.append()} operation adds another value to
-the list. This technique is simpler and faster than an equivalent technique
-using \method{dict.setdefault()}:
-
-\begin{verbatim}
->>> d = {}
->>> for k, v in s:
- d.setdefault(k, []).append(v)
-
->>> d.items()
-[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
-\end{verbatim}
-
-Setting the \member{default_factory} to \class{int} makes the
-\class{defaultdict} useful for counting (like a bag or multiset in other
-languages):
-
-\begin{verbatim}
->>> s = 'mississippi'
->>> d = defaultdict(int)
->>> for k in s:
- d[k] += 1
-
->>> d.items()
-[('i', 4), ('p', 2), ('s', 4), ('m', 1)]
-\end{verbatim}
-
-When a letter is first encountered, it is missing from the mapping, so the
-\member{default_factory} function calls \function{int()} to supply a default
-count of zero. The increment operation then builds up the count for each
-letter.
-
-The function \function{int()} which always returns zero is just a special
-case of constant functions. A faster and more flexible way to create
-constant functions is to use a lambda function which can supply
-any constant value (not just zero):
-
-\begin{verbatim}
->>> def constant_factory(value):
-... return lambda: value
->>> d = defaultdict(constant_factory('<missing>'))
->>> d.update(name='John', action='ran')
->>> '%(name)s %(action)s to %(object)s' % d
-'John ran to <missing>'
-\end{verbatim}
-
-Setting the \member{default_factory} to \class{set} makes the
-\class{defaultdict} useful for building a dictionary of sets:
-
-\begin{verbatim}
->>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
->>> d = defaultdict(set)
->>> for k, v in s:
- d[k].add(v)
-
->>> d.items()
-[('blue', set([2, 4])), ('red', set([1, 3]))]
-\end{verbatim}
-
-
-
-\subsection{\function{NamedTuple} datatype factory function \label{named-tuple-factory}}
-
-\begin{funcdesc}{NamedTuple}{typename, fieldnames}
- Returns a new tuple subclass named \var{typename}. The new subclass is used
- to create tuple-like objects that have fields accessable by attribute
- lookup as well as being indexable and iterable. Instances of the subclass
- also have a helpful docstring (with typename and fieldnames) and a helpful
- \method{__repr__()} method which lists the tuple contents in a \code{name=value}
- format.
- \versionadded{2.6}
-
- The \var{fieldnames} are specified in a single string and are separated by spaces.
- Any valid Python identifier may be used for a field name.
-
- Example:
- \begin{verbatim}
->>> Point = NamedTuple('Point', 'x y')
->>> Point.__doc__ # docstring for the new datatype
-'Point(x, y)'
->>> p = Point(11, y=22) # instantiate with positional or keyword arguments
->>> p[0] + p[1] # works just like the tuple (11, 22)
-33
->>> x, y = p # unpacks just like a tuple
->>> x, y
-(11, 22)
->>> p.x + p.y # fields also accessable by name
-33
->>> p # readable __repr__ with name=value style
-Point(x=11, y=22)
-\end{verbatim}
-
- The use cases are the same as those for tuples. The named factories
- assign meaning to each tuple position and allow for more readable,
- self-documenting code. Named tuples can also be used to assign field names
- to tuples returned by the \module{csv} or \module{sqlite3} modules.
- For example:
-
- \begin{verbatim}
-from itertools import starmap
-import csv
-EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade')
-for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))):
- print record
-\end{verbatim}
-
- To cast an individual record stored as \class{list}, \class{tuple}, or some other
- iterable type, use the star-operator to unpack the values:
-
- \begin{verbatim}
->>> Color = NamedTuple('Color', 'name code')
->>> m = dict(red=1, green=2, blue=3)
->>> print Color(*m.popitem())
-Color(name='blue', code=3)
-\end{verbatim}
-
-\end{funcdesc}
diff --git a/Doc/lib/libcolorsys.tex b/Doc/lib/libcolorsys.tex
deleted file mode 100644
index 2748377..0000000
--- a/Doc/lib/libcolorsys.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{colorsys} ---
- Conversions between color systems}
-
-\declaremodule{standard}{colorsys}
-\modulesynopsis{Conversion functions between RGB and other color systems.}
-\sectionauthor{David Ascher}{da@python.net}
-
-The \module{colorsys} module defines bidirectional conversions of
-color values between colors expressed in the RGB (Red Green Blue)
-color space used in computer monitors and three other coordinate
-systems: YIQ, HLS (Hue Lightness Saturation) and HSV (Hue Saturation
-Value). Coordinates in all of these color spaces are floating point
-values. In the YIQ space, the Y coordinate is between 0 and 1, but
-the I and Q coordinates can be positive or negative. In all other
-spaces, the coordinates are all between 0 and 1.
-
-More information about color spaces can be found at
-\url{http://www.poynton.com/ColorFAQ.html}.
-
-The \module{colorsys} module defines the following functions:
-
-\begin{funcdesc}{rgb_to_yiq}{r, g, b}
-Convert the color from RGB coordinates to YIQ coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{yiq_to_rgb}{y, i, q}
-Convert the color from YIQ coordinates to RGB coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{rgb_to_hls}{r, g, b}
-Convert the color from RGB coordinates to HLS coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{hls_to_rgb}{h, l, s}
-Convert the color from HLS coordinates to RGB coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{rgb_to_hsv}{r, g, b}
-Convert the color from RGB coordinates to HSV coordinates.
-\end{funcdesc}
-
-\begin{funcdesc}{hsv_to_rgb}{h, s, v}
-Convert the color from HSV coordinates to RGB coordinates.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import colorsys
->>> colorsys.rgb_to_hsv(.3, .4, .2)
-(0.25, 0.5, 0.4)
->>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4)
-(0.3, 0.4, 0.2)
-\end{verbatim}
diff --git a/Doc/lib/libcommands.tex b/Doc/lib/libcommands.tex
deleted file mode 100644
index 4a5fa55..0000000
--- a/Doc/lib/libcommands.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{commands} ---
- Utilities for running commands}
-
-\declaremodule{standard}{commands}
- \platform{Unix}
-\modulesynopsis{Utility functions for running external commands.}
-\sectionauthor{Sue Williams}{sbw@provis.com}
-
-
-The \module{commands} module contains wrapper functions for
-\function{os.popen()} which take a system command as a string and
-return any output generated by the command and, optionally, the exit
-status.
-
-The \module{subprocess} module provides more powerful facilities for
-spawning new processes and retrieving their results. Using the
-\module{subprocess} module is preferable to using the \module{commands}
-module.
-
-The \module{commands} module defines the following functions:
-
-
-\begin{funcdesc}{getstatusoutput}{cmd}
-Execute the string \var{cmd} in a shell with \function{os.popen()} and
-return a 2-tuple \code{(\var{status}, \var{output})}. \var{cmd} is
-actually run as \code{\{ \var{cmd} ; \} 2>\&1}, so that the returned
-output will contain output or error messages. A trailing newline is
-stripped from the output. The exit status for the command can be
-interpreted according to the rules for the C function
-\cfunction{wait()}.
-\end{funcdesc}
-
-\begin{funcdesc}{getoutput}{cmd}
-Like \function{getstatusoutput()}, except the exit status is ignored
-and the return value is a string containing the command's output.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import commands
->>> commands.getstatusoutput('ls /bin/ls')
-(0, '/bin/ls')
->>> commands.getstatusoutput('cat /bin/junk')
-(256, 'cat: /bin/junk: No such file or directory')
->>> commands.getstatusoutput('/bin/junk')
-(256, 'sh: /bin/junk: not found')
->>> commands.getoutput('ls /bin/ls')
-'/bin/ls'
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{subprocess}{Module for spawning and managing subprocesses.}
-\end{seealso}
diff --git a/Doc/lib/libcompileall.tex b/Doc/lib/libcompileall.tex
deleted file mode 100644
index 3e9667d..0000000
--- a/Doc/lib/libcompileall.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{compileall} ---
- Byte-compile Python libraries}
-
-\declaremodule{standard}{compileall}
-\modulesynopsis{Tools for byte-compiling all Python source files in a
- directory tree.}
-
-
-This module provides some utility functions to support installing
-Python libraries. These functions compile Python source files in a
-directory tree, allowing users without permission to write to the
-libraries to take advantage of cached byte-code files.
-
-The source file for this module may also be used as a script to
-compile Python sources in directories named on the command line or in
-\code{sys.path}.
-
-
-\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{,
- ddir\optional{, force\optional{,
- rx\optional{, quiet}}}}}}
- Recursively descend the directory tree named by \var{dir}, compiling
- all \file{.py} files along the way. The \var{maxlevels} parameter
- is used to limit the depth of the recursion; it defaults to
- \code{10}. If \var{ddir} is given, it is used as the base path from
- which the filenames used in error messages will be generated. If
- \var{force} is true, modules are re-compiled even if the timestamps
- are up to date.
-
- If \var{rx} is given, it specifies a regular expression of file
- names to exclude from the search; that expression is searched for in
- the full path.
-
- If \var{quiet} is true, nothing is printed to the standard output
- in normal operation.
-\end{funcdesc}
-
-\begin{funcdesc}{compile_path}{\optional{skip_curdir\optional{,
- maxlevels\optional{, force}}}}
- Byte-compile all the \file{.py} files found along \code{sys.path}.
- If \var{skip_curdir} is true (the default), the current directory is
- not included in the search. The \var{maxlevels} and
- \var{force} parameters default to \code{0} and are passed to the
- \function{compile_dir()} function.
-\end{funcdesc}
-
-To force a recompile of all the \file{.py} files in the \file{Lib/}
-subdirectory and all its subdirectories:
-
-\begin{verbatim}
-import compileall
-
-compileall.compile_dir('Lib/', force=True)
-
-# Perform same compilation, excluding files in .svn directories.
-import re
-compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True)
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule[pycompile]{py_compile}{Byte-compile a single source file.}
-\end{seealso}
diff --git a/Doc/lib/libconsts.tex b/Doc/lib/libconsts.tex
deleted file mode 100644
index bf36281..0000000
--- a/Doc/lib/libconsts.tex
+++ /dev/null
@@ -1,33 +0,0 @@
-\section{Built-in Constants}
-
-A small number of constants live in the built-in namespace. They are:
-
-\begin{datadesc}{False}
- The false value of the \class{bool} type.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{True}
- The true value of the \class{bool} type.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{None}
- The sole value of \member{\refmodule{types}.NoneType}. \code{None} is
- frequently used to represent the absence of a value, as when default
- arguments are not passed to a function.
-\end{datadesc}
-
-\begin{datadesc}{NotImplemented}
- Special value which can be returned by the ``rich comparison''
- special methods (\method{__eq__()}, \method{__lt__()}, and friends),
- to indicate that the comparison is not implemented with respect to
- the other type.
-\end{datadesc}
-
-\begin{datadesc}{Ellipsis}
- The same as \code{...}.
- Special value used mostly in conjunction with extended slicing syntax
- for user-defined container data types.
- % XXX Someone who understands extended slicing should fill in here.
-\end{datadesc}
diff --git a/Doc/lib/libcontextlib.tex b/Doc/lib/libcontextlib.tex
deleted file mode 100644
index 0ac5442..0000000
--- a/Doc/lib/libcontextlib.tex
+++ /dev/null
@@ -1,130 +0,0 @@
-\section{\module{contextlib} ---
- Utilities for \keyword{with}-statement contexts.}
-
-\declaremodule{standard}{contextlib}
-\modulesynopsis{Utilities for \keyword{with}-statement contexts.}
-
-\versionadded{2.5}
-
-This module provides utilities for common tasks involving the
-\keyword{with} statement.
-
-Functions provided:
-
-\begin{funcdesc}{contextmanager}{func}
-This function is a decorator that can be used to define a factory
-function for \keyword{with} statement context managers, without
-needing to create a class or separate \method{__enter__()} and
-\method{__exit__()} methods.
-
-A simple example (this is not recommended as a real way of
-generating HTML!):
-
-\begin{verbatim}
-from __future__ import with_statement
-from contextlib import contextmanager
-
-@contextmanager
-def tag(name):
- print "<%s>" % name
- yield
- print "</%s>" % name
-
->>> with tag("h1"):
-... print "foo"
-...
-<h1>
-foo
-</h1>
-\end{verbatim}
-
-The function being decorated must return a generator-iterator when
-called. This iterator must yield exactly one value, which will be
-bound to the targets in the \keyword{with} statement's \keyword{as}
-clause, if any.
-
-At the point where the generator yields, the block nested in the
-\keyword{with} statement is executed. The generator is then resumed
-after the block is exited. If an unhandled exception occurs in the
-block, it is reraised inside the generator at the point where the yield
-occurred. Thus, you can use a
-\keyword{try}...\keyword{except}...\keyword{finally} statement to trap
-the error (if any), or ensure that some cleanup takes place. If an
-exception is trapped merely in order to log it or to perform some
-action (rather than to suppress it entirely), the generator must
-reraise that exception. Otherwise the generator context manager will
-indicate to the \keyword{with} statement that the exception has been
-handled, and execution will resume with the statement immediately
-following the \keyword{with} statement.
-\end{funcdesc}
-
-\begin{funcdesc}{nested}{mgr1\optional{, mgr2\optional{, ...}}}
-Combine multiple context managers into a single nested context manager.
-
-Code like this:
-
-\begin{verbatim}
-from contextlib import nested
-
-with nested(A, B, C) as (X, Y, Z):
- do_something()
-\end{verbatim}
-
-is equivalent to this:
-
-\begin{verbatim}
-with A as X:
- with B as Y:
- with C as Z:
- do_something()
-\end{verbatim}
-
-Note that if the \method{__exit__()} method of one of the nested
-context managers indicates an exception should be suppressed, no
-exception information will be passed to any remaining outer context
-managers. Similarly, if the \method{__exit__()} method of one of the
-nested managers raises an exception, any previous exception state will
-be lost; the new exception will be passed to the
-\method{__exit__()} methods of any remaining outer context managers.
-In general, \method{__exit__()} methods should avoid raising
-exceptions, and in particular they should not re-raise a
-passed-in exception.
-\end{funcdesc}
-
-\label{context-closing}
-\begin{funcdesc}{closing}{thing}
-Return a context manager that closes \var{thing} upon completion of
-the block. This is basically equivalent to:
-
-\begin{verbatim}
-from contextlib import contextmanager
-
-@contextmanager
-def closing(thing):
- try:
- yield thing
- finally:
- thing.close()
-\end{verbatim}
-
-And lets you write code like this:
-\begin{verbatim}
-from __future__ import with_statement
-from contextlib import closing
-import urllib
-
-with closing(urllib.urlopen('http://www.python.org')) as page:
- for line in page:
- print line
-\end{verbatim}
-
-without needing to explicitly close \code{page}. Even if an error
-occurs, \code{page.close()} will be called when the \keyword{with}
-block is exited.
-\end{funcdesc}
-
-\begin{seealso}
- \seepep{0343}{The "with" statement}
- {The specification, background, and examples for the
- Python \keyword{with} statement.}
-\end{seealso}
diff --git a/Doc/lib/libcookie.tex b/Doc/lib/libcookie.tex
deleted file mode 100644
index e5d2038..0000000
--- a/Doc/lib/libcookie.tex
+++ /dev/null
@@ -1,260 +0,0 @@
-\section{\module{Cookie} ---
- HTTP state management}
-
-\declaremodule{standard}{Cookie}
-\modulesynopsis{Support for HTTP state management (cookies).}
-\moduleauthor{Timothy O'Malley}{timo@alum.mit.edu}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-
-
-The \module{Cookie} module defines classes for abstracting the concept of
-cookies, an HTTP state management mechanism. It supports both simple
-string-only cookies, and provides an abstraction for having any serializable
-data-type as cookie value.
-
-The module formerly strictly applied the parsing rules described in
-the \rfc{2109} and \rfc{2068} specifications. It has since been discovered
-that MSIE 3.0x doesn't follow the character rules outlined in those
-specs. As a result, the parsing rules used are a bit less strict.
-
-\begin{excdesc}{CookieError}
-Exception failing because of \rfc{2109} invalidity: incorrect
-attributes, incorrect \mailheader{Set-Cookie} header, etc.
-\end{excdesc}
-
-\begin{classdesc}{BaseCookie}{\optional{input}}
-This class is a dictionary-like object whose keys are strings and
-whose values are \class{Morsel} instances. Note that upon setting a key to
-a value, the value is first converted to a \class{Morsel} containing
-the key and the value.
-
-If \var{input} is given, it is passed to the \method{load()} method.
-\end{classdesc}
-
-\begin{classdesc}{SimpleCookie}{\optional{input}}
-This class derives from \class{BaseCookie} and overrides
-\method{value_decode()} and \method{value_encode()} to be the identity
-and \function{str()} respectively.
-\end{classdesc}
-
-\begin{classdesc}{SerialCookie}{\optional{input}}
-This class derives from \class{BaseCookie} and overrides
-\method{value_decode()} and \method{value_encode()} to be the
-\function{pickle.loads()} and \function{pickle.dumps()}.
-
-\deprecated{2.3}{Reading pickled values from untrusted
-cookie data is a huge security hole, as pickle strings can be crafted
-to cause arbitrary code to execute on your server. It is supported
-for backwards compatibility only, and may eventually go away.}
-\end{classdesc}
-
-\begin{classdesc}{SmartCookie}{\optional{input}}
-This class derives from \class{BaseCookie}. It overrides
-\method{value_decode()} to be \function{pickle.loads()} if it is a
-valid pickle, and otherwise the value itself. It overrides
-\method{value_encode()} to be \function{pickle.dumps()} unless it is a
-string, in which case it returns the value itself.
-
-\deprecated{2.3}{The same security warning from \class{SerialCookie}
-applies here.}
-\end{classdesc}
-
-A further security note is warranted. For backwards compatibility,
-the \module{Cookie} module exports a class named \class{Cookie} which
-is just an alias for \class{SmartCookie}. This is probably a mistake
-and will likely be removed in a future version. You should not use
-the \class{Cookie} class in your applications, for the same reason why
-you should not use the \class{SerialCookie} class.
-
-
-\begin{seealso}
- \seemodule{cookielib}{HTTP cookie handling for web
- \emph{clients}. The \module{cookielib} and \module{Cookie}
- modules do not depend on each other.}
-
- \seerfc{2109}{HTTP State Management Mechanism}{This is the state
- management specification implemented by this module.}
-\end{seealso}
-
-
-\subsection{Cookie Objects \label{cookie-objects}}
-
-\begin{methoddesc}[BaseCookie]{value_decode}{val}
-Return a decoded value from a string representation. Return value can
-be any type. This method does nothing in \class{BaseCookie} --- it exists
-so it can be overridden.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{value_encode}{val}
-Return an encoded value. \var{val} can be any type, but return value
-must be a string. This method does nothing in \class{BaseCookie} --- it exists
-so it can be overridden
-
-In general, it should be the case that \method{value_encode()} and
-\method{value_decode()} are inverses on the range of \var{value_decode}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}}
-Return a string representation suitable to be sent as HTTP headers.
-\var{attrs} and \var{header} are sent to each \class{Morsel}'s
-\method{output()} method. \var{sep} is used to join the headers
-together, and is by default the combination \code{'\e r\e n'} (CRLF).
-\versionchanged[The default separator has been changed from \code{'\e n'}
-to match the cookie specification]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}}
-Return an embeddable JavaScript snippet, which, if run on a browser which
-supports JavaScript, will act the same as if the HTTP headers was sent.
-
-The meaning for \var{attrs} is the same as in \method{output()}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseCookie]{load}{rawdata}
-If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add
-the values found there as \class{Morsel}s. If it is a dictionary, it
-is equivalent to:
-
-\begin{verbatim}
-for k, v in rawdata.items():
- cookie[k] = v
-\end{verbatim}
-\end{methoddesc}
-
-
-\subsection{Morsel Objects \label{morsel-objects}}
-
-\begin{classdesc}{Morsel}{}
-Abstract a key/value pair, which has some \rfc{2109} attributes.
-
-Morsels are dictionary-like objects, whose set of keys is constant ---
-the valid \rfc{2109} attributes, which are
-
-\begin{itemize}
-\item \code{expires}
-\item \code{path}
-\item \code{comment}
-\item \code{domain}
-\item \code{max-age}
-\item \code{secure}
-\item \code{version}
-\end{itemize}
-
-The keys are case-insensitive.
-\end{classdesc}
-
-\begin{memberdesc}[Morsel]{value}
-The value of the cookie.
-\end{memberdesc}
-
-\begin{memberdesc}[Morsel]{coded_value}
-The encoded value of the cookie --- this is what should be sent.
-\end{memberdesc}
-
-\begin{memberdesc}[Morsel]{key}
-The name of the cookie.
-\end{memberdesc}
-
-\begin{methoddesc}[Morsel]{set}{key, value, coded_value}
-Set the \var{key}, \var{value} and \var{coded_value} members.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{isReservedKey}{K}
-Whether \var{K} is a member of the set of keys of a \class{Morsel}.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}}
-Return a string representation of the Morsel, suitable
-to be sent as an HTTP header. By default, all the attributes are included,
-unless \var{attrs} is given, in which case it should be a list of attributes
-to use. \var{header} is by default \code{"Set-Cookie:"}.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{js_output}{\optional{attrs}}
-Return an embeddable JavaScript snippet, which, if run on a browser which
-supports JavaScript, will act the same as if the HTTP header was sent.
-
-The meaning for \var{attrs} is the same as in \method{output()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}}
-Return a string representing the Morsel, without any surrounding HTTP
-or JavaScript.
-
-The meaning for \var{attrs} is the same as in \method{output()}.
-\end{methoddesc}
-
-
-\subsection{Example \label{cookie-example}}
-
-The following example demonstrates how to use the \module{Cookie} module.
-
-\begin{verbatim}
->>> import Cookie
->>> C = Cookie.SimpleCookie()
->>> C = Cookie.SerialCookie()
->>> C = Cookie.SmartCookie()
->>> C["fig"] = "newton"
->>> C["sugar"] = "wafer"
->>> print C # generate HTTP headers
-Set-Cookie: sugar=wafer
-Set-Cookie: fig=newton
->>> print C.output() # same thing
-Set-Cookie: sugar=wafer
-Set-Cookie: fig=newton
->>> C = Cookie.SmartCookie()
->>> C["rocky"] = "road"
->>> C["rocky"]["path"] = "/cookie"
->>> print C.output(header="Cookie:")
-Cookie: rocky=road; Path=/cookie
->>> print C.output(attrs=[], header="Cookie:")
-Cookie: rocky=road
->>> C = Cookie.SmartCookie()
->>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
->>> print C
-Set-Cookie: vienna=finger
-Set-Cookie: chips=ahoy
->>> C = Cookie.SmartCookie()
->>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
->>> print C
-Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
->>> C = Cookie.SmartCookie()
->>> C["oreo"] = "doublestuff"
->>> C["oreo"]["path"] = "/"
->>> print C
-Set-Cookie: oreo=doublestuff; Path=/
->>> C = Cookie.SmartCookie()
->>> C["twix"] = "none for you"
->>> C["twix"].value
-'none for you'
->>> C = Cookie.SimpleCookie()
->>> C["number"] = 7 # equivalent to C["number"] = str(7)
->>> C["string"] = "seven"
->>> C["number"].value
-'7'
->>> C["string"].value
-'seven'
->>> print C
-Set-Cookie: number=7
-Set-Cookie: string=seven
->>> C = Cookie.SerialCookie()
->>> C["number"] = 7
->>> C["string"] = "seven"
->>> C["number"].value
-7
->>> C["string"].value
-'seven'
->>> print C
-Set-Cookie: number="I7\012."
-Set-Cookie: string="S'seven'\012p1\012."
->>> C = Cookie.SmartCookie()
->>> C["number"] = 7
->>> C["string"] = "seven"
->>> C["number"].value
-7
->>> C["string"].value
-'seven'
->>> print C
-Set-Cookie: number="I7\012."
-Set-Cookie: string=seven
-\end{verbatim}
diff --git a/Doc/lib/libcookielib.tex b/Doc/lib/libcookielib.tex
deleted file mode 100644
index 2ea3554..0000000
--- a/Doc/lib/libcookielib.tex
+++ /dev/null
@@ -1,720 +0,0 @@
-\section{\module{cookielib} ---
- Cookie handling for HTTP clients}
-
-\declaremodule{standard}{cookielib}
-\moduleauthor{John J. Lee}{jjl@pobox.com}
-\sectionauthor{John J. Lee}{jjl@pobox.com}
-
-\versionadded{2.4}
-
-\modulesynopsis{Cookie handling for HTTP clients}
-
-The \module{cookielib} module defines classes for automatic handling
-of HTTP cookies. It is useful for accessing web sites that require
-small pieces of data -- \dfn{cookies} -- to be set on the client
-machine by an HTTP response from a web server, and then returned to
-the server in later HTTP requests.
-
-Both the regular Netscape cookie protocol and the protocol defined by
-\rfc{2965} are handled. RFC 2965 handling is switched off by default.
-\rfc{2109} cookies are parsed as Netscape cookies and subsequently
-treated either as Netscape or RFC 2965 cookies according to the
-'policy' in effect. Note that the great majority of cookies on the
-Internet are Netscape cookies. \module{cookielib} attempts to follow
-the de-facto Netscape cookie protocol (which differs substantially
-from that set out in the original Netscape specification), including
-taking note of the \code{max-age} and \code{port} cookie-attributes
-introduced with RFC 2965. \note{The various named parameters found in
-\mailheader{Set-Cookie} and \mailheader{Set-Cookie2} headers
-(eg. \code{domain} and \code{expires}) are conventionally referred to
-as \dfn{attributes}. To distinguish them from Python attributes, the
-documentation for this module uses the term \dfn{cookie-attribute}
-instead}.
-
-
-The module defines the following exception:
-
-\begin{excdesc}{LoadError}
-Instances of \class{FileCookieJar} raise this exception on failure to
-load cookies from a file. \note{For backwards-compatibility
-with Python 2.4 (which raised an \exception{IOError}),
-\exception{LoadError} is a subclass of \exception{IOError}}.
-\end{excdesc}
-
-
-The following classes are provided:
-
-\begin{classdesc}{CookieJar}{policy=\constant{None}}
-\var{policy} is an object implementing the \class{CookiePolicy}
-interface.
-
-The \class{CookieJar} class stores HTTP cookies. It extracts cookies
-from HTTP requests, and returns them in HTTP responses.
-\class{CookieJar} instances automatically expire contained cookies
-when necessary. Subclasses are also responsible for storing and
-retrieving cookies from a file or database.
-\end{classdesc}
-
-\begin{classdesc}{FileCookieJar}{filename, delayload=\constant{None},
- policy=\constant{None}}
-\var{policy} is an object implementing the \class{CookiePolicy}
-interface. For the other arguments, see the documentation for the
-corresponding attributes.
-
-A \class{CookieJar} which can load cookies from, and perhaps save
-cookies to, a file on disk. Cookies are \strong{NOT} loaded from the
-named file until either the \method{load()} or \method{revert()}
-method is called. Subclasses of this class are documented in section
-\ref{file-cookie-jar-classes}.
-\end{classdesc}
-
-\begin{classdesc}{CookiePolicy}{}
-This class is responsible for deciding whether each cookie should be
-accepted from / returned to the server.
-\end{classdesc}
-
-\begin{classdesc}{DefaultCookiePolicy}{
- blocked_domains=\constant{None},
- allowed_domains=\constant{None},
- netscape=\constant{True}, rfc2965=\constant{False},
- rfc2109_as_netscape=\constant{None},
- hide_cookie2=\constant{False},
- strict_domain=\constant{False},
- strict_rfc2965_unverifiable=\constant{True},
- strict_ns_unverifiable=\constant{False},
- strict_ns_domain=\constant{DefaultCookiePolicy.DomainLiberal},
- strict_ns_set_initial_dollar=\constant{False},
- strict_ns_set_path=\constant{False}
- }
-
-Constructor arguments should be passed as keyword arguments only.
-\var{blocked_domains} is a sequence of domain names that we never
-accept cookies from, nor return cookies to. \var{allowed_domains} if
-not \constant{None}, this is a sequence of the only domains for which
-we accept and return cookies. For all other arguments, see the
-documentation for \class{CookiePolicy} and \class{DefaultCookiePolicy}
-objects.
-
-\class{DefaultCookiePolicy} implements the standard accept / reject
-rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies
-(ie. cookies received in a \mailheader{Set-Cookie} header with a
-version cookie-attribute of 1) are treated according to the RFC 2965
-rules. However, if RFC 2965 handling is turned off or
-\member{rfc2109_as_netscape} is True, RFC 2109 cookies are
-'downgraded' by the \class{CookieJar} instance to Netscape cookies, by
-setting the \member{version} attribute of the \class{Cookie} instance
-to 0. \class{DefaultCookiePolicy} also provides some parameters to
-allow some fine-tuning of policy.
-\end{classdesc}
-
-\begin{classdesc}{Cookie}{}
-This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is
-not expected that users of \module{cookielib} construct their own
-\class{Cookie} instances. Instead, if necessary, call
-\method{make_cookies()} on a \class{CookieJar} instance.
-\end{classdesc}
-
-\begin{seealso}
-
-\seemodule{urllib2}{URL opening with automatic cookie handling.}
-
-\seemodule{Cookie}{HTTP cookie classes, principally useful for
-server-side code. The \module{cookielib} and \module{Cookie} modules
-do not depend on each other.}
-
-\seeurl{http://wwwsearch.sf.net/ClientCookie/}{Extensions to this
-module, including a class for reading Microsoft Internet Explorer
-cookies on Windows.}
-
-\seeurl{http://www.netscape.com/newsref/std/cookie_spec.html}{The
-specification of the original Netscape cookie protocol. Though this
-is still the dominant protocol, the 'Netscape cookie protocol'
-implemented by all the major browsers (and \module{cookielib}) only
-bears a passing resemblance to the one sketched out in
-\code{cookie_spec.html}.}
-
-\seerfc{2109}{HTTP State Management Mechanism}{Obsoleted by RFC 2965.
-Uses \mailheader{Set-Cookie} with version=1.}
-
-\seerfc{2965}{HTTP State Management Mechanism}{The Netscape protocol
-with the bugs fixed. Uses \mailheader{Set-Cookie2} in place of
-\mailheader{Set-Cookie}. Not widely used.}
-
-\seeurl{http://kristol.org/cookie/errata.html}{Unfinished errata to
-RFC 2965.}
-
-\seerfc{2964}{Use of HTTP State Management}{}
-
-\end{seealso}
-
-
-\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}}
-
-\class{CookieJar} objects support the iterator protocol for iterating
-over contained \class{Cookie} objects.
-
-\class{CookieJar} has the following methods:
-
-\begin{methoddesc}[CookieJar]{add_cookie_header}{request}
-Add correct \mailheader{Cookie} header to \var{request}.
-
-If policy allows (ie. the \member{rfc2965} and \member{hide_cookie2}
-attributes of the \class{CookieJar}'s \class{CookiePolicy} instance
-are true and false respectively), the \mailheader{Cookie2} header is
-also added when appropriate.
-
-The \var{request} object (usually a \class{urllib2.Request} instance)
-must support the methods \method{get_full_url()}, \method{get_host()},
-\method{get_type()}, \method{unverifiable()},
-\method{get_origin_req_host()}, \method{has_header()},
-\method{get_header()}, \method{header_items()}, and
-\method{add_unredirected_header()},as documented by \module{urllib2}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{extract_cookies}{response, request}
-Extract cookies from HTTP \var{response} and store them in the
-\class{CookieJar}, where allowed by policy.
-
-The \class{CookieJar} will look for allowable \mailheader{Set-Cookie}
-and \mailheader{Set-Cookie2} headers in the \var{response} argument,
-and store cookies as appropriate (subject to the
-\method{CookiePolicy.set_ok()} method's approval).
-
-The \var{response} object (usually the result of a call to
-\method{urllib2.urlopen()}, or similar) should support an
-\method{info()} method, which returns an object with a
-\method{getallmatchingheaders()} method (usually a
-\class{mimetools.Message} instance).
-
-The \var{request} object (usually a \class{urllib2.Request} instance)
-must support the methods \method{get_full_url()}, \method{get_host()},
-\method{unverifiable()}, and \method{get_origin_req_host()}, as
-documented by \module{urllib2}. The request is used to set default
-values for cookie-attributes as well as for checking that the cookie
-is allowed to be set.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{set_policy}{policy}
-Set the \class{CookiePolicy} instance to be used.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{make_cookies}{response, request}
-Return sequence of \class{Cookie} objects extracted from
-\var{response} object.
-
-See the documentation for \method{extract_cookies} for the interfaces
-required of the \var{response} and \var{request} arguments.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{set_cookie_if_ok}{cookie, request}
-Set a \class{Cookie} if policy says it's OK to do so.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{set_cookie}{cookie}
-Set a \class{Cookie}, without checking with policy to see whether or
-not it should be set.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{clear}{\optional{domain\optional{,
- path\optional{, name}}}}
-Clear some cookies.
-
-If invoked without arguments, clear all cookies. If given a single
-argument, only cookies belonging to that \var{domain} will be removed.
-If given two arguments, cookies belonging to the specified
-\var{domain} and URL \var{path} are removed. If given three
-arguments, then the cookie with the specified \var{domain}, \var{path}
-and \var{name} is removed.
-
-Raises \exception{KeyError} if no matching cookie exists.
-\end{methoddesc}
-
-\begin{methoddesc}[CookieJar]{clear_session_cookies}{}
-Discard all session cookies.
-
-Discards all contained cookies that have a true \member{discard}
-attribute (usually because they had either no \code{max-age} or
-\code{expires} cookie-attribute, or an explicit \code{discard}
-cookie-attribute). For interactive browsers, the end of a session
-usually corresponds to closing the browser window.
-
-Note that the \method{save()} method won't save session cookies
-anyway, unless you ask otherwise by passing a true
-\var{ignore_discard} argument.
-\end{methoddesc}
-
-\class{FileCookieJar} implements the following additional methods:
-
-\begin{methoddesc}[FileCookieJar]{save}{filename=\constant{None},
- ignore_discard=\constant{False}, ignore_expires=\constant{False}}
-Save cookies to a file.
-
-This base class raises \exception{NotImplementedError}. Subclasses may
-leave this method unimplemented.
-
-\var{filename} is the name of file in which to save cookies. If
-\var{filename} is not specified, \member{self.filename} is used (whose
-default is the value passed to the constructor, if any); if
-\member{self.filename} is \constant{None}, \exception{ValueError} is
-raised.
-
-\var{ignore_discard}: save even cookies set to be discarded.
-\var{ignore_expires}: save even cookies that have expired
-
-The file is overwritten if it already exists, thus wiping all the
-cookies it contains. Saved cookies can be restored later using the
-\method{load()} or \method{revert()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[FileCookieJar]{load}{filename=\constant{None},
- ignore_discard=\constant{False}, ignore_expires=\constant{False}}
-Load cookies from a file.
-
-Old cookies are kept unless overwritten by newly loaded ones.
-
-Arguments are as for \method{save()}.
-
-The named file must be in the format understood by the class, or
-\exception{LoadError} will be raised. Also, \exception{IOError} may
-be raised, for example if the file does not exist. \note{For
-backwards-compatibility with Python 2.4 (which raised
-an \exception{IOError}), \exception{LoadError} is a subclass
-of \exception{IOError}.}
-\end{methoddesc}
-
-\begin{methoddesc}[FileCookieJar]{revert}{filename=\constant{None},
- ignore_discard=\constant{False}, ignore_expires=\constant{False}}
-Clear all cookies and reload cookies from a saved file.
-
-\method{revert()} can raise the same exceptions as \method{load()}.
-If there is a failure, the object's state will not be altered.
-\end{methoddesc}
-
-\class{FileCookieJar} instances have the following public attributes:
-
-\begin{memberdesc}[FileCookieJar]{filename}
-Filename of default file in which to keep cookies. This attribute may
-be assigned to.
-\end{memberdesc}
-
-\begin{memberdesc}[FileCookieJar]{delayload}
-If true, load cookies lazily from disk. This attribute should not be
-assigned to. This is only a hint, since this only affects
-performance, not behaviour (unless the cookies on disk are changing).
-A \class{CookieJar} object may ignore it. None of the
-\class{FileCookieJar} classes included in the standard library lazily
-loads cookies.
-\end{memberdesc}
-
-
-\subsection{FileCookieJar subclasses and co-operation with web browsers
- \label{file-cookie-jar-classes}}
-
-The following \class{CookieJar} subclasses are provided for reading
-and writing . Further \class{CookieJar} subclasses, including one
-that reads Microsoft Internet Explorer cookies, are available at
-\url{http://wwwsearch.sf.net/ClientCookie/}.
-
-\begin{classdesc}{MozillaCookieJar}{filename, delayload=\constant{None},
- policy=\constant{None}}
-A \class{FileCookieJar} that can load from and save cookies to disk in
-the Mozilla \code{cookies.txt} file format (which is also used by the
-Lynx and Netscape browsers). \note{This loses information about RFC
-2965 cookies, and also about newer or non-standard cookie-attributes
-such as \code{port}.}
-
-\warning{Back up your cookies before saving if you have cookies whose
-loss / corruption would be inconvenient (there are some subtleties
-which may lead to slight changes in the file over a load / save
-round-trip).}
-
-Also note that cookies saved while Mozilla is running will get
-clobbered by Mozilla.
-\end{classdesc}
-
-\begin{classdesc}{LWPCookieJar}{filename, delayload=\constant{None},
- policy=\constant{None}}
-A \class{FileCookieJar} that can load from and save cookies to disk in
-format compatible with the libwww-perl library's \code{Set-Cookie3}
-file format. This is convenient if you want to store cookies in a
-human-readable file.
-\end{classdesc}
-
-
-\subsection{CookiePolicy Objects \label{cookie-policy-objects}}
-
-Objects implementing the \class{CookiePolicy} interface have the
-following methods:
-
-\begin{methoddesc}[CookiePolicy]{set_ok}{cookie, request}
-Return boolean value indicating whether cookie should be accepted from server.
-
-\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is
-an object implementing the interface defined by the documentation for
-\method{CookieJar.extract_cookies()}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookiePolicy]{return_ok}{cookie, request}
-Return boolean value indicating whether cookie should be returned to server.
-
-\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is
-an object implementing the interface defined by the documentation for
-\method{CookieJar.add_cookie_header()}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookiePolicy]{domain_return_ok}{domain, request}
-Return false if cookies should not be returned, given cookie domain.
-
-This method is an optimization. It removes the need for checking
-every cookie with a particular domain (which might involve reading
-many files). Returning true from \method{domain_return_ok()} and
-\method{path_return_ok()} leaves all the work to \method{return_ok()}.
-
-If \method{domain_return_ok()} returns true for the cookie domain,
-\method{path_return_ok()} is called for the cookie path. Otherwise,
-\method{path_return_ok()} and \method{return_ok()} are never called
-for that cookie domain. If \method{path_return_ok()} returns true,
-\method{return_ok()} is called with the \class{Cookie} object itself
-for a full check. Otherwise, \method{return_ok()} is never called for
-that cookie path.
-
-Note that \method{domain_return_ok()} is called for every
-\emph{cookie} domain, not just for the \emph{request} domain. For
-example, the function might be called with both \code{".example.com"}
-and \code{"www.example.com"} if the request domain is
-\code{"www.example.com"}. The same goes for
-\method{path_return_ok()}.
-
-The \var{request} argument is as documented for \method{return_ok()}.
-\end{methoddesc}
-
-\begin{methoddesc}[CookiePolicy]{path_return_ok}{path, request}
-Return false if cookies should not be returned, given cookie path.
-
-See the documentation for \method{domain_return_ok()}.
-\end{methoddesc}
-
-
-In addition to implementing the methods above, implementations of the
-\class{CookiePolicy} interface must also supply the following
-attributes, indicating which protocols should be used, and how. All
-of these attributes may be assigned to.
-
-\begin{memberdesc}[CookiePolicy]{netscape}
-Implement Netscape protocol.
-\end{memberdesc}
-\begin{memberdesc}[CookiePolicy]{rfc2965}
-Implement RFC 2965 protocol.
-\end{memberdesc}
-\begin{memberdesc}[CookiePolicy]{hide_cookie2}
-Don't add \mailheader{Cookie2} header to requests (the presence of
-this header indicates to the server that we understand RFC 2965
-cookies).
-\end{memberdesc}
-
-The most useful way to define a \class{CookiePolicy} class is by
-subclassing from \class{DefaultCookiePolicy} and overriding some or
-all of the methods above. \class{CookiePolicy} itself may be used as
-a 'null policy' to allow setting and receiving any and all cookies
-(this is unlikely to be useful).
-
-
-\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}}
-
-Implements the standard rules for accepting and returning cookies.
-
-Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is
-switched off by default.
-
-The easiest way to provide your own policy is to override this class
-and call its methods in your overridden implementations before adding
-your own additional checks:
-
-\begin{verbatim}
-import cookielib
-class MyCookiePolicy(cookielib.DefaultCookiePolicy):
- def set_ok(self, cookie, request):
- if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
- return False
- if i_dont_want_to_store_this_cookie(cookie):
- return False
- return True
-\end{verbatim}
-
-In addition to the features required to implement the
-\class{CookiePolicy} interface, this class allows you to block and
-allow domains from setting and receiving cookies. There are also some
-strictness switches that allow you to tighten up the rather loose
-Netscape protocol rules a little bit (at the cost of blocking some
-benign cookies).
-
-A domain blacklist and whitelist is provided (both off by default).
-Only domains not in the blacklist and present in the whitelist (if the
-whitelist is active) participate in cookie setting and returning. Use
-the \var{blocked_domains} constructor argument, and
-\method{blocked_domains()} and \method{set_blocked_domains()} methods
-(and the corresponding argument and methods for
-\var{allowed_domains}). If you set a whitelist, you can turn it off
-again by setting it to \constant{None}.
-
-Domains in block or allow lists that do not start with a dot must
-equal the cookie domain to be matched. For example,
-\code{"example.com"} matches a blacklist entry of
-\code{"example.com"}, but \code{"www.example.com"} does not. Domains
-that do start with a dot are matched by more specific domains too.
-For example, both \code{"www.example.com"} and
-\code{"www.coyote.example.com"} match \code{".example.com"} (but
-\code{"example.com"} itself does not). IP addresses are an exception,
-and must match exactly. For example, if blocked_domains contains
-\code{"192.168.1.2"} and \code{".168.1.2"}, 192.168.1.2 is blocked,
-but 193.168.1.2 is not.
-
-\class{DefaultCookiePolicy} implements the following additional
-methods:
-
-\begin{methoddesc}[DefaultCookiePolicy]{blocked_domains}{}
-Return the sequence of blocked domains (as a tuple).
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{set_blocked_domains}
- {blocked_domains}
-Set the sequence of blocked domains.
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{is_blocked}{domain}
-Return whether \var{domain} is on the blacklist for setting or
-receiving cookies.
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{allowed_domains}{}
-Return \constant{None}, or the sequence of allowed domains (as a tuple).
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{set_allowed_domains}
- {allowed_domains}
-Set the sequence of allowed domains, or \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[DefaultCookiePolicy]{is_not_allowed}{domain}
-Return whether \var{domain} is not on the whitelist for setting or
-receiving cookies.
-\end{methoddesc}
-
-\class{DefaultCookiePolicy} instances have the following attributes,
-which are all initialised from the constructor arguments of the same
-name, and which may all be assigned to.
-
-\begin{memberdesc}[DefaultCookiePolicy]{rfc2109_as_netscape}
-If true, request that the \class{CookieJar} instance downgrade RFC
-2109 cookies (ie. cookies received in a \mailheader{Set-Cookie} header
-with a version cookie-attribute of 1) to Netscape cookies by setting
-the version attribute of the \class{Cookie} instance to 0. The
-default value is \constant{None}, in which case RFC 2109 cookies are
-downgraded if and only if RFC 2965 handling is turned off. Therefore,
-RFC 2109 cookies are downgraded by default.
-\versionadded{2.5}
-\end{memberdesc}
-
-General strictness switches:
-
-\begin{memberdesc}[DefaultCookiePolicy]{strict_domain}
-Don't allow sites to set two-component domains with country-code
-top-level domains like \code{.co.uk}, \code{.gov.uk},
-\code{.co.nz}.etc. This is far from perfect and isn't guaranteed to
-work!
-\end{memberdesc}
-
-RFC 2965 protocol strictness switches:
-
-\begin{memberdesc}[DefaultCookiePolicy]{strict_rfc2965_unverifiable}
-Follow RFC 2965 rules on unverifiable transactions (usually, an
-unverifiable transaction is one resulting from a redirect or a request
-for an image hosted on another site). If this is false, cookies are
-\emph{never} blocked on the basis of verifiability
-\end{memberdesc}
-
-Netscape protocol strictness switches:
-
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_unverifiable}
-apply RFC 2965 rules on unverifiable transactions even to Netscape
-cookies
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_domain}
-Flags indicating how strict to be with domain-matching rules for
-Netscape cookies. See below for acceptable values.
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_initial_dollar}
-Ignore cookies in Set-Cookie: headers that have names starting with
-\code{'\$'}.
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_path}
-Don't allow setting cookies whose path doesn't path-match request URI.
-\end{memberdesc}
-
-\member{strict_ns_domain} is a collection of flags. Its value is
-constructed by or-ing together (for example,
-\code{DomainStrictNoDots|DomainStrictNonDomain} means both flags are
-set).
-
-\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNoDots}
-When setting cookies, the 'host prefix' must not contain a dot
-(eg. \code{www.foo.bar.com} can't set a cookie for \code{.bar.com},
-because \code{www.foo} contains a dot).
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNonDomain}
-Cookies that did not explicitly specify a \code{domain}
-cookie-attribute can only be returned to a domain equal to the domain
-that set the cookie (eg. \code{spam.example.com} won't be returned
-cookies from \code{example.com} that had no \code{domain}
-cookie-attribute).
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{DomainRFC2965Match}
-When setting cookies, require a full RFC 2965 domain-match.
-\end{memberdesc}
-
-The following attributes are provided for convenience, and are the
-most useful combinations of the above flags:
-
-\begin{memberdesc}[DefaultCookiePolicy]{DomainLiberal}
-Equivalent to 0 (ie. all of the above Netscape domain strictness flags
-switched off).
-\end{memberdesc}
-\begin{memberdesc}[DefaultCookiePolicy]{DomainStrict}
-Equivalent to \code{DomainStrictNoDots|DomainStrictNonDomain}.
-\end{memberdesc}
-
-
-\subsection{Cookie Objects \label{cookie-objects}}
-
-\class{Cookie} instances have Python attributes roughly corresponding
-to the standard cookie-attributes specified in the various cookie
-standards. The correspondence is not one-to-one, because there are
-complicated rules for assigning default values, because the
-\code{max-age} and \code{expires} cookie-attributes contain equivalent
-information, and because RFC 2109 cookies may be 'downgraded' by
-\module{cookielib} from version 1 to version 0 (Netscape) cookies.
-
-Assignment to these attributes should not be necessary other than in
-rare circumstances in a \class{CookiePolicy} method. The class does
-not enforce internal consistency, so you should know what you're
-doing if you do that.
-
-\begin{memberdesc}[Cookie]{version}
-Integer or \constant{None}. Netscape cookies have \member{version} 0.
-RFC 2965 and RFC 2109 cookies have a \code{version} cookie-attribute
-of 1. However, note that \module{cookielib} may 'downgrade' RFC 2109
-cookies to Netscape cookies, in which case \member{version} is 0.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{name}
-Cookie name (a string).
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{value}
-Cookie value (a string), or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{port}
-String representing a port or a set of ports (eg. '80', or '80,8080'),
-or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{path}
-Cookie path (a string, eg. \code{'/acme/rocket_launchers'}).
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{secure}
-True if cookie should only be returned over a secure connection.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{expires}
-Integer expiry date in seconds since epoch, or \constant{None}. See
-also the \method{is_expired()} method.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{discard}
-True if this is a session cookie.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{comment}
-String comment from the server explaining the function of this cookie,
-or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{comment_url}
-URL linking to a comment from the server explaining the function of
-this cookie, or \constant{None}.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{rfc2109}
-True if this cookie was received as an RFC 2109 cookie (ie. the cookie
-arrived in a \mailheader{Set-Cookie} header, and the value of the
-Version cookie-attribute in that header was 1). This attribute is
-provided because \module{cookielib} may 'downgrade' RFC 2109 cookies
-to Netscape cookies, in which case \member{version} is 0.
-\versionadded{2.5}
-\end{memberdesc}
-
-\begin{memberdesc}[Cookie]{port_specified}
-True if a port or set of ports was explicitly specified by the server
-(in the \mailheader{Set-Cookie} / \mailheader{Set-Cookie2} header).
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{domain_specified}
-True if a domain was explicitly specified by the server.
-\end{memberdesc}
-\begin{memberdesc}[Cookie]{domain_initial_dot}
-True if the domain explicitly specified by the server began with a
-dot (\code{'.'}).
-\end{memberdesc}
-
-Cookies may have additional non-standard cookie-attributes. These may
-be accessed using the following methods:
-
-\begin{methoddesc}[Cookie]{has_nonstandard_attr}{name}
-Return true if cookie has the named cookie-attribute.
-\end{methoddesc}
-\begin{methoddesc}[Cookie]{get_nonstandard_attr}{name, default=\constant{None}}
-If cookie has the named cookie-attribute, return its value.
-Otherwise, return \var{default}.
-\end{methoddesc}
-\begin{methoddesc}[Cookie]{set_nonstandard_attr}{name, value}
-Set the value of the named cookie-attribute.
-\end{methoddesc}
-
-The \class{Cookie} class also defines the following method:
-
-\begin{methoddesc}[Cookie]{is_expired}{\optional{now=\constant{None}}}
-True if cookie has passed the time at which the server requested it
-should expire. If \var{now} is given (in seconds since the epoch),
-return whether the cookie has expired at the specified time.
-\end{methoddesc}
-
-
-\subsection{Examples \label{cookielib-examples}}
-
-The first example shows the most common usage of \module{cookielib}:
-
-\begin{verbatim}
-import cookielib, urllib2
-cj = cookielib.CookieJar()
-opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
-r = opener.open("http://example.com/")
-\end{verbatim}
-
-This example illustrates how to open a URL using your Netscape,
-Mozilla, or Lynx cookies (assumes \UNIX{}/Netscape convention for
-location of the cookies file):
-
-\begin{verbatim}
-import os, cookielib, urllib2
-cj = cookielib.MozillaCookieJar()
-cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
-opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
-r = opener.open("http://example.com/")
-\end{verbatim}
-
-The next example illustrates the use of \class{DefaultCookiePolicy}.
-Turn on RFC 2965 cookies, be more strict about domains when setting
-and returning Netscape cookies, and block some domains from setting
-cookies or having them returned:
-
-\begin{verbatim}
-import urllib2
-from cookielib import CookieJar, DefaultCookiePolicy
-policy = DefaultCookiePolicy(
- rfc2965=True, strict_ns_domain=Policy.DomainStrict,
- blocked_domains=["ads.net", ".ads.net"])
-cj = CookieJar(policy)
-opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
-r = opener.open("http://example.com/")
-\end{verbatim}
diff --git a/Doc/lib/libcopy.tex b/Doc/lib/libcopy.tex
deleted file mode 100644
index 5964187..0000000
--- a/Doc/lib/libcopy.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{\module{copy} ---
- Shallow and deep copy operations}
-
-\declaremodule{standard}{copy}
-\modulesynopsis{Shallow and deep copy operations.}
-
-
-This module provides generic (shallow and deep) copying operations.
-\withsubitem{(in copy)}{\ttindex{copy()}\ttindex{deepcopy()}}
-
-Interface summary:
-
-\begin{verbatim}
-import copy
-
-x = copy.copy(y) # make a shallow copy of y
-x = copy.deepcopy(y) # make a deep copy of y
-\end{verbatim}
-%
-For module specific errors, \exception{copy.error} is raised.
-
-The difference between shallow and deep copying is only relevant for
-compound objects (objects that contain other objects, like lists or
-class instances):
-
-\begin{itemize}
-
-\item
-A \emph{shallow copy} constructs a new compound object and then (to the
-extent possible) inserts \emph{references} into it to the objects found
-in the original.
-
-\item
-A \emph{deep copy} constructs a new compound object and then,
-recursively, inserts \emph{copies} into it of the objects found in the
-original.
-
-\end{itemize}
-
-Two problems often exist with deep copy operations that don't exist
-with shallow copy operations:
-
-\begin{itemize}
-
-\item
-Recursive objects (compound objects that, directly or indirectly,
-contain a reference to themselves) may cause a recursive loop.
-
-\item
-Because deep copy copies \emph{everything} it may copy too much,
-e.g., administrative data structures that should be shared even
-between copies.
-
-\end{itemize}
-
-The \function{deepcopy()} function avoids these problems by:
-
-\begin{itemize}
-
-\item
-keeping a ``memo'' dictionary of objects already copied during the current
-copying pass; and
-
-\item
-letting user-defined classes override the copying operation or the
-set of components copied.
-
-\end{itemize}
-
-This module does not copy types like module, method,
-stack trace, stack frame, file, socket, window, array, or any similar
-types. It does ``copy'' functions and classes (shallow and deeply),
-by returning the original object unchanged; this is compatible with
-the way these are treated by the \module{pickle} module.
-\versionchanged[Added copying functions]{2.5}
-
-Classes can use the same interfaces to control copying that they use
-to control pickling. See the description of module
-\refmodule{pickle}\refstmodindex{pickle} for information on these
-methods. The \module{copy} module does not use the
-\refmodule[copyreg]{copy_reg} registration module.
-
-In order for a class to define its own copy implementation, it can
-define special methods \method{__copy__()} and
-\method{__deepcopy__()}. The former is called to implement the
-shallow copy operation; no additional arguments are passed. The
-latter is called to implement the deep copy operation; it is passed
-one argument, the memo dictionary. If the \method{__deepcopy__()}
-implementation needs to make a deep copy of a component, it should
-call the \function{deepcopy()} function with the component as first
-argument and the memo dictionary as second argument.
-\withsubitem{(copy protocol)}{\ttindex{__copy__()}\ttindex{__deepcopy__()}}
-
-\begin{seealso}
-\seemodule{pickle}{Discussion of the special methods used to
-support object state retrieval and restoration.}
-\end{seealso}
diff --git a/Doc/lib/libcopyreg.tex b/Doc/lib/libcopyreg.tex
deleted file mode 100644
index 594978c..0000000
--- a/Doc/lib/libcopyreg.tex
+++ /dev/null
@@ -1,40 +0,0 @@
-\section{\module{copy_reg} ---
- Register \module{pickle} support functions}
-
-\declaremodule[copyreg]{standard}{copy_reg}
-\modulesynopsis{Register \module{pickle} support functions.}
-
-
-The \module{copy_reg} module provides support for the
-\refmodule{pickle}\refstmodindex{pickle}\ and
-\refmodule{cPickle}\refbimodindex{cPickle}\ modules. The
-\refmodule{copy}\refstmodindex{copy}\ module is likely to use this in the
-future as well. It provides configuration information about object
-constructors which are not classes. Such constructors may be factory
-functions or class instances.
-
-
-\begin{funcdesc}{constructor}{object}
- Declares \var{object} to be a valid constructor. If \var{object} is
- not callable (and hence not valid as a constructor), raises
- \exception{TypeError}.
-\end{funcdesc}
-
-\begin{funcdesc}{pickle}{type, function\optional{, constructor}}
- Declares that \var{function} should be used as a ``reduction''
- function for objects of type \var{type}; \var{type} must not be a
- ``classic'' class object. (Classic classes are handled differently;
- see the documentation for the \refmodule{pickle} module for
- details.) \var{function} should return either a string or a tuple
- containing two or three elements.
-
- The optional \var{constructor} parameter, if provided, is a
- callable object which can be used to reconstruct the object when
- called with the tuple of arguments returned by \var{function} at
- pickling time. \exception{TypeError} will be raised if
- \var{object} is a class or \var{constructor} is not callable.
-
- See the \refmodule{pickle} module for more
- details on the interface expected of \var{function} and
- \var{constructor}.
-\end{funcdesc}
diff --git a/Doc/lib/libcrypt.tex b/Doc/lib/libcrypt.tex
deleted file mode 100644
index 55e7163..0000000
--- a/Doc/lib/libcrypt.tex
+++ /dev/null
@@ -1,60 +0,0 @@
-\section{\module{crypt} ---
- Function to check \UNIX{} passwords}
-
-\declaremodule{builtin}{crypt}
- \platform{Unix}
-\modulesynopsis{The \cfunction{crypt()} function used to check
- \UNIX\ passwords.}
-\moduleauthor{Steven D. Majewski}{sdm7g@virginia.edu}
-\sectionauthor{Steven D. Majewski}{sdm7g@virginia.edu}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-
-This module implements an interface to the
-\manpage{crypt}{3}\index{crypt(3)} routine, which is a one-way hash
-function based upon a modified DES\indexii{cipher}{DES} algorithm; see
-the \UNIX{} man page for further details. Possible uses include
-allowing Python scripts to accept typed passwords from the user, or
-attempting to crack \UNIX{} passwords with a dictionary.
-
-Notice that the behavior of this module depends on the actual implementation
-of the \manpage{crypt}{3}\index{crypt(3)} routine in the running system.
-Therefore, any extensions available on the current implementation will also
-be available on this module.
-\begin{funcdesc}{crypt}{word, salt}
- \var{word} will usually be a user's password as typed at a prompt or
- in a graphical interface. \var{salt} is usually a random
- two-character string which will be used to perturb the DES algorithm
- in one of 4096 ways. The characters in \var{salt} must be in the
- set \regexp{[./a-zA-Z0-9]}. Returns the hashed password as a
- string, which will be composed of characters from the same alphabet
- as the salt (the first two characters represent the salt itself).
-
- Since a few \manpage{crypt}{3}\index{crypt(3)} extensions allow different
- values, with different sizes in the \var{salt}, it is recommended to use
- the full crypted password as salt when checking for a password.
-\end{funcdesc}
-
-
-A simple example illustrating typical use:
-
-\begin{verbatim}
-import crypt, getpass, pwd
-
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-def login():
- username = raw_input('Python login:')
- cryptedpasswd = pwd.getpwnam(username)[1]
- if cryptedpasswd:
- if cryptedpasswd == 'x' or cryptedpasswd == '*':
- raise "Sorry, currently no support for shadow passwords"
- cleartext = getpass.getpass()
- return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
- else:
- return 1
-\end{verbatim}
diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex
deleted file mode 100644
index 75987bf..0000000
--- a/Doc/lib/libcrypto.tex
+++ /dev/null
@@ -1,19 +0,0 @@
-\chapter{Cryptographic Services}
-\label{crypto}
-\index{cryptography}
-
-The modules described in this chapter implement various algorithms of
-a cryptographic nature. They are available at the discretion of the
-installation. Here's an overview:
-
-\localmoduletable
-
-Hardcore cypherpunks will probably find the cryptographic modules
-written by A.M. Kuchling of further interest; the package contains
-modules for various encryption algorithms, most notably AES. These modules
-are not distributed with Python but available separately. See the URL
-\url{http://www.amk.ca/python/code/crypto.html}
-for more information.
-\indexii{AES}{algorithm}
-\index{cryptography}
-\index{Kuchling, Andrew}
diff --git a/Doc/lib/libcsv.tex b/Doc/lib/libcsv.tex
deleted file mode 100644
index 54fc8db..0000000
--- a/Doc/lib/libcsv.tex
+++ /dev/null
@@ -1,538 +0,0 @@
-\section{\module{csv} --- CSV File Reading and Writing}
-
-\declaremodule{standard}{csv}
-\modulesynopsis{Write and read tabular data to and from delimited files.}
-\sectionauthor{Skip Montanaro}{skip@pobox.com}
-
-\versionadded{2.3}
-\index{csv}
-\indexii{data}{tabular}
-
-The so-called CSV (Comma Separated Values) format is the most common import
-and export format for spreadsheets and databases. There is no ``CSV
-standard'', so the format is operationally defined by the many applications
-which read and write it. The lack of a standard means that subtle
-differences often exist in the data produced and consumed by different
-applications. These differences can make it annoying to process CSV files
-from multiple sources. Still, while the delimiters and quoting characters
-vary, the overall format is similar enough that it is possible to write a
-single module which can efficiently manipulate such data, hiding the details
-of reading and writing the data from the programmer.
-
-The \module{csv} module implements classes to read and write tabular data in
-CSV format. It allows programmers to say, ``write this data in the format
-preferred by Excel,'' or ``read data from this file which was generated by
-Excel,'' without knowing the precise details of the CSV format used by
-Excel. Programmers can also describe the CSV formats understood by other
-applications or define their own special-purpose CSV formats.
-
-The \module{csv} module's \class{reader} and \class{writer} objects read and
-write sequences. Programmers can also read and write data in dictionary
-form using the \class{DictReader} and \class{DictWriter} classes.
-
-\begin{notice}
- This version of the \module{csv} module doesn't support Unicode
- input. Also, there are currently some issues regarding \ASCII{} NUL
- characters. Accordingly, all input should be UTF-8 or printable
- \ASCII{} to be safe; see the examples in section~\ref{csv-examples}.
- These restrictions will be removed in the future.
-\end{notice}
-
-\begin{seealso}
-% \seemodule{array}{Arrays of uniformly types numeric values.}
- \seepep{305}{CSV File API}
- {The Python Enhancement Proposal which proposed this addition
- to Python.}
-\end{seealso}
-
-
-\subsection{Module Contents \label{csv-contents}}
-
-The \module{csv} module defines the following functions:
-
-\begin{funcdesc}{reader}{csvfile\optional{,
- dialect=\code{'excel'}}\optional{, fmtparam}}
-Return a reader object which will iterate over lines in the given
-{}\var{csvfile}. \var{csvfile} can be any object which supports the
-iterator protocol and returns a string each time its \method{next}
-method is called --- file objects and list objects are both suitable.
-If \var{csvfile} is a file object, it must be opened with
-the 'b' flag on platforms where that makes a difference. An optional
-{}\var{dialect} parameter can be given
-which is used to define a set of parameters specific to a particular CSV
-dialect. It may be an instance of a subclass of the \class{Dialect}
-class or one of the strings returned by the \function{list_dialects}
-function. The other optional {}\var{fmtparam} keyword arguments can be
-given to override individual formatting parameters in the current
-dialect. For full details about the dialect and formatting
-parameters, see section~\ref{csv-fmt-params}, ``Dialects and Formatting
-Parameters''.
-
-All data read are returned as strings. No automatic data type
-conversion is performed.
-
-\versionchanged[
-The parser is now stricter with respect to multi-line quoted
-fields. Previously, if a line ended within a quoted field without a
-terminating newline character, a newline would be inserted into the
-returned field. This behavior caused problems when reading files
-which contained carriage return characters within fields. The
-behavior was changed to return the field without inserting newlines. As
-a consequence, if newlines embedded within fields are important, the
-input should be split into lines in a manner which preserves the newline
-characters]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{writer}{csvfile\optional{,
- dialect=\code{'excel'}}\optional{, fmtparam}}
-Return a writer object responsible for converting the user's data into
-delimited strings on the given file-like object. \var{csvfile} can be any
-object with a \function{write} method. If \var{csvfile} is a file object,
-it must be opened with the 'b' flag on platforms where that makes a
-difference. An optional
-{}\var{dialect} parameter can be given which is used to define a set of
-parameters specific to a particular CSV dialect. It may be an instance
-of a subclass of the \class{Dialect} class or one of the strings
-returned by the \function{list_dialects} function. The other optional
-{}\var{fmtparam} keyword arguments can be given to override individual
-formatting parameters in the current dialect. For full details
-about the dialect and formatting parameters, see
-section~\ref{csv-fmt-params}, ``Dialects and Formatting Parameters''.
-To make it as easy as possible to
-interface with modules which implement the DB API, the value
-\constant{None} is written as the empty string. While this isn't a
-reversible transformation, it makes it easier to dump SQL NULL data values
-to CSV files without preprocessing the data returned from a
-\code{cursor.fetch*()} call. All other non-string data are stringified
-with \function{str()} before being written.
-\end{funcdesc}
-
-\begin{funcdesc}{register_dialect}{name\optional{, dialect}\optional{, fmtparam}}
-Associate \var{dialect} with \var{name}. \var{name} must be a string
-or Unicode object. The dialect can be specified either by passing a
-sub-class of \class{Dialect}, or by \var{fmtparam} keyword arguments,
-or both, with keyword arguments overriding parameters of the dialect.
-For full details about the dialect and formatting parameters, see
-section~\ref{csv-fmt-params}, ``Dialects and Formatting Parameters''.
-\end{funcdesc}
-
-\begin{funcdesc}{unregister_dialect}{name}
-Delete the dialect associated with \var{name} from the dialect registry. An
-\exception{Error} is raised if \var{name} is not a registered dialect
-name.
-\end{funcdesc}
-
-\begin{funcdesc}{get_dialect}{name}
-Return the dialect associated with \var{name}. An \exception{Error} is
-raised if \var{name} is not a registered dialect name.
-\end{funcdesc}
-
-\begin{funcdesc}{list_dialects}{}
-Return the names of all registered dialects.
-\end{funcdesc}
-
-\begin{funcdesc}{field_size_limit}{\optional{new_limit}}
- Returns the current maximum field size allowed by the parser. If
- \var{new_limit} is given, this becomes the new limit.
- \versionadded{2.5}
-\end{funcdesc}
-
-
-The \module{csv} module defines the following classes:
-
-\begin{classdesc}{DictReader}{csvfile\optional{,
- fieldnames=\constant{None},\optional{,
- restkey=\constant{None}\optional{,
- restval=\constant{None}\optional{,
- dialect=\code{'excel'}\optional{,
- *args, **kwds}}}}}}
-Create an object which operates like a regular reader but maps the
-information read into a dict whose keys are given by the optional
-{} \var{fieldnames}
-parameter. If the \var{fieldnames} parameter is omitted, the values in
-the first row of the \var{csvfile} will be used as the fieldnames.
-If the row read has fewer fields than the fieldnames sequence,
-the value of \var{restval} will be used as the default value. If the row
-read has more fields than the fieldnames sequence, the remaining data is
-added as a sequence keyed by the value of \var{restkey}. If the row read
-has fewer fields than the fieldnames sequence, the remaining keys take the
-value of the optional \var{restval} parameter. Any other optional or
-keyword arguments are passed to the underlying \class{reader} instance.
-\end{classdesc}
-
-
-\begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
- restval=""\optional{,
- extrasaction=\code{'raise'}\optional{,
- dialect=\code{'excel'}\optional{,
- *args, **kwds}}}}}
-Create an object which operates like a regular writer but maps dictionaries
-onto output rows. The \var{fieldnames} parameter identifies the order in
-which values in the dictionary passed to the \method{writerow()} method are
-written to the \var{csvfile}. The optional \var{restval} parameter
-specifies the value to be written if the dictionary is missing a key in
-\var{fieldnames}. If the dictionary passed to the \method{writerow()}
-method contains a key not found in \var{fieldnames}, the optional
-\var{extrasaction} parameter indicates what action to take. If it is set
-to \code{'raise'} a \exception{ValueError} is raised. If it is set to
-\code{'ignore'}, extra values in the dictionary are ignored. Any other
-optional or keyword arguments are passed to the underlying \class{writer}
-instance.
-
-Note that unlike the \class{DictReader} class, the \var{fieldnames}
-parameter of the \class{DictWriter} is not optional. Since Python's
-\class{dict} objects are not ordered, there is not enough information
-available to deduce the order in which the row should be written to the
-\var{csvfile}.
-
-\end{classdesc}
-
-\begin{classdesc*}{Dialect}{}
-The \class{Dialect} class is a container class relied on primarily for its
-attributes, which are used to define the parameters for a specific
-\class{reader} or \class{writer} instance.
-\end{classdesc*}
-
-\begin{classdesc}{excel}{}
-The \class{excel} class defines the usual properties of an Excel-generated
-CSV file. It is registered with the dialect name \code{'excel'}.
-\end{classdesc}
-
-\begin{classdesc}{excel_tab}{}
-The \class{excel_tab} class defines the usual properties of an
-Excel-generated TAB-delimited file. It is registered with the dialect name
-\code{'excel-tab'}.
-\end{classdesc}
-
-\begin{classdesc}{Sniffer}{}
-The \class{Sniffer} class is used to deduce the format of a CSV file.
-\end{classdesc}
-
-The \class{Sniffer} class provides two methods:
-
-\begin{methoddesc}{sniff}{sample\optional{,delimiters=None}}
-Analyze the given \var{sample} and return a \class{Dialect} subclass
-reflecting the parameters found. If the optional \var{delimiters} parameter
-is given, it is interpreted as a string containing possible valid delimiter
-characters.
-\end{methoddesc}
-
-\begin{methoddesc}{has_header}{sample}
-Analyze the sample text (presumed to be in CSV format) and return
-\constant{True} if the first row appears to be a series of column
-headers.
-\end{methoddesc}
-
-
-The \module{csv} module defines the following constants:
-
-\begin{datadesc}{QUOTE_ALL}
-Instructs \class{writer} objects to quote all fields.
-\end{datadesc}
-
-\begin{datadesc}{QUOTE_MINIMAL}
-Instructs \class{writer} objects to only quote those fields which contain
-special characters such as \var{delimiter}, \var{quotechar} or any of the
-characters in \var{lineterminator}.
-\end{datadesc}
-
-\begin{datadesc}{QUOTE_NONNUMERIC}
-Instructs \class{writer} objects to quote all non-numeric
-fields.
-
-Instructs the reader to convert all non-quoted fields to type \var{float}.
-\end{datadesc}
-
-\begin{datadesc}{QUOTE_NONE}
-Instructs \class{writer} objects to never quote fields. When the current
-\var{delimiter} occurs in output data it is preceded by the current
-\var{escapechar} character. If \var{escapechar} is not set, the writer
-will raise \exception{Error} if any characters that require escaping
-are encountered.
-
-Instructs \class{reader} to perform no special processing of quote characters.
-\end{datadesc}
-
-
-The \module{csv} module defines the following exception:
-
-\begin{excdesc}{Error}
-Raised by any of the functions when an error is detected.
-\end{excdesc}
-
-
-\subsection{Dialects and Formatting Parameters\label{csv-fmt-params}}
-
-To make it easier to specify the format of input and output records,
-specific formatting parameters are grouped together into dialects. A
-dialect is a subclass of the \class{Dialect} class having a set of specific
-methods and a single \method{validate()} method. When creating \class{reader}
-or \class{writer} objects, the programmer can specify a string or a subclass
-of the \class{Dialect} class as the dialect parameter. In addition to, or
-instead of, the \var{dialect} parameter, the programmer can also specify
-individual formatting parameters, which have the same names as the
-attributes defined below for the \class{Dialect} class.
-
-Dialects support the following attributes:
-
-\begin{memberdesc}[Dialect]{delimiter}
-A one-character string used to separate fields. It defaults to \code{','}.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{doublequote}
-Controls how instances of \var{quotechar} appearing inside a field should
-be themselves be quoted. When \constant{True}, the character is doubled.
-When \constant{False}, the \var{escapechar} is used as a prefix to the
-\var{quotechar}. It defaults to \constant{True}.
-
-On output, if \var{doublequote} is \constant{False} and no
-\var{escapechar} is set, \exception{Error} is raised if a \var{quotechar}
-is found in a field.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{escapechar}
-A one-character string used by the writer to escape the \var{delimiter} if
-\var{quoting} is set to \constant{QUOTE_NONE} and the \var{quotechar}
-if \var{doublequote} is \constant{False}. On reading, the \var{escapechar}
-removes any special meaning from the following character. It defaults
-to \constant{None}, which disables escaping.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{lineterminator}
-The string used to terminate lines produced by the \class{writer}.
-It defaults to \code{'\e r\e n'}.
-
-\note{The \class{reader} is hard-coded to recognise either \code{'\e r'}
-or \code{'\e n'} as end-of-line, and ignores \var{lineterminator}. This
-behavior may change in the future.}
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{quotechar}
-A one-character string used to quote fields containing special characters,
-such as the \var{delimiter} or \var{quotechar}, or which contain new-line
-characters. It defaults to \code{'"'}.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{quoting}
-Controls when quotes should be generated by the writer and recognised
-by the reader. It can take on any of the \constant{QUOTE_*} constants
-(see section~\ref{csv-contents}) and defaults to \constant{QUOTE_MINIMAL}.
-\end{memberdesc}
-
-\begin{memberdesc}[Dialect]{skipinitialspace}
-When \constant{True}, whitespace immediately following the \var{delimiter}
-is ignored. The default is \constant{False}.
-\end{memberdesc}
-
-
-\subsection{Reader Objects}
-
-Reader objects (\class{DictReader} instances and objects returned by
-the \function{reader()} function) have the following public methods:
-
-\begin{methoddesc}[csv reader]{next}{}
-Return the next row of the reader's iterable object as a list, parsed
-according to the current dialect.
-\end{methoddesc}
-
-Reader objects have the following public attributes:
-
-\begin{memberdesc}[csv reader]{dialect}
-A read-only description of the dialect in use by the parser.
-\end{memberdesc}
-
-\begin{memberdesc}[csv reader]{line_num}
- The number of lines read from the source iterator. This is not the same
- as the number of records returned, as records can span multiple lines.
- \versionadded{2.5}
-\end{memberdesc}
-
-
-\subsection{Writer Objects}
-
-\class{Writer} objects (\class{DictWriter} instances and objects returned by
-the \function{writer()} function) have the following public methods. A
-{}\var{row} must be a sequence of strings or numbers for \class{Writer}
-objects and a dictionary mapping fieldnames to strings or numbers (by
-passing them through \function{str()} first) for {}\class{DictWriter}
-objects. Note that complex numbers are written out surrounded by parens.
-This may cause some problems for other programs which read CSV files
-(assuming they support complex numbers at all).
-
-\begin{methoddesc}[csv writer]{writerow}{row}
-Write the \var{row} parameter to the writer's file object, formatted
-according to the current dialect.
-\end{methoddesc}
-
-\begin{methoddesc}[csv writer]{writerows}{rows}
-Write all the \var{rows} parameters (a list of \var{row} objects as
-described above) to the writer's file object, formatted
-according to the current dialect.
-\end{methoddesc}
-
-Writer objects have the following public attribute:
-
-\begin{memberdesc}[csv writer]{dialect}
-A read-only description of the dialect in use by the writer.
-\end{memberdesc}
-
-
-
-\subsection{Examples\label{csv-examples}}
-
-The simplest example of reading a CSV file:
-
-\begin{verbatim}
-import csv
-reader = csv.reader(open("some.csv", "rb"))
-for row in reader:
- print row
-\end{verbatim}
-
-Reading a file with an alternate format:
-
-\begin{verbatim}
-import csv
-reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
-for row in reader:
- print row
-\end{verbatim}
-
-The corresponding simplest possible writing example is:
-
-\begin{verbatim}
-import csv
-writer = csv.writer(open("some.csv", "wb"))
-writer.writerows(someiterable)
-\end{verbatim}
-
-Registering a new dialect:
-
-\begin{verbatim}
-import csv
-
-csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
-
-reader = csv.reader(open("passwd", "rb"), 'unixpwd')
-\end{verbatim}
-
-A slightly more advanced use of the reader --- catching and reporting errors:
-
-\begin{verbatim}
-import csv, sys
-filename = "some.csv"
-reader = csv.reader(open(filename, "rb"))
-try:
- for row in reader:
- print row
-except csv.Error as e:
- sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
-\end{verbatim}
-
-And while the module doesn't directly support parsing strings, it can
-easily be done:
-
-\begin{verbatim}
-import csv
-for row in csv.reader(['one,two,three']):
- print row
-\end{verbatim}
-
-The \module{csv} module doesn't directly support reading and writing
-Unicode, but it is 8-bit-clean save for some problems with \ASCII{} NUL
-characters. So you can write functions or classes that handle the
-encoding and decoding for you as long as you avoid encodings like
-UTF-16 that use NULs. UTF-8 is recommended.
-
-\function{unicode_csv_reader} below is a generator that wraps
-\class{csv.reader} to handle Unicode CSV data (a list of Unicode
-strings). \function{utf_8_encoder} is a generator that encodes the
-Unicode strings as UTF-8, one string (or row) at a time. The encoded
-strings are parsed by the CSV reader, and
-\function{unicode_csv_reader} decodes the UTF-8-encoded cells back
-into Unicode:
-
-\begin{verbatim}
-import csv
-
-def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
- # csv.py doesn't do Unicode; encode temporarily as UTF-8:
- csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
- dialect=dialect, **kwargs)
- for row in csv_reader:
- # decode UTF-8 back to Unicode, cell by cell:
- yield [unicode(cell, 'utf-8') for cell in row]
-
-def utf_8_encoder(unicode_csv_data):
- for line in unicode_csv_data:
- yield line.encode('utf-8')
-\end{verbatim}
-
-For all other encodings the following \class{UnicodeReader} and
-\class{UnicodeWriter} classes can be used. They take an additional
-\var{encoding} parameter in their constructor and make sure that the data
-passes the real reader or writer encoded as UTF-8:
-
-\begin{verbatim}
-import csv, codecs, cStringIO
-
-class UTF8Recoder:
- """
- Iterator that reads an encoded stream and reencodes the input to UTF-8
- """
- def __init__(self, f, encoding):
- self.reader = codecs.getreader(encoding)(f)
-
- def __iter__(self):
- return self
-
- def __next__(self):
- return next(self.reader).encode("utf-8")
-
-class UnicodeReader:
- """
- A CSV reader which will iterate over lines in the CSV file "f",
- which is encoded in the given encoding.
- """
-
- def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
- f = UTF8Recoder(f, encoding)
- self.reader = csv.reader(f, dialect=dialect, **kwds)
-
- def __next__(self):
- row = next(self.reader)
- return [unicode(s, "utf-8") for s in row]
-
- def __iter__(self):
- return self
-
-class UnicodeWriter:
- """
- A CSV writer which will write rows to CSV file "f",
- which is encoded in the given encoding.
- """
-
- def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
- # Redirect output to a queue
- self.queue = cStringIO.StringIO()
- self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
- self.stream = f
- self.encoder = codecs.getincrementalencoder(encoding)()
-
- def writerow(self, row):
- self.writer.writerow([s.encode("utf-8") for s in row])
- # Fetch UTF-8 output from the queue ...
- data = self.queue.getvalue()
- data = data.decode("utf-8")
- # ... and reencode it into the target encoding
- data = self.encoder.encode(data)
- # write to the target stream
- self.stream.write(data)
- # empty queue
- self.queue.truncate(0)
-
- def writerows(self, rows):
- for row in rows:
- self.writerow(row)
-\end{verbatim}
diff --git a/Doc/lib/libctypes.tex b/Doc/lib/libctypes.tex
deleted file mode 100755
index 346863d..0000000
--- a/Doc/lib/libctypes.tex
+++ /dev/null
@@ -1,2450 +0,0 @@
-\ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi
-\setlength{\locallinewidth}{\linewidth}
-\section{\module{ctypes} --- A foreign function library for Python.}
-\declaremodule{standard}{ctypes}
-\moduleauthor{Thomas Heller}{theller@python.net}
-\modulesynopsis{A foreign function library for Python.}
-\versionadded{2.5}
-
-\code{ctypes} is a foreign function library for Python. It provides C
-compatible data types, and allows calling functions in dlls/shared
-libraries. It can be used to wrap these libraries in pure Python.
-
-
-\subsection{ctypes tutorial\label{ctypes-ctypes-tutorial}}
-
-Note: The code samples in this tutorial use \code{doctest} to make sure
-that they actually work. Since some code samples behave differently
-under Linux, Windows, or Mac OS X, they contain doctest directives in
-comments.
-
-Note: Some code sample references the ctypes \class{c{\_}int} type.
-This type is an alias to the \class{c{\_}long} type on 32-bit systems. So,
-you should not be confused if \class{c{\_}long} is printed if you would
-expect \class{c{\_}int} --- they are actually the same type.
-
-
-\subsubsection{Loading dynamic link libraries\label{ctypes-loading-dynamic-link-libraries}}
-
-\code{ctypes} exports the \var{cdll}, and on Windows also \var{windll} and
-\var{oledll} objects to load dynamic link libraries.
-
-You load libraries by accessing them as attributes of these objects.
-\var{cdll} loads libraries which export functions using the standard
-\code{cdecl} calling convention, while \var{windll} libraries call
-functions using the \code{stdcall} calling convention. \var{oledll} also
-uses the \code{stdcall} calling convention, and assumes the functions
-return a Windows \class{HRESULT} error code. The error code is used to
-automatically raise \class{WindowsError} Python exceptions when the
-function call fails.
-
-Here are some examples for Windows. Note that \code{msvcrt} is the MS
-standard C library containing most standard C functions, and uses the
-cdecl calling convention:
-\begin{verbatim}
->>> from ctypes import *
->>> print windll.kernel32 # doctest: +WINDOWS
-<WinDLL 'kernel32', handle ... at ...>
->>> print cdll.msvcrt # doctest: +WINDOWS
-<CDLL 'msvcrt', handle ... at ...>
->>> libc = cdll.msvcrt # doctest: +WINDOWS
->>>
-\end{verbatim}
-
-Windows appends the usual '.dll' file suffix automatically.
-
-On Linux, it is required to specify the filename \emph{including} the
-extension to load a library, so attribute access does not work.
-Either the \method{LoadLibrary} method of the dll loaders should be used,
-or you should load the library by creating an instance of CDLL by
-calling the constructor:
-\begin{verbatim}
->>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX
-<CDLL 'libc.so.6', handle ... at ...>
->>> libc = CDLL("libc.so.6") # doctest: +LINUX
->>> libc # doctest: +LINUX
-<CDLL 'libc.so.6', handle ... at ...>
->>>
-\end{verbatim}
-% XXX Add section for Mac OS X.
-
-
-\subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}}
-
-Functions are accessed as attributes of dll objects:
-\begin{verbatim}
->>> from ctypes import *
->>> libc.printf
-<_FuncPtr object at 0x...>
->>> print windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
-<_FuncPtr object at 0x...>
->>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "ctypes.py", line 239, in __getattr__
- func = _StdcallFuncPtr(name, self)
-AttributeError: function 'MyOwnFunction' not found
->>>
-\end{verbatim}
-
-Note that win32 system dlls like \code{kernel32} and \code{user32} often
-export ANSI as well as UNICODE versions of a function. The UNICODE
-version is exported with an \code{W} appended to the name, while the ANSI
-version is exported with an \code{A} appended to the name. The win32
-\code{GetModuleHandle} function, which returns a \emph{module handle} for a
-given module name, has the following C prototype, and a macro is used
-to expose one of them as \code{GetModuleHandle} depending on whether
-UNICODE is defined or not:
-\begin{verbatim}
-/* ANSI version */
-HMODULE GetModuleHandleA(LPCSTR lpModuleName);
-/* UNICODE version */
-HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
-\end{verbatim}
-
-\var{windll} does not try to select one of them by magic, you must
-access the version you need by specifying \code{GetModuleHandleA} or
-\code{GetModuleHandleW} explicitely, and then call it with normal strings
-or unicode strings respectively.
-
-Sometimes, dlls export functions with names which aren't valid Python
-identifiers, like \code{"??2@YAPAXI@Z"}. In this case you have to use
-\code{getattr} to retrieve the function:
-\begin{verbatim}
->>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
-<_FuncPtr object at 0x...>
->>>
-\end{verbatim}
-
-On Windows, some dlls export functions not by name but by ordinal.
-These functions can be accessed by indexing the dll object with the
-ordinal number:
-\begin{verbatim}
->>> cdll.kernel32[1] # doctest: +WINDOWS
-<_FuncPtr object at 0x...>
->>> cdll.kernel32[0] # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "ctypes.py", line 310, in __getitem__
- func = _StdcallFuncPtr(name, self)
-AttributeError: function ordinal 0 not found
->>>
-\end{verbatim}
-
-
-\subsubsection{Calling functions\label{ctypes-calling-functions}}
-
-You can call these functions like any other Python callable. This
-example uses the \code{time()} function, which returns system time in
-seconds since the \UNIX{} epoch, and the \code{GetModuleHandleA()} function,
-which returns a win32 module handle.
-
-This example calls both functions with a NULL pointer (\code{None} should
-be used as the NULL pointer):
-\begin{verbatim}
->>> print libc.time(None) # doctest: +SKIP
-1150640792
->>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
-0x1d000000
->>>
-\end{verbatim}
-
-\code{ctypes} tries to protect you from calling functions with the wrong
-number of arguments or the wrong calling convention. Unfortunately
-this only works on Windows. It does this by examining the stack after
-the function returns, so although an error is raised the function
-\emph{has} been called:
-\begin{verbatim}
->>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: Procedure probably called with not enough arguments (4 bytes missing)
->>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: Procedure probably called with too many arguments (4 bytes in excess)
->>>
-\end{verbatim}
-
-The same exception is raised when you call an \code{stdcall} function
-with the \code{cdecl} calling convention, or vice versa:
-\begin{verbatim}
->>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: Procedure probably called with not enough arguments (4 bytes missing)
->>>
-
->>> windll.msvcrt.printf("spam") # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: Procedure probably called with too many arguments (4 bytes in excess)
->>>
-\end{verbatim}
-
-To find out the correct calling convention you have to look into the C
-header file or the documentation for the function you want to call.
-
-On Windows, \code{ctypes} uses win32 structured exception handling to
-prevent crashes from general protection faults when functions are
-called with invalid argument values:
-\begin{verbatim}
->>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-WindowsError: exception: access violation reading 0x00000020
->>>
-\end{verbatim}
-
-There are, however, enough ways to crash Python with \code{ctypes}, so
-you should be careful anyway.
-
-\code{None}, integers, longs, byte strings and unicode strings are the
-only native Python objects that can directly be used as parameters in
-these function calls. \code{None} is passed as a C \code{NULL} pointer,
-byte strings and unicode strings are passed as pointer to the memory
-block that contains their data (\code{char *} or \code{wchar{\_}t *}). Python
-integers and Python longs are passed as the platforms default C
-\code{int} type, their value is masked to fit into the C type.
-
-Before we move on calling functions with other parameter types, we
-have to learn more about \code{ctypes} data types.
-
-
-\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}}
-
-\code{ctypes} defines a number of primitive C compatible data types :
-\begin{quote}
-\begin{tableiii}{l|l|l}{textrm}
-{
-ctypes type
-}
-{
-C type
-}
-{
-Python type
-}
-\lineiii{
-\class{c{\_}char}
-}
-{
-\code{char}
-}
-{
-1-character
-string
-}
-\lineiii{
-\class{c{\_}wchar}
-}
-{
-\code{wchar{\_}t}
-}
-{
-1-character
-unicode string
-}
-\lineiii{
-\class{c{\_}byte}
-}
-{
-\code{char}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ubyte}
-}
-{
-\code{unsigned char}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}short}
-}
-{
-\code{short}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ushort}
-}
-{
-\code{unsigned short}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}int}
-}
-{
-\code{int}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}uint}
-}
-{
-\code{unsigned int}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}long}
-}
-{
-\code{long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ulong}
-}
-{
-\code{unsigned long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}longlong}
-}
-{
-\code{{\_}{\_}int64} or
-\code{long long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}ulonglong}
-}
-{
-\code{unsigned {\_}{\_}int64} or
-\code{unsigned long long}
-}
-{
-int/long
-}
-\lineiii{
-\class{c{\_}float}
-}
-{
-\code{float}
-}
-{
-float
-}
-\lineiii{
-\class{c{\_}double}
-}
-{
-\code{double}
-}
-{
-float
-}
-\lineiii{
-\class{c{\_}char{\_}p}
-}
-{
-\code{char *}
-(NUL terminated)
-}
-{
-string or
-\code{None}
-}
-\lineiii{
-\class{c{\_}wchar{\_}p}
-}
-{
-\code{wchar{\_}t *}
-(NUL terminated)
-}
-{
-unicode or
-\code{None}
-}
-\lineiii{
-\class{c{\_}void{\_}p}
-}
-{
-\code{void *}
-}
-{
-int/long
-or \code{None}
-}
-\end{tableiii}
-\end{quote}
-
-All these types can be created by calling them with an optional
-initializer of the correct type and value:
-\begin{verbatim}
->>> c_int()
-c_long(0)
->>> c_char_p("Hello, World")
-c_char_p('Hello, World')
->>> c_ushort(-3)
-c_ushort(65533)
->>>
-\end{verbatim}
-
-Since these types are mutable, their value can also be changed
-afterwards:
-\begin{verbatim}
->>> i = c_int(42)
->>> print i
-c_long(42)
->>> print i.value
-42
->>> i.value = -99
->>> print i.value
--99
->>>
-\end{verbatim}
-
-Assigning a new value to instances of the pointer types \class{c{\_}char{\_}p},
-\class{c{\_}wchar{\_}p}, and \class{c{\_}void{\_}p} changes the \emph{memory location} they
-point to, \emph{not the contents} of the memory block (of course not,
-because Python strings are immutable):
-\begin{verbatim}
->>> s = "Hello, World"
->>> c_s = c_char_p(s)
->>> print c_s
-c_char_p('Hello, World')
->>> c_s.value = "Hi, there"
->>> print c_s
-c_char_p('Hi, there')
->>> print s # first string is unchanged
-Hello, World
->>>
-\end{verbatim}
-
-You should be careful, however, not to pass them to functions
-expecting pointers to mutable memory. If you need mutable memory
-blocks, ctypes has a \code{create{\_}string{\_}buffer} function which creates
-these in various ways. The current memory block contents can be
-accessed (or changed) with the \code{raw} property; if you want to access
-it as NUL terminated string, use the \code{value} property:
-\begin{verbatim}
->>> from ctypes import *
->>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes
->>> print sizeof(p), repr(p.raw)
-3 '\x00\x00\x00'
->>> p = create_string_buffer("Hello") # create a buffer containing a NUL terminated string
->>> print sizeof(p), repr(p.raw)
-6 'Hello\x00'
->>> print repr(p.value)
-'Hello'
->>> p = create_string_buffer("Hello", 10) # create a 10 byte buffer
->>> print sizeof(p), repr(p.raw)
-10 'Hello\x00\x00\x00\x00\x00'
->>> p.value = "Hi"
->>> print sizeof(p), repr(p.raw)
-10 'Hi\x00lo\x00\x00\x00\x00\x00'
->>>
-\end{verbatim}
-
-The \code{create{\_}string{\_}buffer} function replaces the \code{c{\_}buffer}
-function (which is still available as an alias), as well as the
-\code{c{\_}string} function from earlier ctypes releases. To create a
-mutable memory block containing unicode characters of the C type
-\code{wchar{\_}t} use the \code{create{\_}unicode{\_}buffer} function.
-
-
-\subsubsection{Calling functions, continued\label{ctypes-calling-functions-continued}}
-
-Note that printf prints to the real standard output channel, \emph{not} to
-\code{sys.stdout}, so these examples will only work at the console
-prompt, not from within \emph{IDLE} or \emph{PythonWin}:
-\begin{verbatim}
->>> printf = libc.printf
->>> printf("Hello, %s\n", "World!")
-Hello, World!
-14
->>> printf("Hello, %S", u"World!")
-Hello, World!
-13
->>> printf("%d bottles of beer\n", 42)
-42 bottles of beer
-19
->>> printf("%f bottles of beer\n", 42.5)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2
->>>
-\end{verbatim}
-
-As has been mentioned before, all Python types except integers,
-strings, and unicode strings have to be wrapped in their corresponding
-\code{ctypes} type, so that they can be converted to the required C data
-type:
-\begin{verbatim}
->>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
-Integer 1234, double 3.1400001049
-31
->>>
-\end{verbatim}
-
-
-\subsubsection{Calling functions with your own custom data types\label{ctypes-calling-functions-with-own-custom-data-types}}
-
-You can also customize \code{ctypes} argument conversion to allow
-instances of your own classes be used as function arguments.
-\code{ctypes} looks for an \member{{\_}as{\_}parameter{\_}} attribute and uses this as
-the function argument. Of course, it must be one of integer, string,
-or unicode:
-\begin{verbatim}
->>> class Bottles(object):
-... def __init__(self, number):
-... self._as_parameter_ = number
-...
->>> bottles = Bottles(42)
->>> printf("%d bottles of beer\n", bottles)
-42 bottles of beer
-19
->>>
-\end{verbatim}
-
-If you don't want to store the instance's data in the
-\member{{\_}as{\_}parameter{\_}} instance variable, you could define a \code{property}
-which makes the data avaiblable.
-
-
-\subsubsection{Specifying the required argument types (function prototypes)\label{ctypes-specifying-required-argument-types}}
-
-It is possible to specify the required argument types of functions
-exported from DLLs by setting the \member{argtypes} attribute.
-
-\member{argtypes} must be a sequence of C data types (the \code{printf}
-function is probably not a good example here, because it takes a
-variable number and different types of parameters depending on the
-format string, on the other hand this is quite handy to experiment
-with this feature):
-\begin{verbatim}
->>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
->>> printf("String '%s', Int %d, Double %f\n", "Hi", 10, 2.2)
-String 'Hi', Int 10, Double 2.200000
-37
->>>
-\end{verbatim}
-
-Specifying a format protects against incompatible argument types (just
-as a prototype for a C function), and tries to convert the arguments
-to valid types:
-\begin{verbatim}
->>> printf("%d %d %d", 1, 2, 3)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ArgumentError: argument 2: exceptions.TypeError: wrong type
->>> printf("%s %d %f", "X", 2, 3)
-X 2 3.00000012
-12
->>>
-\end{verbatim}
-
-If you have defined your own classes which you pass to function calls,
-you have to implement a \method{from{\_}param} class method for them to be
-able to use them in the \member{argtypes} sequence. The \method{from{\_}param}
-class method receives the Python object passed to the function call,
-it should do a typecheck or whatever is needed to make sure this
-object is acceptable, and then return the object itself, it's
-\member{{\_}as{\_}parameter{\_}} attribute, or whatever you want to pass as the C
-function argument in this case. Again, the result should be an
-integer, string, unicode, a \code{ctypes} instance, or something having
-the \member{{\_}as{\_}parameter{\_}} attribute.
-
-
-\subsubsection{Return types\label{ctypes-return-types}}
-
-By default functions are assumed to return the C \code{int} type. Other
-return types can be specified by setting the \member{restype} attribute of
-the function object.
-
-Here is a more advanced example, it uses the \code{strchr} function, which
-expects a string pointer and a char, and returns a pointer to a
-string:
-\begin{verbatim}
->>> strchr = libc.strchr
->>> strchr("abcdef", ord("d")) # doctest: +SKIP
-8059983
->>> strchr.restype = c_char_p # c_char_p is a pointer to a string
->>> strchr("abcdef", ord("d"))
-'def'
->>> print strchr("abcdef", ord("x"))
-None
->>>
-\end{verbatim}
-
-If you want to avoid the \code{ord("x")} calls above, you can set the
-\member{argtypes} attribute, and the second argument will be converted from
-a single character Python string into a C char:
-\begin{verbatim}
->>> strchr.restype = c_char_p
->>> strchr.argtypes = [c_char_p, c_char]
->>> strchr("abcdef", "d")
-'def'
->>> strchr("abcdef", "def")
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ArgumentError: argument 2: exceptions.TypeError: one character string expected
->>> print strchr("abcdef", "x")
-None
->>> strchr("abcdef", "d")
-'def'
->>>
-\end{verbatim}
-
-You can also use a callable Python object (a function or a class for
-example) as the \member{restype} attribute, if the foreign function returns
-an integer. The callable will be called with the \code{integer} the C
-function returns, and the result of this call will be used as the
-result of your function call. This is useful to check for error return
-values and automatically raise an exception:
-\begin{verbatim}
->>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
->>> def ValidHandle(value):
-... if value == 0:
-... raise WinError()
-... return value
-...
->>>
->>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS
->>> GetModuleHandle(None) # doctest: +WINDOWS
-486539264
->>> GetModuleHandle("something silly") # doctest: +WINDOWS
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "<stdin>", line 3, in ValidHandle
-WindowsError: [Errno 126] The specified module could not be found.
->>>
-\end{verbatim}
-
-\code{WinError} is a function which will call Windows \code{FormatMessage()}
-api to get the string representation of an error code, and \emph{returns}
-an exception. \code{WinError} takes an optional error code parameter, if
-no one is used, it calls \function{GetLastError()} to retrieve it.
-
-Please note that a much more powerful error checking mechanism is
-available through the \member{errcheck} attribute; see the reference manual
-for details.
-
-
-\subsubsection{Passing pointers (or: passing parameters by reference)\label{ctypes-passing-pointers}}
-
-Sometimes a C api function expects a \emph{pointer} to a data type as
-parameter, probably to write into the corresponding location, or if
-the data is too large to be passed by value. This is also known as
-\emph{passing parameters by reference}.
-
-\code{ctypes} exports the \function{byref} function which is used to pass
-parameters by reference. The same effect can be achieved with the
-\code{pointer} function, although \code{pointer} does a lot more work since
-it constructs a real pointer object, so it is faster to use \function{byref}
-if you don't need the pointer object in Python itself:
-\begin{verbatim}
->>> i = c_int()
->>> f = c_float()
->>> s = create_string_buffer('\000' * 32)
->>> print i.value, f.value, repr(s.value)
-0 0.0 ''
->>> libc.sscanf("1 3.14 Hello", "%d %f %s",
-... byref(i), byref(f), s)
-3
->>> print i.value, f.value, repr(s.value)
-1 3.1400001049 'Hello'
->>>
-\end{verbatim}
-
-
-\subsubsection{Structures and unions\label{ctypes-structures-unions}}
-
-Structures and unions must derive from the \class{Structure} and \class{Union}
-base classes which are defined in the \code{ctypes} module. Each subclass
-must define a \member{{\_}fields{\_}} attribute. \member{{\_}fields{\_}} must be a list of
-\emph{2-tuples}, containing a \emph{field name} and a \emph{field type}.
-
-The field type must be a \code{ctypes} type like \class{c{\_}int}, or any other
-derived \code{ctypes} type: structure, union, array, pointer.
-
-Here is a simple example of a POINT structure, which contains two
-integers named \code{x} and \code{y}, and also shows how to initialize a
-structure in the constructor:
-\begin{verbatim}
->>> from ctypes import *
->>> class POINT(Structure):
-... _fields_ = [("x", c_int),
-... ("y", c_int)]
-...
->>> point = POINT(10, 20)
->>> print point.x, point.y
-10 20
->>> point = POINT(y=5)
->>> print point.x, point.y
-0 5
->>> POINT(1, 2, 3)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: too many initializers
->>>
-\end{verbatim}
-
-You can, however, build much more complicated structures. Structures
-can itself contain other structures by using a structure as a field
-type.
-
-Here is a RECT structure which contains two POINTs named \code{upperleft}
-and \code{lowerright}
-\begin{verbatim}
->>> class RECT(Structure):
-... _fields_ = [("upperleft", POINT),
-... ("lowerright", POINT)]
-...
->>> rc = RECT(point)
->>> print rc.upperleft.x, rc.upperleft.y
-0 5
->>> print rc.lowerright.x, rc.lowerright.y
-0 0
->>>
-\end{verbatim}
-
-Nested structures can also be initialized in the constructor in
-several ways:
-\begin{verbatim}
->>> r = RECT(POINT(1, 2), POINT(3, 4))
->>> r = RECT((1, 2), (3, 4))
-\end{verbatim}
-
-Fields descriptors can be retrieved from the \emph{class}, they are useful
-for debugging because they can provide useful information:
-\begin{verbatim}
->>> print POINT.x
-<Field type=c_long, ofs=0, size=4>
->>> print POINT.y
-<Field type=c_long, ofs=4, size=4>
->>>
-\end{verbatim}
-
-
-\subsubsection{Structure/union alignment and byte order\label{ctypes-structureunion-alignment-byte-order}}
-
-By default, Structure and Union fields are aligned in the same way the
-C compiler does it. It is possible to override this behaviour be
-specifying a \member{{\_}pack{\_}} class attribute in the subclass
-definition. This must be set to a positive integer and specifies the
-maximum alignment for the fields. This is what \code{{\#}pragma pack(n)}
-also does in MSVC.
-
-\code{ctypes} uses the native byte order for Structures and Unions. To
-build structures with non-native byte order, you can use one of the
-BigEndianStructure, LittleEndianStructure, BigEndianUnion, and
-LittleEndianUnion base classes. These classes cannot contain pointer
-fields.
-
-
-\subsubsection{Bit fields in structures and unions\label{ctypes-bit-fields-in-structures-unions}}
-
-It is possible to create structures and unions containing bit fields.
-Bit fields are only possible for integer fields, the bit width is
-specified as the third item in the \member{{\_}fields{\_}} tuples:
-\begin{verbatim}
->>> class Int(Structure):
-... _fields_ = [("first_16", c_int, 16),
-... ("second_16", c_int, 16)]
-...
->>> print Int.first_16
-<Field type=c_long, ofs=0:0, bits=16>
->>> print Int.second_16
-<Field type=c_long, ofs=0:16, bits=16>
->>>
-\end{verbatim}
-
-
-\subsubsection{Arrays\label{ctypes-arrays}}
-
-Arrays are sequences, containing a fixed number of instances of the
-same type.
-
-The recommended way to create array types is by multiplying a data
-type with a positive integer:
-\begin{verbatim}
-TenPointsArrayType = POINT * 10
-\end{verbatim}
-
-Here is an example of an somewhat artifical data type, a structure
-containing 4 POINTs among other stuff:
-\begin{verbatim}
->>> from ctypes import *
->>> class POINT(Structure):
-... _fields_ = ("x", c_int), ("y", c_int)
-...
->>> class MyStruct(Structure):
-... _fields_ = [("a", c_int),
-... ("b", c_float),
-... ("point_array", POINT * 4)]
->>>
->>> print len(MyStruct().point_array)
-4
->>>
-\end{verbatim}
-
-Instances are created in the usual way, by calling the class:
-\begin{verbatim}
-arr = TenPointsArrayType()
-for pt in arr:
- print pt.x, pt.y
-\end{verbatim}
-
-The above code print a series of \code{0 0} lines, because the array
-contents is initialized to zeros.
-
-Initializers of the correct type can also be specified:
-\begin{verbatim}
->>> from ctypes import *
->>> TenIntegers = c_int * 10
->>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
->>> print ii
-<c_long_Array_10 object at 0x...>
->>> for i in ii: print i,
-...
-1 2 3 4 5 6 7 8 9 10
->>>
-\end{verbatim}
-
-
-\subsubsection{Pointers\label{ctypes-pointers}}
-
-Pointer instances are created by calling the \code{pointer} function on a
-\code{ctypes} type:
-\begin{verbatim}
->>> from ctypes import *
->>> i = c_int(42)
->>> pi = pointer(i)
->>>
-\end{verbatim}
-
-Pointer instances have a \code{contents} attribute which returns the
-object to which the pointer points, the \code{i} object above:
-\begin{verbatim}
->>> pi.contents
-c_long(42)
->>>
-\end{verbatim}
-
-Note that \code{ctypes} does not have OOR (original object return), it
-constructs a new, equivalent object each time you retrieve an
-attribute:
-\begin{verbatim}
->>> pi.contents is i
-False
->>> pi.contents is pi.contents
-False
->>>
-\end{verbatim}
-
-Assigning another \class{c{\_}int} instance to the pointer's contents
-attribute would cause the pointer to point to the memory location
-where this is stored:
-\begin{verbatim}
->>> i = c_int(99)
->>> pi.contents = i
->>> pi.contents
-c_long(99)
->>>
-\end{verbatim}
-
-Pointer instances can also be indexed with integers:
-\begin{verbatim}
->>> pi[0]
-99
->>>
-\end{verbatim}
-
-Assigning to an integer index changes the pointed to value:
-\begin{verbatim}
->>> print i
-c_long(99)
->>> pi[0] = 22
->>> print i
-c_long(22)
->>>
-\end{verbatim}
-
-It is also possible to use indexes different from 0, but you must know
-what you're doing, just as in C: You can access or change arbitrary
-memory locations. Generally you only use this feature if you receive a
-pointer from a C function, and you \emph{know} that the pointer actually
-points to an array instead of a single item.
-
-Behind the scenes, the \code{pointer} function does more than simply
-create pointer instances, it has to create pointer \emph{types} first.
-This is done with the \code{POINTER} function, which accepts any
-\code{ctypes} type, and returns a new type:
-\begin{verbatim}
->>> PI = POINTER(c_int)
->>> PI
-<class 'ctypes.LP_c_long'>
->>> PI(42)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: expected c_long instead of int
->>> PI(c_int(42))
-<ctypes.LP_c_long object at 0x...>
->>>
-\end{verbatim}
-
-Calling the pointer type without an argument creates a \code{NULL}
-pointer. \code{NULL} pointers have a \code{False} boolean value:
-\begin{verbatim}
->>> null_ptr = POINTER(c_int)()
->>> print bool(null_ptr)
-False
->>>
-\end{verbatim}
-
-\code{ctypes} checks for \code{NULL} when dereferencing pointers (but
-dereferencing non-\code{NULL} pointers would crash Python):
-\begin{verbatim}
->>> null_ptr[0]
-Traceback (most recent call last):
- ....
-ValueError: NULL pointer access
->>>
-
->>> null_ptr[0] = 1234
-Traceback (most recent call last):
- ....
-ValueError: NULL pointer access
->>>
-\end{verbatim}
-
-
-\subsubsection{Type conversions\label{ctypes-type-conversions}}
-
-Usually, ctypes does strict type checking. This means, if you have
-\code{POINTER(c{\_}int)} in the \member{argtypes} list of a function or as the
-type of a member field in a structure definition, only instances of
-exactly the same type are accepted. There are some exceptions to this
-rule, where ctypes accepts other objects. For example, you can pass
-compatible array instances instead of pointer types. So, for
-\code{POINTER(c{\_}int)}, ctypes accepts an array of c{\_}int:
-\begin{verbatim}
->>> class Bar(Structure):
-... _fields_ = [("count", c_int), ("values", POINTER(c_int))]
-...
->>> bar = Bar()
->>> bar.values = (c_int * 3)(1, 2, 3)
->>> bar.count = 3
->>> for i in range(bar.count):
-... print bar.values[i]
-...
-1
-2
-3
->>>
-\end{verbatim}
-
-To set a POINTER type field to \code{NULL}, you can assign \code{None}:
-\begin{verbatim}
->>> bar.values = None
->>>
-\end{verbatim}
-
-XXX list other conversions...
-
-Sometimes you have instances of incompatible types. In \code{C}, you can
-cast one type into another type. \code{ctypes} provides a \code{cast}
-function which can be used in the same way. The \code{Bar} structure
-defined above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays
-for its \code{values} field, but not instances of other types:
-\begin{verbatim}
->>> bar.values = (c_byte * 4)()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
->>>
-\end{verbatim}
-
-For these cases, the \code{cast} function is handy.
-
-The \code{cast} function can be used to cast a ctypes instance into a
-pointer to a different ctypes data type. \code{cast} takes two
-parameters, a ctypes object that is or can be converted to a pointer
-of some kind, and a ctypes pointer type. It returns an instance of
-the second argument, which references the same memory block as the
-first argument:
-\begin{verbatim}
->>> a = (c_byte * 4)()
->>> cast(a, POINTER(c_int))
-<ctypes.LP_c_long object at ...>
->>>
-\end{verbatim}
-
-So, \code{cast} can be used to assign to the \code{values} field of \code{Bar}
-the structure:
-\begin{verbatim}
->>> bar = Bar()
->>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
->>> print bar.values[0]
-0
->>>
-\end{verbatim}
-
-
-\subsubsection{Incomplete Types\label{ctypes-incomplete-types}}
-
-\emph{Incomplete Types} are structures, unions or arrays whose members are
-not yet specified. In C, they are specified by forward declarations, which
-are defined later:
-\begin{verbatim}
-struct cell; /* forward declaration */
-
-struct {
- char *name;
- struct cell *next;
-} cell;
-\end{verbatim}
-
-The straightforward translation into ctypes code would be this, but it
-does not work:
-\begin{verbatim}
->>> class cell(Structure):
-... _fields_ = [("name", c_char_p),
-... ("next", POINTER(cell))]
-...
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "<stdin>", line 2, in cell
-NameError: name 'cell' is not defined
->>>
-\end{verbatim}
-
-because the new \code{class cell} is not available in the class statement
-itself. In \code{ctypes}, we can define the \code{cell} class and set the
-\member{{\_}fields{\_}} attribute later, after the class statement:
-\begin{verbatim}
->>> from ctypes import *
->>> class cell(Structure):
-... pass
-...
->>> cell._fields_ = [("name", c_char_p),
-... ("next", POINTER(cell))]
->>>
-\end{verbatim}
-
-Lets try it. We create two instances of \code{cell}, and let them point
-to each other, and finally follow the pointer chain a few times:
-\begin{verbatim}
->>> c1 = cell()
->>> c1.name = "foo"
->>> c2 = cell()
->>> c2.name = "bar"
->>> c1.next = pointer(c2)
->>> c2.next = pointer(c1)
->>> p = c1
->>> for i in range(8):
-... print p.name,
-... p = p.next[0]
-...
-foo bar foo bar foo bar foo bar
->>>
-\end{verbatim}
-
-
-\subsubsection{Callback functions\label{ctypes-callback-functions}}
-
-\code{ctypes} allows to create C callable function pointers from Python
-callables. These are sometimes called \emph{callback functions}.
-
-First, you must create a class for the callback function, the class
-knows the calling convention, the return type, and the number and
-types of arguments this function will receive.
-
-The CFUNCTYPE factory function creates types for callback functions
-using the normal cdecl calling convention, and, on Windows, the
-WINFUNCTYPE factory function creates types for callback functions
-using the stdcall calling convention.
-
-Both of these factory functions are called with the result type as
-first argument, and the callback functions expected argument types as
-the remaining arguments.
-
-I will present an example here which uses the standard C library's
-\function{qsort} function, this is used to sort items with the help of a
-callback function. \function{qsort} will be used to sort an array of
-integers:
-\begin{verbatim}
->>> IntArray5 = c_int * 5
->>> ia = IntArray5(5, 1, 7, 33, 99)
->>> qsort = libc.qsort
->>> qsort.restype = None
->>>
-\end{verbatim}
-
-\function{qsort} must be called with a pointer to the data to sort, the
-number of items in the data array, the size of one item, and a pointer
-to the comparison function, the callback. The callback will then be
-called with two pointers to items, and it must return a negative
-integer if the first item is smaller than the second, a zero if they
-are equal, and a positive integer else.
-
-So our callback function receives pointers to integers, and must
-return an integer. First we create the \code{type} for the callback
-function:
-\begin{verbatim}
->>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
->>>
-\end{verbatim}
-
-For the first implementation of the callback function, we simply print
-the arguments we get, and return 0 (incremental development ;-):
-\begin{verbatim}
->>> def py_cmp_func(a, b):
-... print "py_cmp_func", a, b
-... return 0
-...
->>>
-\end{verbatim}
-
-Create the C callable callback:
-\begin{verbatim}
->>> cmp_func = CMPFUNC(py_cmp_func)
->>>
-\end{verbatim}
-
-And we're ready to go:
-\begin{verbatim}
->>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
-py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
->>>
-\end{verbatim}
-
-We know how to access the contents of a pointer, so lets redefine our callback:
-\begin{verbatim}
->>> def py_cmp_func(a, b):
-... print "py_cmp_func", a[0], b[0]
-... return 0
-...
->>> cmp_func = CMPFUNC(py_cmp_func)
->>>
-\end{verbatim}
-
-Here is what we get on Windows:
-\begin{verbatim}
->>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
-py_cmp_func 7 1
-py_cmp_func 33 1
-py_cmp_func 99 1
-py_cmp_func 5 1
-py_cmp_func 7 5
-py_cmp_func 33 5
-py_cmp_func 99 5
-py_cmp_func 7 99
-py_cmp_func 33 99
-py_cmp_func 7 33
->>>
-\end{verbatim}
-
-It is funny to see that on linux the sort function seems to work much
-more efficient, it is doing less comparisons:
-\begin{verbatim}
->>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX
-py_cmp_func 5 1
-py_cmp_func 33 99
-py_cmp_func 7 33
-py_cmp_func 5 7
-py_cmp_func 1 7
->>>
-\end{verbatim}
-
-Ah, we're nearly done! The last step is to actually compare the two
-items and return a useful result:
-\begin{verbatim}
->>> def py_cmp_func(a, b):
-... print "py_cmp_func", a[0], b[0]
-... return a[0] - b[0]
-...
->>>
-\end{verbatim}
-
-Final run on Windows:
-\begin{verbatim}
->>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +WINDOWS
-py_cmp_func 33 7
-py_cmp_func 99 33
-py_cmp_func 5 99
-py_cmp_func 1 99
-py_cmp_func 33 7
-py_cmp_func 1 33
-py_cmp_func 5 33
-py_cmp_func 5 7
-py_cmp_func 1 7
-py_cmp_func 5 1
->>>
-\end{verbatim}
-
-and on Linux:
-\begin{verbatim}
->>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +LINUX
-py_cmp_func 5 1
-py_cmp_func 33 99
-py_cmp_func 7 33
-py_cmp_func 1 7
-py_cmp_func 5 7
->>>
-\end{verbatim}
-
-It is quite interesting to see that the Windows \function{qsort} function
-needs more comparisons than the linux version!
-
-As we can easily check, our array is sorted now:
-\begin{verbatim}
->>> for i in ia: print i,
-...
-1 5 7 33 99
->>>
-\end{verbatim}
-
-\textbf{Important note for callback functions:}
-
-Make sure you keep references to CFUNCTYPE objects as long as they are
-used from C code. \code{ctypes} doesn't, and if you don't, they may be
-garbage collected, crashing your program when a callback is made.
-
-
-\subsubsection{Accessing values exported from dlls\label{ctypes-accessing-values-exported-from-dlls}}
-
-Sometimes, a dll not only exports functions, it also exports
-variables. An example in the Python library itself is the
-\code{Py{\_}OptimizeFlag}, an integer set to 0, 1, or 2, depending on the
-\programopt{-O} or \programopt{-OO} flag given on startup.
-
-\code{ctypes} can access values like this with the \method{in{\_}dll} class
-methods of the type. \var{pythonapi} is a predefined symbol giving
-access to the Python C api:
-\begin{verbatim}
->>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
->>> print opt_flag
-c_long(0)
->>>
-\end{verbatim}
-
-If the interpreter would have been started with \programopt{-O}, the sample
-would have printed \code{c{\_}long(1)}, or \code{c{\_}long(2)} if \programopt{-OO} would have
-been specified.
-
-An extended example which also demonstrates the use of pointers
-accesses the \code{PyImport{\_}FrozenModules} pointer exported by Python.
-
-Quoting the Python docs: \emph{This pointer is initialized to point to an
-array of ``struct {\_}frozen`` records, terminated by one whose members
-are all NULL or zero. When a frozen module is imported, it is searched
-in this table. Third-party code could play tricks with this to provide
-a dynamically created collection of frozen modules.}
-
-So manipulating this pointer could even prove useful. To restrict the
-example size, we show only how this table can be read with
-\code{ctypes}:
-\begin{verbatim}
->>> from ctypes import *
->>>
->>> class struct_frozen(Structure):
-... _fields_ = [("name", c_char_p),
-... ("code", POINTER(c_ubyte)),
-... ("size", c_int)]
-...
->>>
-\end{verbatim}
-
-We have defined the \code{struct {\_}frozen} data type, so we can get the
-pointer to the table:
-\begin{verbatim}
->>> FrozenTable = POINTER(struct_frozen)
->>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
->>>
-\end{verbatim}
-
-Since \code{table} is a \code{pointer} to the array of \code{struct{\_}frozen}
-records, we can iterate over it, but we just have to make sure that
-our loop terminates, because pointers have no size. Sooner or later it
-would probably crash with an access violation or whatever, so it's
-better to break out of the loop when we hit the NULL entry:
-\begin{verbatim}
->>> for item in table:
-... print item.name, item.size
-... if item.name is None:
-... break
-...
-__hello__ 104
-__phello__ -104
-__phello__.spam 104
-None 0
->>>
-\end{verbatim}
-
-The fact that standard Python has a frozen module and a frozen package
-(indicated by the negative size member) is not wellknown, it is only
-used for testing. Try it out with \code{import {\_}{\_}hello{\_}{\_}} for example.
-
-
-\subsubsection{Surprises\label{ctypes-surprises}}
-
-There are some edges in \code{ctypes} where you may be expect something
-else than what actually happens.
-
-Consider the following example:
-\begin{verbatim}
->>> from ctypes import *
->>> class POINT(Structure):
-... _fields_ = ("x", c_int), ("y", c_int)
-...
->>> class RECT(Structure):
-... _fields_ = ("a", POINT), ("b", POINT)
-...
->>> p1 = POINT(1, 2)
->>> p2 = POINT(3, 4)
->>> rc = RECT(p1, p2)
->>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
-1 2 3 4
->>> # now swap the two points
->>> rc.a, rc.b = rc.b, rc.a
->>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
-3 4 3 4
->>>
-\end{verbatim}
-
-Hm. We certainly expected the last statement to print \code{3 4 1 2}.
-What happended? Here are the steps of the \code{rc.a, rc.b = rc.b, rc.a}
-line above:
-\begin{verbatim}
->>> temp0, temp1 = rc.b, rc.a
->>> rc.a = temp0
->>> rc.b = temp1
->>>
-\end{verbatim}
-
-Note that \code{temp0} and \code{temp1} are objects still using the internal
-buffer of the \code{rc} object above. So executing \code{rc.a = temp0}
-copies the buffer contents of \code{temp0} into \code{rc} 's buffer. This,
-in turn, changes the contents of \code{temp1}. So, the last assignment
-\code{rc.b = temp1}, doesn't have the expected effect.
-
-Keep in mind that retrieving subobjects from Structure, Unions, and
-Arrays doesn't \emph{copy} the subobject, instead it retrieves a wrapper
-object accessing the root-object's underlying buffer.
-
-Another example that may behave different from what one would expect is this:
-\begin{verbatim}
->>> s = c_char_p()
->>> s.value = "abc def ghi"
->>> s.value
-'abc def ghi'
->>> s.value is s.value
-False
->>>
-\end{verbatim}
-
-Why is it printing \code{False}? ctypes instances are objects containing
-a memory block plus some descriptors accessing the contents of the
-memory. Storing a Python object in the memory block does not store
-the object itself, instead the \code{contents} of the object is stored.
-Accessing the contents again constructs a new Python each time!
-
-
-\subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}}
-
-\code{ctypes} provides some support for variable-sized arrays and
-structures (this was added in version 0.9.9.7).
-
-The \code{resize} function can be used to resize the memory buffer of an
-existing ctypes object. The function takes the object as first
-argument, and the requested size in bytes as the second argument. The
-memory block cannot be made smaller than the natural memory block
-specified by the objects type, a \code{ValueError} is raised if this is
-tried:
-\begin{verbatim}
->>> short_array = (c_short * 4)()
->>> print sizeof(short_array)
-8
->>> resize(short_array, 4)
-Traceback (most recent call last):
- ...
-ValueError: minimum size is 8
->>> resize(short_array, 32)
->>> sizeof(short_array)
-32
->>> sizeof(type(short_array))
-8
->>>
-\end{verbatim}
-
-This is nice and fine, but how would one access the additional
-elements contained in this array? Since the type still only knows
-about 4 elements, we get errors accessing other elements:
-\begin{verbatim}
->>> short_array[:]
-[0, 0, 0, 0]
->>> short_array[7]
-Traceback (most recent call last):
- ...
-IndexError: invalid index
->>>
-\end{verbatim}
-
-Another way to use variable-sized data types with \code{ctypes} is to use
-the dynamic nature of Python, and (re-)define the data type after the
-required size is already known, on a case by case basis.
-
-
-\subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}}
-
-Enumeration types are not implemented. You can do it easily yourself,
-using \class{c{\_}int} as the base class.
-
-\code{long double} is not implemented.
-% Local Variables:
-% compile-command: "make.bat"
-% End:
-
-
-\subsection{ctypes reference\label{ctypes-ctypes-reference}}
-
-
-\subsubsection{Finding shared libraries\label{ctypes-finding-shared-libraries}}
-
-When programming in a compiled language, shared libraries are accessed
-when compiling/linking a program, and when the program is run.
-
-The purpose of the \code{find{\_}library} function is to locate a library in
-a way similar to what the compiler does (on platforms with several
-versions of a shared library the most recent should be loaded), while
-the ctypes library loaders act like when a program is run, and call
-the runtime loader directly.
-
-The \code{ctypes.util} module provides a function which can help to
-determine the library to load.
-
-\begin{datadescni}{find_library(name)}
-Try to find a library and return a pathname. \var{name} is the
-library name without any prefix like \var{lib}, suffix like \code{.so},
-\code{.dylib} or version number (this is the form used for the posix
-linker option \programopt{-l}). If no library can be found, returns
-\code{None}.
-\end{datadescni}
-
-The exact functionality is system dependend.
-
-On Linux, \code{find{\_}library} tries to run external programs
-(/sbin/ldconfig, gcc, and objdump) to find the library file. It
-returns the filename of the library file. Here are sone examples:
-\begin{verbatim}
->>> from ctypes.util import find_library
->>> find_library("m")
-'libm.so.6'
->>> find_library("c")
-'libc.so.6'
->>> find_library("bz2")
-'libbz2.so.1.0'
->>>
-\end{verbatim}
-
-On OS X, \code{find{\_}library} tries several predefined naming schemes and
-paths to locate the library, and returns a full pathname if successfull:
-\begin{verbatim}
->>> from ctypes.util import find_library
->>> find_library("c")
-'/usr/lib/libc.dylib'
->>> find_library("m")
-'/usr/lib/libm.dylib'
->>> find_library("bz2")
-'/usr/lib/libbz2.dylib'
->>> find_library("AGL")
-'/System/Library/Frameworks/AGL.framework/AGL'
->>>
-\end{verbatim}
-
-On Windows, \code{find{\_}library} searches along the system search path,
-and returns the full pathname, but since there is no predefined naming
-scheme a call like \code{find{\_}library("c")} will fail and return
-\code{None}.
-
-If wrapping a shared library with \code{ctypes}, it \emph{may} be better to
-determine the shared library name at development type, and hardcode
-that into the wrapper module instead of using \code{find{\_}library} to
-locate the library at runtime.
-
-
-\subsubsection{Loading shared libraries\label{ctypes-loading-shared-libraries}}
-
-There are several ways to loaded shared libraries into the Python
-process. One way is to instantiate one of the following classes:
-
-\begin{classdesc}{CDLL}{name, mode=DEFAULT_MODE, handle=None}
-Instances of this class represent loaded shared libraries.
-Functions in these libraries use the standard C calling
-convention, and are assumed to return \code{int}.
-\end{classdesc}
-
-\begin{classdesc}{OleDLL}{name, mode=DEFAULT_MODE, handle=None}
-Windows only: Instances of this class represent loaded shared
-libraries, functions in these libraries use the \code{stdcall}
-calling convention, and are assumed to return the windows specific
-\class{HRESULT} code. \class{HRESULT} values contain information
-specifying whether the function call failed or succeeded, together
-with additional error code. If the return value signals a
-failure, an \class{WindowsError} is automatically raised.
-\end{classdesc}
-
-\begin{classdesc}{WinDLL}{name, mode=DEFAULT_MODE, handle=None}
-Windows only: Instances of this class represent loaded shared
-libraries, functions in these libraries use the \code{stdcall}
-calling convention, and are assumed to return \code{int} by default.
-
-On Windows CE only the standard calling convention is used, for
-convenience the \class{WinDLL} and \class{OleDLL} use the standard calling
-convention on this platform.
-\end{classdesc}
-
-The Python GIL is released before calling any function exported by
-these libraries, and reaquired afterwards.
-
-\begin{classdesc}{PyDLL}{name, mode=DEFAULT_MODE, handle=None}
-Instances of this class behave like \class{CDLL} instances, except
-that the Python GIL is \emph{not} released during the function call,
-and after the function execution the Python error flag is checked.
-If the error flag is set, a Python exception is raised.
-
-Thus, this is only useful to call Python C api functions directly.
-\end{classdesc}
-
-All these classes can be instantiated by calling them with at least
-one argument, the pathname of the shared library. If you have an
-existing handle to an already loaded shard library, it can be passed
-as the \code{handle} named parameter, otherwise the underlying platforms
-\code{dlopen} or \method{LoadLibrary} function is used to load the library
-into the process, and to get a handle to it.
-
-The \var{mode} parameter can be used to specify how the library is
-loaded. For details, consult the \code{dlopen(3)} manpage, on Windows,
-\var{mode} is ignored.
-
-\begin{datadescni}{RTLD_GLOBAL}
-Flag to use as \var{mode} parameter. On platforms where this flag
-is not available, it is defined as the integer zero.
-\end{datadescni}
-
-\begin{datadescni}{RTLD_LOCAL}
-Flag to use as \var{mode} parameter. On platforms where this is not
-available, it is the same as \var{RTLD{\_}GLOBAL}.
-\end{datadescni}
-
-\begin{datadescni}{DEFAULT_MODE}
-The default mode which is used to load shared libraries. On OSX
-10.3, this is \var{RTLD{\_}GLOBAL}, otherwise it is the same as
-\var{RTLD{\_}LOCAL}.
-\end{datadescni}
-
-Instances of these classes have no public methods, however
-\method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} have special behaviour: functions
-exported by the shared library can be accessed as attributes of by
-index. Please note that both \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}}
-cache their result, so calling them repeatedly returns the same object
-each time.
-
-The following public attributes are available, their name starts with
-an underscore to not clash with exported function names:
-
-\begin{memberdesc}{_handle}
-The system handle used to access the library.
-\end{memberdesc}
-
-\begin{memberdesc}{_name}
-The name of the library passed in the contructor.
-\end{memberdesc}
-
-Shared libraries can also be loaded by using one of the prefabricated
-objects, which are instances of the \class{LibraryLoader} class, either by
-calling the \method{LoadLibrary} method, or by retrieving the library as
-attribute of the loader instance.
-
-\begin{classdesc}{LibraryLoader}{dlltype}
-Class which loads shared libraries. \code{dlltype} should be one
-of the \class{CDLL}, \class{PyDLL}, \class{WinDLL}, or \class{OleDLL} types.
-
-\method{{\_}{\_}getattr{\_}{\_}} has special behaviour: It allows to load a shared
-library by accessing it as attribute of a library loader
-instance. The result is cached, so repeated attribute accesses
-return the same library each time.
-\end{classdesc}
-
-\begin{methoddesc}{LoadLibrary}{name}
-Load a shared library into the process and return it. This method
-always returns a new instance of the library.
-\end{methoddesc}
-
-These prefabricated library loaders are available:
-
-\begin{datadescni}{cdll}
-Creates \class{CDLL} instances.
-\end{datadescni}
-
-\begin{datadescni}{windll}
-Windows only: Creates \class{WinDLL} instances.
-\end{datadescni}
-
-\begin{datadescni}{oledll}
-Windows only: Creates \class{OleDLL} instances.
-\end{datadescni}
-
-\begin{datadescni}{pydll}
-Creates \class{PyDLL} instances.
-\end{datadescni}
-
-For accessing the C Python api directly, a ready-to-use Python shared
-library object is available:
-
-\begin{datadescni}{pythonapi}
-An instance of \class{PyDLL} that exposes Python C api functions as
-attributes. Note that all these functions are assumed to return C
-\code{int}, which is of course not always the truth, so you have to
-assign the correct \member{restype} attribute to use these functions.
-\end{datadescni}
-
-
-\subsubsection{Foreign functions\label{ctypes-foreign-functions}}
-
-As explained in the previous section, foreign functions can be
-accessed as attributes of loaded shared libraries. The function
-objects created in this way by default accept any number of arguments,
-accept any ctypes data instances as arguments, and return the default
-result type specified by the library loader. They are instances of a
-private class:
-
-\begin{classdesc*}{_FuncPtr}
-Base class for C callable foreign functions.
-\end{classdesc*}
-
-Instances of foreign functions are also C compatible data types; they
-represent C function pointers.
-
-This behaviour can be customized by assigning to special attributes of
-the foreign function object.
-
-\begin{memberdesc}{restype}
-Assign a ctypes type to specify the result type of the foreign
-function. Use \code{None} for \code{void} a function not returning
-anything.
-
-It is possible to assign a callable Python object that is not a
-ctypes type, in this case the function is assumed to return a
-C \code{int}, and the callable will be called with this integer,
-allowing to do further processing or error checking. Using this
-is deprecated, for more flexible postprocessing or error checking
-use a ctypes data type as \member{restype} and assign a callable to the
-\member{errcheck} attribute.
-\end{memberdesc}
-
-\begin{memberdesc}{argtypes}
-Assign a tuple of ctypes types to specify the argument types that
-the function accepts. Functions using the \code{stdcall} calling
-convention can only be called with the same number of arguments as
-the length of this tuple; functions using the C calling convention
-accept additional, unspecified arguments as well.
-
-When a foreign function is called, each actual argument is passed
-to the \method{from{\_}param} class method of the items in the
-\member{argtypes} tuple, this method allows to adapt the actual
-argument to an object that the foreign function accepts. For
-example, a \class{c{\_}char{\_}p} item in the \member{argtypes} tuple will
-convert a unicode string passed as argument into an byte string
-using ctypes conversion rules.
-
-New: It is now possible to put items in argtypes which are not
-ctypes types, but each item must have a \method{from{\_}param} method
-which returns a value usable as argument (integer, string, ctypes
-instance). This allows to define adapters that can adapt custom
-objects as function parameters.
-\end{memberdesc}
-
-\begin{memberdesc}{errcheck}
-Assign a Python function or another callable to this attribute.
-The callable will be called with three or more arguments:
-\end{memberdesc}
-
-\begin{funcdescni}{callable}{result, func, arguments}
-\code{result} is what the foreign function returns, as specified by the
-\member{restype} attribute.
-
-\code{func} is the foreign function object itself, this allows to
-reuse the same callable object to check or postprocess the results
-of several functions.
-
-\code{arguments} is a tuple containing the parameters originally
-passed to the function call, this allows to specialize the
-behaviour on the arguments used.
-
-The object that this function returns will be returned from the
-foreign function call, but it can also check the result value and
-raise an exception if the foreign function call failed.
-\end{funcdescni}
-
-\begin{excdesc}{ArgumentError()}
-This exception is raised when a foreign function call cannot
-convert one of the passed arguments.
-\end{excdesc}
-
-
-\subsubsection{Function prototypes\label{ctypes-function-prototypes}}
-
-Foreign functions can also be created by instantiating function
-prototypes. Function prototypes are similar to function prototypes in
-C; they describe a function (return type, argument types, calling
-convention) without defining an implementation. The factory
-functions must be called with the desired result type and the argument
-types of the function.
-
-\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes}
-The returned function prototype creates functions that use the
-standard C calling convention. The function will release the GIL
-during the call.
-\end{funcdesc}
-
-\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes}
-Windows only: The returned function prototype creates functions
-that use the \code{stdcall} calling convention, except on Windows CE
-where \function{WINFUNCTYPE} is the same as \function{CFUNCTYPE}. The function
-will release the GIL during the call.
-\end{funcdesc}
-
-\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes}
-The returned function prototype creates functions that use the
-Python calling convention. The function will \emph{not} release the
-GIL during the call.
-\end{funcdesc}
-
-Function prototypes created by the factory functions can be
-instantiated in different ways, depending on the type and number of
-the parameters in the call.
-
-\begin{funcdescni}{prototype}{address}
-Returns a foreign function at the specified address.
-\end{funcdescni}
-
-\begin{funcdescni}{prototype}{callable}
-Create a C callable function (a callback function) from a Python
-\code{callable}.
-\end{funcdescni}
-
-\begin{funcdescni}{prototype}{func_spec\optional{, paramflags}}
-Returns a foreign function exported by a shared library.
-\code{func{\_}spec} must be a 2-tuple \code{(name{\_}or{\_}ordinal, library)}.
-The first item is the name of the exported function as string, or
-the ordinal of the exported function as small integer. The second
-item is the shared library instance.
-\end{funcdescni}
-
-\begin{funcdescni}{prototype}{vtbl_index, name\optional{, paramflags\optional{, iid}}}
-Returns a foreign function that will call a COM method.
-\code{vtbl{\_}index} is the index into the virtual function table, a
-small nonnegative integer. \var{name} is name of the COM method.
-\var{iid} is an optional pointer to the interface identifier which
-is used in extended error reporting.
-
-COM methods use a special calling convention: They require a
-pointer to the COM interface as first argument, in addition to
-those parameters that are specified in the \member{argtypes} tuple.
-\end{funcdescni}
-
-The optional \var{paramflags} parameter creates foreign function
-wrappers with much more functionality than the features described
-above.
-
-\var{paramflags} must be a tuple of the same length as \member{argtypes}.
-
-Each item in this tuple contains further information about a
-parameter, it must be a tuple containing 1, 2, or 3 items.
-
-The first item is an integer containing flags for the parameter:
-
-\begin{datadescni}{1}
-Specifies an input parameter to the function.
-\end{datadescni}
-
-\begin{datadescni}{2}
-Output parameter. The foreign function fills in a value.
-\end{datadescni}
-
-\begin{datadescni}{4}
-Input parameter which defaults to the integer zero.
-\end{datadescni}
-
-The optional second item is the parameter name as string. If this is
-specified, the foreign function can be called with named parameters.
-
-The optional third item is the default value for this parameter.
-
-This example demonstrates how to wrap the Windows \code{MessageBoxA}
-function so that it supports default parameters and named arguments.
-The C declaration from the windows header file is this:
-\begin{verbatim}
-WINUSERAPI int WINAPI
-MessageBoxA(
- HWND hWnd ,
- LPCSTR lpText,
- LPCSTR lpCaption,
- UINT uType);
-\end{verbatim}
-
-Here is the wrapping with \code{ctypes}:
-\begin{quote}
-\begin{verbatim}>>> from ctypes import c_int, WINFUNCTYPE, windll
->>> from ctypes.wintypes import HWND, LPCSTR, UINT
->>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT)
->>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0)
->>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags)
->>>\end{verbatim}
-\end{quote}
-
-The MessageBox foreign function can now be called in these ways:
-\begin{verbatim}
->>> MessageBox()
->>> MessageBox(text="Spam, spam, spam")
->>> MessageBox(flags=2, text="foo bar")
->>>
-\end{verbatim}
-
-A second example demonstrates output parameters. The win32
-\code{GetWindowRect} function retrieves the dimensions of a specified
-window by copying them into \code{RECT} structure that the caller has to
-supply. Here is the C declaration:
-\begin{verbatim}
-WINUSERAPI BOOL WINAPI
-GetWindowRect(
- HWND hWnd,
- LPRECT lpRect);
-\end{verbatim}
-
-Here is the wrapping with \code{ctypes}:
-\begin{quote}
-\begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
->>> from ctypes.wintypes import BOOL, HWND, RECT
->>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
->>> paramflags = (1, "hwnd"), (2, "lprect")
->>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
->>>\end{verbatim}
-\end{quote}
-
-Functions with output parameters will automatically return the output
-parameter value if there is a single one, or a tuple containing the
-output parameter values when there are more than one, so the
-GetWindowRect function now returns a RECT instance, when called.
-
-Output parameters can be combined with the \member{errcheck} protocol to do
-further output processing and error checking. The win32
-\code{GetWindowRect} api function returns a \code{BOOL} to signal success or
-failure, so this function could do the error checking, and raises an
-exception when the api call failed:
-\begin{verbatim}
->>> def errcheck(result, func, args):
-... if not result:
-... raise WinError()
-... return args
->>> GetWindowRect.errcheck = errcheck
->>>
-\end{verbatim}
-
-If the \member{errcheck} function returns the argument tuple it receives
-unchanged, \code{ctypes} continues the normal processing it does on the
-output parameters. If you want to return a tuple of window
-coordinates instead of a \code{RECT} instance, you can retrieve the
-fields in the function and return them instead, the normal processing
-will no longer take place:
-\begin{verbatim}
->>> def errcheck(result, func, args):
-... if not result:
-... raise WinError()
-... rc = args[1]
-... return rc.left, rc.top, rc.bottom, rc.right
->>>
->>> GetWindowRect.errcheck = errcheck
->>>
-\end{verbatim}
-
-
-\subsubsection{Utility functions\label{ctypes-utility-functions}}
-
-\begin{funcdesc}{addressof}{obj}
-Returns the address of the memory buffer as integer. \code{obj} must
-be an instance of a ctypes type.
-\end{funcdesc}
-
-\begin{funcdesc}{alignment}{obj_or_type}
-Returns the alignment requirements of a ctypes type.
-\code{obj{\_}or{\_}type} must be a ctypes type or instance.
-\end{funcdesc}
-
-\begin{funcdesc}{byref}{obj}
-Returns a light-weight pointer to \code{obj}, which must be an
-instance of a ctypes type. The returned object can only be used as
-a foreign function call parameter. It behaves similar to
-\code{pointer(obj)}, but the construction is a lot faster.
-\end{funcdesc}
-
-\begin{funcdesc}{cast}{obj, type}
-This function is similar to the cast operator in C. It returns a
-new instance of \code{type} which points to the same memory block as
-\code{obj}. \code{type} must be a pointer type, and \code{obj} must be an
-object that can be interpreted as a pointer.
-\end{funcdesc}
-
-\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}}
-This function creates a mutable character buffer. The returned
-object is a ctypes array of \class{c{\_}char}.
-
-\code{init{\_}or{\_}size} must be an integer which specifies the size of
-the array, or a string which will be used to initialize the array
-items.
-
-If a string is specified as first argument, the buffer is made one
-item larger than the length of the string so that the last element
-in the array is a NUL termination character. An integer can be
-passed as second argument which allows to specify the size of the
-array if the length of the string should not be used.
-
-If the first parameter is a unicode string, it is converted into
-an 8-bit string according to ctypes conversion rules.
-\end{funcdesc}
-
-\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}}
-This function creates a mutable unicode character buffer. The
-returned object is a ctypes array of \class{c{\_}wchar}.
-
-\code{init{\_}or{\_}size} must be an integer which specifies the size of
-the array, or a unicode string which will be used to initialize
-the array items.
-
-If a unicode string is specified as first argument, the buffer is
-made one item larger than the length of the string so that the
-last element in the array is a NUL termination character. An
-integer can be passed as second argument which allows to specify
-the size of the array if the length of the string should not be
-used.
-
-If the first parameter is a 8-bit string, it is converted into an
-unicode string according to ctypes conversion rules.
-\end{funcdesc}
-
-\begin{funcdesc}{DllCanUnloadNow}{}
-Windows only: This function is a hook which allows to implement
-inprocess COM servers with ctypes. It is called from the
-DllCanUnloadNow function that the {\_}ctypes extension dll exports.
-\end{funcdesc}
-
-\begin{funcdesc}{DllGetClassObject}{}
-Windows only: This function is a hook which allows to implement
-inprocess COM servers with ctypes. It is called from the
-DllGetClassObject function that the \code{{\_}ctypes} extension dll exports.
-\end{funcdesc}
-
-\begin{funcdesc}{FormatError}{\optional{code}}
-Windows only: Returns a textual description of the error code. If
-no error code is specified, the last error code is used by calling
-the Windows api function GetLastError.
-\end{funcdesc}
-
-\begin{funcdesc}{GetLastError}{}
-Windows only: Returns the last error code set by Windows in the
-calling thread.
-\end{funcdesc}
-
-\begin{funcdesc}{memmove}{dst, src, count}
-Same as the standard C memmove library function: copies \var{count}
-bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be
-integers or ctypes instances that can be converted to pointers.
-\end{funcdesc}
-
-\begin{funcdesc}{memset}{dst, c, count}
-Same as the standard C memset library function: fills the memory
-block at address \var{dst} with \var{count} bytes of value
-\var{c}. \var{dst} must be an integer specifying an address, or a
-ctypes instance.
-\end{funcdesc}
-
-\begin{funcdesc}{POINTER}{type}
-This factory function creates and returns a new ctypes pointer
-type. Pointer types are cached an reused internally, so calling
-this function repeatedly is cheap. type must be a ctypes type.
-\end{funcdesc}
-
-\begin{funcdesc}{pointer}{obj}
-This function creates a new pointer instance, pointing to
-\code{obj}. The returned object is of the type POINTER(type(obj)).
-
-Note: If you just want to pass a pointer to an object to a foreign
-function call, you should use \code{byref(obj)} which is much faster.
-\end{funcdesc}
-
-\begin{funcdesc}{resize}{obj, size}
-This function resizes the internal memory buffer of obj, which
-must be an instance of a ctypes type. It is not possible to make
-the buffer smaller than the native size of the objects type, as
-given by sizeof(type(obj)), but it is possible to enlarge the
-buffer.
-\end{funcdesc}
-
-\begin{funcdesc}{set_conversion_mode}{encoding, errors}
-This function sets the rules that ctypes objects use when
-converting between 8-bit strings and unicode strings. encoding
-must be a string specifying an encoding, like \code{'utf-8'} or
-\code{'mbcs'}, errors must be a string specifying the error handling
-on encoding/decoding errors. Examples of possible values are
-\code{"strict"}, \code{"replace"}, or \code{"ignore"}.
-
-\code{set{\_}conversion{\_}mode} returns a 2-tuple containing the previous
-conversion rules. On windows, the initial conversion rules are
-\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}.
-\end{funcdesc}
-
-\begin{funcdesc}{sizeof}{obj_or_type}
-Returns the size in bytes of a ctypes type or instance memory
-buffer. Does the same as the C \code{sizeof()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{string_at}{address\optional{, size}}
-This function returns the string starting at memory address
-address. If size is specified, it is used as size, otherwise the
-string is assumed to be zero-terminated.
-\end{funcdesc}
-
-\begin{funcdesc}{WinError}{code=None, descr=None}
-Windows only: this function is probably the worst-named thing in
-ctypes. It creates an instance of WindowsError. If \var{code} is not
-specified, \code{GetLastError} is called to determine the error
-code. If \code{descr} is not spcified, \function{FormatError} is called to
-get a textual description of the error.
-\end{funcdesc}
-
-\begin{funcdesc}{wstring_at}{address}
-This function returns the wide character string starting at memory
-address \code{address} as unicode string. If \code{size} is specified,
-it is used as the number of characters of the string, otherwise
-the string is assumed to be zero-terminated.
-\end{funcdesc}
-
-
-\subsubsection{Data types\label{ctypes-data-types}}
-
-\begin{classdesc*}{_CData}
-This non-public class is the common base class of all ctypes data
-types. Among other things, all ctypes type instances contain a
-memory block that hold C compatible data; the address of the
-memory block is returned by the \code{addressof()} helper function.
-Another instance variable is exposed as \member{{\_}objects}; this
-contains other Python objects that need to be kept alive in case
-the memory block contains pointers.
-\end{classdesc*}
-
-Common methods of ctypes data types, these are all class methods (to
-be exact, they are methods of the metaclass):
-
-\begin{methoddesc}{from_address}{address}
-This method returns a ctypes type instance using the memory
-specified by address which must be an integer.
-\end{methoddesc}
-
-\begin{methoddesc}{from_param}{obj}
-This method adapts obj to a ctypes type. It is called with the
-actual object used in a foreign function call, when the type is
-present in the foreign functions \member{argtypes} tuple; it must
-return an object that can be used as function call parameter.
-
-All ctypes data types have a default implementation of this
-classmethod, normally it returns \code{obj} if that is an instance of
-the type. Some types accept other objects as well.
-\end{methoddesc}
-
-\begin{methoddesc}{in_dll}{library, name}
-This method returns a ctypes type instance exported by a shared
-library. \var{name} is the name of the symbol that exports the data,
-\var{library} is the loaded shared library.
-\end{methoddesc}
-
-Common instance variables of ctypes data types:
-
-\begin{memberdesc}{_b_base_}
-Sometimes ctypes data instances do not own the memory block they
-contain, instead they share part of the memory block of a base
-object. The \member{{\_}b{\_}base{\_}} readonly member is the root ctypes
-object that owns the memory block.
-\end{memberdesc}
-
-\begin{memberdesc}{_b_needsfree_}
-This readonly variable is true when the ctypes data instance has
-allocated the memory block itself, false otherwise.
-\end{memberdesc}
-
-\begin{memberdesc}{_objects}
-This member is either \code{None} or a dictionary containing Python
-objects that need to be kept alive so that the memory block
-contents is kept valid. This object is only exposed for
-debugging; never modify the contents of this dictionary.
-\end{memberdesc}
-
-
-\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types-2}}
-
-\begin{classdesc*}{_SimpleCData}
-This non-public class is the base class of all fundamental ctypes
-data types. It is mentioned here because it contains the common
-attributes of the fundamental ctypes data types. \code{{\_}SimpleCData}
-is a subclass of \code{{\_}CData}, so it inherits their methods and
-attributes.
-\end{classdesc*}
-
-Instances have a single attribute:
-
-\begin{memberdesc}{value}
-This attribute contains the actual value of the instance. For
-integer and pointer types, it is an integer, for character types,
-it is a single character string, for character pointer types it
-is a Python string or unicode string.
-
-When the \code{value} attribute is retrieved from a ctypes instance,
-usually a new object is returned each time. \code{ctypes} does \emph{not}
-implement original object return, always a new object is
-constructed. The same is true for all other ctypes object
-instances.
-\end{memberdesc}
-
-Fundamental data types, when returned as foreign function call
-results, or, for example, by retrieving structure field members or
-array items, are transparently converted to native Python types. In
-other words, if a foreign function has a \member{restype} of \class{c{\_}char{\_}p},
-you will always receive a Python string, \emph{not} a \class{c{\_}char{\_}p}
-instance.
-
-Subclasses of fundamental data types do \emph{not} inherit this behaviour.
-So, if a foreign functions \member{restype} is a subclass of \class{c{\_}void{\_}p},
-you will receive an instance of this subclass from the function call.
-Of course, you can get the value of the pointer by accessing the
-\code{value} attribute.
-
-These are the fundamental ctypes data types:
-
-\begin{classdesc*}{c_byte}
-Represents the C signed char datatype, and interprets the value as
-small integer. The constructor accepts an optional integer
-initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_char}
-Represents the C char datatype, and interprets the value as a single
-character. The constructor accepts an optional string initializer,
-the length of the string must be exactly one character.
-\end{classdesc*}
-
-\begin{classdesc*}{c_char_p}
-Represents the C char * datatype, which must be a pointer to a
-zero-terminated string. The constructor accepts an integer
-address, or a string.
-\end{classdesc*}
-
-\begin{classdesc*}{c_double}
-Represents the C double datatype. The constructor accepts an
-optional float initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_float}
-Represents the C double datatype. The constructor accepts an
-optional float initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int}
-Represents the C signed int datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done. On
-platforms where \code{sizeof(int) == sizeof(long)} it is an alias to
-\class{c{\_}long}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int8}
-Represents the C 8-bit \code{signed int} datatype. Usually an alias for
-\class{c{\_}byte}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int16}
-Represents the C 16-bit signed int datatype. Usually an alias for
-\class{c{\_}short}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int32}
-Represents the C 32-bit signed int datatype. Usually an alias for
-\class{c{\_}int}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int64}
-Represents the C 64-bit \code{signed int} datatype. Usually an alias
-for \class{c{\_}longlong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_long}
-Represents the C \code{signed long} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_longlong}
-Represents the C \code{signed long long} datatype. The constructor accepts
-an optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_short}
-Represents the C \code{signed short} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_size_t}
-Represents the C \code{size{\_}t} datatype.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ubyte}
-Represents the C \code{unsigned char} datatype, it interprets the
-value as small integer. The constructor accepts an optional
-integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint}
-Represents the C \code{unsigned int} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done. On
-platforms where \code{sizeof(int) == sizeof(long)} it is an alias for
-\class{c{\_}ulong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint8}
-Represents the C 8-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ubyte}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint16}
-Represents the C 16-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ushort}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint32}
-Represents the C 32-bit unsigned int datatype. Usually an alias for
-\class{c{\_}uint}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint64}
-Represents the C 64-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ulonglong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ulong}
-Represents the C \code{unsigned long} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ulonglong}
-Represents the C \code{unsigned long long} datatype. The constructor
-accepts an optional integer initializer; no overflow checking is
-done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ushort}
-Represents the C \code{unsigned short} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_void_p}
-Represents the C \code{void *} type. The value is represented as
-integer. The constructor accepts an optional integer initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_wchar}
-Represents the C \code{wchar{\_}t} datatype, and interprets the value as a
-single character unicode string. The constructor accepts an
-optional string initializer, the length of the string must be
-exactly one character.
-\end{classdesc*}
-
-\begin{classdesc*}{c_wchar_p}
-Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to
-a zero-terminated wide character string. The constructor accepts
-an integer address, or a string.
-\end{classdesc*}
-
-\begin{classdesc*}{c_bool}
-Represent the C \code{bool} datatype (more accurately, _Bool from C99).
-Its value can be True or False, and the constructor accepts any object that
-has a truth value.
-\versionadded{2.6}
-\end{classdesc*}
-
-\begin{classdesc*}{HRESULT}
-Windows only: Represents a \class{HRESULT} value, which contains success
-or error information for a function or method call.
-\end{classdesc*}
-
-\begin{classdesc*}{py_object}
-Represents the C \code{PyObject *} datatype. Calling this without an
-argument creates a \code{NULL} \code{PyObject *} pointer.
-\end{classdesc*}
-
-The \code{ctypes.wintypes} module provides quite some other Windows
-specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}.
-Some useful structures like \code{MSG} or \code{RECT} are also defined.
-
-
-\subsubsection{Structured data types\label{ctypes-structured-data-types}}
-
-\begin{classdesc}{Union}{*args, **kw}
-Abstract base class for unions in native byte order.
-\end{classdesc}
-
-\begin{classdesc}{BigEndianStructure}{*args, **kw}
-Abstract base class for structures in \emph{big endian} byte order.
-\end{classdesc}
-
-\begin{classdesc}{LittleEndianStructure}{*args, **kw}
-Abstract base class for structures in \emph{little endian} byte order.
-\end{classdesc}
-
-Structures with non-native byte order cannot contain pointer type
-fields, or any other data types containing pointer type fields.
-
-\begin{classdesc}{Structure}{*args, **kw}
-Abstract base class for structures in \emph{native} byte order.
-\end{classdesc}
-
-Concrete structure and union types must be created by subclassing one
-of these types, and at least define a \member{{\_}fields{\_}} class variable.
-\code{ctypes} will create descriptors which allow reading and writing the
-fields by direct attribute accesses. These are the
-
-\begin{memberdesc}{_fields_}
-A sequence defining the structure fields. The items must be
-2-tuples or 3-tuples. The first item is the name of the field,
-the second item specifies the type of the field; it can be any
-ctypes data type.
-
-For integer type fields like \class{c{\_}int}, a third optional item can
-be given. It must be a small positive integer defining the bit
-width of the field.
-
-Field names must be unique within one structure or union. This is
-not checked, only one field can be accessed when names are
-repeated.
-
-It is possible to define the \member{{\_}fields{\_}} class variable \emph{after}
-the class statement that defines the Structure subclass, this
-allows to create data types that directly or indirectly reference
-themselves:
-\begin{verbatim}
-class List(Structure):
- pass
-List._fields_ = [("pnext", POINTER(List)),
- ...
- ]
-\end{verbatim}
-
-The \member{{\_}fields{\_}} class variable must, however, be defined before
-the type is first used (an instance is created, \code{sizeof()} is
-called on it, and so on). Later assignments to the \member{{\_}fields{\_}}
-class variable will raise an AttributeError.
-
-Structure and union subclass constructors accept both positional
-and named arguments. Positional arguments are used to initialize
-the fields in the same order as they appear in the \member{{\_}fields{\_}}
-definition, named arguments are used to initialize the fields with
-the corresponding name.
-
-It is possible to defined sub-subclasses of structure types, they
-inherit the fields of the base class plus the \member{{\_}fields{\_}} defined
-in the sub-subclass, if any.
-\end{memberdesc}
-
-\begin{memberdesc}{_pack_}
-An optional small integer that allows to override the alignment of
-structure fields in the instance. \member{{\_}pack{\_}} must already be
-defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no
-effect.
-\end{memberdesc}
-
-\begin{memberdesc}{_anonymous_}
-An optional sequence that lists the names of unnamed (anonymous)
-fields. \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}}
-is assigned, otherwise it will have no effect.
-
-The fields listed in this variable must be structure or union type
-fields. \code{ctypes} will create descriptors in the structure type
-that allows to access the nested fields directly, without the need
-to create the structure or union field.
-
-Here is an example type (Windows):
-\begin{verbatim}
-class _U(Union):
- _fields_ = [("lptdesc", POINTER(TYPEDESC)),
- ("lpadesc", POINTER(ARRAYDESC)),
- ("hreftype", HREFTYPE)]
-
-class TYPEDESC(Structure):
- _fields_ = [("u", _U),
- ("vt", VARTYPE)]
-
- _anonymous_ = ("u",)
-\end{verbatim}
-
-The \code{TYPEDESC} structure describes a COM data type, the \code{vt}
-field specifies which one of the union fields is valid. Since the
-\code{u} field is defined as anonymous field, it is now possible to
-access the members directly off the TYPEDESC instance.
-\code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former
-is faster since it does not need to create a temporary union
-instance:
-\begin{verbatim}
-td = TYPEDESC()
-td.vt = VT_PTR
-td.lptdesc = POINTER(some_type)
-td.u.lptdesc = POINTER(some_type)
-\end{verbatim}
-\end{memberdesc}
-
-It is possible to defined sub-subclasses of structures, they inherit
-the fields of the base class. If the subclass definition has a
-separate \member{{\_}fields{\_}} variable, the fields specified in this are
-appended to the fields of the base class.
-
-Structure and union constructors accept both positional and
-keyword arguments. Positional arguments are used to initialize member
-fields in the same order as they are appear in \member{{\_}fields{\_}}. Keyword
-arguments in the constructor are interpreted as attribute assignments,
-so they will initialize \member{{\_}fields{\_}} with the same name, or create new
-attributes for names not present in \member{{\_}fields{\_}}.
-
-
-\subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}}
-
-Not yet written - please see section~\ref{ctypes-pointers}, pointers and
-section~\ref{ctypes-arrays}, arrays in the tutorial.
-
diff --git a/Doc/lib/libcurses.tex b/Doc/lib/libcurses.tex
deleted file mode 100644
index 33dea5a..0000000
--- a/Doc/lib/libcurses.tex
+++ /dev/null
@@ -1,1405 +0,0 @@
-\section{\module{curses} ---
- Terminal handling for character-cell displays}
-
-\declaremodule{standard}{curses}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\sectionauthor{Eric Raymond}{esr@thyrsus.com}
-\modulesynopsis{An interface to the curses library, providing portable
- terminal handling.}
-
-\versionchanged[Added support for the \code{ncurses} library and
- converted to a package]{1.6}
-
-The \module{curses} module provides an interface to the curses
-library, the de-facto standard for portable advanced terminal
-handling.
-
-While curses is most widely used in the \UNIX{} environment, versions
-are available for DOS, OS/2, and possibly other systems as well. This
-extension module is designed to match the API of ncurses, an
-open-source curses library hosted on Linux and the BSD variants of
-\UNIX.
-
-\begin{seealso}
- \seemodule{curses.ascii}{Utilities for working with \ASCII{}
- characters, regardless of your locale
- settings.}
- \seemodule{curses.panel}{A panel stack extension that adds depth to
- curses windows.}
- \seemodule{curses.textpad}{Editable text widget for curses supporting
- \program{Emacs}-like bindings.}
- \seemodule{curses.wrapper}{Convenience function to ensure proper
- terminal setup and resetting on
- application entry and exit.}
- \seetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses
- Programming with Python}{Tutorial material on using curses
- with Python, by Andrew Kuchling and Eric Raymond, is
- available on the Python Web site.}
- \seetext{The \file{Demo/curses/} directory in the Python source
- distribution contains some example programs using the
- curses bindings provided by this module.}
-\end{seealso}
-
-
-\subsection{Functions \label{curses-functions}}
-
-The module \module{curses} defines the following exception:
-
-\begin{excdesc}{error}
-Exception raised when a curses library function returns an error.
-\end{excdesc}
-
-\note{Whenever \var{x} or \var{y} arguments to a function
-or a method are optional, they default to the current cursor location.
-Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}.}
-
-The module \module{curses} defines the following functions:
-
-\begin{funcdesc}{baudrate}{}
-Returns the output speed of the terminal in bits per second. On
-software terminal emulators it will have a fixed high value.
-Included for historical reasons; in former times, it was used to
-write output loops for time delays and occasionally to change
-interfaces depending on the line speed.
-\end{funcdesc}
-
-\begin{funcdesc}{beep}{}
-Emit a short attention sound.
-\end{funcdesc}
-
-\begin{funcdesc}{can_change_color}{}
-Returns true or false, depending on whether the programmer can change
-the colors displayed by the terminal.
-\end{funcdesc}
-
-\begin{funcdesc}{cbreak}{}
-Enter cbreak mode. In cbreak mode (sometimes called ``rare'' mode)
-normal tty line buffering is turned off and characters are available
-to be read one by one. However, unlike raw mode, special characters
-(interrupt, quit, suspend, and flow control) retain their effects on
-the tty driver and calling program. Calling first \function{raw()}
-then \function{cbreak()} leaves the terminal in cbreak mode.
-\end{funcdesc}
-
-\begin{funcdesc}{color_content}{color_number}
-Returns the intensity of the red, green, and blue (RGB) components in
-the color \var{color_number}, which must be between \code{0} and
-\constant{COLORS}. A 3-tuple is returned, containing the R,G,B values
-for the given color, which will be between \code{0} (no component) and
-\code{1000} (maximum amount of component).
-\end{funcdesc}
-
-\begin{funcdesc}{color_pair}{color_number}
-Returns the attribute value for displaying text in the specified
-color. This attribute value can be combined with
-\constant{A_STANDOUT}, \constant{A_REVERSE}, and the other
-\constant{A_*} attributes. \function{pair_number()} is the
-counterpart to this function.
-\end{funcdesc}
-
-\begin{funcdesc}{curs_set}{visibility}
-Sets the cursor state. \var{visibility} can be set to 0, 1, or 2, for
-invisible, normal, or very visible. If the terminal supports the
-visibility requested, the previous cursor state is returned;
-otherwise, an exception is raised. On many terminals, the ``visible''
-mode is an underline cursor and the ``very visible'' mode is a block cursor.
-\end{funcdesc}
-
-\begin{funcdesc}{def_prog_mode}{}
-Saves the current terminal mode as the ``program'' mode, the mode when
-the running program is using curses. (Its counterpart is the
-``shell'' mode, for when the program is not in curses.) Subsequent calls
-to \function{reset_prog_mode()} will restore this mode.
-\end{funcdesc}
-
-\begin{funcdesc}{def_shell_mode}{}
-Saves the current terminal mode as the ``shell'' mode, the mode when
-the running program is not using curses. (Its counterpart is the
-``program'' mode, when the program is using curses capabilities.)
-Subsequent calls
-to \function{reset_shell_mode()} will restore this mode.
-\end{funcdesc}
-
-\begin{funcdesc}{delay_output}{ms}
-Inserts an \var{ms} millisecond pause in output.
-\end{funcdesc}
-
-\begin{funcdesc}{doupdate}{}
-Update the physical screen. The curses library keeps two data
-structures, one representing the current physical screen contents
-and a virtual screen representing the desired next state. The
-\function{doupdate()} ground updates the physical screen to match the
-virtual screen.
-
-The virtual screen may be updated by a \method{noutrefresh()} call
-after write operations such as \method{addstr()} have been performed
-on a window. The normal \method{refresh()} call is simply
-\method{noutrefresh()} followed by \function{doupdate()}; if you have
-to update multiple windows, you can speed performance and perhaps
-reduce screen flicker by issuing \method{noutrefresh()} calls on
-all windows, followed by a single \function{doupdate()}.
-\end{funcdesc}
-
-\begin{funcdesc}{echo}{}
-Enter echo mode. In echo mode, each character input is echoed to the
-screen as it is entered.
-\end{funcdesc}
-
-\begin{funcdesc}{endwin}{}
-De-initialize the library, and return terminal to normal status.
-\end{funcdesc}
-
-\begin{funcdesc}{erasechar}{}
-Returns the user's current erase character. Under \UNIX{} operating
-systems this is a property of the controlling tty of the curses
-program, and is not set by the curses library itself.
-\end{funcdesc}
-
-\begin{funcdesc}{filter}{}
-The \function{filter()} routine, if used, must be called before
-\function{initscr()} is called. The effect is that, during those
-calls, LINES is set to 1; the capabilities clear, cup, cud, cud1,
-cuu1, cuu, vpa are disabled; and the home string is set to the value of cr.
-The effect is that the cursor is confined to the current line, and so
-are screen updates. This may be used for enabling character-at-a-time
-line editing without touching the rest of the screen.
-\end{funcdesc}
-
-\begin{funcdesc}{flash}{}
-Flash the screen. That is, change it to reverse-video and then change
-it back in a short interval. Some people prefer such as `visible bell'
-to the audible attention signal produced by \function{beep()}.
-\end{funcdesc}
-
-\begin{funcdesc}{flushinp}{}
-Flush all input buffers. This throws away any typeahead that has
-been typed by the user and has not yet been processed by the program.
-\end{funcdesc}
-
-\begin{funcdesc}{getmouse}{}
-After \method{getch()} returns \constant{KEY_MOUSE} to signal a mouse
-event, this method should be call to retrieve the queued mouse event,
-represented as a 5-tuple
-\code{(\var{id}, \var{x}, \var{y}, \var{z}, \var{bstate})}.
-\var{id} is an ID value used to distinguish multiple devices,
-and \var{x}, \var{y}, \var{z} are the event's coordinates. (\var{z}
-is currently unused.). \var{bstate} is an integer value whose bits
-will be set to indicate the type of event, and will be the bitwise OR
-of one or more of the following constants, where \var{n} is the button
-number from 1 to 4:
-\constant{BUTTON\var{n}_PRESSED},
-\constant{BUTTON\var{n}_RELEASED},
-\constant{BUTTON\var{n}_CLICKED},
-\constant{BUTTON\var{n}_DOUBLE_CLICKED},
-\constant{BUTTON\var{n}_TRIPLE_CLICKED},
-\constant{BUTTON_SHIFT},
-\constant{BUTTON_CTRL},
-\constant{BUTTON_ALT}.
-\end{funcdesc}
-
-\begin{funcdesc}{getsyx}{}
-Returns the current coordinates of the virtual screen cursor in y and
-x. If leaveok is currently true, then -1,-1 is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{getwin}{file}
-Reads window related data stored in the file by an earlier
-\function{putwin()} call. The routine then creates and initializes a
-new window using that data, returning the new window object.
-\end{funcdesc}
-
-\begin{funcdesc}{has_colors}{}
-Returns true if the terminal can display colors; otherwise, it
-returns false.
-\end{funcdesc}
-
-\begin{funcdesc}{has_ic}{}
-Returns true if the terminal has insert- and delete- character
-capabilities. This function is included for historical reasons only,
-as all modern software terminal emulators have such capabilities.
-\end{funcdesc}
-
-\begin{funcdesc}{has_il}{}
-Returns true if the terminal has insert- and
-delete-line capabilities, or can simulate them using
-scrolling regions. This function is included for historical reasons only,
-as all modern software terminal emulators have such capabilities.
-\end{funcdesc}
-
-\begin{funcdesc}{has_key}{ch}
-Takes a key value \var{ch}, and returns true if the current terminal
-type recognizes a key with that value.
-\end{funcdesc}
-
-\begin{funcdesc}{halfdelay}{tenths}
-Used for half-delay mode, which is similar to cbreak mode in that
-characters typed by the user are immediately available to the program.
-However, after blocking for \var{tenths} tenths of seconds, an
-exception is raised if nothing has been typed. The value of
-\var{tenths} must be a number between 1 and 255. Use
-\function{nocbreak()} to leave half-delay mode.
-\end{funcdesc}
-
-\begin{funcdesc}{init_color}{color_number, r, g, b}
-Changes the definition of a color, taking the number of the color to
-be changed followed by three RGB values (for the amounts of red,
-green, and blue components). The value of \var{color_number} must be
-between \code{0} and \constant{COLORS}. Each of \var{r}, \var{g},
-\var{b}, must be a value between \code{0} and \code{1000}. When
-\function{init_color()} is used, all occurrences of that color on the
-screen immediately change to the new definition. This function is a
-no-op on most terminals; it is active only if
-\function{can_change_color()} returns \code{1}.
-\end{funcdesc}
-
-\begin{funcdesc}{init_pair}{pair_number, fg, bg}
-Changes the definition of a color-pair. It takes three arguments: the
-number of the color-pair to be changed, the foreground color number,
-and the background color number. The value of \var{pair_number} must
-be between \code{1} and \code{COLOR_PAIRS - 1} (the \code{0} color
-pair is wired to white on black and cannot be changed). The value of
-\var{fg} and \var{bg} arguments must be between \code{0} and
-\constant{COLORS}. If the color-pair was previously initialized, the
-screen is refreshed and all occurrences of that color-pair are changed
-to the new definition.
-\end{funcdesc}
-
-\begin{funcdesc}{initscr}{}
-Initialize the library. Returns a \class{WindowObject} which represents
-the whole screen. \note{If there is an error opening the terminal,
-the underlying curses library may cause the interpreter to exit.}
-\end{funcdesc}
-
-\begin{funcdesc}{isendwin}{}
-Returns true if \function{endwin()} has been called (that is, the
-curses library has been deinitialized).
-\end{funcdesc}
-
-\begin{funcdesc}{keyname}{k}
-Return the name of the key numbered \var{k}. The name of a key
-generating printable ASCII character is the key's character. The name
-of a control-key combination is a two-character string consisting of a
-caret followed by the corresponding printable ASCII character. The
-name of an alt-key combination (128-255) is a string consisting of the
-prefix `M-' followed by the name of the corresponding ASCII character.
-\end{funcdesc}
-
-\begin{funcdesc}{killchar}{}
-Returns the user's current line kill character. Under \UNIX{} operating
-systems this is a property of the controlling tty of the curses
-program, and is not set by the curses library itself.
-\end{funcdesc}
-
-\begin{funcdesc}{longname}{}
-Returns a string containing the terminfo long name field describing the current
-terminal. The maximum length of a verbose description is 128
-characters. It is defined only after the call to
-\function{initscr()}.
-\end{funcdesc}
-
-\begin{funcdesc}{meta}{yes}
-If \var{yes} is 1, allow 8-bit characters to be input. If \var{yes} is 0,
-allow only 7-bit chars.
-\end{funcdesc}
-
-\begin{funcdesc}{mouseinterval}{interval}
-Sets the maximum time in milliseconds that can elapse between press and
-release events in order for them to be recognized as a click, and
-returns the previous interval value. The default value is 200 msec,
-or one fifth of a second.
-\end{funcdesc}
-
-\begin{funcdesc}{mousemask}{mousemask}
-Sets the mouse events to be reported, and returns a tuple
-\code{(\var{availmask}, \var{oldmask})}.
-\var{availmask} indicates which of the
-specified mouse events can be reported; on complete failure it returns
-0. \var{oldmask} is the previous value of the given window's mouse
-event mask. If this function is never called, no mouse events are
-ever reported.
-\end{funcdesc}
-
-\begin{funcdesc}{napms}{ms}
-Sleep for \var{ms} milliseconds.
-\end{funcdesc}
-
-\begin{funcdesc}{newpad}{nlines, ncols}
-Creates and returns a pointer to a new pad data structure with the
-given number of lines and columns. A pad is returned as a
-window object.
-
-A pad is like a window, except that it is not restricted by the screen
-size, and is not necessarily associated with a particular part of the
-screen. Pads can be used when a large window is needed, and only a
-part of the window will be on the screen at one time. Automatic
-refreshes of pads (such as from scrolling or echoing of input) do not
-occur. The \method{refresh()} and \method{noutrefresh()} methods of a
-pad require 6 arguments to specify the part of the pad to be
-displayed and the location on the screen to be used for the display.
-The arguments are pminrow, pmincol, sminrow, smincol, smaxrow,
-smaxcol; the p arguments refer to the upper left corner of the pad
-region to be displayed and the s arguments define a clipping box on
-the screen within which the pad region is to be displayed.
-\end{funcdesc}
-
-\begin{funcdesc}{newwin}{\optional{nlines, ncols,} begin_y, begin_x}
-Return a new window, whose left-upper corner is at
-\code{(\var{begin_y}, \var{begin_x})}, and whose height/width is
-\var{nlines}/\var{ncols}.
-
-By default, the window will extend from the
-specified position to the lower right corner of the screen.
-\end{funcdesc}
-
-\begin{funcdesc}{nl}{}
-Enter newline mode. This mode translates the return key into newline
-on input, and translates newline into return and line-feed on output.
-Newline mode is initially on.
-\end{funcdesc}
-
-\begin{funcdesc}{nocbreak}{}
-Leave cbreak mode. Return to normal ``cooked'' mode with line buffering.
-\end{funcdesc}
-
-\begin{funcdesc}{noecho}{}
-Leave echo mode. Echoing of input characters is turned off.
-\end{funcdesc}
-
-\begin{funcdesc}{nonl}{}
-Leave newline mode. Disable translation of return into newline on
-input, and disable low-level translation of newline into
-newline/return on output (but this does not change the behavior of
-\code{addch('\e n')}, which always does the equivalent of return and
-line feed on the virtual screen). With translation off, curses can
-sometimes speed up vertical motion a little; also, it will be able to
-detect the return key on input.
-\end{funcdesc}
-
-\begin{funcdesc}{noqiflush}{}
-When the noqiflush routine is used, normal flush of input and
-output queues associated with the INTR, QUIT and SUSP
-characters will not be done. You may want to call
-\function{noqiflush()} in a signal handler if you want output
-to continue as though the interrupt had not occurred, after the
-handler exits.
-\end{funcdesc}
-
-\begin{funcdesc}{noraw}{}
-Leave raw mode. Return to normal ``cooked'' mode with line buffering.
-\end{funcdesc}
-
-\begin{funcdesc}{pair_content}{pair_number}
-Returns a tuple \code{(\var{fg}, \var{bg})} containing the colors for
-the requested color pair. The value of \var{pair_number} must be
-between \code{1} and \code{\constant{COLOR_PAIRS} - 1}.
-\end{funcdesc}
-
-\begin{funcdesc}{pair_number}{attr}
-Returns the number of the color-pair set by the attribute value
-\var{attr}. \function{color_pair()} is the counterpart to this
-function.
-\end{funcdesc}
-
-\begin{funcdesc}{putp}{string}
-Equivalent to \code{tputs(str, 1, putchar)}; emits the value of a
-specified terminfo capability for the current terminal. Note that the
-output of putp always goes to standard output.
-\end{funcdesc}
-
-\begin{funcdesc}{qiflush}{ \optional{flag} }
-If \var{flag} is false, the effect is the same as calling
-\function{noqiflush()}. If \var{flag} is true, or no argument is
-provided, the queues will be flushed when these control characters are
-read.
-\end{funcdesc}
-
-\begin{funcdesc}{raw}{}
-Enter raw mode. In raw mode, normal line buffering and
-processing of interrupt, quit, suspend, and flow control keys are
-turned off; characters are presented to curses input functions one
-by one.
-\end{funcdesc}
-
-\begin{funcdesc}{reset_prog_mode}{}
-Restores the terminal to ``program'' mode, as previously saved
-by \function{def_prog_mode()}.
-\end{funcdesc}
-
-\begin{funcdesc}{reset_shell_mode}{}
-Restores the terminal to ``shell'' mode, as previously saved
-by \function{def_shell_mode()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setsyx}{y, x}
-Sets the virtual screen cursor to \var{y}, \var{x}.
-If \var{y} and \var{x} are both -1, then leaveok is set.
-\end{funcdesc}
-
-\begin{funcdesc}{setupterm}{\optional{termstr, fd}}
-Initializes the terminal. \var{termstr} is a string giving the
-terminal name; if omitted, the value of the TERM environment variable
-will be used. \var{fd} is the file descriptor to which any
-initialization sequences will be sent; if not supplied, the file
-descriptor for \code{sys.stdout} will be used.
-\end{funcdesc}
-
-\begin{funcdesc}{start_color}{}
-Must be called if the programmer wants to use colors, and before any
-other color manipulation routine is called. It is good
-practice to call this routine right after \function{initscr()}.
-
-\function{start_color()} initializes eight basic colors (black, red,
-green, yellow, blue, magenta, cyan, and white), and two global
-variables in the \module{curses} module, \constant{COLORS} and
-\constant{COLOR_PAIRS}, containing the maximum number of colors and
-color-pairs the terminal can support. It also restores the colors on
-the terminal to the values they had when the terminal was just turned
-on.
-\end{funcdesc}
-
-\begin{funcdesc}{termattrs}{}
-Returns a logical OR of all video attributes supported by the
-terminal. This information is useful when a curses program needs
-complete control over the appearance of the screen.
-\end{funcdesc}
-
-\begin{funcdesc}{termname}{}
-Returns the value of the environment variable TERM, truncated to 14
-characters.
-\end{funcdesc}
-
-\begin{funcdesc}{tigetflag}{capname}
-Returns the value of the Boolean capability corresponding to the
-terminfo capability name \var{capname}. The value \code{-1} is
-returned if \var{capname} is not a Boolean capability, or \code{0} if
-it is canceled or absent from the terminal description.
-\end{funcdesc}
-
-\begin{funcdesc}{tigetnum}{capname}
-Returns the value of the numeric capability corresponding to the
-terminfo capability name \var{capname}. The value \code{-2} is
-returned if \var{capname} is not a numeric capability, or \code{-1} if
-it is canceled or absent from the terminal description.
-\end{funcdesc}
-
-\begin{funcdesc}{tigetstr}{capname}
-Returns the value of the string capability corresponding to the
-terminfo capability name \var{capname}. \code{None} is returned if
-\var{capname} is not a string capability, or is canceled or absent
-from the terminal description.
-\end{funcdesc}
-
-\begin{funcdesc}{tparm}{str\optional{,...}}
-Instantiates the string \var{str} with the supplied parameters, where
-\var{str} should be a parameterized string obtained from the terminfo
-database. E.g. \code{tparm(tigetstr("cup"), 5, 3)} could result in
-\code{'\e{}033[6;4H'}, the exact result depending on terminal type.
-\end{funcdesc}
-
-\begin{funcdesc}{typeahead}{fd}
-Specifies that the file descriptor \var{fd} be used for typeahead
-checking. If \var{fd} is \code{-1}, then no typeahead checking is
-done.
-
-The curses library does ``line-breakout optimization'' by looking for
-typeahead periodically while updating the screen. If input is found,
-and it is coming from a tty, the current update is postponed until
-refresh or doupdate is called again, allowing faster response to
-commands typed in advance. This function allows specifying a different
-file descriptor for typeahead checking.
-\end{funcdesc}
-
-\begin{funcdesc}{unctrl}{ch}
-Returns a string which is a printable representation of the character
-\var{ch}. Control characters are displayed as a caret followed by the
-character, for example as \code{\textasciicircum C}. Printing
-characters are left as they are.
-\end{funcdesc}
-
-\begin{funcdesc}{ungetch}{ch}
-Push \var{ch} so the next \method{getch()} will return it.
-\note{Only one \var{ch} can be pushed before \method{getch()}
-is called.}
-\end{funcdesc}
-
-\begin{funcdesc}{ungetmouse}{id, x, y, z, bstate}
-Push a \constant{KEY_MOUSE} event onto the input queue, associating
-the given state data with it.
-\end{funcdesc}
-
-\begin{funcdesc}{use_env}{flag}
-If used, this function should be called before \function{initscr()} or
-newterm are called. When \var{flag} is false, the values of
-lines and columns specified in the terminfo database will be
-used, even if environment variables \envvar{LINES} and
-\envvar{COLUMNS} (used by default) are set, or if curses is running in
-a window (in which case default behavior would be to use the window
-size if \envvar{LINES} and \envvar{COLUMNS} are not set).
-\end{funcdesc}
-
-\begin{funcdesc}{use_default_colors}{}
-Allow use of default values for colors on terminals supporting this
-feature. Use this to support transparency in your
-application. The default color is assigned to the color number -1.
-After calling this function,
-\code{init_pair(x, curses.COLOR_RED, -1)} initializes, for instance,
-color pair \var{x} to a red foreground color on the default background.
-\end{funcdesc}
-
-\subsection{Window Objects \label{curses-window-objects}}
-
-Window objects, as returned by \function{initscr()} and
-\function{newwin()} above, have the
-following methods:
-
-\begin{methoddesc}[window]{addch}{\optional{y, x,} ch\optional{, attr}}
-\note{A \emph{character} means a C character (an
-\ASCII{} code), rather then a Python character (a string of length 1).
-(This note is true whenever the documentation mentions a character.)
-The builtin \function{ord()} is handy for conveying strings to codes.}
-
-Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, overwriting any character previously painter at that
-location. By default, the character position and attributes are the
-current settings for the window object.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{addnstr}{\optional{y, x,} str, n\optional{, attr}}
-Paint at most \var{n} characters of the
-string \var{str} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, overwriting anything previously on the display.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{addstr}{\optional{y, x,} str\optional{, attr}}
-Paint the string \var{str} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, overwriting anything previously on the display.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{attroff}{attr}
-Remove attribute \var{attr} from the ``background'' set applied to all
-writes to the current window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{attron}{attr}
-Add attribute \var{attr} from the ``background'' set applied to all
-writes to the current window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{attrset}{attr}
-Set the ``background'' set of attributes to \var{attr}. This set is
-initially 0 (no attributes).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{bkgd}{ch\optional{, attr}}
-Sets the background property of the window to the character \var{ch},
-with attributes \var{attr}. The change is then applied to every
-character position in that window:
-\begin{itemize}
-\item
-The attribute of every character in the window is
-changed to the new background attribute.
-\item
-Wherever the former background character appears,
-it is changed to the new background character.
-\end{itemize}
-
-\end{methoddesc}
-
-\begin{methoddesc}[window]{bkgdset}{ch\optional{, attr}}
-Sets the window's background. A window's background consists of a
-character and any combination of attributes. The attribute part of
-the background is combined (OR'ed) with all non-blank characters that
-are written into the window. Both the character and attribute parts
-of the background are combined with the blank characters. The
-background becomes a property of the character and moves with the
-character through any scrolling and insert/delete line/character
-operations.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{border}{\optional{ls\optional{, rs\optional{,
- ts\optional{, bs\optional{, tl\optional{,
- tr\optional{, bl\optional{, br}}}}}}}}}
-Draw a border around the edges of the window. Each parameter specifies
-the character to use for a specific part of the border; see the table
-below for more details. The characters can be specified as integers
-or as one-character strings.
-
-\note{A \code{0} value for any parameter will cause the
-default character to be used for that parameter. Keyword parameters
-can \emph{not} be used. The defaults are listed in this table:}
-
-\begin{tableiii}{l|l|l}{var}{Parameter}{Description}{Default value}
- \lineiii{ls}{Left side}{\constant{ACS_VLINE}}
- \lineiii{rs}{Right side}{\constant{ACS_VLINE}}
- \lineiii{ts}{Top}{\constant{ACS_HLINE}}
- \lineiii{bs}{Bottom}{\constant{ACS_HLINE}}
- \lineiii{tl}{Upper-left corner}{\constant{ACS_ULCORNER}}
- \lineiii{tr}{Upper-right corner}{\constant{ACS_URCORNER}}
- \lineiii{bl}{Bottom-left corner}{\constant{ACS_LLCORNER}}
- \lineiii{br}{Bottom-right corner}{\constant{ACS_LRCORNER}}
-\end{tableiii}
-\end{methoddesc}
-
-\begin{methoddesc}[window]{box}{\optional{vertch, horch}}
-Similar to \method{border()}, but both \var{ls} and \var{rs} are
-\var{vertch} and both \var{ts} and {bs} are \var{horch}. The default
-corner characters are always used by this function.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{chgat}{\optional{y, x, } \optional{num,} attr}
-Sets the attributes of \var{num} characters at the current cursor
-position, or at position \code{(\var{y}, \var{x})} if supplied. If no
-value of \var{num} is given or \var{num} = -1, the attribute will
-be set on all the characters to the end of the line.
-This function does not move the cursor. The changed line
-will be touched using the \method{touchline} method so that the
-contents will be redisplayed by the next window refresh.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clear}{}
-Like \method{erase()}, but also causes the whole window to be repainted
-upon next call to \method{refresh()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clearok}{yes}
-If \var{yes} is 1, the next call to \method{refresh()}
-will clear the window completely.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clrtobot}{}
-Erase from cursor to the end of the window: all lines below the cursor
-are deleted, and then the equivalent of \method{clrtoeol()} is performed.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{clrtoeol}{}
-Erase from cursor to the end of the line.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{cursyncup}{}
-Updates the current cursor position of all the ancestors of the window
-to reflect the current cursor position of the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{delch}{\optional{y, x}}
-Delete any character at \code{(\var{y}, \var{x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{deleteln}{}
-Delete the line under the cursor. All following lines are moved up
-by 1 line.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{derwin}{\optional{nlines, ncols,} begin_y, begin_x}
-An abbreviation for ``derive window'', \method{derwin()} is the same
-as calling \method{subwin()}, except that \var{begin_y} and
-\var{begin_x} are relative to the origin of the window, rather than
-relative to the entire screen. Returns a window object for the
-derived window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{echochar}{ch\optional{, attr}}
-Add character \var{ch} with attribute \var{attr}, and immediately
-call \method{refresh()} on the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{enclose}{y, x}
-Tests whether the given pair of screen-relative character-cell
-coordinates are enclosed by the given window, returning true or
-false. It is useful for determining what subset of the screen
-windows enclose the location of a mouse event.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{erase}{}
-Clear the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getbegyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left
-corner.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getch}{\optional{y, x}}
-Get a character. Note that the integer returned does \emph{not} have to
-be in \ASCII{} range: function keys, keypad keys and so on return numbers
-higher than 256. In no-delay mode, -1 is returned if there is
-no input.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getkey}{\optional{y, x}}
-Get a character, returning a string instead of an integer, as
-\method{getch()} does. Function keys, keypad keys and so on return a
-multibyte string containing the key name. In no-delay mode, an
-exception is raised if there is no input.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getmaxyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of the height and width of
-the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getparyx}{}
-Returns the beginning coordinates of this window relative to its
-parent window into two integer variables y and x. Returns
-\code{-1,-1} if this window has no parent.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getstr}{\optional{y, x}}
-Read a string from the user, with primitive line editing capacity.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{getyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of current cursor position
-relative to the window's upper-left corner.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{hline}{\optional{y, x,} ch, n}
-Display a horizontal line starting at \code{(\var{y}, \var{x})} with
-length \var{n} consisting of the character \var{ch}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{idcok}{flag}
-If \var{flag} is false, curses no longer considers using the hardware
-insert/delete character feature of the terminal; if \var{flag} is
-true, use of character insertion and deletion is enabled. When curses
-is first initialized, use of character insert/delete is enabled by
-default.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{idlok}{yes}
-If called with \var{yes} equal to 1, \module{curses} will try and use
-hardware line editing facilities. Otherwise, line insertion/deletion
-are disabled.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{immedok}{flag}
-If \var{flag} is true, any change in the window image
-automatically causes the window to be refreshed; you no longer
-have to call \method{refresh()} yourself. However, it may
-degrade performance considerably, due to repeated calls to
-wrefresh. This option is disabled by default.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{inch}{\optional{y, x}}
-Return the character at the given position in the window. The bottom
-8 bits are the character proper, and upper bits are the attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insch}{\optional{y, x,} ch\optional{, attr}}
-Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
-\var{attr}, moving the line from position \var{x} right by one
-character.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insdelln}{nlines}
-Inserts \var{nlines} lines into the specified window above the current
-line. The \var{nlines} bottom lines are lost. For negative
-\var{nlines}, delete \var{nlines} lines starting with the one under
-the cursor, and move the remaining lines up. The bottom \var{nlines}
-lines are cleared. The current cursor position remains the same.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insertln}{}
-Insert a blank line under the cursor. All following lines are moved
-down by 1 line.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insnstr}{\optional{y, x,} str, n \optional{, attr}}
-Insert a character string (as many characters as will fit on the line)
-before the character under the cursor, up to \var{n} characters.
-If \var{n} is zero or negative,
-the entire string is inserted.
-All characters to the right of
-the cursor are shifted right, with the rightmost characters on the
-line being lost. The cursor position does not change (after moving to
-\var{y}, \var{x}, if specified).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{insstr}{\optional{y, x, } str \optional{, attr}}
-Insert a character string (as many characters as will fit on the line)
-before the character under the cursor. All characters to the right of
-the cursor are shifted right, with the rightmost characters on the
-line being lost. The cursor position does not change (after moving to
-\var{y}, \var{x}, if specified).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{instr}{\optional{y, x} \optional{, n}}
-Returns a string of characters, extracted from the window starting at
-the current cursor position, or at \var{y}, \var{x} if specified.
-Attributes are stripped from the characters. If \var{n} is specified,
-\method{instr()} returns return a string at most \var{n} characters
-long (exclusive of the trailing NUL).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{is_linetouched}{\var{line}}
-Returns true if the specified line was modified since the last call to
-\method{refresh()}; otherwise returns false. Raises a
-\exception{curses.error} exception if \var{line} is not valid
-for the given window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{is_wintouched}{}
-Returns true if the specified window was modified since the last call to
-\method{refresh()}; otherwise returns false.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{keypad}{yes}
-If \var{yes} is 1, escape sequences generated by some keys (keypad,
-function keys) will be interpreted by \module{curses}.
-If \var{yes} is 0, escape sequences will be left as is in the input
-stream.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{leaveok}{yes}
-If \var{yes} is 1, cursor is left where it is on update, instead of
-being at ``cursor position.'' This reduces cursor movement where
-possible. If possible the cursor will be made invisible.
-
-If \var{yes} is 0, cursor will always be at ``cursor position'' after
-an update.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{move}{new_y, new_x}
-Move cursor to \code{(\var{new_y}, \var{new_x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{mvderwin}{y, x}
-Moves the window inside its parent window. The screen-relative
-parameters of the window are not changed. This routine is used to
-display different parts of the parent window at the same physical
-position on the screen.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{mvwin}{new_y, new_x}
-Move the window so its upper-left corner is at
-\code{(\var{new_y}, \var{new_x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{nodelay}{yes}
-If \var{yes} is \code{1}, \method{getch()} will be non-blocking.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{notimeout}{yes}
-If \var{yes} is \code{1}, escape sequences will not be timed out.
-
-If \var{yes} is \code{0}, after a few milliseconds, an escape sequence
-will not be interpreted, and will be left in the input stream as is.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{noutrefresh}{}
-Mark for refresh but wait. This function updates the data structure
-representing the desired state of the window, but does not force
-an update of the physical screen. To accomplish that, call
-\function{doupdate()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{overlay}{destwin\optional{, sminrow, smincol,
- dminrow, dmincol, dmaxrow, dmaxcol}}
-Overlay the window on top of \var{destwin}. The windows need not be
-the same size, only the overlapping region is copied. This copy is
-non-destructive, which means that the current background character
-does not overwrite the old contents of \var{destwin}.
-
-To get fine-grained control over the copied region, the second form
-of \method{overlay()} can be used. \var{sminrow} and \var{smincol} are
-the upper-left coordinates of the source window, and the other variables
-mark a rectangle in the destination window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{overwrite}{destwin\optional{, sminrow, smincol,
- dminrow, dmincol, dmaxrow, dmaxcol}}
-Overwrite the window on top of \var{destwin}. The windows need not be
-the same size, in which case only the overlapping region is
-copied. This copy is destructive, which means that the current
-background character overwrites the old contents of \var{destwin}.
-
-To get fine-grained control over the copied region, the second form
-of \method{overwrite()} can be used. \var{sminrow} and \var{smincol} are
-the upper-left coordinates of the source window, the other variables
-mark a rectangle in the destination window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{putwin}{file}
-Writes all data associated with the window into the provided file
-object. This information can be later retrieved using the
-\function{getwin()} function.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{redrawln}{beg, num}
-Indicates that the \var{num} screen lines, starting at line \var{beg},
-are corrupted and should be completely redrawn on the next
-\method{refresh()} call.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{redrawwin}{}
-Touches the entire window, causing it to be completely redrawn on the
-next \method{refresh()} call.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{refresh}{\optional{pminrow, pmincol, sminrow,
- smincol, smaxrow, smaxcol}}
-Update the display immediately (sync actual screen with previous
-drawing/deleting methods).
-
-The 6 optional arguments can only be specified when the window is a
-pad created with \function{newpad()}. The additional parameters are
-needed to indicate what part of the pad and screen are involved.
-\var{pminrow} and \var{pmincol} specify the upper left-hand corner of the
-rectangle to be displayed in the pad. \var{sminrow}, \var{smincol},
-\var{smaxrow}, and \var{smaxcol} specify the edges of the rectangle to
-be displayed on the screen. The lower right-hand corner of the
-rectangle to be displayed in the pad is calculated from the screen
-coordinates, since the rectangles must be the same size. Both
-rectangles must be entirely contained within their respective
-structures. Negative values of \var{pminrow}, \var{pmincol},
-\var{sminrow}, or \var{smincol} are treated as if they were zero.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{scroll}{\optional{lines\code{ = 1}}}
-Scroll the screen or scrolling region upward by \var{lines} lines.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{scrollok}{flag}
-Controls what happens when the cursor of a window is moved off the
-edge of the window or scrolling region, either as a result of a
-newline action on the bottom line, or typing the last character
-of the last line. If \var{flag} is false, the cursor is left
-on the bottom line. If \var{flag} is true, the window is
-scrolled up one line. Note that in order to get the physical
-scrolling effect on the terminal, it is also necessary to call
-\method{idlok()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{setscrreg}{top, bottom}
-Set the scrolling region from line \var{top} to line \var{bottom}. All
-scrolling actions will take place in this region.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{standend}{}
-Turn off the standout attribute. On some terminals this has the
-side effect of turning off all attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{standout}{}
-Turn on attribute \var{A_STANDOUT}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{subpad}{\optional{nlines, ncols,} begin_y, begin_x}
-Return a sub-window, whose upper-left corner is at
-\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
-\var{ncols}/\var{nlines}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{subwin}{\optional{nlines, ncols,} begin_y, begin_x}
-Return a sub-window, whose upper-left corner is at
-\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
-\var{ncols}/\var{nlines}.
-
-By default, the sub-window will extend from the
-specified position to the lower right corner of the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{syncdown}{}
-Touches each location in the window that has been touched in any of
-its ancestor windows. This routine is called by \method{refresh()},
-so it should almost never be necessary to call it manually.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{syncok}{flag}
-If called with \var{flag} set to true, then \method{syncup()} is
-called automatically whenever there is a change in the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{syncup}{}
-Touches all locations in ancestors of the window that have been changed in
-the window.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{timeout}{delay}
-Sets blocking or non-blocking read behavior for the window. If
-\var{delay} is negative, blocking read is used (which will wait
-indefinitely for input). If \var{delay} is zero, then non-blocking
-read is used, and -1 will be returned by \method{getch()} if no input
-is waiting. If \var{delay} is positive, then \method{getch()} will
-block for \var{delay} milliseconds, and return -1 if there is still no
-input at the end of that time.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{touchline}{start, count\optional{, changed}}
-Pretend \var{count} lines have been changed, starting with line
-\var{start}. If \var{changed} is supplied, it specifies
-whether the affected lines are marked as
-having been changed (\var{changed}=1) or unchanged (\var{changed}=0).
-\end{methoddesc}
-
-\begin{methoddesc}[window]{touchwin}{}
-Pretend the whole window has been changed, for purposes of drawing
-optimizations.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{untouchwin}{}
-Marks all lines in the window as unchanged since the last call to
-\method{refresh()}.
-\end{methoddesc}
-
-\begin{methoddesc}[window]{vline}{\optional{y, x,} ch, n}
-Display a vertical line starting at \code{(\var{y}, \var{x})} with
-length \var{n} consisting of the character \var{ch}.
-\end{methoddesc}
-
-\subsection{Constants}
-
-The \module{curses} module defines the following data members:
-
-\begin{datadesc}{ERR}
-Some curses routines that return an integer, such as
-\function{getch()}, return \constant{ERR} upon failure.
-\end{datadesc}
-
-\begin{datadesc}{OK}
-Some curses routines that return an integer, such as
-\function{napms()}, return \constant{OK} upon success.
-\end{datadesc}
-
-\begin{datadesc}{version}
-A string representing the current version of the module.
-Also available as \constant{__version__}.
-\end{datadesc}
-
-Several constants are available to specify character cell attributes:
-
-\begin{tableii}{l|l}{code}{Attribute}{Meaning}
- \lineii{A_ALTCHARSET}{Alternate character set mode.}
- \lineii{A_BLINK}{Blink mode.}
- \lineii{A_BOLD}{Bold mode.}
- \lineii{A_DIM}{Dim mode.}
- \lineii{A_NORMAL}{Normal attribute.}
- \lineii{A_STANDOUT}{Standout mode.}
- \lineii{A_UNDERLINE}{Underline mode.}
-\end{tableii}
-
-Keys are referred to by integer constants with names starting with
-\samp{KEY_}. The exact keycaps available are system dependent.
-
-% XXX this table is far too large!
-% XXX should this table be alphabetized?
-
-\begin{longtableii}{l|l}{code}{Key constant}{Key}
- \lineii{KEY_MIN}{Minimum key value}
- \lineii{KEY_BREAK}{ Break key (unreliable) }
- \lineii{KEY_DOWN}{ Down-arrow }
- \lineii{KEY_UP}{ Up-arrow }
- \lineii{KEY_LEFT}{ Left-arrow }
- \lineii{KEY_RIGHT}{ Right-arrow }
- \lineii{KEY_HOME}{ Home key (upward+left arrow) }
- \lineii{KEY_BACKSPACE}{ Backspace (unreliable) }
- \lineii{KEY_F0}{ Function keys. Up to 64 function keys are supported. }
- \lineii{KEY_F\var{n}}{ Value of function key \var{n} }
- \lineii{KEY_DL}{ Delete line }
- \lineii{KEY_IL}{ Insert line }
- \lineii{KEY_DC}{ Delete character }
- \lineii{KEY_IC}{ Insert char or enter insert mode }
- \lineii{KEY_EIC}{ Exit insert char mode }
- \lineii{KEY_CLEAR}{ Clear screen }
- \lineii{KEY_EOS}{ Clear to end of screen }
- \lineii{KEY_EOL}{ Clear to end of line }
- \lineii{KEY_SF}{ Scroll 1 line forward }
- \lineii{KEY_SR}{ Scroll 1 line backward (reverse) }
- \lineii{KEY_NPAGE}{ Next page }
- \lineii{KEY_PPAGE}{ Previous page }
- \lineii{KEY_STAB}{ Set tab }
- \lineii{KEY_CTAB}{ Clear tab }
- \lineii{KEY_CATAB}{ Clear all tabs }
- \lineii{KEY_ENTER}{ Enter or send (unreliable) }
- \lineii{KEY_SRESET}{ Soft (partial) reset (unreliable) }
- \lineii{KEY_RESET}{ Reset or hard reset (unreliable) }
- \lineii{KEY_PRINT}{ Print }
- \lineii{KEY_LL}{ Home down or bottom (lower left) }
- \lineii{KEY_A1}{ Upper left of keypad }
- \lineii{KEY_A3}{ Upper right of keypad }
- \lineii{KEY_B2}{ Center of keypad }
- \lineii{KEY_C1}{ Lower left of keypad }
- \lineii{KEY_C3}{ Lower right of keypad }
- \lineii{KEY_BTAB}{ Back tab }
- \lineii{KEY_BEG}{ Beg (beginning) }
- \lineii{KEY_CANCEL}{ Cancel }
- \lineii{KEY_CLOSE}{ Close }
- \lineii{KEY_COMMAND}{ Cmd (command) }
- \lineii{KEY_COPY}{ Copy }
- \lineii{KEY_CREATE}{ Create }
- \lineii{KEY_END}{ End }
- \lineii{KEY_EXIT}{ Exit }
- \lineii{KEY_FIND}{ Find }
- \lineii{KEY_HELP}{ Help }
- \lineii{KEY_MARK}{ Mark }
- \lineii{KEY_MESSAGE}{ Message }
- \lineii{KEY_MOVE}{ Move }
- \lineii{KEY_NEXT}{ Next }
- \lineii{KEY_OPEN}{ Open }
- \lineii{KEY_OPTIONS}{ Options }
- \lineii{KEY_PREVIOUS}{ Prev (previous) }
- \lineii{KEY_REDO}{ Redo }
- \lineii{KEY_REFERENCE}{ Ref (reference) }
- \lineii{KEY_REFRESH}{ Refresh }
- \lineii{KEY_REPLACE}{ Replace }
- \lineii{KEY_RESTART}{ Restart }
- \lineii{KEY_RESUME}{ Resume }
- \lineii{KEY_SAVE}{ Save }
- \lineii{KEY_SBEG}{ Shifted Beg (beginning) }
- \lineii{KEY_SCANCEL}{ Shifted Cancel }
- \lineii{KEY_SCOMMAND}{ Shifted Command }
- \lineii{KEY_SCOPY}{ Shifted Copy }
- \lineii{KEY_SCREATE}{ Shifted Create }
- \lineii{KEY_SDC}{ Shifted Delete char }
- \lineii{KEY_SDL}{ Shifted Delete line }
- \lineii{KEY_SELECT}{ Select }
- \lineii{KEY_SEND}{ Shifted End }
- \lineii{KEY_SEOL}{ Shifted Clear line }
- \lineii{KEY_SEXIT}{ Shifted Dxit }
- \lineii{KEY_SFIND}{ Shifted Find }
- \lineii{KEY_SHELP}{ Shifted Help }
- \lineii{KEY_SHOME}{ Shifted Home }
- \lineii{KEY_SIC}{ Shifted Input }
- \lineii{KEY_SLEFT}{ Shifted Left arrow }
- \lineii{KEY_SMESSAGE}{ Shifted Message }
- \lineii{KEY_SMOVE}{ Shifted Move }
- \lineii{KEY_SNEXT}{ Shifted Next }
- \lineii{KEY_SOPTIONS}{ Shifted Options }
- \lineii{KEY_SPREVIOUS}{ Shifted Prev }
- \lineii{KEY_SPRINT}{ Shifted Print }
- \lineii{KEY_SREDO}{ Shifted Redo }
- \lineii{KEY_SREPLACE}{ Shifted Replace }
- \lineii{KEY_SRIGHT}{ Shifted Right arrow }
- \lineii{KEY_SRSUME}{ Shifted Resume }
- \lineii{KEY_SSAVE}{ Shifted Save }
- \lineii{KEY_SSUSPEND}{ Shifted Suspend }
- \lineii{KEY_SUNDO}{ Shifted Undo }
- \lineii{KEY_SUSPEND}{ Suspend }
- \lineii{KEY_UNDO}{ Undo }
- \lineii{KEY_MOUSE}{ Mouse event has occurred }
- \lineii{KEY_RESIZE}{ Terminal resize event }
- \lineii{KEY_MAX}{Maximum key value}
-\end{longtableii}
-
-On VT100s and their software emulations, such as X terminal emulators,
-there are normally at least four function keys (\constant{KEY_F1},
-\constant{KEY_F2}, \constant{KEY_F3}, \constant{KEY_F4}) available,
-and the arrow keys mapped to \constant{KEY_UP}, \constant{KEY_DOWN},
-\constant{KEY_LEFT} and \constant{KEY_RIGHT} in the obvious way. If
-your machine has a PC keyboard, it is safe to expect arrow keys and
-twelve function keys (older PC keyboards may have only ten function
-keys); also, the following keypad mappings are standard:
-
-\begin{tableii}{l|l}{kbd}{Keycap}{Constant}
- \lineii{Insert}{KEY_IC}
- \lineii{Delete}{KEY_DC}
- \lineii{Home}{KEY_HOME}
- \lineii{End}{KEY_END}
- \lineii{Page Up}{KEY_NPAGE}
- \lineii{Page Down}{KEY_PPAGE}
-\end{tableii}
-
-The following table lists characters from the alternate character set.
-These are inherited from the VT100 terminal, and will generally be
-available on software emulations such as X terminals. When there
-is no graphic available, curses falls back on a crude printable ASCII
-approximation.
-\note{These are available only after \function{initscr()} has
-been called.}
-
-\begin{longtableii}{l|l}{code}{ACS code}{Meaning}
- \lineii{ACS_BBSS}{alternate name for upper right corner}
- \lineii{ACS_BLOCK}{solid square block}
- \lineii{ACS_BOARD}{board of squares}
- \lineii{ACS_BSBS}{alternate name for horizontal line}
- \lineii{ACS_BSSB}{alternate name for upper left corner}
- \lineii{ACS_BSSS}{alternate name for top tee}
- \lineii{ACS_BTEE}{bottom tee}
- \lineii{ACS_BULLET}{bullet}
- \lineii{ACS_CKBOARD}{checker board (stipple)}
- \lineii{ACS_DARROW}{arrow pointing down}
- \lineii{ACS_DEGREE}{degree symbol}
- \lineii{ACS_DIAMOND}{diamond}
- \lineii{ACS_GEQUAL}{greater-than-or-equal-to}
- \lineii{ACS_HLINE}{horizontal line}
- \lineii{ACS_LANTERN}{lantern symbol}
- \lineii{ACS_LARROW}{left arrow}
- \lineii{ACS_LEQUAL}{less-than-or-equal-to}
- \lineii{ACS_LLCORNER}{lower left-hand corner}
- \lineii{ACS_LRCORNER}{lower right-hand corner}
- \lineii{ACS_LTEE}{left tee}
- \lineii{ACS_NEQUAL}{not-equal sign}
- \lineii{ACS_PI}{letter pi}
- \lineii{ACS_PLMINUS}{plus-or-minus sign}
- \lineii{ACS_PLUS}{big plus sign}
- \lineii{ACS_RARROW}{right arrow}
- \lineii{ACS_RTEE}{right tee}
- \lineii{ACS_S1}{scan line 1}
- \lineii{ACS_S3}{scan line 3}
- \lineii{ACS_S7}{scan line 7}
- \lineii{ACS_S9}{scan line 9}
- \lineii{ACS_SBBS}{alternate name for lower right corner}
- \lineii{ACS_SBSB}{alternate name for vertical line}
- \lineii{ACS_SBSS}{alternate name for right tee}
- \lineii{ACS_SSBB}{alternate name for lower left corner}
- \lineii{ACS_SSBS}{alternate name for bottom tee}
- \lineii{ACS_SSSB}{alternate name for left tee}
- \lineii{ACS_SSSS}{alternate name for crossover or big plus}
- \lineii{ACS_STERLING}{pound sterling}
- \lineii{ACS_TTEE}{top tee}
- \lineii{ACS_UARROW}{up arrow}
- \lineii{ACS_ULCORNER}{upper left corner}
- \lineii{ACS_URCORNER}{upper right corner}
- \lineii{ACS_VLINE}{vertical line}
-\end{longtableii}
-
-The following table lists the predefined colors:
-
-\begin{tableii}{l|l}{code}{Constant}{Color}
- \lineii{COLOR_BLACK}{Black}
- \lineii{COLOR_BLUE}{Blue}
- \lineii{COLOR_CYAN}{Cyan (light greenish blue)}
- \lineii{COLOR_GREEN}{Green}
- \lineii{COLOR_MAGENTA}{Magenta (purplish red)}
- \lineii{COLOR_RED}{Red}
- \lineii{COLOR_WHITE}{White}
- \lineii{COLOR_YELLOW}{Yellow}
-\end{tableii}
-
-\section{\module{curses.textpad} ---
- Text input widget for curses programs}
-
-\declaremodule{standard}{curses.textpad}
-\sectionauthor{Eric Raymond}{esr@thyrsus.com}
-\moduleauthor{Eric Raymond}{esr@thyrsus.com}
-\modulesynopsis{Emacs-like input editing in a curses window.}
-\versionadded{1.6}
-
-The \module{curses.textpad} module provides a \class{Textbox} class
-that handles elementary text editing in a curses window, supporting a
-set of keybindings resembling those of Emacs (thus, also of Netscape
-Navigator, BBedit 6.x, FrameMaker, and many other programs). The
-module also provides a rectangle-drawing function useful for framing
-text boxes or for other purposes.
-
-The module \module{curses.textpad} defines the following function:
-
-\begin{funcdesc}{rectangle}{win, uly, ulx, lry, lrx}
-Draw a rectangle. The first argument must be a window object; the
-remaining arguments are coordinates relative to that window. The
-second and third arguments are the y and x coordinates of the upper
-left hand corner of the rectangle to be drawn; the fourth and fifth
-arguments are the y and x coordinates of the lower right hand corner.
-The rectangle will be drawn using VT100/IBM PC forms characters on
-terminals that make this possible (including xterm and most other
-software terminal emulators). Otherwise it will be drawn with ASCII
-dashes, vertical bars, and plus signs.
-\end{funcdesc}
-
-
-\subsection{Textbox objects \label{curses-textpad-objects}}
-
-You can instantiate a \class{Textbox} object as follows:
-
-\begin{classdesc}{Textbox}{win}
-Return a textbox widget object. The \var{win} argument should be a
-curses \class{WindowObject} in which the textbox is to be contained.
-The edit cursor of the textbox is initially located at the upper left
-hand corner of the containing window, with coordinates \code{(0, 0)}.
-The instance's \member{stripspaces} flag is initially on.
-\end{classdesc}
-
-\class{Textbox} objects have the following methods:
-
-\begin{methoddesc}{edit}{\optional{validator}}
-This is the entry point you will normally use. It accepts editing
-keystrokes until one of the termination keystrokes is entered. If
-\var{validator} is supplied, it must be a function. It will be called
-for each keystroke entered with the keystroke as a parameter; command
-dispatch is done on the result. This method returns the window
-contents as a string; whether blanks in the window are included is
-affected by the \member{stripspaces} member.
-\end{methoddesc}
-
-\begin{methoddesc}{do_command}{ch}
-Process a single command keystroke. Here are the supported special
-keystrokes:
-
-\begin{tableii}{l|l}{kbd}{Keystroke}{Action}
- \lineii{Control-A}{Go to left edge of window.}
- \lineii{Control-B}{Cursor left, wrapping to previous line if appropriate.}
- \lineii{Control-D}{Delete character under cursor.}
- \lineii{Control-E}{Go to right edge (stripspaces off) or end of line
- (stripspaces on).}
- \lineii{Control-F}{Cursor right, wrapping to next line when appropriate.}
- \lineii{Control-G}{Terminate, returning the window contents.}
- \lineii{Control-H}{Delete character backward.}
- \lineii{Control-J}{Terminate if the window is 1 line, otherwise
- insert newline.}
- \lineii{Control-K}{If line is blank, delete it, otherwise clear to
- end of line.}
- \lineii{Control-L}{Refresh screen.}
- \lineii{Control-N}{Cursor down; move down one line.}
- \lineii{Control-O}{Insert a blank line at cursor location.}
- \lineii{Control-P}{Cursor up; move up one line.}
-\end{tableii}
-
-Move operations do nothing if the cursor is at an edge where the
-movement is not possible. The following synonyms are supported where
-possible:
-
-\begin{tableii}{l|l}{constant}{Constant}{Keystroke}
- \lineii{KEY_LEFT}{\kbd{Control-B}}
- \lineii{KEY_RIGHT}{\kbd{Control-F}}
- \lineii{KEY_UP}{\kbd{Control-P}}
- \lineii{KEY_DOWN}{\kbd{Control-N}}
- \lineii{KEY_BACKSPACE}{\kbd{Control-h}}
-\end{tableii}
-
-All other keystrokes are treated as a command to insert the given
-character and move right (with line wrapping).
-\end{methoddesc}
-
-\begin{methoddesc}{gather}{}
-This method returns the window contents as a string; whether blanks in
-the window are included is affected by the \member{stripspaces}
-member.
-\end{methoddesc}
-
-\begin{memberdesc}{stripspaces}
-This data member is a flag which controls the interpretation of blanks in
-the window. When it is on, trailing blanks on each line are ignored;
-any cursor motion that would land the cursor on a trailing blank goes
-to the end of that line instead, and trailing blanks are stripped when
-the window contents are gathered.
-\end{memberdesc}
-
-
-\section{\module{curses.wrapper} ---
- Terminal handler for curses programs}
-
-\declaremodule{standard}{curses.wrapper}
-\sectionauthor{Eric Raymond}{esr@thyrsus.com}
-\moduleauthor{Eric Raymond}{esr@thyrsus.com}
-\modulesynopsis{Terminal configuration wrapper for curses programs.}
-\versionadded{1.6}
-
-This module supplies one function, \function{wrapper()}, which runs
-another function which should be the rest of your curses-using
-application. If the application raises an exception,
-\function{wrapper()} will restore the terminal to a sane state before
-re-raising the exception and generating a traceback.
-
-\begin{funcdesc}{wrapper}{func, \moreargs}
-Wrapper function that initializes curses and calls another function,
-\var{func}, restoring normal keyboard/screen behavior on error.
-The callable object \var{func} is then passed the main window 'stdscr'
-as its first argument, followed by any other arguments passed to
-\function{wrapper()}.
-\end{funcdesc}
-
-Before calling the hook function, \function{wrapper()} turns on cbreak
-mode, turns off echo, enables the terminal keypad, and initializes
-colors if the terminal has color support. On exit (whether normally
-or by exception) it restores cooked mode, turns on echo, and disables
-the terminal keypad.
-
diff --git a/Doc/lib/libcursespanel.tex b/Doc/lib/libcursespanel.tex
deleted file mode 100644
index 14d83e3..0000000
--- a/Doc/lib/libcursespanel.tex
+++ /dev/null
@@ -1,96 +0,0 @@
-\section{\module{curses.panel} ---
- A panel stack extension for curses.}
-
-\declaremodule{standard}{curses.panel}
-\sectionauthor{A.M. Kuchling}{amk@amk.ca}
-\modulesynopsis{A panel stack extension that adds depth to
- curses windows.}
-
-Panels are windows with the added feature of depth, so they can be
-stacked on top of each other, and only the visible portions of
-each window will be displayed. Panels can be added, moved up
-or down in the stack, and removed.
-
-\subsection{Functions \label{cursespanel-functions}}
-
-The module \module{curses.panel} defines the following functions:
-
-
-\begin{funcdesc}{bottom_panel}{}
-Returns the bottom panel in the panel stack.
-\end{funcdesc}
-
-\begin{funcdesc}{new_panel}{win}
-Returns a panel object, associating it with the given window \var{win}.
-Be aware that you need to keep the returned panel object referenced
-explicitly. If you don't, the panel object is garbage collected and
-removed from the panel stack.
-\end{funcdesc}
-
-\begin{funcdesc}{top_panel}{}
-Returns the top panel in the panel stack.
-\end{funcdesc}
-
-\begin{funcdesc}{update_panels}{}
-Updates the virtual screen after changes in the panel stack. This does
-not call \function{curses.doupdate()}, so you'll have to do this yourself.
-\end{funcdesc}
-
-\subsection{Panel Objects \label{curses-panel-objects}}
-
-Panel objects, as returned by \function{new_panel()} above, are windows
-with a stacking order. There's always a window associated with a
-panel which determines the content, while the panel methods are
-responsible for the window's depth in the panel stack.
-
-Panel objects have the following methods:
-
-\begin{methoddesc}[Panel]{above}{}
-Returns the panel above the current panel.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{below}{}
-Returns the panel below the current panel.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{bottom}{}
-Push the panel to the bottom of the stack.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{hidden}{}
-Returns true if the panel is hidden (not visible), false otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{hide}{}
-Hide the panel. This does not delete the object, it just makes the
-window on screen invisible.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{move}{y, x}
-Move the panel to the screen coordinates \code{(\var{y}, \var{x})}.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{replace}{win}
-Change the window associated with the panel to the window \var{win}.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{set_userptr}{obj}
-Set the panel's user pointer to \var{obj}. This is used to associate an
-arbitrary piece of data with the panel, and can be any Python object.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{show}{}
-Display the panel (which might have been hidden).
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{top}{}
-Push panel to the top of the stack.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{userptr}{}
-Returns the user pointer for the panel. This might be any Python object.
-\end{methoddesc}
-
-\begin{methoddesc}[Panel]{window}{}
-Returns the window object associated with the panel.
-\end{methoddesc}
diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex
deleted file mode 100644
index fb13ea7..0000000
--- a/Doc/lib/libdatetime.tex
+++ /dev/null
@@ -1,1441 +0,0 @@
-% XXX what order should the types be discussed in?
-
-\section{\module{datetime} ---
- Basic date and time types}
-
-\declaremodule{builtin}{datetime}
-\modulesynopsis{Basic date and time types.}
-\moduleauthor{Tim Peters}{tim@zope.com}
-\sectionauthor{Tim Peters}{tim@zope.com}
-\sectionauthor{A.M. Kuchling}{amk@amk.ca}
-
-\versionadded{2.3}
-
-
-The \module{datetime} module supplies classes for manipulating dates
-and times in both simple and complex ways. While date and time
-arithmetic is supported, the focus of the implementation is on
-efficient member extraction for output formatting and manipulation.
-
-There are two kinds of date and time objects: ``naive'' and ``aware''.
-This distinction refers to whether the object has any notion of time
-zone, daylight saving time, or other kind of algorithmic or political
-time adjustment. Whether a naive \class{datetime} object represents
-Coordinated Universal Time (UTC), local time, or time in some other
-timezone is purely up to the program, just like it's up to the program
-whether a particular number represents metres, miles, or mass. Naive
-\class{datetime} objects are easy to understand and to work with, at
-the cost of ignoring some aspects of reality.
-
-For applications requiring more, \class{datetime} and \class{time}
-objects have an optional time zone information member,
-\member{tzinfo}, that can contain an instance of a subclass of
-the abstract \class{tzinfo} class. These \class{tzinfo} objects
-capture information about the offset from UTC time, the time zone
-name, and whether Daylight Saving Time is in effect. Note that no
-concrete \class{tzinfo} classes are supplied by the \module{datetime}
-module. Supporting timezones at whatever level of detail is required
-is up to the application. The rules for time adjustment across the
-world are more political than rational, and there is no standard
-suitable for every application.
-
-The \module{datetime} module exports the following constants:
-
-\begin{datadesc}{MINYEAR}
- The smallest year number allowed in a \class{date} or
- \class{datetime} object. \constant{MINYEAR}
- is \code{1}.
-\end{datadesc}
-
-\begin{datadesc}{MAXYEAR}
- The largest year number allowed in a \class{date} or \class{datetime}
- object. \constant{MAXYEAR} is \code{9999}.
-\end{datadesc}
-
-\begin{seealso}
- \seemodule{calendar}{General calendar related functions.}
- \seemodule{time}{Time access and conversions.}
-\end{seealso}
-
-\subsection{Available Types}
-
-\begin{classdesc*}{date}
- An idealized naive date, assuming the current Gregorian calendar
- always was, and always will be, in effect.
- Attributes: \member{year}, \member{month}, and \member{day}.
-\end{classdesc*}
-
-\begin{classdesc*}{time}
- An idealized time, independent of any particular day, assuming
- that every day has exactly 24*60*60 seconds (there is no notion
- of "leap seconds" here).
- Attributes: \member{hour}, \member{minute}, \member{second},
- \member{microsecond}, and \member{tzinfo}.
-\end{classdesc*}
-
-\begin{classdesc*}{datetime}
- A combination of a date and a time.
- Attributes: \member{year}, \member{month}, \member{day},
- \member{hour}, \member{minute}, \member{second},
- \member{microsecond}, and \member{tzinfo}.
-\end{classdesc*}
-
-\begin{classdesc*}{timedelta}
- A duration expressing the difference between two \class{date},
- \class{time}, or \class{datetime} instances to microsecond
- resolution.
-\end{classdesc*}
-
-\begin{classdesc*}{tzinfo}
- An abstract base class for time zone information objects. These
- are used by the \class{datetime} and \class{time} classes to
- provide a customizable notion of time adjustment (for example, to
- account for time zone and/or daylight saving time).
-\end{classdesc*}
-
-Objects of these types are immutable.
-
-Objects of the \class{date} type are always naive.
-
-An object \var{d} of type \class{time} or \class{datetime} may be
-naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not
-\code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return
-\code{None}. If \code{\var{d}.tzinfo} is \code{None}, or if
-\code{\var{d}.tzinfo} is not \code{None} but
-\code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d}
-is naive.
-
-The distinction between naive and aware doesn't apply to
-\class{timedelta} objects.
-
-Subclass relationships:
-
-\begin{verbatim}
-object
- timedelta
- tzinfo
- time
- date
- datetime
-\end{verbatim}
-
-\subsection{\class{timedelta} Objects \label{datetime-timedelta}}
-
-A \class{timedelta} object represents a duration, the difference
-between two dates or times.
-
-\begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{,
- microseconds\optional{, milliseconds\optional{,
- minutes\optional{, hours\optional{, weeks}}}}}}}}
- All arguments are optional and default to \code{0}. Arguments may
- be ints, longs, or floats, and may be positive or negative.
-
- Only \var{days}, \var{seconds} and \var{microseconds} are stored
- internally. Arguments are converted to those units:
-
-\begin{itemize}
- \item A millisecond is converted to 1000 microseconds.
- \item A minute is converted to 60 seconds.
- \item An hour is converted to 3600 seconds.
- \item A week is converted to 7 days.
-\end{itemize}
-
- and days, seconds and microseconds are then normalized so that the
- representation is unique, with
-
-\begin{itemize}
- \item \code{0 <= \var{microseconds} < 1000000}
- \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day)
- \item \code{-999999999 <= \var{days} <= 999999999}
-\end{itemize}
-
- If any argument is a float and there are fractional microseconds,
- the fractional microseconds left over from all arguments are combined
- and their sum is rounded to the nearest microsecond. If no
- argument is a float, the conversion and normalization processes
- are exact (no information is lost).
-
- If the normalized value of days lies outside the indicated range,
- \exception{OverflowError} is raised.
-
- Note that normalization of negative values may be surprising at first.
- For example,
-
-\begin{verbatim}
->>> d = timedelta(microseconds=-1)
->>> (d.days, d.seconds, d.microseconds)
-(-1, 86399, 999999)
-\end{verbatim}
-\end{classdesc}
-
-Class attributes are:
-
-\begin{memberdesc}{min}
- The most negative \class{timedelta} object,
- \code{timedelta(-999999999)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The most positive \class{timedelta} object,
- \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59,
- microseconds=999999)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal
- \class{timedelta} objects, \code{timedelta(microseconds=1)}.
-\end{memberdesc}
-
-Note that, because of normalization, \code{timedelta.max} \textgreater
-\code{-timedelta.min}. \code{-timedelta.max} is not representable as
-a \class{timedelta} object.
-
-Instance attributes (read-only):
-
-\begin{tableii}{c|l}{code}{Attribute}{Value}
- \lineii{days}{Between -999999999 and 999999999 inclusive}
- \lineii{seconds}{Between 0 and 86399 inclusive}
- \lineii{microseconds}{Between 0 and 999999 inclusive}
-\end{tableii}
-
-Supported operations:
-
-% XXX this table is too wide!
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{\var{t1} = \var{t2} + \var{t3}}
- {Sum of \var{t2} and \var{t3}.
- Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3}
- == \var{t2} are true.
- (1)}
- \lineii{\var{t1} = \var{t2} - \var{t3}}
- {Difference of \var{t2} and \var{t3}.
- Afterwards \var{t1} == \var{t2} - \var{t3} and
- \var{t2} == \var{t1} + \var{t3} are true.
- (1)}
- \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}}
- {Delta multiplied by an integer or long.
- Afterwards \var{t1} // i == \var{t2} is true,
- provided \code{i != 0}.}
- \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true.
- (1)}
- \lineii{\var{t1} = \var{t2} // \var{i}}
- {The floor is computed and the remainder (if any) is thrown away.
- (3)}
- \lineii{+\var{t1}}
- {Returns a \class{timedelta} object with the same value.
- (2)}
- \lineii{-\var{t1}}
- {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds},
- -\var{t1.microseconds}), and to \var{t1}* -1.
- (1)(4)}
- \lineii{abs(\var{t})}
- {equivalent to +\var{t} when \code{t.days >= 0}, and to
- -\var{t} when \code{t.days < 0}.
- (2)}
-\end{tableii}
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)]
- This is exact, but may overflow.
-
-\item[(2)]
- This is exact, and cannot overflow.
-
-\item[(3)]
- Division by 0 raises \exception{ZeroDivisionError}.
-
-\item[(4)]
- -\var{timedelta.max} is not representable as a \class{timedelta} object.
-\end{description}
-
-In addition to the operations listed above \class{timedelta} objects
-support certain additions and subtractions with \class{date} and
-\class{datetime} objects (see below).
-
-Comparisons of \class{timedelta} objects are supported with the
-\class{timedelta} object representing the smaller duration considered
-to be the smaller timedelta.
-In order to stop mixed-type comparisons from falling back to the
-default comparison by object address, when a \class{timedelta} object is
-compared to an object of a different type, \exception{TypeError} is
-raised unless the comparison is \code{==} or \code{!=}. The latter
-cases return \constant{False} or \constant{True}, respectively.
-
-\class{timedelta} objects are hashable (usable as dictionary keys),
-support efficient pickling, and in Boolean contexts, a \class{timedelta}
-object is considered to be true if and only if it isn't equal to
-\code{timedelta(0)}.
-
-
-\subsection{\class{date} Objects \label{datetime-date}}
-
-A \class{date} object represents a date (year, month and day) in an idealized
-calendar, the current Gregorian calendar indefinitely extended in both
-directions. January 1 of year 1 is called day number 1, January 2 of year
-1 is called day number 2, and so on. This matches the definition of the
-"proleptic Gregorian" calendar in Dershowitz and Reingold's book
-\citetitle{Calendrical Calculations}, where it's the base calendar for all
-computations. See the book for algorithms for converting between
-proleptic Gregorian ordinals and many other calendar systems.
-
-\begin{classdesc}{date}{year, month, day}
- All arguments are required. Arguments may be ints or longs, in the
- following ranges:
-
- \begin{itemize}
- \item \code{MINYEAR <= \var{year} <= MAXYEAR}
- \item \code{1 <= \var{month} <= 12}
- \item \code{1 <= \var{day} <= number of days in the given month and year}
- \end{itemize}
-
- If an argument outside those ranges is given, \exception{ValueError}
- is raised.
-\end{classdesc}
-
-Other constructors, all class methods:
-
-\begin{methoddesc}{today}{}
- Return the current local date. This is equivalent to
- \code{date.fromtimestamp(time.time())}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromtimestamp}{timestamp}
- Return the local date corresponding to the POSIX timestamp, such
- as is returned by \function{time.time()}. This may raise
- \exception{ValueError}, if the timestamp is out of the range of
- values supported by the platform C \cfunction{localtime()}
- function. It's common for this to be restricted to years from 1970
- through 2038. Note that on non-POSIX systems that include leap
- seconds in their notion of a timestamp, leap seconds are ignored by
- \method{fromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromordinal}{ordinal}
- Return the date corresponding to the proleptic Gregorian ordinal,
- where January 1 of year 1 has ordinal 1. \exception{ValueError} is
- raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}.
- For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) ==
- \var{d}}.
-\end{methoddesc}
-
-Class attributes:
-
-\begin{memberdesc}{min}
- The earliest representable date, \code{date(MINYEAR, 1, 1)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The latest representable date, \code{date(MAXYEAR, 12, 31)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal date
- objects, \code{timedelta(days=1)}.
-\end{memberdesc}
-
-Instance attributes (read-only):
-
-\begin{memberdesc}{year}
- Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{month}
- Between 1 and 12 inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{day}
- Between 1 and the number of days in the given month of the given
- year.
-\end{memberdesc}
-
-Supported operations:
-
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{\var{date2} = \var{date1} + \var{timedelta}}
- {\var{date2} is \code{\var{timedelta}.days} days removed from
- \var{date1}. (1)}
-
-
- \lineii{\var{date2} = \var{date1} - \var{timedelta}}
- {Computes \var{date2} such that \code{\var{date2} + \var{timedelta}
- == \var{date1}}. (2)}
-
- \lineii{\var{timedelta} = \var{date1} - \var{date2}}
- {(3)}
-
- \lineii{\var{date1} < \var{date2}}
- {\var{date1} is considered less than \var{date2} when \var{date1}
- precedes \var{date2} in time. (4)}
-
-\end{tableii}
-
-Notes:
-\begin{description}
-
-\item[(1)]
- \var{date2} is moved forward in time if \code{\var{timedelta}.days
- > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward
- \code{\var{date2} - \var{date1} == \var{timedelta}.days}.
- \code{\var{timedelta}.seconds} and
- \code{\var{timedelta}.microseconds} are ignored.
- \exception{OverflowError} is raised if \code{\var{date2}.year}
- would be smaller than \constant{MINYEAR} or larger than
- \constant{MAXYEAR}.
-
-\item[(2)]
- This isn't quite equivalent to date1 +
- (-timedelta), because -timedelta in isolation can overflow in cases
- where date1 - timedelta does not. \code{\var{timedelta}.seconds}
- and \code{\var{timedelta}.microseconds} are ignored.
-
-\item[(3)]
-This is exact, and cannot overflow. timedelta.seconds and
- timedelta.microseconds are 0, and date2 + timedelta == date1
- after.
-
-\item[(4)]
-In other words, \code{date1 < date2}
- if and only if \code{\var{date1}.toordinal() <
- \var{date2}.toordinal()}.
-In order to stop comparison from falling back to the default
-scheme of comparing object addresses, date comparison
-normally raises \exception{TypeError} if the other comparand
-isn't also a \class{date} object. However, \code{NotImplemented}
-is returned instead if the other comparand has a
-\method{timetuple} attribute. This hook gives other kinds of
-date objects a chance at implementing mixed-type comparison.
-If not, when a \class{date} object is
-compared to an object of a different type, \exception{TypeError} is
-raised unless the comparison is \code{==} or \code{!=}. The latter
-cases return \constant{False} or \constant{True}, respectively.
-
-\end{description}
-
-
-Dates can be used as dictionary keys. In Boolean contexts, all
-\class{date} objects are considered to be true.
-
-Instance methods:
-
-\begin{methoddesc}{replace}{year, month, day}
- Return a date with the same value, except for those members given
- new values by whichever keyword arguments are specified. For
- example, if \code{d == date(2002, 12, 31)}, then
- \code{d.replace(day=26) == date(2002, 12, 26)}.
-\end{methoddesc}
-
-\begin{methoddesc}{timetuple}{}
- Return a \class{time.struct_time} such as returned by
- \function{time.localtime()}. The hours, minutes and seconds are
- 0, and the DST flag is -1.
- \code{\var{d}.timetuple()} is equivalent to
- \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
- 0, 0, 0,
- \var{d}.weekday(),
- \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
- -1))}
-\end{methoddesc}
-
-\begin{methoddesc}{toordinal}{}
- Return the proleptic Gregorian ordinal of the date, where January 1
- of year 1 has ordinal 1. For any \class{date} object \var{d},
- \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}.
-\end{methoddesc}
-
-\begin{methoddesc}{weekday}{}
- Return the day of the week as an integer, where Monday is 0 and
- Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a
- Wednesday.
- See also \method{isoweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoweekday}{}
- Return the day of the week as an integer, where Monday is 1 and
- Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a
- Wednesday.
- See also \method{weekday()}, \method{isocalendar()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isocalendar}{}
- Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
-
- The ISO calendar is a widely used variant of the Gregorian calendar.
- See \url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm}
- for a good explanation.
-
- The ISO year consists of 52 or 53 full weeks, and where a week starts
- on a Monday and ends on a Sunday. The first week of an ISO year is
- the first (Gregorian) calendar week of a year containing a Thursday.
- This is called week number 1, and the ISO year of that Thursday is
- the same as its Gregorian year.
-
- For example, 2004 begins on a Thursday, so the first week of ISO
- year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan
- 2004, so that
- \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)}
- and
- \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoformat}{}
- Return a string representing the date in ISO 8601 format,
- 'YYYY-MM-DD'. For example,
- \code{date(2002, 12, 4).isoformat() == '2002-12-04'}.
-\end{methoddesc}
-
-\begin{methoddesc}{__str__}{}
- For a date \var{d}, \code{str(\var{d})} is equivalent to
- \code{\var{d}.isoformat()}.
-\end{methoddesc}
-
-\begin{methoddesc}{ctime}{}
- Return a string representing the date, for example
- date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'.
- \code{\var{d}.ctime()} is equivalent to
- \code{time.ctime(time.mktime(\var{d}.timetuple()))}
- on platforms where the native C \cfunction{ctime()} function
- (which \function{time.ctime()} invokes, but which
- \method{date.ctime()} does not invoke) conforms to the C standard.
-\end{methoddesc}
-
-\begin{methoddesc}{strftime}{format}
- Return a string representing the date, controlled by an explicit
- format string. Format codes referring to hours, minutes or seconds
- will see 0 values.
- See section~\ref{strftime-behavior} -- \method{strftime()} behavior.
-\end{methoddesc}
-
-
-\subsection{\class{datetime} Objects \label{datetime-datetime}}
-
-A \class{datetime} object is a single object containing all the
-information from a \class{date} object and a \class{time} object. Like a
-\class{date} object, \class{datetime} assumes the current Gregorian
-calendar extended in both directions; like a time object,
-\class{datetime} assumes there are exactly 3600*24 seconds in every
-day.
-
-Constructor:
-
-\begin{classdesc}{datetime}{year, month, day\optional{,
- hour\optional{, minute\optional{,
- second\optional{, microsecond\optional{,
- tzinfo}}}}}}
- The year, month and day arguments are required. \var{tzinfo} may
- be \code{None}, or an instance of a \class{tzinfo} subclass. The
- remaining arguments may be ints or longs, in the following ranges:
-
- \begin{itemize}
- \item \code{MINYEAR <= \var{year} <= MAXYEAR}
- \item \code{1 <= \var{month} <= 12}
- \item \code{1 <= \var{day} <= number of days in the given month and year}
- \item \code{0 <= \var{hour} < 24}
- \item \code{0 <= \var{minute} < 60}
- \item \code{0 <= \var{second} < 60}
- \item \code{0 <= \var{microsecond} < 1000000}
- \end{itemize}
-
- If an argument outside those ranges is given,
- \exception{ValueError} is raised.
-\end{classdesc}
-
-Other constructors, all class methods:
-
-\begin{methoddesc}{today}{}
- Return the current local datetime, with \member{tzinfo} \code{None}.
- This is equivalent to
- \code{datetime.fromtimestamp(time.time())}.
- See also \method{now()}, \method{fromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{now}{\optional{tz}}
- Return the current local date and time. If optional argument
- \var{tz} is \code{None} or not specified, this is like
- \method{today()}, but, if possible, supplies more precision than can
- be gotten from going through a \function{time.time()} timestamp (for
- example, this may be possible on platforms supplying the C
- \cfunction{gettimeofday()} function).
-
- Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
- and the current date and time are converted to \var{tz}'s time
- zone. In this case the result is equivalent to
- \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}.
- See also \method{today()}, \method{utcnow()}.
-\end{methoddesc}
-
-\begin{methoddesc}{utcnow}{}
- Return the current UTC date and time, with \member{tzinfo} \code{None}.
- This is like \method{now()}, but returns the current UTC date and time,
- as a naive \class{datetime} object.
- See also \method{now()}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}}
- Return the local date and time corresponding to the \POSIX{}
- timestamp, such as is returned by \function{time.time()}.
- If optional argument \var{tz} is \code{None} or not specified, the
- timestamp is converted to the platform's local date and time, and
- the returned \class{datetime} object is naive.
-
- Else \var{tz} must be an instance of a class \class{tzinfo} subclass,
- and the timestamp is converted to \var{tz}'s time zone. In this case
- the result is equivalent to
- \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}.
-
- \method{fromtimestamp()} may raise \exception{ValueError}, if the
- timestamp is out of the range of values supported by the platform C
- \cfunction{localtime()} or \cfunction{gmtime()} functions. It's common
- for this to be restricted to years in 1970 through 2038.
- Note that on non-POSIX systems that include leap seconds in their
- notion of a timestamp, leap seconds are ignored by
- \method{fromtimestamp()}, and then it's possible to have two timestamps
- differing by a second that yield identical \class{datetime} objects.
- See also \method{utcfromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{utcfromtimestamp}{timestamp}
- Return the UTC \class{datetime} corresponding to the \POSIX{}
- timestamp, with \member{tzinfo} \code{None}.
- This may raise \exception{ValueError}, if the
- timestamp is out of the range of values supported by the platform
- C \cfunction{gmtime()} function. It's common for this to be
- restricted to years in 1970 through 2038.
- See also \method{fromtimestamp()}.
-\end{methoddesc}
-
-\begin{methoddesc}{fromordinal}{ordinal}
- Return the \class{datetime} corresponding to the proleptic
- Gregorian ordinal, where January 1 of year 1 has ordinal 1.
- \exception{ValueError} is raised unless \code{1 <= ordinal <=
- datetime.max.toordinal()}. The hour, minute, second and
- microsecond of the result are all 0,
- and \member{tzinfo} is \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}{combine}{date, time}
- Return a new \class{datetime} object whose date members are
- equal to the given \class{date} object's, and whose time
- and \member{tzinfo} members are equal to the given \class{time} object's.
- For any \class{datetime} object \var{d}, \code{\var{d} ==
- datetime.combine(\var{d}.date(), \var{d}.timetz())}. If date is a
- \class{datetime} object, its time and \member{tzinfo} members are
- ignored.
- \end{methoddesc}
-
-\begin{methoddesc}{strptime}{date_string, format}
- Return a \class{datetime} corresponding to \var{date_string}, parsed
- according to \var{format}. This is equivalent to
- \code{datetime(*(time.strptime(date_string,
- format)[0:6]))}. \exception{ValueError} is raised if the date_string and
- format can't be parsed by \function{time.strptime()} or if it returns a
- value which isn't a time tuple.
-
- \versionadded{2.5}
-\end{methoddesc}
-
-Class attributes:
-
-\begin{memberdesc}{min}
- The earliest representable \class{datetime},
- \code{datetime(MINYEAR, 1, 1, tzinfo=None)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The latest representable \class{datetime},
- \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal \class{datetime}
- objects, \code{timedelta(microseconds=1)}.
-\end{memberdesc}
-
-Instance attributes (read-only):
-
-\begin{memberdesc}{year}
- Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{month}
- Between 1 and 12 inclusive.
-\end{memberdesc}
-
-\begin{memberdesc}{day}
- Between 1 and the number of days in the given month of the given
- year.
-\end{memberdesc}
-
-\begin{memberdesc}{hour}
- In \code{range(24)}.
-\end{memberdesc}
-
-\begin{memberdesc}{minute}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{second}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{microsecond}
- In \code{range(1000000)}.
-\end{memberdesc}
-
-\begin{memberdesc}{tzinfo}
- The object passed as the \var{tzinfo} argument to the
- \class{datetime} constructor, or \code{None} if none was passed.
-\end{memberdesc}
-
-Supported operations:
-
-\begin{tableii}{c|l}{code}{Operation}{Result}
- \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)}
-
- \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)}
-
- \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)}
-
- \lineii{\var{datetime1} < \var{datetime2}}
- {Compares \class{datetime} to \class{datetime}.
- (4)}
-
-\end{tableii}
-
-\begin{description}
-
-\item[(1)]
-
- datetime2 is a duration of timedelta removed from datetime1, moving
- forward in time if \code{\var{timedelta}.days} > 0, or backward if
- \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member
- as the input datetime, and datetime2 - datetime1 == timedelta after.
- \exception{OverflowError} is raised if datetime2.year would be
- smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}.
- Note that no time zone adjustments are done even if the input is an
- aware object.
-
-\item[(2)]
- Computes the datetime2 such that datetime2 + timedelta == datetime1.
- As for addition, the result has the same \member{tzinfo} member
- as the input datetime, and no time zone adjustments are done even
- if the input is aware.
- This isn't quite equivalent to datetime1 + (-timedelta), because
- -timedelta in isolation can overflow in cases where
- datetime1 - timedelta does not.
-
-\item[(3)]
- Subtraction of a \class{datetime} from a
- \class{datetime} is defined only if both
- operands are naive, or if both are aware. If one is aware and the
- other is naive, \exception{TypeError} is raised.
-
- If both are naive, or both are aware and have the same \member{tzinfo}
- member, the \member{tzinfo} members are ignored, and the result is
- a \class{timedelta} object \var{t} such that
- \code{\var{datetime2} + \var{t} == \var{datetime1}}. No time zone
- adjustments are done in this case.
-
- If both are aware and have different \member{tzinfo} members,
- \code{a-b} acts as if \var{a} and \var{b} were first converted to
- naive UTC datetimes first. The result is
- \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) -
- (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())}
- except that the implementation never overflows.
-
-\item[(4)]
-
-\var{datetime1} is considered less than \var{datetime2}
-when \var{datetime1} precedes \var{datetime2} in time.
-
-If one comparand is naive and
-the other is aware, \exception{TypeError} is raised. If both
- comparands are aware, and have the same \member{tzinfo} member,
- the common \member{tzinfo} member is ignored and the base datetimes
- are compared. If both comparands are aware and have different
- \member{tzinfo} members, the comparands are first adjusted by
- subtracting their UTC offsets (obtained from \code{self.utcoffset()}).
- \note{In order to stop comparison from falling back to the default
- scheme of comparing object addresses, datetime comparison
- normally raises \exception{TypeError} if the other comparand
- isn't also a \class{datetime} object. However,
- \code{NotImplemented} is returned instead if the other comparand
- has a \method{timetuple} attribute. This hook gives other
- kinds of date objects a chance at implementing mixed-type
- comparison. If not, when a \class{datetime} object is
- compared to an object of a different type, \exception{TypeError}
- is raised unless the comparison is \code{==} or \code{!=}. The
- latter cases return \constant{False} or \constant{True},
- respectively.}
-
-\end{description}
-
-\class{datetime} objects can be used as dictionary keys. In Boolean
-contexts, all \class{datetime} objects are considered to be true.
-
-
-Instance methods:
-
-\begin{methoddesc}{date}{}
- Return \class{date} object with same year, month and day.
-\end{methoddesc}
-
-\begin{methoddesc}{time}{}
- Return \class{time} object with same hour, minute, second and microsecond.
- \member{tzinfo} is \code{None}. See also method \method{timetz()}.
-\end{methoddesc}
-
-\begin{methoddesc}{timetz}{}
- Return \class{time} object with same hour, minute, second, microsecond,
- and tzinfo members. See also method \method{time()}.
-\end{methoddesc}
-
-\begin{methoddesc}{replace}{\optional{year\optional{, month\optional{,
- day\optional{, hour\optional{, minute\optional{,
- second\optional{, microsecond\optional{,
- tzinfo}}}}}}}}}
- Return a datetime with the same members, except for those members given
- new values by whichever keyword arguments are specified. Note that
- \code{tzinfo=None} can be specified to create a naive datetime from
- an aware datetime with no conversion of date and time members.
-\end{methoddesc}
-
-\begin{methoddesc}{astimezone}{tz}
- Return a \class{datetime} object with new \member{tzinfo} member
- \var{tz}, adjusting the date and time members so the result is the
- same UTC time as \var{self}, but in \var{tz}'s local time.
-
- \var{tz} must be an instance of a \class{tzinfo} subclass, and its
- \method{utcoffset()} and \method{dst()} methods must not return
- \code{None}. \var{self} must be aware (\code{\var{self}.tzinfo} must
- not be \code{None}, and \code{\var{self}.utcoffset()} must not return
- \code{None}).
-
- If \code{\var{self}.tzinfo} is \var{tz},
- \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no
- adjustment of date or time members is performed.
- Else the result is local time in time zone \var{tz}, representing the
- same UTC time as \var{self}: after \code{\var{astz} =
- \var{dt}.astimezone(\var{tz})},
- \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same
- date and time members as \code{\var{dt} - \var{dt}.utcoffset()}.
- The discussion of class \class{tzinfo} explains the cases at Daylight
- Saving Time transition boundaries where this cannot be achieved (an issue
- only if \var{tz} models both standard and daylight time).
-
- If you merely want to attach a time zone object \var{tz} to a
- datetime \var{dt} without adjustment of date and time members,
- use \code{\var{dt}.replace(tzinfo=\var{tz})}. If
- you merely want to remove the time zone object from an aware datetime
- \var{dt} without conversion of date and time members, use
- \code{\var{dt}.replace(tzinfo=None)}.
-
- Note that the default \method{tzinfo.fromutc()} method can be overridden
- in a \class{tzinfo} subclass to affect the result returned by
- \method{astimezone()}. Ignoring error cases, \method{astimezone()}
- acts like:
-
- \begin{verbatim}
- def astimezone(self, tz):
- if self.tzinfo is tz:
- return self
- # Convert self to UTC, and attach the new time zone object.
- utc = (self - self.utcoffset()).replace(tzinfo=tz)
- # Convert from UTC to tz's local time.
- return tz.fromutc(utc)
- \end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{utcoffset}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and
- raises an exception if the latter doesn't return \code{None}, or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{dst}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.dst(\var{self})}, and
- raises an exception if the latter doesn't return \code{None}, or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{tzname}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.tzname(\var{self})},
- raises an exception if the latter doesn't return \code{None} or
- a string object,
-\end{methoddesc}
-
-\begin{methoddesc}{timetuple}{}
- Return a \class{time.struct_time} such as returned by
- \function{time.localtime()}.
- \code{\var{d}.timetuple()} is equivalent to
- \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day,
- \var{d}.hour, \var{d}.minute, \var{d}.second,
- \var{d}.weekday(),
- \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1,
- dst))}
- The \member{tm_isdst} flag of the result is set according to
- the \method{dst()} method: \member{tzinfo} is \code{None} or
- \method{dst()} returns \code{None},
- \member{tm_isdst} is set to \code{-1}; else if \method{dst()} returns
- a non-zero value, \member{tm_isdst} is set to \code{1};
- else \code{tm_isdst} is set to \code{0}.
-\end{methoddesc}
-
-\begin{methoddesc}{utctimetuple}{}
- If \class{datetime} instance \var{d} is naive, this is the same as
- \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0
- regardless of what \code{d.dst()} returns. DST is never in effect
- for a UTC time.
-
- If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting
- \code{\var{d}.utcoffset()}, and a \class{time.struct_time} for the
- normalized time is returned. \member{tm_isdst} is forced to 0.
- Note that the result's \member{tm_year} member may be
- \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was
- \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a
- year boundary.
-\end{methoddesc}
-
-\begin{methoddesc}{toordinal}{}
- Return the proleptic Gregorian ordinal of the date. The same as
- \code{self.date().toordinal()}.
-\end{methoddesc}
-
-\begin{methoddesc}{weekday}{}
- Return the day of the week as an integer, where Monday is 0 and
- Sunday is 6. The same as \code{self.date().weekday()}.
- See also \method{isoweekday()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoweekday}{}
- Return the day of the week as an integer, where Monday is 1 and
- Sunday is 7. The same as \code{self.date().isoweekday()}.
- See also \method{weekday()}, \method{isocalendar()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isocalendar}{}
- Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The
- same as \code{self.date().isocalendar()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isoformat}{\optional{sep}}
- Return a string representing the date and time in ISO 8601 format,
- YYYY-MM-DDTHH:MM:SS.mmmmmm
- or, if \member{microsecond} is 0,
- YYYY-MM-DDTHH:MM:SS
-
- If \method{utcoffset()} does not return \code{None}, a 6-character
- string is appended, giving the UTC offset in (signed) hours and
- minutes:
- YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM
- or, if \member{microsecond} is 0
- YYYY-MM-DDTHH:MM:SS+HH:MM
-
- The optional argument \var{sep} (default \code{'T'}) is a
- one-character separator, placed between the date and time portions
- of the result. For example,
-
-\begin{verbatim}
->>> from datetime import tzinfo, timedelta, datetime
->>> class TZ(tzinfo):
-... def utcoffset(self, dt): return timedelta(minutes=-399)
-...
->>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
-'2002-12-25 00:00:00-06:39'
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{__str__}{}
- For a \class{datetime} instance \var{d}, \code{str(\var{d})} is
- equivalent to \code{\var{d}.isoformat(' ')}.
-\end{methoddesc}
-
-\begin{methoddesc}{ctime}{}
- Return a string representing the date and time, for example
- \code{datetime(2002, 12, 4, 20, 30, 40).ctime() ==
- 'Wed Dec 4 20:30:40 2002'}.
- \code{d.ctime()} is equivalent to
- \code{time.ctime(time.mktime(d.timetuple()))} on platforms where
- the native C \cfunction{ctime()} function (which
- \function{time.ctime()} invokes, but which
- \method{datetime.ctime()} does not invoke) conforms to the C
- standard.
-\end{methoddesc}
-
-\begin{methoddesc}{strftime}{format}
- Return a string representing the date and time, controlled by an
- explicit format string. See section~\ref{strftime-behavior} --
- \method{strftime()} behavior.
-\end{methoddesc}
-
-
-\subsection{\class{time} Objects \label{datetime-time}}
-
-A time object represents a (local) time of day, independent of any
-particular day, and subject to adjustment via a \class{tzinfo} object.
-
-\begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{,
- microsecond\optional{, tzinfo}}}}}
- All arguments are optional. \var{tzinfo} may be \code{None}, or
- an instance of a \class{tzinfo} subclass. The remaining arguments
- may be ints or longs, in the following ranges:
-
- \begin{itemize}
- \item \code{0 <= \var{hour} < 24}
- \item \code{0 <= \var{minute} < 60}
- \item \code{0 <= \var{second} < 60}
- \item \code{0 <= \var{microsecond} < 1000000}.
- \end{itemize}
-
- If an argument outside those ranges is given,
- \exception{ValueError} is raised. All default to \code{0} except
- \var{tzinfo}, which defaults to \constant{None}.
-\end{classdesc}
-
-Class attributes:
-
-\begin{memberdesc}{min}
- The earliest representable \class{time}, \code{time(0, 0, 0, 0)}.
-\end{memberdesc}
-
-\begin{memberdesc}{max}
- The latest representable \class{time}, \code{time(23, 59, 59, 999999)}.
-\end{memberdesc}
-
-\begin{memberdesc}{resolution}
- The smallest possible difference between non-equal \class{time}
- objects, \code{timedelta(microseconds=1)}, although note that
- arithmetic on \class{time} objects is not supported.
-\end{memberdesc}
-
-Instance attributes (read-only):
-
-\begin{memberdesc}{hour}
- In \code{range(24)}.
-\end{memberdesc}
-
-\begin{memberdesc}{minute}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{second}
- In \code{range(60)}.
-\end{memberdesc}
-
-\begin{memberdesc}{microsecond}
- In \code{range(1000000)}.
-\end{memberdesc}
-
-\begin{memberdesc}{tzinfo}
- The object passed as the tzinfo argument to the \class{time}
- constructor, or \code{None} if none was passed.
-\end{memberdesc}
-
-Supported operations:
-
-\begin{itemize}
- \item
- comparison of \class{time} to \class{time},
- where \var{a} is considered less than \var{b} when \var{a} precedes
- \var{b} in time. If one comparand is naive and the other is aware,
- \exception{TypeError} is raised. If both comparands are aware, and
- have the same \member{tzinfo} member, the common \member{tzinfo}
- member is ignored and the base times are compared. If both
- comparands are aware and have different \member{tzinfo} members,
- the comparands are first adjusted by subtracting their UTC offsets
- (obtained from \code{self.utcoffset()}).
- In order to stop mixed-type comparisons from falling back to the
- default comparison by object address, when a \class{time} object is
- compared to an object of a different type, \exception{TypeError} is
- raised unless the comparison is \code{==} or \code{!=}. The latter
- cases return \constant{False} or \constant{True}, respectively.
-
- \item
- hash, use as dict key
-
- \item
- efficient pickling
-
- \item
- in Boolean contexts, a \class{time} object is considered to be
- true if and only if, after converting it to minutes and
- subtracting \method{utcoffset()} (or \code{0} if that's
- \code{None}), the result is non-zero.
-\end{itemize}
-
-Instance methods:
-
-\begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{,
- second\optional{, microsecond\optional{,
- tzinfo}}}}}}
- Return a \class{time} with the same value, except for those members given
- new values by whichever keyword arguments are specified. Note that
- \code{tzinfo=None} can be specified to create a naive \class{time} from
- an aware \class{time}, without conversion of the time members.
-\end{methoddesc}
-
-\begin{methoddesc}{isoformat}{}
- Return a string representing the time in ISO 8601 format,
- HH:MM:SS.mmmmmm
- or, if self.microsecond is 0,
- HH:MM:SS
- If \method{utcoffset()} does not return \code{None}, a 6-character
- string is appended, giving the UTC offset in (signed) hours and
- minutes:
- HH:MM:SS.mmmmmm+HH:MM
- or, if self.microsecond is 0,
- HH:MM:SS+HH:MM
-\end{methoddesc}
-
-\begin{methoddesc}{__str__}{}
- For a time \var{t}, \code{str(\var{t})} is equivalent to
- \code{\var{t}.isoformat()}.
-\end{methoddesc}
-
-\begin{methoddesc}{strftime}{format}
- Return a string representing the time, controlled by an explicit
- format string. See section~\ref{strftime-behavior} --
- \method{strftime()} behavior.
-\end{methoddesc}
-
-\begin{methoddesc}{utcoffset}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.utcoffset(None)}, and
- raises an exception if the latter doesn't return \code{None} or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{dst}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.dst(None)}, and
- raises an exception if the latter doesn't return \code{None}, or
- a \class{timedelta} object representing a whole number of minutes
- with magnitude less than one day.
-\end{methoddesc}
-
-\begin{methoddesc}{tzname}{}
- If \member{tzinfo} is \code{None}, returns \code{None}, else
- returns \code{\var{self}.tzinfo.tzname(None)}, or
- raises an exception if the latter doesn't return \code{None} or
- a string object.
-\end{methoddesc}
-
-
-\subsection{\class{tzinfo} Objects \label{datetime-tzinfo}}
-
-\class{tzinfo} is an abstract base clase, meaning that this class
-should not be instantiated directly. You need to derive a concrete
-subclass, and (at least) supply implementations of the standard
-\class{tzinfo} methods needed by the \class{datetime} methods you
-use. The \module{datetime} module does not supply any concrete
-subclasses of \class{tzinfo}.
-
-An instance of (a concrete subclass of) \class{tzinfo} can be passed
-to the constructors for \class{datetime} and \class{time} objects.
-The latter objects view their members as being in local time, and the
-\class{tzinfo} object supports methods revealing offset of local time
-from UTC, the name of the time zone, and DST offset, all relative to a
-date or time object passed to them.
-
-Special requirement for pickling: A \class{tzinfo} subclass must have an
-\method{__init__} method that can be called with no arguments, else it
-can be pickled but possibly not unpickled again. This is a technical
-requirement that may be relaxed in the future.
-
-A concrete subclass of \class{tzinfo} may need to implement the
-following methods. Exactly which methods are needed depends on the
-uses made of aware \module{datetime} objects. If in doubt, simply
-implement all of them.
-
-\begin{methoddesc}[tzinfo]{utcoffset}{self, dt}
- Return offset of local time from UTC, in minutes east of UTC. If
- local time is west of UTC, this should be negative. Note that this
- is intended to be the total offset from UTC; for example, if a
- \class{tzinfo} object represents both time zone and DST adjustments,
- \method{utcoffset()} should return their sum. If the UTC offset
- isn't known, return \code{None}. Else the value returned must be
- a \class{timedelta} object specifying a whole number of minutes in the
- range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset
- must be less than one day). Most implementations of
- \method{utcoffset()} will probably look like one of these two:
-
-\begin{verbatim}
- return CONSTANT # fixed-offset class
- return CONSTANT + self.dst(dt) # daylight-aware class
-\end{verbatim}
-
- If \method{utcoffset()} does not return \code{None},
- \method{dst()} should not return \code{None} either.
-
- The default implementation of \method{utcoffset()} raises
- \exception{NotImplementedError}.
-\end{methoddesc}
-
-\begin{methoddesc}[tzinfo]{dst}{self, dt}
- Return the daylight saving time (DST) adjustment, in minutes east of
- UTC, or \code{None} if DST information isn't known. Return
- \code{timedelta(0)} if DST is not in effect.
- If DST is in effect, return the offset as a
- \class{timedelta} object (see \method{utcoffset()} for details).
- Note that DST offset, if applicable, has
- already been added to the UTC offset returned by
- \method{utcoffset()}, so there's no need to consult \method{dst()}
- unless you're interested in obtaining DST info separately. For
- example, \method{datetime.timetuple()} calls its \member{tzinfo}
- member's \method{dst()} method to determine how the
- \member{tm_isdst} flag should be set, and
- \method{tzinfo.fromutc()} calls \method{dst()} to account for
- DST changes when crossing time zones.
-
- An instance \var{tz} of a \class{tzinfo} subclass that models both
- standard and daylight times must be consistent in this sense:
-
- \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})}
-
- must return the same result for every \class{datetime} \var{dt}
- with \code{\var{dt}.tzinfo == \var{tz}} For sane \class{tzinfo}
- subclasses, this expression yields the time zone's "standard offset",
- which should not depend on the date or the time, but only on geographic
- location. The implementation of \method{datetime.astimezone()} relies
- on this, but cannot detect violations; it's the programmer's
- responsibility to ensure it. If a \class{tzinfo} subclass cannot
- guarantee this, it may be able to override the default implementation
- of \method{tzinfo.fromutc()} to work correctly with \method{astimezone()}
- regardless.
-
- Most implementations of \method{dst()} will probably look like one
- of these two:
-
-\begin{verbatim}
- def dst(self):
- # a fixed-offset class: doesn't account for DST
- return timedelta(0)
-\end{verbatim}
-
- or
-
-\begin{verbatim}
- def dst(self):
- # Code to set dston and dstoff to the time zone's DST
- # transition times based on the input dt.year, and expressed
- # in standard local time. Then
-
- if dston <= dt.replace(tzinfo=None) < dstoff:
- return timedelta(hours=1)
- else:
- return timedelta(0)
-\end{verbatim}
-
- The default implementation of \method{dst()} raises
- \exception{NotImplementedError}.
-\end{methoddesc}
-
-\begin{methoddesc}[tzinfo]{tzname}{self, dt}
- Return the time zone name corresponding to the \class{datetime}
- object \var{dt}, as a string.
- Nothing about string names is defined by the
- \module{datetime} module, and there's no requirement that it mean
- anything in particular. For example, "GMT", "UTC", "-500", "-5:00",
- "EDT", "US/Eastern", "America/New York" are all valid replies. Return
- \code{None} if a string name isn't known. Note that this is a method
- rather than a fixed string primarily because some \class{tzinfo}
- subclasses will wish to return different names depending on the specific
- value of \var{dt} passed, especially if the \class{tzinfo} class is
- accounting for daylight time.
-
- The default implementation of \method{tzname()} raises
- \exception{NotImplementedError}.
-\end{methoddesc}
-
-These methods are called by a \class{datetime} or \class{time} object,
-in response to their methods of the same names. A \class{datetime}
-object passes itself as the argument, and a \class{time} object passes
-\code{None} as the argument. A \class{tzinfo} subclass's methods should
-therefore be prepared to accept a \var{dt} argument of \code{None}, or of
-class \class{datetime}.
-
-When \code{None} is passed, it's up to the class designer to decide the
-best response. For example, returning \code{None} is appropriate if the
-class wishes to say that time objects don't participate in the
-\class{tzinfo} protocols. It may be more useful for \code{utcoffset(None)}
-to return the standard UTC offset, as there is no other convention for
-discovering the standard offset.
-
-When a \class{datetime} object is passed in response to a
-\class{datetime} method, \code{dt.tzinfo} is the same object as
-\var{self}. \class{tzinfo} methods can rely on this, unless
-user code calls \class{tzinfo} methods directly. The intent is that
-the \class{tzinfo} methods interpret \var{dt} as being in local time,
-and not need worry about objects in other timezones.
-
-There is one more \class{tzinfo} method that a subclass may wish to
-override:
-
-\begin{methoddesc}[tzinfo]{fromutc}{self, dt}
- This is called from the default \class{datetime.astimezone()}
- implementation. When called from that, \code{\var{dt}.tzinfo} is
- \var{self}, and \var{dt}'s date and time members are to be viewed as
- expressing a UTC time. The purpose of \method{fromutc()} is to
- adjust the date and time members, returning an equivalent datetime in
- \var{self}'s local time.
-
- Most \class{tzinfo} subclasses should be able to inherit the default
- \method{fromutc()} implementation without problems. It's strong enough
- to handle fixed-offset time zones, and time zones accounting for both
- standard and daylight time, and the latter even if the DST transition
- times differ in different years. An example of a time zone the default
- \method{fromutc()} implementation may not handle correctly in all cases
- is one where the standard offset (from UTC) depends on the specific date
- and time passed, which can happen for political reasons.
- The default implementations of \method{astimezone()} and
- \method{fromutc()} may not produce the result you want if the result is
- one of the hours straddling the moment the standard offset changes.
-
- Skipping code for error cases, the default \method{fromutc()}
- implementation acts like:
-
- \begin{verbatim}
- def fromutc(self, dt):
- # raise ValueError error if dt.tzinfo is not self
- dtoff = dt.utcoffset()
- dtdst = dt.dst()
- # raise ValueError if dtoff is None or dtdst is None
- delta = dtoff - dtdst # this is self's standard offset
- if delta:
- dt += delta # convert to standard local time
- dtdst = dt.dst()
- # raise ValueError if dtdst is None
- if dtdst:
- return dt + dtdst
- else:
- return dt
- \end{verbatim}
-\end{methoddesc}
-
-Example \class{tzinfo} classes:
-
-\verbatiminput{tzinfo-examples.py}
-
-Note that there are unavoidable subtleties twice per year in a
-\class{tzinfo}
-subclass accounting for both standard and daylight time, at the DST
-transition points. For concreteness, consider US Eastern (UTC -0500),
-where EDT begins the minute after 1:59 (EST) on the first Sunday in
-April, and ends the minute after 1:59 (EDT) on the last Sunday in October:
-
-\begin{verbatim}
- UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
- EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
- EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
-
- start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
-
- end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
-\end{verbatim}
-
-When DST starts (the "start" line), the local wall clock leaps from 1:59
-to 3:00. A wall time of the form 2:MM doesn't really make sense on that
-day, so \code{astimezone(Eastern)} won't deliver a result with
-\code{hour == 2} on the
-day DST begins. In order for \method{astimezone()} to make this
-guarantee, the \method{rzinfo.dst()} method must consider times
-in the "missing hour" (2:MM for Eastern) to be in daylight time.
-
-When DST ends (the "end" line), there's a potentially worse problem:
-there's an hour that can't be spelled unambiguously in local wall time:
-the last hour of daylight time. In Eastern, that's times of
-the form 5:MM UTC on the day daylight time ends. The local wall clock
-leaps from 1:59 (daylight time) back to 1:00 (standard time) again.
-Local times of the form 1:MM are ambiguous. \method{astimezone()} mimics
-the local clock's behavior by mapping two adjacent UTC hours into the
-same local hour then. In the Eastern example, UTC times of the form
-5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for
-\method{astimezone()} to make this guarantee, the \method{tzinfo.dst()}
-method must consider times in the "repeated hour" to be in
-standard time. This is easily arranged, as in the example, by expressing
-DST switch times in the time zone's standard local time.
-
-Applications that can't bear such ambiguities should avoid using hybrid
-\class{tzinfo} subclasses; there are no ambiguities when using UTC, or
-any other fixed-offset \class{tzinfo} subclass (such as a class
-representing only EST (fixed offset -5 hours), or only EDT (fixed offset
--4 hours)).
-
-
-\subsection{\method{strftime()} Behavior\label{strftime-behavior}}
-
-\class{date}, \class{datetime}, and \class{time}
-objects all support a \code{strftime(\var{format})}
-method, to create a string representing the time under the control of
-an explicit format string. Broadly speaking,
-\code{d.strftime(fmt)}
-acts like the \refmodule{time} module's
-\code{time.strftime(fmt, d.timetuple())}
-although not all objects support a \method{timetuple()} method.
-
-For \class{time} objects, the format codes for
-year, month, and day should not be used, as time objects have no such
-values. If they're used anyway, \code{1900} is substituted for the
-year, and \code{0} for the month and day.
-
-For \class{date} objects, the format codes for hours, minutes, and
-seconds should not be used, as \class{date} objects have no such
-values. If they're used anyway, \code{0} is substituted for them.
-
-For a naive object, the \code{\%z} and \code{\%Z} format codes are
-replaced by empty strings.
-
-For an aware object:
-
-\begin{itemize}
- \item[\code{\%z}]
- \method{utcoffset()} is transformed into a 5-character string of
- the form +HHMM or -HHMM, where HH is a 2-digit string giving the
- number of UTC offset hours, and MM is a 2-digit string giving the
- number of UTC offset minutes. For example, if
- \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)},
- \code{\%z} is replaced with the string \code{'-0330'}.
-
- \item[\code{\%Z}]
- If \method{tzname()} returns \code{None}, \code{\%Z} is replaced
- by an empty string. Otherwise \code{\%Z} is replaced by the returned
- value, which must be a string.
-\end{itemize}
-
-The full set of format codes supported varies across platforms,
-because Python calls the platform C library's \function{strftime()}
-function, and platform variations are common. The documentation for
-Python's \refmodule{time} module lists the format codes that the C
-standard (1989 version) requires, and those work on all platforms
-with a standard C implementation. Note that the 1999 version of the
-C standard added additional format codes.
-
-The exact range of years for which \method{strftime()} works also
-varies across platforms. Regardless of platform, years before 1900
-cannot be used.
-
-%%% This example is obsolete, since strptime is now supported by datetime.
-%
-% \subsection{Examples}
-%
-% \subsubsection{Creating Datetime Objects from Formatted Strings}
-%
-% The \class{datetime} class does not directly support parsing formatted time
-% strings. You can use \function{time.strptime} to do the parsing and create
-% a \class{datetime} object from the tuple it returns:
-%
-% \begin{verbatim}
-% >>> s = "2005-12-06T12:13:14"
-% >>> from datetime import datetime
-% >>> from time import strptime
-% >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
-% datetime.datetime(2005, 12, 6, 12, 13, 14)
-% \end{verbatim}
-%
diff --git a/Doc/lib/libdbhash.tex b/Doc/lib/libdbhash.tex
deleted file mode 100644
index 5852b73..0000000
--- a/Doc/lib/libdbhash.tex
+++ /dev/null
@@ -1,88 +0,0 @@
-\section{\module{dbhash} ---
- DBM-style interface to the BSD database library}
-
-\declaremodule{standard}{dbhash}
-\modulesynopsis{DBM-style interface to the BSD database library.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{dbhash} module provides a function to open databases using
-the BSD \code{db} library. This module mirrors the interface of the
-other Python database modules that provide access to DBM-style
-databases. The \refmodule{bsddb}\refbimodindex{bsddb} module is required
-to use \module{dbhash}.
-
-This module provides an exception and a function:
-
-
-\begin{excdesc}{error}
- Exception raised on database errors other than
- \exception{KeyError}. It is a synonym for \exception{bsddb.error}.
-\end{excdesc}
-
-\begin{funcdesc}{open}{path\optional{, flag\optional{, mode}}}
- Open a \code{db} database and return the database object. The
- \var{path} argument is the name of the database file.
-
- The \var{flag} argument can be
- \code{'r'} (the default), \code{'w'},
- \code{'c'} (which creates the database if it doesn't exist), or
- \code{'n'} (which always creates a new empty database).
- For platforms on which the BSD \code{db} library supports locking,
- an \character{l} can be appended to indicate that locking should be
- used.
-
- The optional \var{mode} parameter is used to indicate the \UNIX{}
- permission bits that should be set if a new database must be
- created; this will be masked by the current umask value for the
- process.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{bsddb}{Lower-level interface to the BSD \code{db} library.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
-
-
-\subsection{Database Objects \label{dbhash-objects}}
-
-The database objects returned by \function{open()} provide the methods
-common to all the DBM-style databases and mapping objects. The following
-methods are available in addition to the standard methods.
-
-\begin{methoddesc}[dbhash]{first}{}
- It's possible to loop over every key/value pair in the database using
- this method and the \method{next()} method. The traversal is ordered by
- the databases internal hash values, and won't be sorted by the key
- values. This method returns the starting key.
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{last}{}
- Return the last key/value pair in a database traversal. This may be used to
- begin a reverse-order traversal; see \method{previous()}.
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{next}{}
- Returns the key next key/value pair in a database traversal. The
- following code prints every key in the database \code{db}, without
- having to create a list in memory that contains them all:
-
-\begin{verbatim}
-print db.first()
-for i in range(1, len(db)):
- print db.next()
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{previous}{}
- Returns the previous key/value pair in a forward-traversal of the database.
- In conjunction with \method{last()}, this may be used to implement
- a reverse-order traversal.
-\end{methoddesc}
-
-\begin{methoddesc}[dbhash]{sync}{}
- This method forces any unwritten data to be written to the disk.
-\end{methoddesc}
diff --git a/Doc/lib/libdbm.tex b/Doc/lib/libdbm.tex
deleted file mode 100644
index e08af99..0000000
--- a/Doc/lib/libdbm.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\section{\module{dbm} ---
- Simple ``database'' interface}
-
-\declaremodule{builtin}{dbm}
- \platform{Unix}
-\modulesynopsis{The standard ``database'' interface, based on ndbm.}
-
-
-The \module{dbm} module provides an interface to the \UNIX{}
-(\code{n})\code{dbm} library. Dbm objects behave like mappings
-(dictionaries), except that keys and values are always strings.
-Printing a dbm object doesn't print the keys and values, and the
-\method{items()} and \method{values()} methods are not supported.
-
-This module can be used with the ``classic'' ndbm interface, the BSD
-DB compatibility interface, or the GNU GDBM compatibility interface.
-On \UNIX, the \program{configure} script will attempt to locate the
-appropriate header file to simplify building this module.
-
-The module defines the following:
-
-\begin{excdesc}{error}
-Raised on dbm-specific errors, such as I/O errors.
-\exception{KeyError} is raised for general mapping errors like
-specifying an incorrect key.
-\end{excdesc}
-
-\begin{datadesc}{library}
-Name of the \code{ndbm} implementation library used.
-\end{datadesc}
-
-\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
-Open a dbm database and return a dbm object. The \var{filename}
-argument is the name of the database file (without the \file{.dir} or
-\file{.pag} extensions; note that the BSD DB implementation of the
-interface will append the extension \file{.db} and only create one
-file).
-
-The optional \var{flag} argument must be one of these values:
-
-\begin{tableii}{c|l}{code}{Value}{Meaning}
- \lineii{'r'}{Open existing database for reading only (default)}
- \lineii{'w'}{Open existing database for reading and writing}
- \lineii{'c'}{Open database for reading and writing, creating it if
- it doesn't exist}
- \lineii{'n'}{Always create a new, empty database, open for reading
- and writing}
-\end{tableii}
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex
deleted file mode 100644
index 8c665da..0000000
--- a/Doc/lib/libdecimal.tex
+++ /dev/null
@@ -1,1313 +0,0 @@
-\section{\module{decimal} ---
- Decimal floating point arithmetic}
-
-\declaremodule{standard}{decimal}
-\modulesynopsis{Implementation of the General Decimal Arithmetic
-Specification.}
-
-\moduleauthor{Eric Price}{eprice at tjhsst.edu}
-\moduleauthor{Facundo Batista}{facundo at taniquetil.com.ar}
-\moduleauthor{Raymond Hettinger}{python at rcn.com}
-\moduleauthor{Aahz}{aahz at pobox.com}
-\moduleauthor{Tim Peters}{tim.one at comcast.net}
-
-\sectionauthor{Raymond D. Hettinger}{python at rcn.com}
-
-\versionadded{2.4}
-
-The \module{decimal} module provides support for decimal floating point
-arithmetic. It offers several advantages over the \class{float()} datatype:
-
-\begin{itemize}
-
-\item Decimal numbers can be represented exactly. In contrast, numbers like
-\constant{1.1} do not have an exact representation in binary floating point.
-End users typically would not expect \constant{1.1} to display as
-\constant{1.1000000000000001} as it does with binary floating point.
-
-\item The exactness carries over into arithmetic. In decimal floating point,
-\samp{0.1 + 0.1 + 0.1 - 0.3} is exactly equal to zero. In binary floating
-point, result is \constant{5.5511151231257827e-017}. While near to zero, the
-differences prevent reliable equality testing and differences can accumulate.
-For this reason, decimal would be preferred in accounting applications which
-have strict equality invariants.
-
-\item The decimal module incorporates a notion of significant places so that
-\samp{1.30 + 1.20} is \constant{2.50}. The trailing zero is kept to indicate
-significance. This is the customary presentation for monetary applications. For
-multiplication, the ``schoolbook'' approach uses all the figures in the
-multiplicands. For instance, \samp{1.3 * 1.2} gives \constant{1.56} while
-\samp{1.30 * 1.20} gives \constant{1.5600}.
-
-\item Unlike hardware based binary floating point, the decimal module has a user
-settable precision (defaulting to 28 places) which can be as large as needed for
-a given problem:
-
-\begin{verbatim}
->>> getcontext().prec = 6
->>> Decimal(1) / Decimal(7)
-Decimal("0.142857")
->>> getcontext().prec = 28
->>> Decimal(1) / Decimal(7)
-Decimal("0.1428571428571428571428571429")
-\end{verbatim}
-
-\item Both binary and decimal floating point are implemented in terms of published
-standards. While the built-in float type exposes only a modest portion of its
-capabilities, the decimal module exposes all required parts of the standard.
-When needed, the programmer has full control over rounding and signal handling.
-
-\end{itemize}
-
-
-The module design is centered around three concepts: the decimal number, the
-context for arithmetic, and signals.
-
-A decimal number is immutable. It has a sign, coefficient digits, and an
-exponent. To preserve significance, the coefficient digits do not truncate
-trailing zeroes. Decimals also include special values such as
-\constant{Infinity}, \constant{-Infinity}, and \constant{NaN}. The standard
-also differentiates \constant{-0} from \constant{+0}.
-
-The context for arithmetic is an environment specifying precision, rounding
-rules, limits on exponents, flags indicating the results of operations,
-and trap enablers which determine whether signals are treated as
-exceptions. Rounding options include \constant{ROUND_CEILING},
-\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN},
-\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, and \constant{ROUND_UP}.
-
-Signals are groups of exceptional conditions arising during the course of
-computation. Depending on the needs of the application, signals may be
-ignored, considered as informational, or treated as exceptions. The signals in
-the decimal module are: \constant{Clamped}, \constant{InvalidOperation},
-\constant{DivisionByZero}, \constant{Inexact}, \constant{Rounded},
-\constant{Subnormal}, \constant{Overflow}, and \constant{Underflow}.
-
-For each signal there is a flag and a trap enabler. When a signal is
-encountered, its flag is incremented from zero and, then, if the trap enabler
-is set to one, an exception is raised. Flags are sticky, so the user
-needs to reset them before monitoring a calculation.
-
-
-\begin{seealso}
- \seetext{IBM's General Decimal Arithmetic Specification,
- \citetitle[http://www2.hursley.ibm.com/decimal/decarith.html]
- {The General Decimal Arithmetic Specification}.}
-
- \seetext{IEEE standard 854-1987,
- \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html]
- {Unofficial IEEE 854 Text}.}
-\end{seealso}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Quick-start Tutorial \label{decimal-tutorial}}
-
-The usual start to using decimals is importing the module, viewing the current
-context with \function{getcontext()} and, if necessary, setting new values
-for precision, rounding, or enabled traps:
-
-\begin{verbatim}
->>> from decimal import *
->>> getcontext()
-Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
- capitals=1, flags=[], traps=[Overflow, InvalidOperation,
- DivisionByZero])
-
->>> getcontext().prec = 7 # Set a new precision
-\end{verbatim}
-
-
-Decimal instances can be constructed from integers, strings, or tuples. To
-create a Decimal from a \class{float}, first convert it to a string. This
-serves as an explicit reminder of the details of the conversion (including
-representation error). Decimal numbers include special values such as
-\constant{NaN} which stands for ``Not a number'', positive and negative
-\constant{Infinity}, and \constant{-0}.
-
-\begin{verbatim}
->>> Decimal(10)
-Decimal("10")
->>> Decimal("3.14")
-Decimal("3.14")
->>> Decimal((0, (3, 1, 4), -2))
-Decimal("3.14")
->>> Decimal(str(2.0 ** 0.5))
-Decimal("1.41421356237")
->>> Decimal("NaN")
-Decimal("NaN")
->>> Decimal("-Infinity")
-Decimal("-Infinity")
-\end{verbatim}
-
-
-The significance of a new Decimal is determined solely by the number
-of digits input. Context precision and rounding only come into play during
-arithmetic operations.
-
-\begin{verbatim}
->>> getcontext().prec = 6
->>> Decimal('3.0')
-Decimal("3.0")
->>> Decimal('3.1415926535')
-Decimal("3.1415926535")
->>> Decimal('3.1415926535') + Decimal('2.7182818285')
-Decimal("5.85987")
->>> getcontext().rounding = ROUND_UP
->>> Decimal('3.1415926535') + Decimal('2.7182818285')
-Decimal("5.85988")
-\end{verbatim}
-
-
-Decimals interact well with much of the rest of Python. Here is a small
-decimal floating point flying circus:
-
-\begin{verbatim}
->>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
->>> max(data)
-Decimal("9.25")
->>> min(data)
-Decimal("0.03")
->>> sorted(data)
-[Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"),
- Decimal("2.35"), Decimal("3.45"), Decimal("9.25")]
->>> sum(data)
-Decimal("19.29")
->>> a,b,c = data[:3]
->>> str(a)
-'1.34'
->>> float(a)
-1.3400000000000001
->>> round(a, 1) # round() first converts to binary floating point
-1.3
->>> int(a)
-1
->>> a * 5
-Decimal("6.70")
->>> a * b
-Decimal("2.5058")
->>> c % a
-Decimal("0.77")
-\end{verbatim}
-
-The \method{quantize()} method rounds a number to a fixed exponent. This
-method is useful for monetary applications that often round results to a fixed
-number of places:
-
-\begin{verbatim}
->>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
-Decimal("7.32")
->>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
-Decimal("8")
-\end{verbatim}
-
-As shown above, the \function{getcontext()} function accesses the current
-context and allows the settings to be changed. This approach meets the
-needs of most applications.
-
-For more advanced work, it may be useful to create alternate contexts using
-the Context() constructor. To make an alternate active, use the
-\function{setcontext()} function.
-
-In accordance with the standard, the \module{Decimal} module provides two
-ready to use standard contexts, \constant{BasicContext} and
-\constant{ExtendedContext}. The former is especially useful for debugging
-because many of the traps are enabled:
-
-\begin{verbatim}
->>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
->>> setcontext(myothercontext)
->>> Decimal(1) / Decimal(7)
-Decimal("0.142857142857142857142857142857142857142857142857142857142857")
-
->>> ExtendedContext
-Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
- capitals=1, flags=[], traps=[])
->>> setcontext(ExtendedContext)
->>> Decimal(1) / Decimal(7)
-Decimal("0.142857143")
->>> Decimal(42) / Decimal(0)
-Decimal("Infinity")
-
->>> setcontext(BasicContext)
->>> Decimal(42) / Decimal(0)
-Traceback (most recent call last):
- File "<pyshell#143>", line 1, in -toplevel-
- Decimal(42) / Decimal(0)
-DivisionByZero: x / 0
-\end{verbatim}
-
-
-Contexts also have signal flags for monitoring exceptional conditions
-encountered during computations. The flags remain set until explicitly
-cleared, so it is best to clear the flags before each set of monitored
-computations by using the \method{clear_flags()} method.
-
-\begin{verbatim}
->>> setcontext(ExtendedContext)
->>> getcontext().clear_flags()
->>> Decimal(355) / Decimal(113)
-Decimal("3.14159292")
->>> getcontext()
-Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
- capitals=1, flags=[Inexact, Rounded], traps=[])
-\end{verbatim}
-
-The \var{flags} entry shows that the rational approximation to \constant{Pi}
-was rounded (digits beyond the context precision were thrown away) and that
-the result is inexact (some of the discarded digits were non-zero).
-
-Individual traps are set using the dictionary in the \member{traps}
-field of a context:
-
-\begin{verbatim}
->>> Decimal(1) / Decimal(0)
-Decimal("Infinity")
->>> getcontext().traps[DivisionByZero] = 1
->>> Decimal(1) / Decimal(0)
-Traceback (most recent call last):
- File "<pyshell#112>", line 1, in -toplevel-
- Decimal(1) / Decimal(0)
-DivisionByZero: x / 0
-\end{verbatim}
-
-Most programs adjust the current context only once, at the beginning of the
-program. And, in many applications, data is converted to \class{Decimal} with
-a single cast inside a loop. With context set and decimals created, the bulk
-of the program manipulates the data no differently than with other Python
-numeric types.
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Decimal objects \label{decimal-decimal}}
-
-\begin{classdesc}{Decimal}{\optional{value \optional{, context}}}
- Constructs a new \class{Decimal} object based from \var{value}.
-
- \var{value} can be an integer, string, tuple, or another \class{Decimal}
- object. If no \var{value} is given, returns \code{Decimal("0")}. If
- \var{value} is a string, it should conform to the decimal numeric string
- syntax:
-
- \begin{verbatim}
- sign ::= '+' | '-'
- digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
- indicator ::= 'e' | 'E'
- digits ::= digit [digit]...
- decimal-part ::= digits '.' [digits] | ['.'] digits
- exponent-part ::= indicator [sign] digits
- infinity ::= 'Infinity' | 'Inf'
- nan ::= 'NaN' [digits] | 'sNaN' [digits]
- numeric-value ::= decimal-part [exponent-part] | infinity
- numeric-string ::= [sign] numeric-value | [sign] nan
- \end{verbatim}
-
- If \var{value} is a \class{tuple}, it should have three components,
- a sign (\constant{0} for positive or \constant{1} for negative),
- a \class{tuple} of digits, and an integer exponent. For example,
- \samp{Decimal((0, (1, 4, 1, 4), -3))} returns \code{Decimal("1.414")}.
-
- The \var{context} precision does not affect how many digits are stored.
- That is determined exclusively by the number of digits in \var{value}. For
- example, \samp{Decimal("3.00000")} records all five zeroes even if the
- context precision is only three.
-
- The purpose of the \var{context} argument is determining what to do if
- \var{value} is a malformed string. If the context traps
- \constant{InvalidOperation}, an exception is raised; otherwise, the
- constructor returns a new Decimal with the value of \constant{NaN}.
-
- Once constructed, \class{Decimal} objects are immutable.
-\end{classdesc}
-
-Decimal floating point objects share many properties with the other builtin
-numeric types such as \class{float} and \class{int}. All of the usual
-math operations and special methods apply. Likewise, decimal objects can
-be copied, pickled, printed, used as dictionary keys, used as set elements,
-compared, sorted, and coerced to another type (such as \class{float}
-or \class{long}).
-
-In addition to the standard numeric properties, decimal floating point objects
-also have a number of specialized methods:
-
-\begin{methoddesc}{adjusted}{}
- Return the adjusted exponent after shifting out the coefficient's rightmost
- digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()}
- returns seven. Used for determining the position of the most significant
- digit with respect to the decimal point.
-\end{methoddesc}
-
-\begin{methoddesc}{as_tuple}{}
- Returns a tuple representation of the number:
- \samp{(sign, digittuple, exponent)}.
-\end{methoddesc}
-
-\begin{methoddesc}{compare}{other\optional{, context}}
- Compares like \method{__cmp__()} but returns a decimal instance:
- \begin{verbatim}
- a or b is a NaN ==> Decimal("NaN")
- a < b ==> Decimal("-1")
- a == b ==> Decimal("0")
- a > b ==> Decimal("1")
- \end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{max}{other\optional{, context}}
- Like \samp{max(self, other)} except that the context rounding rule
- is applied before returning and that \constant{NaN} values are
- either signalled or ignored (depending on the context and whether
- they are signaling or quiet).
-\end{methoddesc}
-
-\begin{methoddesc}{min}{other\optional{, context}}
- Like \samp{min(self, other)} except that the context rounding rule
- is applied before returning and that \constant{NaN} values are
- either signalled or ignored (depending on the context and whether
- they are signaling or quiet).
-\end{methoddesc}
-
-\begin{methoddesc}{normalize}{\optional{context}}
- Normalize the number by stripping the rightmost trailing zeroes and
- converting any result equal to \constant{Decimal("0")} to
- \constant{Decimal("0e0")}. Used for producing canonical values for members
- of an equivalence class. For example, \code{Decimal("32.100")} and
- \code{Decimal("0.321000e+2")} both normalize to the equivalent value
- \code{Decimal("32.1")}.
-\end{methoddesc}
-
-\begin{methoddesc}{quantize}
- {exp \optional{, rounding\optional{, context\optional{, watchexp}}}}
- Quantize makes the exponent the same as \var{exp}. Searches for a
- rounding method in \var{rounding}, then in \var{context}, and then
- in the current context.
-
- If \var{watchexp} is set (default), then an error is returned whenever
- the resulting exponent is greater than \member{Emax} or less than
- \member{Etiny}.
-\end{methoddesc}
-
-\begin{methoddesc}{remainder_near}{other\optional{, context}}
- Computes the modulo as either a positive or negative value depending
- on which is closest to zero. For instance,
- \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
- which is closer to zero than \code{Decimal("4")}.
-
- If both are equally close, the one chosen will have the same sign
- as \var{self}.
-\end{methoddesc}
-
-\begin{methoddesc}{same_quantum}{other\optional{, context}}
- Test whether self and other have the same exponent or whether both
- are \constant{NaN}.
-\end{methoddesc}
-
-\begin{methoddesc}{sqrt}{\optional{context}}
- Return the square root to full precision.
-\end{methoddesc}
-
-\begin{methoddesc}{to_eng_string}{\optional{context}}
- Convert to an engineering-type string.
-
- Engineering notation has an exponent which is a multiple of 3, so there
- are up to 3 digits left of the decimal place. For example, converts
- \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
-\end{methoddesc}
-
-\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}}
- Rounds to the nearest integer without signaling \constant{Inexact}
- or \constant{Rounded}. If given, applies \var{rounding}; otherwise,
- uses the rounding method in either the supplied \var{context} or the
- current context.
-\end{methoddesc}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Context objects \label{decimal-context}}
-
-Contexts are environments for arithmetic operations. They govern precision,
-set rules for rounding, determine which signals are treated as exceptions, and
-limit the range for exponents.
-
-Each thread has its own current context which is accessed or changed using
-the \function{getcontext()} and \function{setcontext()} functions:
-
-\begin{funcdesc}{getcontext}{}
- Return the current context for the active thread.
-\end{funcdesc}
-
-\begin{funcdesc}{setcontext}{c}
- Set the current context for the active thread to \var{c}.
-\end{funcdesc}
-
-Beginning with Python 2.5, you can also use the \keyword{with} statement
-and the \function{localcontext()} function to temporarily change the
-active context.
-
-\begin{funcdesc}{localcontext}{\optional{c}}
- Return a context manager that will set the current context for
- the active thread to a copy of \var{c} on entry to the with-statement
- and restore the previous context when exiting the with-statement. If
- no context is specified, a copy of the current context is used.
- \versionadded{2.5}
-
- For example, the following code sets the current decimal precision
- to 42 places, performs a calculation, and then automatically restores
- the previous context:
-\begin{verbatim}
- from __future__ import with_statement
- from decimal import localcontext
-
- with localcontext() as ctx:
- ctx.prec = 42 # Perform a high precision calculation
- s = calculate_something()
- s = +s # Round the final result back to the default precision
-\end{verbatim}
-\end{funcdesc}
-
-New contexts can also be created using the \class{Context} constructor
-described below. In addition, the module provides three pre-made
-contexts:
-
-\begin{classdesc*}{BasicContext}
- This is a standard context defined by the General Decimal Arithmetic
- Specification. Precision is set to nine. Rounding is set to
- \constant{ROUND_HALF_UP}. All flags are cleared. All traps are enabled
- (treated as exceptions) except \constant{Inexact}, \constant{Rounded}, and
- \constant{Subnormal}.
-
- Because many of the traps are enabled, this context is useful for debugging.
-\end{classdesc*}
-
-\begin{classdesc*}{ExtendedContext}
- This is a standard context defined by the General Decimal Arithmetic
- Specification. Precision is set to nine. Rounding is set to
- \constant{ROUND_HALF_EVEN}. All flags are cleared. No traps are enabled
- (so that exceptions are not raised during computations).
-
- Because the trapped are disabled, this context is useful for applications
- that prefer to have result value of \constant{NaN} or \constant{Infinity}
- instead of raising exceptions. This allows an application to complete a
- run in the presence of conditions that would otherwise halt the program.
-\end{classdesc*}
-
-\begin{classdesc*}{DefaultContext}
- This context is used by the \class{Context} constructor as a prototype for
- new contexts. Changing a field (such a precision) has the effect of
- changing the default for new contexts creating by the \class{Context}
- constructor.
-
- This context is most useful in multi-threaded environments. Changing one of
- the fields before threads are started has the effect of setting system-wide
- defaults. Changing the fields after threads have started is not recommended
- as it would require thread synchronization to prevent race conditions.
-
- In single threaded environments, it is preferable to not use this context
- at all. Instead, simply create contexts explicitly as described below.
-
- The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled
- traps for Overflow, InvalidOperation, and DivisionByZero.
-\end{classdesc*}
-
-
-In addition to the three supplied contexts, new contexts can be created
-with the \class{Context} constructor.
-
-\begin{classdesc}{Context}{prec=None, rounding=None, traps=None,
- flags=None, Emin=None, Emax=None, capitals=1}
- Creates a new context. If a field is not specified or is \constant{None},
- the default values are copied from the \constant{DefaultContext}. If the
- \var{flags} field is not specified or is \constant{None}, all flags are
- cleared.
-
- The \var{prec} field is a positive integer that sets the precision for
- arithmetic operations in the context.
-
- The \var{rounding} option is one of:
- \begin{itemize}
- \item \constant{ROUND_CEILING} (towards \constant{Infinity}),
- \item \constant{ROUND_DOWN} (towards zero),
- \item \constant{ROUND_FLOOR} (towards \constant{-Infinity}),
- \item \constant{ROUND_HALF_DOWN} (to nearest with ties going towards zero),
- \item \constant{ROUND_HALF_EVEN} (to nearest with ties going to nearest even integer),
- \item \constant{ROUND_HALF_UP} (to nearest with ties going away from zero), or
- \item \constant{ROUND_UP} (away from zero).
- \end{itemize}
-
- The \var{traps} and \var{flags} fields list any signals to be set.
- Generally, new contexts should only set traps and leave the flags clear.
-
- The \var{Emin} and \var{Emax} fields are integers specifying the outer
- limits allowable for exponents.
-
- The \var{capitals} field is either \constant{0} or \constant{1} (the
- default). If set to \constant{1}, exponents are printed with a capital
- \constant{E}; otherwise, a lowercase \constant{e} is used:
- \constant{Decimal('6.02e+23')}.
-\end{classdesc}
-
-The \class{Context} class defines several general purpose methods as well as a
-large number of methods for doing arithmetic directly in a given context.
-
-\begin{methoddesc}{clear_flags}{}
- Resets all of the flags to \constant{0}.
-\end{methoddesc}
-
-\begin{methoddesc}{copy}{}
- Return a duplicate of the context.
-\end{methoddesc}
-
-\begin{methoddesc}{create_decimal}{num}
- Creates a new Decimal instance from \var{num} but using \var{self} as
- context. Unlike the \class{Decimal} constructor, the context precision,
- rounding method, flags, and traps are applied to the conversion.
-
- This is useful because constants are often given to a greater precision than
- is needed by the application. Another benefit is that rounding immediately
- eliminates unintended effects from digits beyond the current precision.
- In the following example, using unrounded inputs means that adding zero
- to a sum can change the result:
-
- \begin{verbatim}
- >>> getcontext().prec = 3
- >>> Decimal("3.4445") + Decimal("1.0023")
- Decimal("4.45")
- >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
- Decimal("4.44")
- \end{verbatim}
-
-\end{methoddesc}
-
-\begin{methoddesc}{Etiny}{}
- Returns a value equal to \samp{Emin - prec + 1} which is the minimum
- exponent value for subnormal results. When underflow occurs, the
- exponent is set to \constant{Etiny}.
-\end{methoddesc}
-
-\begin{methoddesc}{Etop}{}
- Returns a value equal to \samp{Emax - prec + 1}.
-\end{methoddesc}
-
-
-The usual approach to working with decimals is to create \class{Decimal}
-instances and then apply arithmetic operations which take place within the
-current context for the active thread. An alternate approach is to use
-context methods for calculating within a specific context. The methods are
-similar to those for the \class{Decimal} class and are only briefly recounted
-here.
-
-\begin{methoddesc}{abs}{x}
- Returns the absolute value of \var{x}.
-\end{methoddesc}
-
-\begin{methoddesc}{add}{x, y}
- Return the sum of \var{x} and \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{compare}{x, y}
- Compares values numerically.
-
- Like \method{__cmp__()} but returns a decimal instance:
- \begin{verbatim}
- a or b is a NaN ==> Decimal("NaN")
- a < b ==> Decimal("-1")
- a == b ==> Decimal("0")
- a > b ==> Decimal("1")
- \end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{divide}{x, y}
- Return \var{x} divided by \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{divmod}{x, y}
- Divides two numbers and returns the integer part of the result.
-\end{methoddesc}
-
-\begin{methoddesc}{max}{x, y}
- Compare two values numerically and return the maximum.
-
- If they are numerically equal then the left-hand operand is chosen as the
- result.
-\end{methoddesc}
-
-\begin{methoddesc}{min}{x, y}
- Compare two values numerically and return the minimum.
-
- If they are numerically equal then the left-hand operand is chosen as the
- result.
-\end{methoddesc}
-
-\begin{methoddesc}{minus}{x}
- Minus corresponds to the unary prefix minus operator in Python.
-\end{methoddesc}
-
-\begin{methoddesc}{multiply}{x, y}
- Return the product of \var{x} and \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{normalize}{x}
- Normalize reduces an operand to its simplest form.
-
- Essentially a \method{plus} operation with all trailing zeros removed from
- the result.
-\end{methoddesc}
-
-\begin{methoddesc}{plus}{x}
- Plus corresponds to the unary prefix plus operator in Python. This
- operation applies the context precision and rounding, so it is
- \emph{not} an identity operation.
-\end{methoddesc}
-
-\begin{methoddesc}{power}{x, y\optional{, modulo}}
- Return \samp{x ** y} to the \var{modulo} if given.
-
- The right-hand operand must be a whole number whose integer part (after any
- exponent has been applied) has no more than 9 digits and whose fractional
- part (if any) is all zeros before any rounding. The operand may be positive,
- negative, or zero; if negative, the absolute value of the power is used, and
- the left-hand operand is inverted (divided into 1) before use.
-
- If the increased precision needed for the intermediate calculations exceeds
- the capabilities of the implementation then an \constant{InvalidOperation}
- condition is signaled.
-
- If, when raising to a negative power, an underflow occurs during the
- division into 1, the operation is not halted at that point but continues.
-\end{methoddesc}
-
-\begin{methoddesc}{quantize}{x, y}
- Returns a value equal to \var{x} after rounding and having the exponent of
- \var{y}.
-
- Unlike other operations, if the length of the coefficient after the quantize
- operation would be greater than precision, then an
- \constant{InvalidOperation} is signaled. This guarantees that, unless there
- is an error condition, the quantized exponent is always equal to that of the
- right-hand operand.
-
- Also unlike other operations, quantize never signals Underflow, even
- if the result is subnormal and inexact.
-\end{methoddesc}
-
-\begin{methoddesc}{remainder}{x, y}
- Returns the remainder from integer division.
-
- The sign of the result, if non-zero, is the same as that of the original
- dividend.
-\end{methoddesc}
-
-\begin{methoddesc}{remainder_near}{x, y}
- Computed the modulo as either a positive or negative value depending
- on which is closest to zero. For instance,
- \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")}
- which is closer to zero than \code{Decimal("4")}.
-
- If both are equally close, the one chosen will have the same sign
- as \var{self}.
-\end{methoddesc}
-
-\begin{methoddesc}{same_quantum}{x, y}
- Test whether \var{x} and \var{y} have the same exponent or whether both are
- \constant{NaN}.
-\end{methoddesc}
-
-\begin{methoddesc}{sqrt}{x}
- Return the square root of \var{x} to full precision.
-\end{methoddesc}
-
-\begin{methoddesc}{subtract}{x, y}
- Return the difference between \var{x} and \var{y}.
-\end{methoddesc}
-
-\begin{methoddesc}{to_eng_string}{}
- Convert to engineering-type string.
-
- Engineering notation has an exponent which is a multiple of 3, so there
- are up to 3 digits left of the decimal place. For example, converts
- \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")}
-\end{methoddesc}
-
-\begin{methoddesc}{to_integral}{x}
- Rounds to the nearest integer without signaling \constant{Inexact}
- or \constant{Rounded}.
-\end{methoddesc}
-
-\begin{methoddesc}{to_sci_string}{x}
- Converts a number to a string using scientific notation.
-\end{methoddesc}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Signals \label{decimal-signals}}
-
-Signals represent conditions that arise during computation.
-Each corresponds to one context flag and one context trap enabler.
-
-The context flag is incremented whenever the condition is encountered.
-After the computation, flags may be checked for informational
-purposes (for instance, to determine whether a computation was exact).
-After checking the flags, be sure to clear all flags before starting
-the next computation.
-
-If the context's trap enabler is set for the signal, then the condition
-causes a Python exception to be raised. For example, if the
-\class{DivisionByZero} trap is set, then a \exception{DivisionByZero}
-exception is raised upon encountering the condition.
-
-
-\begin{classdesc*}{Clamped}
- Altered an exponent to fit representation constraints.
-
- Typically, clamping occurs when an exponent falls outside the context's
- \member{Emin} and \member{Emax} limits. If possible, the exponent is
- reduced to fit by adding zeroes to the coefficient.
-\end{classdesc*}
-
-\begin{classdesc*}{DecimalException}
- Base class for other signals and a subclass of
- \exception{ArithmeticError}.
-\end{classdesc*}
-
-\begin{classdesc*}{DivisionByZero}
- Signals the division of a non-infinite number by zero.
-
- Can occur with division, modulo division, or when raising a number to a
- negative power. If this signal is not trapped, returns
- \constant{Infinity} or \constant{-Infinity} with the sign determined by
- the inputs to the calculation.
-\end{classdesc*}
-
-\begin{classdesc*}{Inexact}
- Indicates that rounding occurred and the result is not exact.
-
- Signals when non-zero digits were discarded during rounding. The rounded
- result is returned. The signal flag or trap is used to detect when
- results are inexact.
-\end{classdesc*}
-
-\begin{classdesc*}{InvalidOperation}
- An invalid operation was performed.
-
- Indicates that an operation was requested that does not make sense.
- If not trapped, returns \constant{NaN}. Possible causes include:
-
- \begin{verbatim}
- Infinity - Infinity
- 0 * Infinity
- Infinity / Infinity
- x % 0
- Infinity % x
- x._rescale( non-integer )
- sqrt(-x) and x > 0
- 0 ** 0
- x ** (non-integer)
- x ** Infinity
- \end{verbatim}
-\end{classdesc*}
-
-\begin{classdesc*}{Overflow}
- Numerical overflow.
-
- Indicates the exponent is larger than \member{Emax} after rounding has
- occurred. If not trapped, the result depends on the rounding mode, either
- pulling inward to the largest representable finite number or rounding
- outward to \constant{Infinity}. In either case, \class{Inexact} and
- \class{Rounded} are also signaled.
-\end{classdesc*}
-
-\begin{classdesc*}{Rounded}
- Rounding occurred though possibly no information was lost.
-
- Signaled whenever rounding discards digits; even if those digits are
- zero (such as rounding \constant{5.00} to \constant{5.0}). If not
- trapped, returns the result unchanged. This signal is used to detect
- loss of significant digits.
-\end{classdesc*}
-
-\begin{classdesc*}{Subnormal}
- Exponent was lower than \member{Emin} prior to rounding.
-
- Occurs when an operation result is subnormal (the exponent is too small).
- If not trapped, returns the result unchanged.
-\end{classdesc*}
-
-\begin{classdesc*}{Underflow}
- Numerical underflow with result rounded to zero.
-
- Occurs when a subnormal result is pushed to zero by rounding.
- \class{Inexact} and \class{Subnormal} are also signaled.
-\end{classdesc*}
-
-The following table summarizes the hierarchy of signals:
-
-\begin{verbatim}
- exceptions.ArithmeticError(exceptions.Exception)
- DecimalException
- Clamped
- DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
- Inexact
- Overflow(Inexact, Rounded)
- Underflow(Inexact, Rounded, Subnormal)
- InvalidOperation
- Rounded
- Subnormal
-\end{verbatim}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Floating Point Notes \label{decimal-notes}}
-
-\subsubsection{Mitigating round-off error with increased precision}
-
-The use of decimal floating point eliminates decimal representation error
-(making it possible to represent \constant{0.1} exactly); however, some
-operations can still incur round-off error when non-zero digits exceed the
-fixed precision.
-
-The effects of round-off error can be amplified by the addition or subtraction
-of nearly offsetting quantities resulting in loss of significance. Knuth
-provides two instructive examples where rounded floating point arithmetic with
-insufficient precision causes the breakdown of the associative and
-distributive properties of addition:
-
-\begin{verbatim}
-# Examples from Seminumerical Algorithms, Section 4.2.2.
->>> from decimal import Decimal, getcontext
->>> getcontext().prec = 8
-
->>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
->>> (u + v) + w
-Decimal("9.5111111")
->>> u + (v + w)
-Decimal("10")
-
->>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
->>> (u*v) + (u*w)
-Decimal("0.01")
->>> u * (v+w)
-Decimal("0.0060000")
-\end{verbatim}
-
-The \module{decimal} module makes it possible to restore the identities
-by expanding the precision sufficiently to avoid loss of significance:
-
-\begin{verbatim}
->>> getcontext().prec = 20
->>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
->>> (u + v) + w
-Decimal("9.51111111")
->>> u + (v + w)
-Decimal("9.51111111")
->>>
->>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
->>> (u*v) + (u*w)
-Decimal("0.0060000")
->>> u * (v+w)
-Decimal("0.0060000")
-\end{verbatim}
-
-\subsubsection{Special values}
-
-The number system for the \module{decimal} module provides special
-values including \constant{NaN}, \constant{sNaN}, \constant{-Infinity},
-\constant{Infinity}, and two zeroes, \constant{+0} and \constant{-0}.
-
-Infinities can be constructed directly with: \code{Decimal('Infinity')}. Also,
-they can arise from dividing by zero when the \exception{DivisionByZero}
-signal is not trapped. Likewise, when the \exception{Overflow} signal is not
-trapped, infinity can result from rounding beyond the limits of the largest
-representable number.
-
-The infinities are signed (affine) and can be used in arithmetic operations
-where they get treated as very large, indeterminate numbers. For instance,
-adding a constant to infinity gives another infinite result.
-
-Some operations are indeterminate and return \constant{NaN}, or if the
-\exception{InvalidOperation} signal is trapped, raise an exception. For
-example, \code{0/0} returns \constant{NaN} which means ``not a number''. This
-variety of \constant{NaN} is quiet and, once created, will flow through other
-computations always resulting in another \constant{NaN}. This behavior can be
-useful for a series of computations that occasionally have missing inputs ---
-it allows the calculation to proceed while flagging specific results as
-invalid.
-
-A variant is \constant{sNaN} which signals rather than remaining quiet
-after every operation. This is a useful return value when an invalid
-result needs to interrupt a calculation for special handling.
-
-The signed zeros can result from calculations that underflow.
-They keep the sign that would have resulted if the calculation had
-been carried out to greater precision. Since their magnitude is
-zero, both positive and negative zeros are treated as equal and their
-sign is informational.
-
-In addition to the two signed zeros which are distinct yet equal,
-there are various representations of zero with differing precisions
-yet equivalent in value. This takes a bit of getting used to. For
-an eye accustomed to normalized floating point representations, it
-is not immediately obvious that the following calculation returns
-a value equal to zero:
-
-\begin{verbatim}
->>> 1 / Decimal('Infinity')
-Decimal("0E-1000000026")
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Working with threads \label{decimal-threads}}
-
-The \function{getcontext()} function accesses a different \class{Context}
-object for each thread. Having separate thread contexts means that threads
-may make changes (such as \code{getcontext.prec=10}) without interfering with
-other threads.
-
-Likewise, the \function{setcontext()} function automatically assigns its target
-to the current thread.
-
-If \function{setcontext()} has not been called before \function{getcontext()},
-then \function{getcontext()} will automatically create a new context for use
-in the current thread.
-
-The new context is copied from a prototype context called
-\var{DefaultContext}. To control the defaults so that each thread will use the
-same values throughout the application, directly modify the
-\var{DefaultContext} object. This should be done \emph{before} any threads are
-started so that there won't be a race condition between threads calling
-\function{getcontext()}. For example:
-
-\begin{verbatim}
-# Set applicationwide defaults for all threads about to be launched
-DefaultContext.prec = 12
-DefaultContext.rounding = ROUND_DOWN
-DefaultContext.traps = ExtendedContext.traps.copy()
-DefaultContext.traps[InvalidOperation] = 1
-setcontext(DefaultContext)
-
-# Afterwards, the threads can be started
-t1.start()
-t2.start()
-t3.start()
- . . .
-\end{verbatim}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Recipes \label{decimal-recipes}}
-
-Here are a few recipes that serve as utility functions and that demonstrate
-ways to work with the \class{Decimal} class:
-
-\begin{verbatim}
-def moneyfmt(value, places=2, curr='', sep=',', dp='.',
- pos='', neg='-', trailneg=''):
- """Convert Decimal to a money formatted string.
-
- places: required number of places after the decimal point
- curr: optional currency symbol before the sign (may be blank)
- sep: optional grouping separator (comma, period, space, or blank)
- dp: decimal point indicator (comma or period)
- only specify as blank when places is zero
- pos: optional sign for positive numbers: '+', space or blank
- neg: optional sign for negative numbers: '-', '(', space or blank
- trailneg:optional trailing minus indicator: '-', ')', space or blank
-
- >>> d = Decimal('-1234567.8901')
- >>> moneyfmt(d, curr='$')
- '-$1,234,567.89'
- >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
- '1.234.568-'
- >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
- '($1,234,567.89)'
- >>> moneyfmt(Decimal(123456789), sep=' ')
- '123 456 789.00'
- >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
- '<.02>'
-
- """
- q = Decimal((0, (1,), -places)) # 2 places --> '0.01'
- sign, digits, exp = value.quantize(q).as_tuple()
- assert exp == -places
- result = []
- digits = map(str, digits)
- build, next = result.append, digits.pop
- if sign:
- build(trailneg)
- for i in range(places):
- if digits:
- build(next())
- else:
- build('0')
- build(dp)
- i = 0
- while digits:
- build(next())
- i += 1
- if i == 3 and digits:
- i = 0
- build(sep)
- build(curr)
- if sign:
- build(neg)
- else:
- build(pos)
- result.reverse()
- return ''.join(result)
-
-def pi():
- """Compute Pi to the current precision.
-
- >>> print pi()
- 3.141592653589793238462643383
-
- """
- getcontext().prec += 2 # extra digits for intermediate steps
- three = Decimal(3) # substitute "three=3.0" for regular floats
- lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
- while s != lasts:
- lasts = s
- n, na = n+na, na+8
- d, da = d+da, da+32
- t = (t * n) / d
- s += t
- getcontext().prec -= 2
- return +s # unary plus applies the new precision
-
-def exp(x):
- """Return e raised to the power of x. Result type matches input type.
-
- >>> print exp(Decimal(1))
- 2.718281828459045235360287471
- >>> print exp(Decimal(2))
- 7.389056098930650227230427461
- >>> print exp(2.0)
- 7.38905609893
- >>> print exp(2+0j)
- (7.38905609893+0j)
-
- """
- getcontext().prec += 2
- i, lasts, s, fact, num = 0, 0, 1, 1, 1
- while s != lasts:
- lasts = s
- i += 1
- fact *= i
- num *= x
- s += num / fact
- getcontext().prec -= 2
- return +s
-
-def cos(x):
- """Return the cosine of x as measured in radians.
-
- >>> print cos(Decimal('0.5'))
- 0.8775825618903727161162815826
- >>> print cos(0.5)
- 0.87758256189
- >>> print cos(0.5+0j)
- (0.87758256189+0j)
-
- """
- getcontext().prec += 2
- i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
- while s != lasts:
- lasts = s
- i += 2
- fact *= i * (i-1)
- num *= x * x
- sign *= -1
- s += num / fact * sign
- getcontext().prec -= 2
- return +s
-
-def sin(x):
- """Return the sine of x as measured in radians.
-
- >>> print sin(Decimal('0.5'))
- 0.4794255386042030002732879352
- >>> print sin(0.5)
- 0.479425538604
- >>> print sin(0.5+0j)
- (0.479425538604+0j)
-
- """
- getcontext().prec += 2
- i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
- while s != lasts:
- lasts = s
- i += 2
- fact *= i * (i-1)
- num *= x * x
- sign *= -1
- s += num / fact * sign
- getcontext().prec -= 2
- return +s
-
-\end{verbatim}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Decimal FAQ \label{decimal-faq}}
-
-Q. It is cumbersome to type \code{decimal.Decimal('1234.5')}. Is there a way
-to minimize typing when using the interactive interpreter?
-
-A. Some users abbreviate the constructor to just a single letter:
-
-\begin{verbatim}
->>> D = decimal.Decimal
->>> D('1.23') + D('3.45')
-Decimal("4.68")
-\end{verbatim}
-
-
-Q. In a fixed-point application with two decimal places, some inputs
-have many places and need to be rounded. Others are not supposed to have
-excess digits and need to be validated. What methods should be used?
-
-A. The \method{quantize()} method rounds to a fixed number of decimal places.
-If the \constant{Inexact} trap is set, it is also useful for validation:
-
-\begin{verbatim}
->>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
-
->>> # Round to two places
->>> Decimal("3.214").quantize(TWOPLACES)
-Decimal("3.21")
-
->>> # Validate that a number does not exceed two places
->>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
-Decimal("3.21")
-
->>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
-Traceback (most recent call last):
- ...
-Inexact: Changed in rounding
-\end{verbatim}
-
-
-Q. Once I have valid two place inputs, how do I maintain that invariant
-throughout an application?
-
-A. Some operations like addition and subtraction automatically preserve fixed
-point. Others, like multiplication and division, change the number of decimal
-places and need to be followed-up with a \method{quantize()} step.
-
-
-Q. There are many ways to express the same value. The numbers
-\constant{200}, \constant{200.000}, \constant{2E2}, and \constant{.02E+4} all
-have the same value at various precisions. Is there a way to transform them to
-a single recognizable canonical value?
-
-A. The \method{normalize()} method maps all equivalent values to a single
-representative:
-
-\begin{verbatim}
->>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
->>> [v.normalize() for v in values]
-[Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]
-\end{verbatim}
-
-
-Q. Some decimal values always print with exponential notation. Is there
-a way to get a non-exponential representation?
-
-A. For some values, exponential notation is the only way to express
-the number of significant places in the coefficient. For example,
-expressing \constant{5.0E+3} as \constant{5000} keeps the value
-constant but cannot show the original's two-place significance.
-
-
-Q. Is there a way to convert a regular float to a \class{Decimal}?
-
-A. Yes, all binary floating point numbers can be exactly expressed as a
-Decimal. An exact conversion may take more precision than intuition would
-suggest, so trapping \constant{Inexact} will signal a need for more precision:
-
-\begin{verbatim}
-def floatToDecimal(f):
- "Convert a floating point number to a Decimal with no loss of information"
- # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an
- # exponent. Double the mantissa until it is an integer. Use the integer
- # mantissa and exponent to compute an equivalent Decimal. If this cannot
- # be done exactly, then retry with more precision.
-
- mantissa, exponent = math.frexp(f)
- while mantissa != int(mantissa):
- mantissa *= 2.0
- exponent -= 1
- mantissa = int(mantissa)
-
- oldcontext = getcontext()
- setcontext(Context(traps=[Inexact]))
- try:
- while True:
- try:
- return mantissa * Decimal(2) ** exponent
- except Inexact:
- getcontext().prec += 1
- finally:
- setcontext(oldcontext)
-\end{verbatim}
-
-
-Q. Why isn't the \function{floatToDecimal()} routine included in the module?
-
-A. There is some question about whether it is advisable to mix binary and
-decimal floating point. Also, its use requires some care to avoid the
-representation issues associated with binary floating point:
-
-\begin{verbatim}
->>> floatToDecimal(1.1)
-Decimal("1.100000000000000088817841970012523233890533447265625")
-\end{verbatim}
-
-
-Q. Within a complex calculation, how can I make sure that I haven't gotten a
-spurious result because of insufficient precision or rounding anomalies.
-
-A. The decimal module makes it easy to test results. A best practice is to
-re-run calculations using greater precision and with various rounding modes.
-Widely differing results indicate insufficient precision, rounding mode
-issues, ill-conditioned inputs, or a numerically unstable algorithm.
-
-
-Q. I noticed that context precision is applied to the results of operations
-but not to the inputs. Is there anything to watch out for when mixing
-values of different precisions?
-
-A. Yes. The principle is that all values are considered to be exact and so
-is the arithmetic on those values. Only the results are rounded. The
-advantage for inputs is that ``what you type is what you get''. A
-disadvantage is that the results can look odd if you forget that the inputs
-haven't been rounded:
-
-\begin{verbatim}
->>> getcontext().prec = 3
->>> Decimal('3.104') + D('2.104')
-Decimal("5.21")
->>> Decimal('3.104') + D('0.000') + D('2.104')
-Decimal("5.20")
-\end{verbatim}
-
-The solution is either to increase precision or to force rounding of inputs
-using the unary plus operation:
-
-\begin{verbatim}
->>> getcontext().prec = 3
->>> +Decimal('1.23456789') # unary plus triggers rounding
-Decimal("1.23")
-\end{verbatim}
-
-Alternatively, inputs can be rounded upon creation using the
-\method{Context.create_decimal()} method:
-
-\begin{verbatim}
->>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
-Decimal("1.2345")
-\end{verbatim}
diff --git a/Doc/lib/libdifflib.tex b/Doc/lib/libdifflib.tex
deleted file mode 100644
index 7fb8e92..0000000
--- a/Doc/lib/libdifflib.tex
+++ /dev/null
@@ -1,704 +0,0 @@
-\section{\module{difflib} ---
- Helpers for computing deltas}
-
-\declaremodule{standard}{difflib}
-\modulesynopsis{Helpers for computing differences between objects.}
-\moduleauthor{Tim Peters}{tim_one@users.sourceforge.net}
-\sectionauthor{Tim Peters}{tim_one@users.sourceforge.net}
-% LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
-
-\versionadded{2.1}
-
-
-\begin{classdesc*}{SequenceMatcher}
- This is a flexible class for comparing pairs of sequences of any
- type, so long as the sequence elements are hashable. The basic
- algorithm predates, and is a little fancier than, an algorithm
- published in the late 1980's by Ratcliff and Obershelp under the
- hyperbolic name ``gestalt pattern matching.'' The idea is to find
- the longest contiguous matching subsequence that contains no
- ``junk'' elements (the Ratcliff and Obershelp algorithm doesn't
- address junk). The same idea is then applied recursively to the
- pieces of the sequences to the left and to the right of the matching
- subsequence. This does not yield minimal edit sequences, but does
- tend to yield matches that ``look right'' to people.
-
- \strong{Timing:} The basic Ratcliff-Obershelp algorithm is cubic
- time in the worst case and quadratic time in the expected case.
- \class{SequenceMatcher} is quadratic time for the worst case and has
- expected-case behavior dependent in a complicated way on how many
- elements the sequences have in common; best case time is linear.
-\end{classdesc*}
-
-\begin{classdesc*}{Differ}
- This is a class for comparing sequences of lines of text, and
- producing human-readable differences or deltas. Differ uses
- \class{SequenceMatcher} both to compare sequences of lines, and to
- compare sequences of characters within similar (near-matching)
- lines.
-
- Each line of a \class{Differ} delta begins with a two-letter code:
-
-\begin{tableii}{l|l}{code}{Code}{Meaning}
- \lineii{'- '}{line unique to sequence 1}
- \lineii{'+ '}{line unique to sequence 2}
- \lineii{' '}{line common to both sequences}
- \lineii{'? '}{line not present in either input sequence}
-\end{tableii}
-
- Lines beginning with `\code{?~}' attempt to guide the eye to
- intraline differences, and were not present in either input
- sequence. These lines can be confusing if the sequences contain tab
- characters.
-\end{classdesc*}
-
-\begin{classdesc*}{HtmlDiff}
-
- This class can be used to create an HTML table (or a complete HTML file
- containing the table) showing a side by side, line by line comparison
- of text with inter-line and intra-line change highlights. The table can
- be generated in either full or contextual difference mode.
-
- The constructor for this class is:
-
- \begin{funcdesc}{__init__}{\optional{tabsize}\optional{,
- wrapcolumn}\optional{, linejunk}\optional{, charjunk}}
-
- Initializes instance of \class{HtmlDiff}.
-
- \var{tabsize} is an optional keyword argument to specify tab stop spacing
- and defaults to \code{8}.
-
- \var{wrapcolumn} is an optional keyword to specify column number where
- lines are broken and wrapped, defaults to \code{None} where lines are not
- wrapped.
-
- \var{linejunk} and \var{charjunk} are optional keyword arguments passed
- into \code{ndiff()} (used by \class{HtmlDiff} to generate the
- side by side HTML differences). See \code{ndiff()} documentation for
- argument default values and descriptions.
-
- \end{funcdesc}
-
- The following methods are public:
-
- \begin{funcdesc}{make_file}{fromlines, tolines
- \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{,
- numlines}}
- Compares \var{fromlines} and \var{tolines} (lists of strings) and returns
- a string which is a complete HTML file containing a table showing line by
- line differences with inter-line and intra-line changes highlighted.
-
- \var{fromdesc} and \var{todesc} are optional keyword arguments to specify
- from/to file column header strings (both default to an empty string).
-
- \var{context} and \var{numlines} are both optional keyword arguments.
- Set \var{context} to \code{True} when contextual differences are to be
- shown, else the default is \code{False} to show the full files.
- \var{numlines} defaults to \code{5}. When \var{context} is \code{True}
- \var{numlines} controls the number of context lines which surround the
- difference highlights. When \var{context} is \code{False} \var{numlines}
- controls the number of lines which are shown before a difference
- highlight when using the "next" hyperlinks (setting to zero would cause
- the "next" hyperlinks to place the next difference highlight at the top of
- the browser without any leading context).
- \end{funcdesc}
-
- \begin{funcdesc}{make_table}{fromlines, tolines
- \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{,
- numlines}}
- Compares \var{fromlines} and \var{tolines} (lists of strings) and returns
- a string which is a complete HTML table showing line by line differences
- with inter-line and intra-line changes highlighted.
-
- The arguments for this method are the same as those for the
- \method{make_file()} method.
- \end{funcdesc}
-
- \file{Tools/scripts/diff.py} is a command-line front-end to this class
- and contains a good example of its use.
-
- \versionadded{2.4}
-\end{classdesc*}
-
-\begin{funcdesc}{context_diff}{a, b\optional{, fromfile}\optional{,
- tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{,
- n}\optional{, lineterm}}
- Compare \var{a} and \var{b} (lists of strings); return a
- delta (a generator generating the delta lines) in context diff
- format.
-
- Context diffs are a compact way of showing just the lines that have
- changed plus a few lines of context. The changes are shown in a
- before/after style. The number of context lines is set by \var{n}
- which defaults to three.
-
- By default, the diff control lines (those with \code{***} or \code{---})
- are created with a trailing newline. This is helpful so that inputs created
- from \function{file.readlines()} result in diffs that are suitable for use
- with \function{file.writelines()} since both the inputs and outputs have
- trailing newlines.
-
- For inputs that do not have trailing newlines, set the \var{lineterm}
- argument to \code{""} so that the output will be uniformly newline free.
-
- The context diff format normally has a header for filenames and
- modification times. Any or all of these may be specified using strings for
- \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}.
- The modification times are normally expressed in the format returned by
- \function{time.ctime()}. If not specified, the strings default to blanks.
-
- \file{Tools/scripts/diff.py} is a command-line front-end for this
- function.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{get_close_matches}{word, possibilities\optional{,
- n}\optional{, cutoff}}
- Return a list of the best ``good enough'' matches. \var{word} is a
- sequence for which close matches are desired (typically a string),
- and \var{possibilities} is a list of sequences against which to
- match \var{word} (typically a list of strings).
-
- Optional argument \var{n} (default \code{3}) is the maximum number
- of close matches to return; \var{n} must be greater than \code{0}.
-
- Optional argument \var{cutoff} (default \code{0.6}) is a float in
- the range [0, 1]. Possibilities that don't score at least that
- similar to \var{word} are ignored.
-
- The best (no more than \var{n}) matches among the possibilities are
- returned in a list, sorted by similarity score, most similar first.
-
-\begin{verbatim}
->>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
-['apple', 'ape']
->>> import keyword
->>> get_close_matches('wheel', keyword.kwlist)
-['while']
->>> get_close_matches('apple', keyword.kwlist)
-[]
->>> get_close_matches('accept', keyword.kwlist)
-['except']
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{ndiff}{a, b\optional{, linejunk}\optional{, charjunk}}
- Compare \var{a} and \var{b} (lists of strings); return a
- \class{Differ}-style delta (a generator generating the delta lines).
-
- Optional keyword parameters \var{linejunk} and \var{charjunk} are
- for filter functions (or \code{None}):
-
- \var{linejunk}: A function that accepts a single string
- argument, and returns true if the string is junk, or false if not.
- The default is (\code{None}), starting with Python 2.3. Before then,
- the default was the module-level function
- \function{IS_LINE_JUNK()}, which filters out lines without visible
- characters, except for at most one pound character (\character{\#}).
- As of Python 2.3, the underlying \class{SequenceMatcher} class
- does a dynamic analysis of which lines are so frequent as to
- constitute noise, and this usually works better than the pre-2.3
- default.
-
- \var{charjunk}: A function that accepts a character (a string of
- length 1), and returns if the character is junk, or false if not.
- The default is module-level function \function{IS_CHARACTER_JUNK()},
- which filters out whitespace characters (a blank or tab; note: bad
- idea to include newline in this!).
-
- \file{Tools/scripts/ndiff.py} is a command-line front-end to this
- function.
-
-\begin{verbatim}
->>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
-... 'ore\ntree\nemu\n'.splitlines(1))
->>> print ''.join(diff),
-- one
-? ^
-+ ore
-? ^
-- two
-- three
-? -
-+ tree
-+ emu
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{restore}{sequence, which}
- Return one of the two sequences that generated a delta.
-
- Given a \var{sequence} produced by \method{Differ.compare()} or
- \function{ndiff()}, extract lines originating from file 1 or 2
- (parameter \var{which}), stripping off line prefixes.
-
- Example:
-
-\begin{verbatim}
->>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
-... 'ore\ntree\nemu\n'.splitlines(1))
->>> diff = list(diff) # materialize the generated delta into a list
->>> print ''.join(restore(diff, 1)),
-one
-two
-three
->>> print ''.join(restore(diff, 2)),
-ore
-tree
-emu
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{unified_diff}{a, b\optional{, fromfile}\optional{,
- tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{,
- n}\optional{, lineterm}}
- Compare \var{a} and \var{b} (lists of strings); return a
- delta (a generator generating the delta lines) in unified diff
- format.
-
- Unified diffs are a compact way of showing just the lines that have
- changed plus a few lines of context. The changes are shown in a
- inline style (instead of separate before/after blocks). The number
- of context lines is set by \var{n} which defaults to three.
-
- By default, the diff control lines (those with \code{---}, \code{+++},
- or \code{@@}) are created with a trailing newline. This is helpful so
- that inputs created from \function{file.readlines()} result in diffs
- that are suitable for use with \function{file.writelines()} since both
- the inputs and outputs have trailing newlines.
-
- For inputs that do not have trailing newlines, set the \var{lineterm}
- argument to \code{""} so that the output will be uniformly newline free.
-
- The context diff format normally has a header for filenames and
- modification times. Any or all of these may be specified using strings for
- \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}.
- The modification times are normally expressed in the format returned by
- \function{time.ctime()}. If not specified, the strings default to blanks.
-
- \file{Tools/scripts/diff.py} is a command-line front-end for this
- function.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{IS_LINE_JUNK}{line}
- Return true for ignorable lines. The line \var{line} is ignorable
- if \var{line} is blank or contains a single \character{\#},
- otherwise it is not ignorable. Used as a default for parameter
- \var{linejunk} in \function{ndiff()} before Python 2.3.
-\end{funcdesc}
-
-
-\begin{funcdesc}{IS_CHARACTER_JUNK}{ch}
- Return true for ignorable characters. The character \var{ch} is
- ignorable if \var{ch} is a space or tab, otherwise it is not
- ignorable. Used as a default for parameter \var{charjunk} in
- \function{ndiff()}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.ddj.com/184407970?pgno=5]
- {Pattern Matching: The Gestalt Approach}{Discussion of a
- similar algorithm by John W. Ratcliff and D. E. Metzener.
- This was published in
- \citetitle[http://www.ddj.com/]{Dr. Dobb's Journal} in
- July, 1988.}
-\end{seealso}
-
-
-\subsection{SequenceMatcher Objects \label{sequence-matcher}}
-
-The \class{SequenceMatcher} class has this constructor:
-
-\begin{classdesc}{SequenceMatcher}{\optional{isjunk\optional{,
- a\optional{, b}}}}
- Optional argument \var{isjunk} must be \code{None} (the default) or
- a one-argument function that takes a sequence element and returns
- true if and only if the element is ``junk'' and should be ignored.
- Passing \code{None} for \var{isjunk} is equivalent to passing
- \code{lambda x: 0}; in other words, no elements are ignored. For
- example, pass:
-
-\begin{verbatim}
-lambda x: x in " \t"
-\end{verbatim}
-
- if you're comparing lines as sequences of characters, and don't want
- to synch up on blanks or hard tabs.
-
- The optional arguments \var{a} and \var{b} are sequences to be
- compared; both default to empty strings. The elements of both
- sequences must be hashable.
-\end{classdesc}
-
-
-\class{SequenceMatcher} objects have the following methods:
-
-\begin{methoddesc}{set_seqs}{a, b}
- Set the two sequences to be compared.
-\end{methoddesc}
-
-\class{SequenceMatcher} computes and caches detailed information about
-the second sequence, so if you want to compare one sequence against
-many sequences, use \method{set_seq2()} to set the commonly used
-sequence once and call \method{set_seq1()} repeatedly, once for each
-of the other sequences.
-
-\begin{methoddesc}{set_seq1}{a}
- Set the first sequence to be compared. The second sequence to be
- compared is not changed.
-\end{methoddesc}
-
-\begin{methoddesc}{set_seq2}{b}
- Set the second sequence to be compared. The first sequence to be
- compared is not changed.
-\end{methoddesc}
-
-\begin{methoddesc}{find_longest_match}{alo, ahi, blo, bhi}
- Find longest matching block in \code{\var{a}[\var{alo}:\var{ahi}]}
- and \code{\var{b}[\var{blo}:\var{bhi}]}.
-
- If \var{isjunk} was omitted or \code{None},
- \method{get_longest_match()} returns \code{(\var{i}, \var{j},
- \var{k})} such that \code{\var{a}[\var{i}:\var{i}+\var{k}]} is equal
- to \code{\var{b}[\var{j}:\var{j}+\var{k}]}, where
- \code{\var{alo} <= \var{i} <= \var{i}+\var{k} <= \var{ahi}} and
- \code{\var{blo} <= \var{j} <= \var{j}+\var{k} <= \var{bhi}}.
- For all \code{(\var{i'}, \var{j'}, \var{k'})} meeting those
- conditions, the additional conditions
- \code{\var{k} >= \var{k'}},
- \code{\var{i} <= \var{i'}},
- and if \code{\var{i} == \var{i'}}, \code{\var{j} <= \var{j'}}
- are also met.
- In other words, of all maximal matching blocks, return one that
- starts earliest in \var{a}, and of all those maximal matching blocks
- that start earliest in \var{a}, return the one that starts earliest
- in \var{b}.
-
-\begin{verbatim}
->>> s = SequenceMatcher(None, " abcd", "abcd abcd")
->>> s.find_longest_match(0, 5, 0, 9)
-(0, 4, 5)
-\end{verbatim}
-
- If \var{isjunk} was provided, first the longest matching block is
- determined as above, but with the additional restriction that no
- junk element appears in the block. Then that block is extended as
- far as possible by matching (only) junk elements on both sides.
- So the resulting block never matches on junk except as identical
- junk happens to be adjacent to an interesting match.
-
- Here's the same example as before, but considering blanks to be junk.
- That prevents \code{' abcd'} from matching the \code{' abcd'} at the
- tail end of the second sequence directly. Instead only the
- \code{'abcd'} can match, and matches the leftmost \code{'abcd'} in
- the second sequence:
-
-\begin{verbatim}
->>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
->>> s.find_longest_match(0, 5, 0, 9)
-(1, 0, 4)
-\end{verbatim}
-
- If no blocks match, this returns \code{(\var{alo}, \var{blo}, 0)}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_matching_blocks}{}
- Return list of triples describing matching subsequences.
- Each triple is of the form \code{(\var{i}, \var{j}, \var{n})}, and
- means that \code{\var{a}[\var{i}:\var{i}+\var{n}] ==
- \var{b}[\var{j}:\var{j}+\var{n}]}. The triples are monotonically
- increasing in \var{i} and \var{j}.
-
- The last triple is a dummy, and has the value \code{(len(\var{a}),
- len(\var{b}), 0)}. It is the only triple with \code{\var{n} == 0}.
- % Explain why a dummy is used!
-
- If
- \code{(\var{i}, \var{j}, \var{n})} and
- \code{(\var{i'}, \var{j'}, \var{n'})} are adjacent triples in the list,
- and the second is not the last triple in the list, then
- \code{\var{i}+\var{n} != \var{i'}} or
- \code{\var{j}+\var{n} != \var{j'}}; in other words, adjacent triples
- always describe non-adjacent equal blocks.
- \versionchanged[The guarantee that adjacent triples always describe
- non-adjacent blocks was implemented]{2.5}
-
-\begin{verbatim}
->>> s = SequenceMatcher(None, "abxcd", "abcd")
->>> s.get_matching_blocks()
-[(0, 0, 2), (3, 2, 2), (5, 4, 0)]
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{get_opcodes}{}
- Return list of 5-tuples describing how to turn \var{a} into \var{b}.
- Each tuple is of the form \code{(\var{tag}, \var{i1}, \var{i2},
- \var{j1}, \var{j2})}. The first tuple has \code{\var{i1} ==
- \var{j1} == 0}, and remaining tuples have \var{i1} equal to the
- \var{i2} from the preceding tuple, and, likewise, \var{j1} equal to
- the previous \var{j2}.
-
- The \var{tag} values are strings, with these meanings:
-
-\begin{tableii}{l|l}{code}{Value}{Meaning}
- \lineii{'replace'}{\code{\var{a}[\var{i1}:\var{i2}]} should be
- replaced by \code{\var{b}[\var{j1}:\var{j2}]}.}
- \lineii{'delete'}{\code{\var{a}[\var{i1}:\var{i2}]} should be
- deleted. Note that \code{\var{j1} == \var{j2}} in
- this case.}
- \lineii{'insert'}{\code{\var{b}[\var{j1}:\var{j2}]} should be
- inserted at \code{\var{a}[\var{i1}:\var{i1}]}.
- Note that \code{\var{i1} == \var{i2}} in this
- case.}
- \lineii{'equal'}{\code{\var{a}[\var{i1}:\var{i2}] ==
- \var{b}[\var{j1}:\var{j2}]} (the sub-sequences are
- equal).}
-\end{tableii}
-
-For example:
-
-\begin{verbatim}
->>> a = "qabxcd"
->>> b = "abycdf"
->>> s = SequenceMatcher(None, a, b)
->>> for tag, i1, i2, j1, j2 in s.get_opcodes():
-... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
-... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
- delete a[0:1] (q) b[0:0] ()
- equal a[1:3] (ab) b[0:2] (ab)
-replace a[3:4] (x) b[2:3] (y)
- equal a[4:6] (cd) b[3:5] (cd)
- insert a[6:6] () b[5:6] (f)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}{get_grouped_opcodes}{\optional{n}}
- Return a generator of groups with up to \var{n} lines of context.
-
- Starting with the groups returned by \method{get_opcodes()},
- this method splits out smaller change clusters and eliminates
- intervening ranges which have no changes.
-
- The groups are returned in the same format as \method{get_opcodes()}.
- \versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}{ratio}{}
- Return a measure of the sequences' similarity as a float in the
- range [0, 1].
-
- Where T is the total number of elements in both sequences, and M is
- the number of matches, this is 2.0*M / T. Note that this is
- \code{1.0} if the sequences are identical, and \code{0.0} if they
- have nothing in common.
-
- This is expensive to compute if \method{get_matching_blocks()} or
- \method{get_opcodes()} hasn't already been called, in which case you
- may want to try \method{quick_ratio()} or
- \method{real_quick_ratio()} first to get an upper bound.
-\end{methoddesc}
-
-\begin{methoddesc}{quick_ratio}{}
- Return an upper bound on \method{ratio()} relatively quickly.
-
- This isn't defined beyond that it is an upper bound on
- \method{ratio()}, and is faster to compute.
-\end{methoddesc}
-
-\begin{methoddesc}{real_quick_ratio}{}
- Return an upper bound on \method{ratio()} very quickly.
-
- This isn't defined beyond that it is an upper bound on
- \method{ratio()}, and is faster to compute than either
- \method{ratio()} or \method{quick_ratio()}.
-\end{methoddesc}
-
-The three methods that return the ratio of matching to total characters
-can give different results due to differing levels of approximation,
-although \method{quick_ratio()} and \method{real_quick_ratio()} are always
-at least as large as \method{ratio()}:
-
-\begin{verbatim}
->>> s = SequenceMatcher(None, "abcd", "bcde")
->>> s.ratio()
-0.75
->>> s.quick_ratio()
-0.75
->>> s.real_quick_ratio()
-1.0
-\end{verbatim}
-
-
-\subsection{SequenceMatcher Examples \label{sequencematcher-examples}}
-
-
-This example compares two strings, considering blanks to be ``junk:''
-
-\begin{verbatim}
->>> s = SequenceMatcher(lambda x: x == " ",
-... "private Thread currentThread;",
-... "private volatile Thread currentThread;")
-\end{verbatim}
-
-\method{ratio()} returns a float in [0, 1], measuring the similarity
-of the sequences. As a rule of thumb, a \method{ratio()} value over
-0.6 means the sequences are close matches:
-
-\begin{verbatim}
->>> print round(s.ratio(), 3)
-0.866
-\end{verbatim}
-
-If you're only interested in where the sequences match,
-\method{get_matching_blocks()} is handy:
-
-\begin{verbatim}
->>> for block in s.get_matching_blocks():
-... print "a[%d] and b[%d] match for %d elements" % block
-a[0] and b[0] match for 8 elements
-a[8] and b[17] match for 6 elements
-a[14] and b[23] match for 15 elements
-a[29] and b[38] match for 0 elements
-\end{verbatim}
-
-Note that the last tuple returned by \method{get_matching_blocks()} is
-always a dummy, \code{(len(\var{a}), len(\var{b}), 0)}, and this is
-the only case in which the last tuple element (number of elements
-matched) is \code{0}.
-
-If you want to know how to change the first sequence into the second,
-use \method{get_opcodes()}:
-
-\begin{verbatim}
->>> for opcode in s.get_opcodes():
-... print "%6s a[%d:%d] b[%d:%d]" % opcode
- equal a[0:8] b[0:8]
-insert a[8:8] b[8:17]
- equal a[8:14] b[17:23]
- equal a[14:29] b[23:38]
-\end{verbatim}
-
-See also the function \function{get_close_matches()} in this module,
-which shows how simple code building on \class{SequenceMatcher} can be
-used to do useful work.
-
-
-\subsection{Differ Objects \label{differ-objects}}
-
-Note that \class{Differ}-generated deltas make no claim to be
-\strong{minimal} diffs. To the contrary, minimal diffs are often
-counter-intuitive, because they synch up anywhere possible, sometimes
-accidental matches 100 pages apart. Restricting synch points to
-contiguous matches preserves some notion of locality, at the
-occasional cost of producing a longer diff.
-
-The \class{Differ} class has this constructor:
-
-\begin{classdesc}{Differ}{\optional{linejunk\optional{, charjunk}}}
- Optional keyword parameters \var{linejunk} and \var{charjunk} are
- for filter functions (or \code{None}):
-
- \var{linejunk}: A function that accepts a single string
- argument, and returns true if the string is junk. The default is
- \code{None}, meaning that no line is considered junk.
-
- \var{charjunk}: A function that accepts a single character argument
- (a string of length 1), and returns true if the character is junk.
- The default is \code{None}, meaning that no character is
- considered junk.
-\end{classdesc}
-
-\class{Differ} objects are used (deltas generated) via a single
-method:
-
-\begin{methoddesc}{compare}{a, b}
- Compare two sequences of lines, and generate the delta (a sequence
- of lines).
-
- Each sequence must contain individual single-line strings ending
- with newlines. Such sequences can be obtained from the
- \method{readlines()} method of file-like objects. The delta generated
- also consists of newline-terminated strings, ready to be printed as-is
- via the \method{writelines()} method of a file-like object.
-\end{methoddesc}
-
-
-\subsection{Differ Example \label{differ-examples}}
-
-This example compares two texts. First we set up the texts, sequences
-of individual single-line strings ending with newlines (such sequences
-can also be obtained from the \method{readlines()} method of file-like
-objects):
-
-\begin{verbatim}
->>> text1 = ''' 1. Beautiful is better than ugly.
-... 2. Explicit is better than implicit.
-... 3. Simple is better than complex.
-... 4. Complex is better than complicated.
-... '''.splitlines(1)
->>> len(text1)
-4
->>> text1[0][-1]
-'\n'
->>> text2 = ''' 1. Beautiful is better than ugly.
-... 3. Simple is better than complex.
-... 4. Complicated is better than complex.
-... 5. Flat is better than nested.
-... '''.splitlines(1)
-\end{verbatim}
-
-Next we instantiate a Differ object:
-
-\begin{verbatim}
->>> d = Differ()
-\end{verbatim}
-
-Note that when instantiating a \class{Differ} object we may pass
-functions to filter out line and character ``junk.'' See the
-\method{Differ()} constructor for details.
-
-Finally, we compare the two:
-
-\begin{verbatim}
->>> result = list(d.compare(text1, text2))
-\end{verbatim}
-
-\code{result} is a list of strings, so let's pretty-print it:
-
-\begin{verbatim}
->>> from pprint import pprint
->>> pprint(result)
-[' 1. Beautiful is better than ugly.\n',
- '- 2. Explicit is better than implicit.\n',
- '- 3. Simple is better than complex.\n',
- '+ 3. Simple is better than complex.\n',
- '? ++ \n',
- '- 4. Complex is better than complicated.\n',
- '? ^ ---- ^ \n',
- '+ 4. Complicated is better than complex.\n',
- '? ++++ ^ ^ \n',
- '+ 5. Flat is better than nested.\n']
-\end{verbatim}
-
-As a single multi-line string it looks like this:
-
-\begin{verbatim}
->>> import sys
->>> sys.stdout.writelines(result)
- 1. Beautiful is better than ugly.
-- 2. Explicit is better than implicit.
-- 3. Simple is better than complex.
-+ 3. Simple is better than complex.
-? ++
-- 4. Complex is better than complicated.
-? ^ ---- ^
-+ 4. Complicated is better than complex.
-? ++++ ^ ^
-+ 5. Flat is better than nested.
-\end{verbatim}
diff --git a/Doc/lib/libdircache.tex b/Doc/lib/libdircache.tex
deleted file mode 100644
index 5884549..0000000
--- a/Doc/lib/libdircache.tex
+++ /dev/null
@@ -1,49 +0,0 @@
-\section{\module{dircache} ---
- Cached directory listings}
-
-\declaremodule{standard}{dircache}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Return directory listing, with cache mechanism.}
-
-The \module{dircache} module defines a function for reading directory listing
-using a cache, and cache invalidation using the \var{mtime} of the directory.
-Additionally, it defines a function to annotate directories by appending
-a slash.
-
-The \module{dircache} module defines the following functions:
-
-\begin{funcdesc}{reset}{}
-Resets the directory cache.
-\end{funcdesc}
-
-\begin{funcdesc}{listdir}{path}
-Return a directory listing of \var{path}, as gotten from
-\function{os.listdir()}. Note that unless \var{path} changes, further call
-to \function{listdir()} will not re-read the directory structure.
-
-Note that the list returned should be regarded as read-only. (Perhaps
-a future version should change it to return a tuple?)
-\end{funcdesc}
-
-\begin{funcdesc}{opendir}{path}
-Same as \function{listdir()}. Defined for backwards compatibility.
-\end{funcdesc}
-
-\begin{funcdesc}{annotate}{head, list}
-Assume \var{list} is a list of paths relative to \var{head}, and append,
-in place, a \character{/} to each path which points to a directory.
-\end{funcdesc}
-
-\begin{verbatim}
->>> import dircache
->>> a = dircache.listdir('/')
->>> a = a[:] # Copy the return value so we can change 'a'
->>> a
-['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
-found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
->>> dircache.annotate('/', a)
->>> a
-['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
-', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
-linuz']
-\end{verbatim}
diff --git a/Doc/lib/libdis.tex b/Doc/lib/libdis.tex
deleted file mode 100644
index 2d78d9a..0000000
--- a/Doc/lib/libdis.tex
+++ /dev/null
@@ -1,674 +0,0 @@
-\section{\module{dis} ---
- Disassembler for Python byte code}
-
-\declaremodule{standard}{dis}
-\modulesynopsis{Disassembler for Python byte code.}
-
-
-The \module{dis} module supports the analysis of Python byte code by
-disassembling it. Since there is no Python assembler, this module
-defines the Python assembly language. The Python byte code which
-this module takes as an input is defined in the file
-\file{Include/opcode.h} and used by the compiler and the interpreter.
-
-Example: Given the function \function{myfunc}:
-
-\begin{verbatim}
-def myfunc(alist):
- return len(alist)
-\end{verbatim}
-
-the following command can be used to get the disassembly of
-\function{myfunc()}:
-
-\begin{verbatim}
->>> dis.dis(myfunc)
- 2 0 LOAD_GLOBAL 0 (len)
- 3 LOAD_FAST 0 (alist)
- 6 CALL_FUNCTION 1
- 9 RETURN_VALUE
-\end{verbatim}
-
-(The ``2'' is a line number).
-
-The \module{dis} module defines the following functions and constants:
-
-\begin{funcdesc}{dis}{\optional{bytesource}}
-Disassemble the \var{bytesource} object. \var{bytesource} can denote
-either a module, a class, a method, a function, or a code object.
-For a module, it disassembles all functions. For a class,
-it disassembles all methods. For a single code sequence, it prints
-one line per byte code instruction. If no object is provided, it
-disassembles the last traceback.
-\end{funcdesc}
-
-\begin{funcdesc}{distb}{\optional{tb}}
-Disassembles the top-of-stack function of a traceback, using the last
-traceback if none was passed. The instruction causing the exception
-is indicated.
-\end{funcdesc}
-
-\begin{funcdesc}{disassemble}{code\optional{, lasti}}
-Disassembles a code object, indicating the last instruction if \var{lasti}
-was provided. The output is divided in the following columns:
-
-\begin{enumerate}
-\item the line number, for the first instruction of each line
-\item the current instruction, indicated as \samp{-->},
-\item a labelled instruction, indicated with \samp{>>},
-\item the address of the instruction,
-\item the operation code name,
-\item operation parameters, and
-\item interpretation of the parameters in parentheses.
-\end{enumerate}
-
-The parameter interpretation recognizes local and global
-variable names, constant values, branch targets, and compare
-operators.
-\end{funcdesc}
-
-\begin{funcdesc}{disco}{code\optional{, lasti}}
-A synonym for disassemble. It is more convenient to type, and kept
-for compatibility with earlier Python releases.
-\end{funcdesc}
-
-\begin{datadesc}{opname}
-Sequence of operation names, indexable using the byte code.
-\end{datadesc}
-
-\begin{datadesc}{opmap}
-Dictionary mapping byte codes to operation names.
-\end{datadesc}
-
-\begin{datadesc}{cmp_op}
-Sequence of all compare operation names.
-\end{datadesc}
-
-\begin{datadesc}{hasconst}
-Sequence of byte codes that have a constant parameter.
-\end{datadesc}
-
-\begin{datadesc}{hasfree}
-Sequence of byte codes that access a free variable.
-\end{datadesc}
-
-\begin{datadesc}{hasname}
-Sequence of byte codes that access an attribute by name.
-\end{datadesc}
-
-\begin{datadesc}{hasjrel}
-Sequence of byte codes that have a relative jump target.
-\end{datadesc}
-
-\begin{datadesc}{hasjabs}
-Sequence of byte codes that have an absolute jump target.
-\end{datadesc}
-
-\begin{datadesc}{haslocal}
-Sequence of byte codes that access a local variable.
-\end{datadesc}
-
-\begin{datadesc}{hascompare}
-Sequence of byte codes of Boolean operations.
-\end{datadesc}
-
-\subsection{Python Byte Code Instructions}
-\label{bytecodes}
-
-The Python compiler currently generates the following byte code
-instructions.
-
-\setindexsubitem{(byte code insns)}
-
-\begin{opcodedesc}{STOP_CODE}{}
-Indicates end-of-code to the compiler, not used by the interpreter.
-\end{opcodedesc}
-
-\begin{opcodedesc}{NOP}{}
-Do nothing code. Used as a placeholder by the bytecode optimizer.
-\end{opcodedesc}
-
-\begin{opcodedesc}{POP_TOP}{}
-Removes the top-of-stack (TOS) item.
-\end{opcodedesc}
-
-\begin{opcodedesc}{ROT_TWO}{}
-Swaps the two top-most stack items.
-\end{opcodedesc}
-
-\begin{opcodedesc}{ROT_THREE}{}
-Lifts second and third stack item one position up, moves top down
-to position three.
-\end{opcodedesc}
-
-\begin{opcodedesc}{ROT_FOUR}{}
-Lifts second, third and forth stack item one position up, moves top down to
-position four.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DUP_TOP}{}
-Duplicates the reference on top of the stack.
-\end{opcodedesc}
-
-Unary Operations take the top of the stack, apply the operation, and
-push the result back on the stack.
-
-\begin{opcodedesc}{UNARY_POSITIVE}{}
-Implements \code{TOS = +TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNARY_NEGATIVE}{}
-Implements \code{TOS = -TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNARY_NOT}{}
-Implements \code{TOS = not TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNARY_INVERT}{}
-Implements \code{TOS = \~{}TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{GET_ITER}{}
-Implements \code{TOS = iter(TOS)}.
-\end{opcodedesc}
-
-Binary operations remove the top of the stack (TOS) and the second top-most
-stack item (TOS1) from the stack. They perform the operation, and put the
-result back on the stack.
-
-\begin{opcodedesc}{BINARY_POWER}{}
-Implements \code{TOS = TOS1 ** TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_MULTIPLY}{}
-Implements \code{TOS = TOS1 * TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_FLOOR_DIVIDE}{}
-Implements \code{TOS = TOS1 // TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_TRUE_DIVIDE}{}
-Implements \code{TOS = TOS1 / TOS} when
-\code{from __future__ import division} is in effect.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_MODULO}{}
-Implements \code{TOS = TOS1 \%{} TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_ADD}{}
-Implements \code{TOS = TOS1 + TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_SUBTRACT}{}
-Implements \code{TOS = TOS1 - TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_SUBSCR}{}
-Implements \code{TOS = TOS1[TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_LSHIFT}{}
-Implements \code{TOS = TOS1 <\code{}< TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_RSHIFT}{}
-Implements \code{TOS = TOS1 >\code{}> TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_AND}{}
-Implements \code{TOS = TOS1 \&\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_XOR}{}
-Implements \code{TOS = TOS1 \^\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BINARY_OR}{}
-Implements \code{TOS = TOS1 | TOS}.
-\end{opcodedesc}
-
-In-place operations are like binary operations, in that they remove TOS and
-TOS1, and push the result back on the stack, but the operation is done
-in-place when TOS1 supports it, and the resulting TOS may be (but does not
-have to be) the original TOS1.
-
-\begin{opcodedesc}{INPLACE_POWER}{}
-Implements in-place \code{TOS = TOS1 ** TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_MULTIPLY}{}
-Implements in-place \code{TOS = TOS1 * TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_FLOOR_DIVIDE}{}
-Implements in-place \code{TOS = TOS1 // TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_TRUE_DIVIDE}{}
-Implements in-place \code{TOS = TOS1 / TOS} when
-\code{from __future__ import division} is in effect.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_MODULO}{}
-Implements in-place \code{TOS = TOS1 \%{} TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_ADD}{}
-Implements in-place \code{TOS = TOS1 + TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_SUBTRACT}{}
-Implements in-place \code{TOS = TOS1 - TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_LSHIFT}{}
-Implements in-place \code{TOS = TOS1 <\code{}< TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_RSHIFT}{}
-Implements in-place \code{TOS = TOS1 >\code{}> TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_AND}{}
-Implements in-place \code{TOS = TOS1 \&\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_XOR}{}
-Implements in-place \code{TOS = TOS1 \^\ TOS}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{INPLACE_OR}{}
-Implements in-place \code{TOS = TOS1 | TOS}.
-\end{opcodedesc}
-
-The slice opcodes take up to three parameters.
-
-\begin{opcodedesc}{SLICE+0}{}
-Implements \code{TOS = TOS[:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SLICE+1}{}
-Implements \code{TOS = TOS1[TOS:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SLICE+2}{}
-Implements \code{TOS = TOS1[:TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SLICE+3}{}
-Implements \code{TOS = TOS2[TOS1:TOS]}.
-\end{opcodedesc}
-
-Slice assignment needs even an additional parameter. As any statement,
-they put nothing on the stack.
-
-\begin{opcodedesc}{STORE_SLICE+0}{}
-Implements \code{TOS[:] = TOS1}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SLICE+1}{}
-Implements \code{TOS1[TOS:] = TOS2}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SLICE+2}{}
-Implements \code{TOS1[:TOS] = TOS2}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SLICE+3}{}
-Implements \code{TOS2[TOS1:TOS] = TOS3}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+0}{}
-Implements \code{del TOS[:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+1}{}
-Implements \code{del TOS1[TOS:]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+2}{}
-Implements \code{del TOS1[:TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SLICE+3}{}
-Implements \code{del TOS2[TOS1:TOS]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_SUBSCR}{}
-Implements \code{TOS1[TOS] = TOS2}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_SUBSCR}{}
-Implements \code{del TOS1[TOS]}.
-\end{opcodedesc}
-
-Miscellaneous opcodes.
-
-\begin{opcodedesc}{PRINT_EXPR}{}
-Implements the expression statement for the interactive mode. TOS is
-removed from the stack and printed. In non-interactive mode, an
-expression statement is terminated with \code{POP_STACK}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BREAK_LOOP}{}
-Terminates a loop due to a \keyword{break} statement.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CONTINUE_LOOP}{target}
-Continues a loop due to a \keyword{continue} statement. \var{target}
-is the address to jump to (which should be a \code{FOR_ITER}
-instruction).
-\end{opcodedesc}
-
-\begin{opcodedesc}{SET_ADD}{}
-Calls \code{set.add(TOS1, TOS)}. Used to implement set comprehensions.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LIST_APPEND}{}
-Calls \code{list.append(TOS1, TOS)}. Used to implement list comprehensions.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_LOCALS}{}
-Pushes a reference to the locals of the current scope on the stack.
-This is used in the code for a class definition: After the class body
-is evaluated, the locals are passed to the class definition.
-\end{opcodedesc}
-
-\begin{opcodedesc}{RETURN_VALUE}{}
-Returns with TOS to the caller of the function.
-\end{opcodedesc}
-
-\begin{opcodedesc}{YIELD_VALUE}{}
-Pops \code{TOS} and yields it from a generator.
-\end{opcodedesc}
-
-\begin{opcodedesc}{IMPORT_STAR}{}
-Loads all symbols not starting with \character{_} directly from the module TOS
-to the local namespace. The module is popped after loading all names.
-This opcode implements \code{from module import *}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{POP_BLOCK}{}
-Removes one block from the block stack. Per frame, there is a
-stack of blocks, denoting nested loops, try statements, and such.
-\end{opcodedesc}
-
-\begin{opcodedesc}{END_FINALLY}{}
-Terminates a \keyword{finally} clause. The interpreter recalls
-whether the exception has to be re-raised, or whether the function
-returns, and continues with the outer-next block.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_CLASS}{}
-Creates a new class object. TOS is the methods dictionary, TOS1
-the tuple of the names of the base classes, and TOS2 the class name.
-\end{opcodedesc}
-
-All of the following opcodes expect arguments. An argument is two
-bytes, with the more significant byte last.
-
-\begin{opcodedesc}{STORE_NAME}{namei}
-Implements \code{name = TOS}. \var{namei} is the index of \var{name}
-in the attribute \member{co_names} of the code object.
-The compiler tries to use \code{STORE_LOCAL} or \code{STORE_GLOBAL}
-if possible.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_NAME}{namei}
-Implements \code{del name}, where \var{namei} is the index into
-\member{co_names} attribute of the code object.
-\end{opcodedesc}
-
-\begin{opcodedesc}{UNPACK_SEQUENCE}{count}
-Unpacks TOS into \var{count} individual values, which are put onto
-the stack right-to-left.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{UNPACK_LIST}{count}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-%\begin{opcodedesc}{UNPACK_ARG}{count}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{DUP_TOPX}{count}
-Duplicate \var{count} items, keeping them in the same order. Due to
-implementation limits, \var{count} should be between 1 and 5 inclusive.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_ATTR}{namei}
-Implements \code{TOS.name = TOS1}, where \var{namei} is the index
-of name in \member{co_names}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_ATTR}{namei}
-Implements \code{del TOS.name}, using \var{namei} as index into
-\member{co_names}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_GLOBAL}{namei}
-Works as \code{STORE_NAME}, but stores the name as a global.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_GLOBAL}{namei}
-Works as \code{DELETE_NAME}, but deletes a global name.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{UNPACK_VARARG}{argc}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_CONST}{consti}
-Pushes \samp{co_consts[\var{consti}]} onto the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_NAME}{namei}
-Pushes the value associated with \samp{co_names[\var{namei}]} onto the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_TUPLE}{count}
-Creates a tuple consuming \var{count} items from the stack, and pushes
-the resulting tuple onto the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_LIST}{count}
-Works as \code{BUILD_TUPLE}, but creates a list.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_SET}{count}
-Works as \code{BUILD_TUPLE}, but creates a set.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_MAP}{zero}
-Pushes a new empty dictionary object onto the stack. The argument is
-ignored and set to zero by the compiler.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_ATTR}{namei}
-Replaces TOS with \code{getattr(TOS, co_names[\var{namei}])}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{COMPARE_OP}{opname}
-Performs a Boolean operation. The operation name can be found
-in \code{cmp_op[\var{opname}]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{IMPORT_NAME}{namei}
-Imports the module \code{co_names[\var{namei}]}. The module object is
-pushed onto the stack. The current namespace is not affected: for a
-proper import statement, a subsequent \code{STORE_FAST} instruction
-modifies the namespace.
-\end{opcodedesc}
-
-\begin{opcodedesc}{IMPORT_FROM}{namei}
-Loads the attribute \code{co_names[\var{namei}]} from the module found in
-TOS. The resulting object is pushed onto the stack, to be subsequently
-stored by a \code{STORE_FAST} instruction.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_FORWARD}{delta}
-Increments byte code counter by \var{delta}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_IF_TRUE}{delta}
-If TOS is true, increment the byte code counter by \var{delta}. TOS is
-left on the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_IF_FALSE}{delta}
-If TOS is false, increment the byte code counter by \var{delta}. TOS
-is not changed.
-\end{opcodedesc}
-
-\begin{opcodedesc}{JUMP_ABSOLUTE}{target}
-Set byte code counter to \var{target}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{FOR_ITER}{delta}
- \code{TOS} is an iterator. Call its \method{__next__()} method. If this
- yields a new value, push it on the stack (leaving the iterator below it). If
- the iterator indicates it is exhausted \code{TOS} is popped, and the byte code
- counter is incremented by \var{delta}.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{FOR_LOOP}{delta}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-%\begin{opcodedesc}{LOAD_LOCAL}{namei}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_GLOBAL}{namei}
-Loads the global named \code{co_names[\var{namei}]} onto the stack.
-\end{opcodedesc}
-
-%\begin{opcodedesc}{SET_FUNC_ARGS}{argc}
-%This opcode is obsolete.
-%\end{opcodedesc}
-
-\begin{opcodedesc}{SETUP_LOOP}{delta}
-Pushes a block for a loop onto the block stack. The block spans
-from the current instruction with a size of \var{delta} bytes.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SETUP_EXCEPT}{delta}
-Pushes a try block from a try-except clause onto the block stack.
-\var{delta} points to the first except block.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SETUP_FINALLY}{delta}
-Pushes a try block from a try-except clause onto the block stack.
-\var{delta} points to the finally block.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_FAST}{var_num}
-Pushes a reference to the local \code{co_varnames[\var{var_num}]} onto
-the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_FAST}{var_num}
-Stores TOS into the local \code{co_varnames[\var{var_num}]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{DELETE_FAST}{var_num}
-Deletes local \code{co_varnames[\var{var_num}]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_CLOSURE}{i}
-Pushes a reference to the cell contained in slot \var{i} of the
-cell and free variable storage. The name of the variable is
-\code{co_cellvars[\var{i}]} if \var{i} is less than the length of
-\var{co_cellvars}. Otherwise it is
-\code{co_freevars[\var{i} - len(co_cellvars)]}.
-\end{opcodedesc}
-
-\begin{opcodedesc}{LOAD_DEREF}{i}
-Loads the cell contained in slot \var{i} of the cell and free variable
-storage. Pushes a reference to the object the cell contains on the
-stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{STORE_DEREF}{i}
-Stores TOS into the cell contained in slot \var{i} of the cell and
-free variable storage.
-\end{opcodedesc}
-
-\begin{opcodedesc}{SET_LINENO}{lineno}
-This opcode is obsolete.
-\end{opcodedesc}
-
-\begin{opcodedesc}{RAISE_VARARGS}{argc}
-Raises an exception. \var{argc} indicates the number of parameters
-to the raise statement, ranging from 0 to 3. The handler will find
-the traceback as TOS2, the parameter as TOS1, and the exception
-as TOS.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION}{argc}
-Calls a function. The low byte of \var{argc} indicates the number of
-positional parameters, the high byte the number of keyword parameters.
-On the stack, the opcode finds the keyword parameters first. For each
-keyword argument, the value is on top of the key. Below the keyword
-parameters, the positional parameters are on the stack, with the
-right-most parameter on top. Below the parameters, the function object
-to call is on the stack.
-\end{opcodedesc}
-
-\begin{opcodedesc}{MAKE_FUNCTION}{argc}
-Pushes a new function object on the stack. TOS is the code associated
-with the function. The function object is defined to have \var{argc}
-default parameters, which are found below TOS.
-\end{opcodedesc}
-
-\begin{opcodedesc}{MAKE_CLOSURE}{argc}
-Creates a new function object, sets its \var{__closure__} slot, and
-pushes it on the stack. TOS is the code associated with the function.
-If the code object has N free variables, the next N items on the stack
-are the cells for these variables. The function also has \var{argc}
-default parameters, where are found before the cells.
-\end{opcodedesc}
-
-\begin{opcodedesc}{BUILD_SLICE}{argc}
-Pushes a slice object on the stack. \var{argc} must be 2 or 3. If it
-is 2, \code{slice(TOS1, TOS)} is pushed; if it is 3,
-\code{slice(TOS2, TOS1, TOS)} is pushed.
-See the \code{slice()}\bifuncindex{slice} built-in function for more
-information.
-\end{opcodedesc}
-
-\begin{opcodedesc}{EXTENDED_ARG}{ext}
-Prefixes any opcode which has an argument too big to fit into the
-default two bytes. \var{ext} holds two additional bytes which, taken
-together with the subsequent opcode's argument, comprise a four-byte
-argument, \var{ext} being the two most-significant bytes.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION_VAR}{argc}
-Calls a function. \var{argc} is interpreted as in \code{CALL_FUNCTION}.
-The top element on the stack contains the variable argument list, followed
-by keyword and positional arguments.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION_KW}{argc}
-Calls a function. \var{argc} is interpreted as in \code{CALL_FUNCTION}.
-The top element on the stack contains the keyword arguments dictionary,
-followed by explicit keyword and positional arguments.
-\end{opcodedesc}
-
-\begin{opcodedesc}{CALL_FUNCTION_VAR_KW}{argc}
-Calls a function. \var{argc} is interpreted as in
-\code{CALL_FUNCTION}. The top element on the stack contains the
-keyword arguments dictionary, followed by the variable-arguments
-tuple, followed by explicit keyword and positional arguments.
-\end{opcodedesc}
-
-\begin{opcodedesc}{HAVE_ARGUMENT}{}
-This is not really an opcode. It identifies the dividing line between
-opcodes which don't take arguments \code{< HAVE_ARGUMENT} and those which do
-\code{>= HAVE_ARGUMENT}.
-\end{opcodedesc}
diff --git a/Doc/lib/libdl.tex b/Doc/lib/libdl.tex
deleted file mode 100644
index d4a799e..0000000
--- a/Doc/lib/libdl.tex
+++ /dev/null
@@ -1,101 +0,0 @@
-\section{\module{dl} ---
- Call C functions in shared objects}
-\declaremodule{extension}{dl}
- \platform{Unix} %?????????? Anyone????????????
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Call C functions in shared objects.}
-
-The \module{dl} module defines an interface to the
-\cfunction{dlopen()} function, which is the most common interface on
-\UNIX{} platforms for handling dynamically linked libraries. It allows
-the program to call arbitrary functions in such a library.
-
-\warning{The \module{dl} module bypasses the Python type system and
-error handling. If used incorrectly it may cause segmentation faults,
-crashes or other incorrect behaviour.}
-
-\note{This module will not work unless
-\code{sizeof(int) == sizeof(long) == sizeof(char *)}
-If this is not the case, \exception{SystemError} will be raised on
-import.}
-
-The \module{dl} module defines the following function:
-
-\begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}}
-Open a shared object file, and return a handle. Mode
-signifies late binding (\constant{RTLD_LAZY}) or immediate binding
-(\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some
-systems do not support \constant{RTLD_NOW}.
-
-Return value is a \class{dlobject}.
-\end{funcdesc}
-
-The \module{dl} module defines the following constants:
-
-\begin{datadesc}{RTLD_LAZY}
-Useful as an argument to \function{open()}.
-\end{datadesc}
-
-\begin{datadesc}{RTLD_NOW}
-Useful as an argument to \function{open()}. Note that on systems
-which do not support immediate binding, this constant will not appear
-in the module. For maximum portability, use \function{hasattr()} to
-determine if the system supports immediate binding.
-\end{datadesc}
-
-The \module{dl} module defines the following exception:
-
-\begin{excdesc}{error}
-Exception raised when an error has occurred inside the dynamic loading
-and linking routines.
-\end{excdesc}
-
-Example:
-
-\begin{verbatim}
->>> import dl, time
->>> a=dl.open('/lib/libc.so.6')
->>> a.call('time'), time.time()
-(929723914, 929723914.498)
-\end{verbatim}
-
-This example was tried on a Debian GNU/Linux system, and is a good
-example of the fact that using this module is usually a bad alternative.
-
-\subsection{Dl Objects \label{dl-objects}}
-
-Dl objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[dl]{close}{}
-Free all resources, except the memory.
-\end{methoddesc}
-
-\begin{methoddesc}[dl]{sym}{name}
-Return the pointer for the function named \var{name}, as a number, if
-it exists in the referenced shared object, otherwise \code{None}. This
-is useful in code like:
-
-\begin{verbatim}
->>> if a.sym('time'):
-... a.call('time')
-... else:
-... time.time()
-\end{verbatim}
-
-(Note that this function will return a non-zero number, as zero is the
-\NULL{} pointer)
-\end{methoddesc}
-
-\begin{methoddesc}[dl]{call}{name\optional{, arg1\optional{, arg2\ldots}}}
-Call the function named \var{name} in the referenced shared object.
-The arguments must be either Python integers, which will be
-passed as is, Python strings, to which a pointer will be passed,
-or \code{None}, which will be passed as \NULL. Note that
-strings should only be passed to functions as \ctype{const char*}, as
-Python will not like its string mutated.
-
-There must be at most 10 arguments, and arguments not given will be
-treated as \code{None}. The function's return value must be a C
-\ctype{long}, which is a Python integer.
-\end{methoddesc}
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
deleted file mode 100644
index 9143b84..0000000
--- a/Doc/lib/libdoctest.tex
+++ /dev/null
@@ -1,1974 +0,0 @@
-\section{\module{doctest} ---
- Test interactive Python examples}
-
-\declaremodule{standard}{doctest}
-\moduleauthor{Tim Peters}{tim@python.org}
-\sectionauthor{Tim Peters}{tim@python.org}
-\sectionauthor{Moshe Zadka}{moshez@debian.org}
-\sectionauthor{Edward Loper}{edloper@users.sourceforge.net}
-
-\modulesynopsis{A framework for verifying interactive Python examples.}
-
-The \refmodule{doctest} module searches for pieces of text that look like
-interactive Python sessions, and then executes those sessions to
-verify that they work exactly as shown. There are several common ways to
-use doctest:
-
-\begin{itemize}
-\item To check that a module's docstrings are up-to-date by verifying
- that all interactive examples still work as documented.
-\item To perform regression testing by verifying that interactive
- examples from a test file or a test object work as expected.
-\item To write tutorial documentation for a package, liberally
- illustrated with input-output examples. Depending on whether
- the examples or the expository text are emphasized, this has
- the flavor of "literate testing" or "executable documentation".
-\end{itemize}
-
-Here's a complete but small example module:
-
-\begin{verbatim}
-"""
-This is the "example" module.
-
-The example module supplies one function, factorial(). For example,
-
->>> factorial(5)
-120
-"""
-
-def factorial(n):
- """Return the factorial of n, an exact integer >= 0.
-
- If the result is small enough to fit in an int, return an int.
- Else return a long.
-
- >>> [factorial(n) for n in range(6)]
- [1, 1, 2, 6, 24, 120]
- >>> [factorial(long(n)) for n in range(6)]
- [1, 1, 2, 6, 24, 120]
- >>> factorial(30)
- 265252859812191058636308480000000L
- >>> factorial(30L)
- 265252859812191058636308480000000L
- >>> factorial(-1)
- Traceback (most recent call last):
- ...
- ValueError: n must be >= 0
-
- Factorials of floats are OK, but the float must be an exact integer:
- >>> factorial(30.1)
- Traceback (most recent call last):
- ...
- ValueError: n must be exact integer
- >>> factorial(30.0)
- 265252859812191058636308480000000L
-
- It must also not be ridiculously large:
- >>> factorial(1e100)
- Traceback (most recent call last):
- ...
- OverflowError: n too large
- """
-
-\end{verbatim}
-% allow LaTeX to break here.
-\begin{verbatim}
-
- import math
- if not n >= 0:
- raise ValueError("n must be >= 0")
- if math.floor(n) != n:
- raise ValueError("n must be exact integer")
- if n+1 == n: # catch a value like 1e300
- raise OverflowError("n too large")
- result = 1
- factor = 2
- while factor <= n:
- result *= factor
- factor += 1
- return result
-
-def _test():
- import doctest
- doctest.testmod()
-
-if __name__ == "__main__":
- _test()
-\end{verbatim}
-
-If you run \file{example.py} directly from the command line,
-\refmodule{doctest} works its magic:
-
-\begin{verbatim}
-$ python example.py
-$
-\end{verbatim}
-
-There's no output! That's normal, and it means all the examples
-worked. Pass \programopt{-v} to the script, and \refmodule{doctest}
-prints a detailed log of what it's trying, and prints a summary at the
-end:
-
-\begin{verbatim}
-$ python example.py -v
-Trying:
- factorial(5)
-Expecting:
- 120
-ok
-Trying:
- [factorial(n) for n in range(6)]
-Expecting:
- [1, 1, 2, 6, 24, 120]
-ok
-Trying:
- [factorial(long(n)) for n in range(6)]
-Expecting:
- [1, 1, 2, 6, 24, 120]
-ok
-\end{verbatim}
-
-And so on, eventually ending with:
-
-\begin{verbatim}
-Trying:
- factorial(1e100)
-Expecting:
- Traceback (most recent call last):
- ...
- OverflowError: n too large
-ok
-1 items had no tests:
- __main__._test
-2 items passed all tests:
- 1 tests in __main__
- 8 tests in __main__.factorial
-9 tests in 3 items.
-9 passed and 0 failed.
-Test passed.
-$
-\end{verbatim}
-
-That's all you need to know to start making productive use of
-\refmodule{doctest}! Jump in. The following sections provide full
-details. Note that there are many examples of doctests in
-the standard Python test suite and libraries. Especially useful examples
-can be found in the standard test file \file{Lib/test/test_doctest.py}.
-
-\subsection{Simple Usage: Checking Examples in
- Docstrings\label{doctest-simple-testmod}}
-
-The simplest way to start using doctest (but not necessarily the way
-you'll continue to do it) is to end each module \module{M} with:
-
-\begin{verbatim}
-def _test():
- import doctest
- doctest.testmod()
-
-if __name__ == "__main__":
- _test()
-\end{verbatim}
-
-\refmodule{doctest} then examines docstrings in module \module{M}.
-
-Running the module as a script causes the examples in the docstrings
-to get executed and verified:
-
-\begin{verbatim}
-python M.py
-\end{verbatim}
-
-This won't display anything unless an example fails, in which case the
-failing example(s) and the cause(s) of the failure(s) are printed to stdout,
-and the final line of output is
-\samp{***Test Failed*** \var{N} failures.}, where \var{N} is the
-number of examples that failed.
-
-Run it with the \programopt{-v} switch instead:
-
-\begin{verbatim}
-python M.py -v
-\end{verbatim}
-
-and a detailed report of all examples tried is printed to standard
-output, along with assorted summaries at the end.
-
-You can force verbose mode by passing \code{verbose=True} to
-\function{testmod()}, or
-prohibit it by passing \code{verbose=False}. In either of those cases,
-\code{sys.argv} is not examined by \function{testmod()} (so passing
-\programopt{-v} or not has no effect).
-
-Since Python 2.6, there is also a command line shortcut for running
-\function{testmod()}. You can instruct the Python interpreter to run
-the doctest module directly from the standard library and pass the module
-name(s) on the command line:
-
-\begin{verbatim}
-python -m doctest -v example.py
-\end{verbatim}
-
-This will import \file{example.py} as a standalone module and run
-\function{testmod()} on it. Note that this may not work correctly if the
-file is part of a package and imports other submodules from that package.
-
-For more information on \function{testmod()}, see
-section~\ref{doctest-basic-api}.
-
-\subsection{Simple Usage: Checking Examples in a Text
- File\label{doctest-simple-testfile}}
-
-Another simple application of doctest is testing interactive examples
-in a text file. This can be done with the \function{testfile()}
-function:
-
-\begin{verbatim}
-import doctest
-doctest.testfile("example.txt")
-\end{verbatim}
-
-That short script executes and verifies any interactive Python
-examples contained in the file \file{example.txt}. The file content
-is treated as if it were a single giant docstring; the file doesn't
-need to contain a Python program! For example, perhaps \file{example.txt}
-contains this:
-
-\begin{verbatim}
-The ``example`` module
-======================
-
-Using ``factorial``
--------------------
-
-This is an example text file in reStructuredText format. First import
-``factorial`` from the ``example`` module:
-
- >>> from example import factorial
-
-Now use it:
-
- >>> factorial(6)
- 120
-\end{verbatim}
-
-Running \code{doctest.testfile("example.txt")} then finds the error
-in this documentation:
-
-\begin{verbatim}
-File "./example.txt", line 14, in example.txt
-Failed example:
- factorial(6)
-Expected:
- 120
-Got:
- 720
-\end{verbatim}
-
-As with \function{testmod()}, \function{testfile()} won't display anything
-unless an example fails. If an example does fail, then the failing
-example(s) and the cause(s) of the failure(s) are printed to stdout, using
-the same format as \function{testmod()}.
-
-By default, \function{testfile()} looks for files in the calling
-module's directory. See section~\ref{doctest-basic-api} for a
-description of the optional arguments that can be used to tell it to
-look for files in other locations.
-
-Like \function{testmod()}, \function{testfile()}'s verbosity can be
-set with the \programopt{-v} command-line switch or with the optional
-keyword argument \var{verbose}.
-
-Since Python 2.6, there is also a command line shortcut for running
-\function{testfile()}. You can instruct the Python interpreter to run
-the doctest module directly from the standard library and pass the file
-name(s) on the command line:
-
-\begin{verbatim}
-python -m doctest -v example.txt
-\end{verbatim}
-
-Because the file name does not end with \file{.py}, \module{doctest} infers
-that it must be run with \function{testfile()}, not \function{testmod()}.
-
-For more information on \function{testfile()}, see
-section~\ref{doctest-basic-api}.
-
-\subsection{How It Works\label{doctest-how-it-works}}
-
-This section examines in detail how doctest works: which docstrings it
-looks at, how it finds interactive examples, what execution context it
-uses, how it handles exceptions, and how option flags can be used to
-control its behavior. This is the information that you need to know
-to write doctest examples; for information about actually running
-doctest on these examples, see the following sections.
-
-\subsubsection{Which Docstrings Are Examined?\label{doctest-which-docstrings}}
-
-The module docstring, and all function, class and method docstrings are
-searched. Objects imported into the module are not searched.
-
-In addition, if \code{M.__test__} exists and "is true", it must be a
-dict, and each entry maps a (string) name to a function object, class
-object, or string. Function and class object docstrings found from
-\code{M.__test__} are searched, and strings are treated as if they
-were docstrings. In output, a key \code{K} in \code{M.__test__} appears
-with name
-
-\begin{verbatim}
-<name of M>.__test__.K
-\end{verbatim}
-
-Any classes found are recursively searched similarly, to test docstrings in
-their contained methods and nested classes.
-
-\versionchanged[A "private name" concept is deprecated and no longer
- documented]{2.4}
-
-\subsubsection{How are Docstring Examples
- Recognized?\label{doctest-finding-examples}}
-
-In most cases a copy-and-paste of an interactive console session works
-fine, but doctest isn't trying to do an exact emulation of any specific
-Python shell. All hard tab characters are expanded to spaces, using
-8-column tab stops. If you don't believe tabs should mean that, too
-bad: don't use hard tabs, or write your own \class{DocTestParser}
-class.
-
-\versionchanged[Expanding tabs to spaces is new; previous versions
- tried to preserve hard tabs, with confusing results]{2.4}
-
-\begin{verbatim}
->>> # comments are ignored
->>> x = 12
->>> x
-12
->>> if x == 13:
-... print "yes"
-... else:
-... print "no"
-... print "NO"
-... print "NO!!!"
-...
-no
-NO
-NO!!!
->>>
-\end{verbatim}
-
-Any expected output must immediately follow the final
-\code{'>>>~'} or \code{'...~'} line containing the code, and
-the expected output (if any) extends to the next \code{'>>>~'}
-or all-whitespace line.
-
-The fine print:
-
-\begin{itemize}
-
-\item Expected output cannot contain an all-whitespace line, since such a
- line is taken to signal the end of expected output. If expected
- output does contain a blank line, put \code{<BLANKLINE>} in your
- doctest example each place a blank line is expected.
- \versionchanged[\code{<BLANKLINE>} was added; there was no way to
- use expected output containing empty lines in
- previous versions]{2.4}
-
-\item Output to stdout is captured, but not output to stderr (exception
- tracebacks are captured via a different means).
-
-\item If you continue a line via backslashing in an interactive session,
- or for any other reason use a backslash, you should use a raw
- docstring, which will preserve your backslashes exactly as you type
- them:
-
-\begin{verbatim}
->>> def f(x):
-... r'''Backslashes in a raw docstring: m\n'''
->>> print f.__doc__
-Backslashes in a raw docstring: m\n
-\end{verbatim}
-
- Otherwise, the backslash will be interpreted as part of the string.
- For example, the "{\textbackslash}" above would be interpreted as a
- newline character. Alternatively, you can double each backslash in the
- doctest version (and not use a raw string):
-
-\begin{verbatim}
->>> def f(x):
-... '''Backslashes in a raw docstring: m\\n'''
->>> print f.__doc__
-Backslashes in a raw docstring: m\n
-\end{verbatim}
-
-\item The starting column doesn't matter:
-
-\begin{verbatim}
- >>> assert "Easy!"
- >>> import math
- >>> math.floor(1.9)
- 1.0
-\end{verbatim}
-
-and as many leading whitespace characters are stripped from the
-expected output as appeared in the initial \code{'>>>~'} line
-that started the example.
-\end{itemize}
-
-\subsubsection{What's the Execution Context?\label{doctest-execution-context}}
-
-By default, each time \refmodule{doctest} finds a docstring to test, it
-uses a \emph{shallow copy} of \module{M}'s globals, so that running tests
-doesn't change the module's real globals, and so that one test in
-\module{M} can't leave behind crumbs that accidentally allow another test
-to work. This means examples can freely use any names defined at top-level
-in \module{M}, and names defined earlier in the docstring being run.
-Examples cannot see names defined in other docstrings.
-
-You can force use of your own dict as the execution context by passing
-\code{globs=your_dict} to \function{testmod()} or
-\function{testfile()} instead.
-
-\subsubsection{What About Exceptions?\label{doctest-exceptions}}
-
-No problem, provided that the traceback is the only output produced by
-the example: just paste in the traceback.\footnote{Examples containing
- both expected output and an exception are not supported. Trying
- to guess where one ends and the other begins is too error-prone,
- and that also makes for a confusing test.}
-Since tracebacks contain details that are likely to change rapidly (for
-example, exact file paths and line numbers), this is one case where doctest
-works hard to be flexible in what it accepts.
-
-Simple example:
-
-\begin{verbatim}
->>> [1, 2, 3].remove(42)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: list.remove(x): x not in list
-\end{verbatim}
-
-That doctest succeeds if \exception{ValueError} is raised, with the
-\samp{list.remove(x): x not in list} detail as shown.
-
-The expected output for an exception must start with a traceback
-header, which may be either of the following two lines, indented the
-same as the first line of the example:
-
-\begin{verbatim}
-Traceback (most recent call last):
-Traceback (innermost last):
-\end{verbatim}
-
-The traceback header is followed by an optional traceback stack, whose
-contents are ignored by doctest. The traceback stack is typically
-omitted, or copied verbatim from an interactive session.
-
-The traceback stack is followed by the most interesting part: the
-line(s) containing the exception type and detail. This is usually the
-last line of a traceback, but can extend across multiple lines if the
-exception has a multi-line detail:
-
-\begin{verbatim}
->>> raise ValueError('multi\n line\ndetail')
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: multi
- line
-detail
-\end{verbatim}
-
-The last three lines (starting with \exception{ValueError}) are
-compared against the exception's type and detail, and the rest are
-ignored.
-
-Best practice is to omit the traceback stack, unless it adds
-significant documentation value to the example. So the last example
-is probably better as:
-
-\begin{verbatim}
->>> raise ValueError('multi\n line\ndetail')
-Traceback (most recent call last):
- ...
-ValueError: multi
- line
-detail
-\end{verbatim}
-
-Note that tracebacks are treated very specially. In particular, in the
-rewritten example, the use of \samp{...} is independent of doctest's
-\constant{ELLIPSIS} option. The ellipsis in that example could be left
-out, or could just as well be three (or three hundred) commas or digits,
-or an indented transcript of a Monty Python skit.
-
-Some details you should read once, but won't need to remember:
-
-\begin{itemize}
-
-\item Doctest can't guess whether your expected output came from an
- exception traceback or from ordinary printing. So, e.g., an example
- that expects \samp{ValueError: 42 is prime} will pass whether
- \exception{ValueError} is actually raised or if the example merely
- prints that traceback text. In practice, ordinary output rarely begins
- with a traceback header line, so this doesn't create real problems.
-
-\item Each line of the traceback stack (if present) must be indented
- further than the first line of the example, \emph{or} start with a
- non-alphanumeric character. The first line following the traceback
- header indented the same and starting with an alphanumeric is taken
- to be the start of the exception detail. Of course this does the
- right thing for genuine tracebacks.
-
-\item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is
- is specified, everything following the leftmost colon is ignored.
-
-\item The interactive shell omits the traceback header line for some
- \exception{SyntaxError}s. But doctest uses the traceback header
- line to distinguish exceptions from non-exceptions. So in the rare
- case where you need to test a \exception{SyntaxError} that omits the
- traceback header, you will need to manually add the traceback header
- line to your test example.
-
-\item For some \exception{SyntaxError}s, Python displays the character
- position of the syntax error, using a \code{\^} marker:
-
-\begin{verbatim}
->>> 1 1
- File "<stdin>", line 1
- 1 1
- ^
-SyntaxError: invalid syntax
-\end{verbatim}
-
- Since the lines showing the position of the error come before the
- exception type and detail, they are not checked by doctest. For
- example, the following test would pass, even though it puts the
- \code{\^} marker in the wrong location:
-
-\begin{verbatim}
->>> 1 1
-Traceback (most recent call last):
- File "<stdin>", line 1
- 1 1
- ^
-SyntaxError: invalid syntax
-\end{verbatim}
-
-\end{itemize}
-
-\versionchanged[The ability to handle a multi-line exception detail,
- and the \constant{IGNORE_EXCEPTION_DETAIL} doctest option,
- were added]{2.4}
-
-\subsubsection{Option Flags and Directives\label{doctest-options}}
-
-A number of option flags control various aspects of doctest's
-behavior. Symbolic names for the flags are supplied as module constants,
-which can be or'ed together and passed to various functions. The names
-can also be used in doctest directives (see below).
-
-The first group of options define test semantics, controlling
-aspects of how doctest decides whether actual output matches an
-example's expected output:
-
-\begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
- By default, if an expected output block contains just \code{1},
- an actual output block containing just \code{1} or just
- \code{True} is considered to be a match, and similarly for \code{0}
- versus \code{False}. When \constant{DONT_ACCEPT_TRUE_FOR_1} is
- specified, neither substitution is allowed. The default behavior
- caters to that Python changed the return type of many functions
- from integer to boolean; doctests expecting "little integer"
- output still work in these cases. This option will probably go
- away, but not for several years.
-\end{datadesc}
-
-\begin{datadesc}{DONT_ACCEPT_BLANKLINE}
- By default, if an expected output block contains a line
- containing only the string \code{<BLANKLINE>}, then that line
- will match a blank line in the actual output. Because a
- genuinely blank line delimits the expected output, this is
- the only way to communicate that a blank line is expected. When
- \constant{DONT_ACCEPT_BLANKLINE} is specified, this substitution
- is not allowed.
-\end{datadesc}
-
-\begin{datadesc}{NORMALIZE_WHITESPACE}
- When specified, all sequences of whitespace (blanks and newlines) are
- treated as equal. Any sequence of whitespace within the expected
- output will match any sequence of whitespace within the actual output.
- By default, whitespace must match exactly.
- \constant{NORMALIZE_WHITESPACE} is especially useful when a line
- of expected output is very long, and you want to wrap it across
- multiple lines in your source.
-\end{datadesc}
-
-\begin{datadesc}{ELLIPSIS}
- When specified, an ellipsis marker (\code{...}) in the expected output
- can match any substring in the actual output. This includes
- substrings that span line boundaries, and empty substrings, so it's
- best to keep usage of this simple. Complicated uses can lead to the
- same kinds of "oops, it matched too much!" surprises that \regexp{.*}
- is prone to in regular expressions.
-\end{datadesc}
-
-\begin{datadesc}{IGNORE_EXCEPTION_DETAIL}
- When specified, an example that expects an exception passes if
- an exception of the expected type is raised, even if the exception
- detail does not match. For example, an example expecting
- \samp{ValueError: 42} will pass if the actual exception raised is
- \samp{ValueError: 3*14}, but will fail, e.g., if
- \exception{TypeError} is raised.
-
- Note that a similar effect can be obtained using \constant{ELLIPSIS},
- and \constant{IGNORE_EXCEPTION_DETAIL} may go away when Python releases
- prior to 2.4 become uninteresting. Until then,
- \constant{IGNORE_EXCEPTION_DETAIL} is the only clear way to write a
- doctest that doesn't care about the exception detail yet continues
- to pass under Python releases prior to 2.4 (doctest directives
- appear to be comments to them). For example,
-
-\begin{verbatim}
->>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: object doesn't support item assignment
-\end{verbatim}
-
- passes under Python 2.4 and Python 2.3. The detail changed in 2.4,
- to say "does not" instead of "doesn't".
-
-\end{datadesc}
-
-\begin{datadesc}{SKIP}
-
- When specified, do not run the example at all. This can be useful
- in contexts where doctest examples serve as both documentation and
- test cases, and an example should be included for documentation
- purposes, but should not be checked. E.g., the example's output
- might be random; or the example might depend on resources which
- would be unavailable to the test driver.
-
- The SKIP flag can also be used for temporarily "commenting out"
- examples.
-
-\end{datadesc}
-
-\begin{datadesc}{COMPARISON_FLAGS}
- A bitmask or'ing together all the comparison flags above.
-\end{datadesc}
-
-The second group of options controls how test failures are reported:
-
-\begin{datadesc}{REPORT_UDIFF}
- When specified, failures that involve multi-line expected and
- actual outputs are displayed using a unified diff.
-\end{datadesc}
-
-\begin{datadesc}{REPORT_CDIFF}
- When specified, failures that involve multi-line expected and
- actual outputs will be displayed using a context diff.
-\end{datadesc}
-
-\begin{datadesc}{REPORT_NDIFF}
- When specified, differences are computed by \code{difflib.Differ},
- using the same algorithm as the popular \file{ndiff.py} utility.
- This is the only method that marks differences within lines as
- well as across lines. For example, if a line of expected output
- contains digit \code{1} where actual output contains letter \code{l},
- a line is inserted with a caret marking the mismatching column
- positions.
-\end{datadesc}
-
-\begin{datadesc}{REPORT_ONLY_FIRST_FAILURE}
- When specified, display the first failing example in each doctest,
- but suppress output for all remaining examples. This will prevent
- doctest from reporting correct examples that break because of
- earlier failures; but it might also hide incorrect examples that
- fail independently of the first failure. When
- \constant{REPORT_ONLY_FIRST_FAILURE} is specified, the remaining
- examples are still run, and still count towards the total number of
- failures reported; only the output is suppressed.
-\end{datadesc}
-
-\begin{datadesc}{REPORTING_FLAGS}
- A bitmask or'ing together all the reporting flags above.
-\end{datadesc}
-
-"Doctest directives" may be used to modify the option flags for
-individual examples. Doctest directives are expressed as a special
-Python comment following an example's source code:
-
-\begin{productionlist}[doctest]
- \production{directive}
- {"\#" "doctest:" \token{directive_options}}
- \production{directive_options}
- {\token{directive_option} ("," \token{directive_option})*}
- \production{directive_option}
- {\token{on_or_off} \token{directive_option_name}}
- \production{on_or_off}
- {"+" | "-"}
- \production{directive_option_name}
- {"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...}
-\end{productionlist}
-
-Whitespace is not allowed between the \code{+} or \code{-} and the
-directive option name. The directive option name can be any of the
-option flag names explained above.
-
-An example's doctest directives modify doctest's behavior for that
-single example. Use \code{+} to enable the named behavior, or
-\code{-} to disable it.
-
-For example, this test passes:
-
-\begin{verbatim}
->>> print range(20) #doctest: +NORMALIZE_WHITESPACE
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
-10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
-\end{verbatim}
-
-Without the directive it would fail, both because the actual output
-doesn't have two blanks before the single-digit list elements, and
-because the actual output is on a single line. This test also passes,
-and also requires a directive to do so:
-
-\begin{verbatim}
->>> print range(20) # doctest:+ELLIPSIS
-[0, 1, ..., 18, 19]
-\end{verbatim}
-
-Multiple directives can be used on a single physical line, separated
-by commas:
-
-\begin{verbatim}
->>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
-[0, 1, ..., 18, 19]
-\end{verbatim}
-
-If multiple directive comments are used for a single example, then
-they are combined:
-
-\begin{verbatim}
->>> print range(20) # doctest: +ELLIPSIS
-... # doctest: +NORMALIZE_WHITESPACE
-[0, 1, ..., 18, 19]
-\end{verbatim}
-
-As the previous example shows, you can add \samp{...} lines to your
-example containing only directives. This can be useful when an
-example is too long for a directive to comfortably fit on the same
-line:
-
-\begin{verbatim}
->>> print range(5) + range(10,20) + range(30,40) + range(50,60)
-... # doctest: +ELLIPSIS
-[0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
-\end{verbatim}
-
-Note that since all options are disabled by default, and directives apply
-only to the example they appear in, enabling options (via \code{+} in a
-directive) is usually the only meaningful choice. However, option flags
-can also be passed to functions that run doctests, establishing different
-defaults. In such cases, disabling an option via \code{-} in a directive
-can be useful.
-
-\versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
- \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
- \constant{IGNORE_EXCEPTION_DETAIL},
- \constant{REPORT_UDIFF}, \constant{REPORT_CDIFF},
- \constant{REPORT_NDIFF}, \constant{REPORT_ONLY_FIRST_FAILURE},
- \constant{COMPARISON_FLAGS} and \constant{REPORTING_FLAGS}
- were added; by default \code{<BLANKLINE>} in expected output
- matches an empty line in actual output; and doctest directives
- were added]{2.4}
-\versionchanged[Constant \constant{SKIP} was added]{2.5}
-
-There's also a way to register new option flag names, although this
-isn't useful unless you intend to extend \refmodule{doctest} internals
-via subclassing:
-
-\begin{funcdesc}{register_optionflag}{name}
- Create a new option flag with a given name, and return the new
- flag's integer value. \function{register_optionflag()} can be
- used when subclassing \class{OutputChecker} or
- \class{DocTestRunner} to create new options that are supported by
- your subclasses. \function{register_optionflag} should always be
- called using the following idiom:
-
-\begin{verbatim}
- MY_FLAG = register_optionflag('MY_FLAG')
-\end{verbatim}
-
- \versionadded{2.4}
-\end{funcdesc}
-
-\subsubsection{Warnings\label{doctest-warnings}}
-
-\refmodule{doctest} is serious about requiring exact matches in expected
-output. If even a single character doesn't match, the test fails. This
-will probably surprise you a few times, as you learn exactly what Python
-does and doesn't guarantee about output. For example, when printing a
-dict, Python doesn't guarantee that the key-value pairs will be printed
-in any particular order, so a test like
-
-% Hey! What happened to Monty Python examples?
-% Tim: ask Guido -- it's his example!
-\begin{verbatim}
->>> foo()
-{"Hermione": "hippogryph", "Harry": "broomstick"}
-\end{verbatim}
-
-is vulnerable! One workaround is to do
-
-\begin{verbatim}
->>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
-True
-\end{verbatim}
-
-instead. Another is to do
-
-\begin{verbatim}
->>> d = foo().items()
->>> d.sort()
->>> d
-[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
-\end{verbatim}
-
-There are others, but you get the idea.
-
-Another bad idea is to print things that embed an object address, like
-
-\begin{verbatim}
->>> id(1.0) # certain to fail some of the time
-7948648
->>> class C: pass
->>> C() # the default repr() for instances embeds an address
-<__main__.C instance at 0x00AC18F0>
-\end{verbatim}
-
-The \constant{ELLIPSIS} directive gives a nice approach for the last
-example:
-
-\begin{verbatim}
->>> C() #doctest: +ELLIPSIS
-<__main__.C instance at 0x...>
-\end{verbatim}
-
-Floating-point numbers are also subject to small output variations across
-platforms, because Python defers to the platform C library for float
-formatting, and C libraries vary widely in quality here.
-
-\begin{verbatim}
->>> 1./7 # risky
-0.14285714285714285
->>> print 1./7 # safer
-0.142857142857
->>> print round(1./7, 6) # much safer
-0.142857
-\end{verbatim}
-
-Numbers of the form \code{I/2.**J} are safe across all platforms, and I
-often contrive doctest examples to produce numbers of that form:
-
-\begin{verbatim}
->>> 3./4 # utterly safe
-0.75
-\end{verbatim}
-
-Simple fractions are also easier for people to understand, and that makes
-for better documentation.
-
-\subsection{Basic API\label{doctest-basic-api}}
-
-The functions \function{testmod()} and \function{testfile()} provide a
-simple interface to doctest that should be sufficient for most basic
-uses. For a less formal introduction to these two functions, see
-sections \ref{doctest-simple-testmod} and
-\ref{doctest-simple-testfile}.
-
-\begin{funcdesc}{testfile}{filename\optional{, module_relative}\optional{,
- name}\optional{, package}\optional{,
- globs}\optional{, verbose}\optional{,
- report}\optional{, optionflags}\optional{,
- extraglobs}\optional{, raise_on_error}\optional{,
- parser}\optional{, encoding}}
-
- All arguments except \var{filename} are optional, and should be
- specified in keyword form.
-
- Test examples in the file named \var{filename}. Return
- \samp{(\var{failure_count}, \var{test_count})}.
-
- Optional argument \var{module_relative} specifies how the filename
- should be interpreted:
-
- \begin{itemize}
- \item If \var{module_relative} is \code{True} (the default), then
- \var{filename} specifies an OS-independent module-relative
- path. By default, this path is relative to the calling
- module's directory; but if the \var{package} argument is
- specified, then it is relative to that package. To ensure
- OS-independence, \var{filename} should use \code{/} characters
- to separate path segments, and may not be an absolute path
- (i.e., it may not begin with \code{/}).
- \item If \var{module_relative} is \code{False}, then \var{filename}
- specifies an OS-specific path. The path may be absolute or
- relative; relative paths are resolved with respect to the
- current working directory.
- \end{itemize}
-
- Optional argument \var{name} gives the name of the test; by default,
- or if \code{None}, \code{os.path.basename(\var{filename})} is used.
-
- Optional argument \var{package} is a Python package or the name of a
- Python package whose directory should be used as the base directory
- for a module-relative filename. If no package is specified, then
- the calling module's directory is used as the base directory for
- module-relative filenames. It is an error to specify \var{package}
- if \var{module_relative} is \code{False}.
-
- Optional argument \var{globs} gives a dict to be used as the globals
- when executing examples. A new shallow copy of this dict is
- created for the doctest, so its examples start with a clean slate.
- By default, or if \code{None}, a new empty dict is used.
-
- Optional argument \var{extraglobs} gives a dict merged into the
- globals used to execute examples. This works like
- \method{dict.update()}: if \var{globs} and \var{extraglobs} have a
- common key, the associated value in \var{extraglobs} appears in the
- combined dict. By default, or if \code{None}, no extra globals are
- used. This is an advanced feature that allows parameterization of
- doctests. For example, a doctest can be written for a base class, using
- a generic name for the class, then reused to test any number of
- subclasses by passing an \var{extraglobs} dict mapping the generic
- name to the subclass to be tested.
-
- Optional argument \var{verbose} prints lots of stuff if true, and prints
- only failures if false; by default, or if \code{None}, it's true
- if and only if \code{'-v'} is in \code{sys.argv}.
-
- Optional argument \var{report} prints a summary at the end when true,
- else prints nothing at the end. In verbose mode, the summary is
- detailed, else the summary is very brief (in fact, empty if all tests
- passed).
-
- Optional argument \var{optionflags} or's together option flags. See
- section~\ref{doctest-options}.
-
- Optional argument \var{raise_on_error} defaults to false. If true,
- an exception is raised upon the first failure or unexpected exception
- in an example. This allows failures to be post-mortem debugged.
- Default behavior is to continue running examples.
-
- Optional argument \var{parser} specifies a \class{DocTestParser} (or
- subclass) that should be used to extract tests from the files. It
- defaults to a normal parser (i.e., \code{\class{DocTestParser}()}).
-
- Optional argument \var{encoding} specifies an encoding that should
- be used to convert the file to unicode.
-
- \versionadded{2.4}
-
- \versionchanged[The parameter \var{encoding} was added]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
- globs}\optional{, verbose}\optional{,
- report}\optional{,
- optionflags}\optional{, extraglobs}\optional{,
- raise_on_error}\optional{, exclude_empty}}
-
- All arguments are optional, and all except for \var{m} should be
- specified in keyword form.
-
- Test examples in docstrings in functions and classes reachable
- from module \var{m} (or module \module{__main__} if \var{m} is not
- supplied or is \code{None}), starting with \code{\var{m}.__doc__}.
-
- Also test examples reachable from dict \code{\var{m}.__test__}, if it
- exists and is not \code{None}. \code{\var{m}.__test__} maps
- names (strings) to functions, classes and strings; function and class
- docstrings are searched for examples; strings are searched directly,
- as if they were docstrings.
-
- Only docstrings attached to objects belonging to module \var{m} are
- searched.
-
- Return \samp{(\var{failure_count}, \var{test_count})}.
-
- Optional argument \var{name} gives the name of the module; by default,
- or if \code{None}, \code{\var{m}.__name__} is used.
-
- Optional argument \var{exclude_empty} defaults to false. If true,
- objects for which no doctests are found are excluded from consideration.
- The default is a backward compatibility hack, so that code still
- using \method{doctest.master.summarize()} in conjunction with
- \function{testmod()} continues to get output for objects with no tests.
- The \var{exclude_empty} argument to the newer \class{DocTestFinder}
- constructor defaults to true.
-
- Optional arguments \var{extraglobs}, \var{verbose}, \var{report},
- \var{optionflags}, \var{raise_on_error}, and \var{globs} are the same as
- for function \function{testfile()} above, except that \var{globs}
- defaults to \code{\var{m}.__dict__}.
-
- \versionchanged[The parameter \var{optionflags} was added]{2.3}
-
- \versionchanged[The parameters \var{extraglobs}, \var{raise_on_error}
- and \var{exclude_empty} were added]{2.4}
-
- \versionchanged[The optional argument \var{isprivate}, deprecated
- in 2.4, was removed]{2.5}
-
-\end{funcdesc}
-
-There's also a function to run the doctests associated with a single object.
-This function is provided for backward compatibility. There are no plans
-to deprecate it, but it's rarely useful:
-
-\begin{funcdesc}{run_docstring_examples}{f, globs\optional{,
- verbose}\optional{, name}\optional{,
- compileflags}\optional{, optionflags}}
-
- Test examples associated with object \var{f}; for example, \var{f} may
- be a module, function, or class object.
-
- A shallow copy of dictionary argument \var{globs} is used for the
- execution context.
-
- Optional argument \var{name} is used in failure messages, and defaults
- to \code{"NoName"}.
-
- If optional argument \var{verbose} is true, output is generated even
- if there are no failures. By default, output is generated only in case
- of an example failure.
-
- Optional argument \var{compileflags} gives the set of flags that should
- be used by the Python compiler when running the examples. By default, or
- if \code{None}, flags are deduced corresponding to the set of future
- features found in \var{globs}.
-
- Optional argument \var{optionflags} works as for function
- \function{testfile()} above.
-\end{funcdesc}
-
-\subsection{Unittest API\label{doctest-unittest-api}}
-
-As your collection of doctest'ed modules grows, you'll want a way to run
-all their doctests systematically. Prior to Python 2.4, \refmodule{doctest}
-had a barely documented \class{Tester} class that supplied a rudimentary
-way to combine doctests from multiple modules. \class{Tester} was feeble,
-and in practice most serious Python testing frameworks build on the
-\refmodule{unittest} module, which supplies many flexible ways to combine
-tests from multiple sources. So, in Python 2.4, \refmodule{doctest}'s
-\class{Tester} class is deprecated, and \refmodule{doctest} provides two
-functions that can be used to create \refmodule{unittest} test suites from
-modules and text files containing doctests. These test suites can then be
-run using \refmodule{unittest} test runners:
-
-\begin{verbatim}
-import unittest
-import doctest
-import my_module_with_doctests, and_another
-
-suite = unittest.TestSuite()
-for mod in my_module_with_doctests, and_another:
- suite.addTest(doctest.DocTestSuite(mod))
-runner = unittest.TextTestRunner()
-runner.run(suite)
-\end{verbatim}
-
-There are two main functions for creating \class{\refmodule{unittest}.TestSuite}
-instances from text files and modules with doctests:
-
-\begin{funcdesc}{DocFileSuite}{\optional{module_relative}\optional{,
- package}\optional{, setUp}\optional{,
- tearDown}\optional{, globs}\optional{,
- optionflags}\optional{, parser}\optional{,
- encoding}}
-
- Convert doctest tests from one or more text files to a
- \class{\refmodule{unittest}.TestSuite}.
-
- The returned \class{\refmodule{unittest}.TestSuite} is to be run by the
- unittest framework and runs the interactive examples in each file. If an
- example in any file fails, then the synthesized unit test fails, and a
- \exception{failureException} exception is raised showing the name of the
- file containing the test and a (sometimes approximate) line number.
-
- Pass one or more paths (as strings) to text files to be examined.
-
- Options may be provided as keyword arguments:
-
- Optional argument \var{module_relative} specifies how
- the filenames in \var{paths} should be interpreted:
-
- \begin{itemize}
- \item If \var{module_relative} is \code{True} (the default), then
- each filename specifies an OS-independent module-relative
- path. By default, this path is relative to the calling
- module's directory; but if the \var{package} argument is
- specified, then it is relative to that package. To ensure
- OS-independence, each filename should use \code{/} characters
- to separate path segments, and may not be an absolute path
- (i.e., it may not begin with \code{/}).
- \item If \var{module_relative} is \code{False}, then each filename
- specifies an OS-specific path. The path may be absolute or
- relative; relative paths are resolved with respect to the
- current working directory.
- \end{itemize}
-
- Optional argument \var{package} is a Python package or the name
- of a Python package whose directory should be used as the base
- directory for module-relative filenames. If no package is
- specified, then the calling module's directory is used as the base
- directory for module-relative filenames. It is an error to specify
- \var{package} if \var{module_relative} is \code{False}.
-
- Optional argument \var{setUp} specifies a set-up function for
- the test suite. This is called before running the tests in each
- file. The \var{setUp} function will be passed a \class{DocTest}
- object. The setUp function can access the test globals as the
- \var{globs} attribute of the test passed.
-
- Optional argument \var{tearDown} specifies a tear-down function
- for the test suite. This is called after running the tests in each
- file. The \var{tearDown} function will be passed a \class{DocTest}
- object. The setUp function can access the test globals as the
- \var{globs} attribute of the test passed.
-
- Optional argument \var{globs} is a dictionary containing the
- initial global variables for the tests. A new copy of this
- dictionary is created for each test. By default, \var{globs} is
- a new empty dictionary.
-
- Optional argument \var{optionflags} specifies the default
- doctest options for the tests, created by or-ing together
- individual option flags. See section~\ref{doctest-options}.
- See function \function{set_unittest_reportflags()} below for
- a better way to set reporting options.
-
- Optional argument \var{parser} specifies a \class{DocTestParser} (or
- subclass) that should be used to extract tests from the files. It
- defaults to a normal parser (i.e., \code{\class{DocTestParser}()}).
-
- Optional argument \var{encoding} specifies an encoding that should
- be used to convert the file to unicode.
-
- \versionadded{2.4}
-
- \versionchanged[The global \code{__file__} was added to the
- globals provided to doctests loaded from a text file using
- \function{DocFileSuite()}]{2.5}
-
- \versionchanged[The parameter \var{encoding} was added]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{DocTestSuite}{\optional{module}\optional{,
- globs}\optional{, extraglobs}\optional{,
- test_finder}\optional{, setUp}\optional{,
- tearDown}\optional{, checker}}
- Convert doctest tests for a module to a
- \class{\refmodule{unittest}.TestSuite}.
-
- The returned \class{\refmodule{unittest}.TestSuite} is to be run by the
- unittest framework and runs each doctest in the module. If any of the
- doctests fail, then the synthesized unit test fails, and a
- \exception{failureException} exception is raised showing the name of the
- file containing the test and a (sometimes approximate) line number.
-
- Optional argument \var{module} provides the module to be tested. It
- can be a module object or a (possibly dotted) module name. If not
- specified, the module calling this function is used.
-
- Optional argument \var{globs} is a dictionary containing the
- initial global variables for the tests. A new copy of this
- dictionary is created for each test. By default, \var{globs} is
- a new empty dictionary.
-
- Optional argument \var{extraglobs} specifies an extra set of
- global variables, which is merged into \var{globs}. By default, no
- extra globals are used.
-
- Optional argument \var{test_finder} is the \class{DocTestFinder}
- object (or a drop-in replacement) that is used to extract doctests
- from the module.
-
- Optional arguments \var{setUp}, \var{tearDown}, and \var{optionflags}
- are the same as for function \function{DocFileSuite()} above.
-
- \versionadded{2.3}
-
- \versionchanged[The parameters \var{globs}, \var{extraglobs},
- \var{test_finder}, \var{setUp}, \var{tearDown}, and
- \var{optionflags} were added; this function now uses the same search
- technique as \function{testmod()}]{2.4}
-\end{funcdesc}
-
-Under the covers, \function{DocTestSuite()} creates a
-\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocTestCase}
-instances, and \class{DocTestCase} is a subclass of
-\class{\refmodule{unittest}.TestCase}. \class{DocTestCase} isn't documented
-here (it's an internal detail), but studying its code can answer questions
-about the exact details of \refmodule{unittest} integration.
-
-Similarly, \function{DocFileSuite()} creates a
-\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocFileCase}
-instances, and \class{DocFileCase} is a subclass of \class{DocTestCase}.
-
-So both ways of creating a \class{\refmodule{unittest}.TestSuite} run
-instances of \class{DocTestCase}. This is important for a subtle reason:
-when you run \refmodule{doctest} functions yourself, you can control the
-\refmodule{doctest} options in use directly, by passing option flags to
-\refmodule{doctest} functions. However, if you're writing a
-\refmodule{unittest} framework, \refmodule{unittest} ultimately controls
-when and how tests get run. The framework author typically wants to
-control \refmodule{doctest} reporting options (perhaps, e.g., specified by
-command line options), but there's no way to pass options through
-\refmodule{unittest} to \refmodule{doctest} test runners.
-
-For this reason, \refmodule{doctest} also supports a notion of
-\refmodule{doctest} reporting flags specific to \refmodule{unittest}
-support, via this function:
-
-\begin{funcdesc}{set_unittest_reportflags}{flags}
- Set the \refmodule{doctest} reporting flags to use.
-
- Argument \var{flags} or's together option flags. See
- section~\ref{doctest-options}. Only "reporting flags" can be used.
-
- This is a module-global setting, and affects all future doctests run by
- module \refmodule{unittest}: the \method{runTest()} method of
- \class{DocTestCase} looks at the option flags specified for the test case
- when the \class{DocTestCase} instance was constructed. If no reporting
- flags were specified (which is the typical and expected case),
- \refmodule{doctest}'s \refmodule{unittest} reporting flags are or'ed into
- the option flags, and the option flags so augmented are passed to the
- \class{DocTestRunner} instance created to run the doctest. If any
- reporting flags were specified when the \class{DocTestCase} instance was
- constructed, \refmodule{doctest}'s \refmodule{unittest} reporting flags
- are ignored.
-
- The value of the \refmodule{unittest} reporting flags in effect before the
- function was called is returned by the function.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-
-\subsection{Advanced API\label{doctest-advanced-api}}
-
-The basic API is a simple wrapper that's intended to make doctest easy
-to use. It is fairly flexible, and should meet most users' needs;
-however, if you require more fine-grained control over testing, or
-wish to extend doctest's capabilities, then you should use the
-advanced API.
-
-The advanced API revolves around two container classes, which are used
-to store the interactive examples extracted from doctest cases:
-
-\begin{itemize}
-\item \class{Example}: A single python statement, paired with its
- expected output.
-\item \class{DocTest}: A collection of \class{Example}s, typically
- extracted from a single docstring or text file.
-\end{itemize}
-
-Additional processing classes are defined to find, parse, and run, and
-check doctest examples:
-
-\begin{itemize}
-\item \class{DocTestFinder}: Finds all docstrings in a given module,
- and uses a \class{DocTestParser} to create a \class{DocTest}
- from every docstring that contains interactive examples.
-\item \class{DocTestParser}: Creates a \class{DocTest} object from
- a string (such as an object's docstring).
-\item \class{DocTestRunner}: Executes the examples in a
- \class{DocTest}, and uses an \class{OutputChecker} to verify
- their output.
-\item \class{OutputChecker}: Compares the actual output from a
- doctest example with the expected output, and decides whether
- they match.
-\end{itemize}
-
-The relationships among these processing classes are summarized in the
-following diagram:
-
-\begin{verbatim}
- list of:
-+------+ +---------+
-|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
-+------+ | ^ +---------+ | ^ (printed)
- | | | Example | | |
- v | | ... | v |
- DocTestParser | Example | OutputChecker
- +---------+
-\end{verbatim}
-
-\subsubsection{DocTest Objects\label{doctest-DocTest}}
-\begin{classdesc}{DocTest}{examples, globs, name, filename, lineno,
- docstring}
- A collection of doctest examples that should be run in a single
- namespace. The constructor arguments are used to initialize the
- member variables of the same names.
- \versionadded{2.4}
-\end{classdesc}
-
-\class{DocTest} defines the following member variables. They are
-initialized by the constructor, and should not be modified directly.
-
-\begin{memberdesc}{examples}
- A list of \class{Example} objects encoding the individual
- interactive Python examples that should be run by this test.
-\end{memberdesc}
-
-\begin{memberdesc}{globs}
- The namespace (aka globals) that the examples should be run in.
- This is a dictionary mapping names to values. Any changes to the
- namespace made by the examples (such as binding new variables)
- will be reflected in \member{globs} after the test is run.
-\end{memberdesc}
-
-\begin{memberdesc}{name}
- A string name identifying the \class{DocTest}. Typically, this is
- the name of the object or file that the test was extracted from.
-\end{memberdesc}
-
-\begin{memberdesc}{filename}
- The name of the file that this \class{DocTest} was extracted from;
- or \code{None} if the filename is unknown, or if the
- \class{DocTest} was not extracted from a file.
-\end{memberdesc}
-
-\begin{memberdesc}{lineno}
- The line number within \member{filename} where this
- \class{DocTest} begins, or \code{None} if the line number is
- unavailable. This line number is zero-based with respect to the
- beginning of the file.
-\end{memberdesc}
-
-\begin{memberdesc}{docstring}
- The string that the test was extracted from, or `None` if the
- string is unavailable, or if the test was not extracted from a
- string.
-\end{memberdesc}
-
-\subsubsection{Example Objects\label{doctest-Example}}
-\begin{classdesc}{Example}{source, want\optional{,
- exc_msg}\optional{, lineno}\optional{,
- indent}\optional{, options}}
- A single interactive example, consisting of a Python statement and
- its expected output. The constructor arguments are used to
- initialize the member variables of the same names.
- \versionadded{2.4}
-\end{classdesc}
-
-\class{Example} defines the following member variables. They are
-initialized by the constructor, and should not be modified directly.
-
-\begin{memberdesc}{source}
- A string containing the example's source code. This source code
- consists of a single Python statement, and always ends with a
- newline; the constructor adds a newline when necessary.
-\end{memberdesc}
-
-\begin{memberdesc}{want}
- The expected output from running the example's source code (either
- from stdout, or a traceback in case of exception). \member{want}
- ends with a newline unless no output is expected, in which case
- it's an empty string. The constructor adds a newline when
- necessary.
-\end{memberdesc}
-
-\begin{memberdesc}{exc_msg}
- The exception message generated by the example, if the example is
- expected to generate an exception; or \code{None} if it is not
- expected to generate an exception. This exception message is
- compared against the return value of
- \function{traceback.format_exception_only()}. \member{exc_msg}
- ends with a newline unless it's \code{None}. The constructor adds
- a newline if needed.
-\end{memberdesc}
-
-\begin{memberdesc}{lineno}
- The line number within the string containing this example where
- the example begins. This line number is zero-based with respect
- to the beginning of the containing string.
-\end{memberdesc}
-
-\begin{memberdesc}{indent}
- The example's indentation in the containing string, i.e., the
- number of space characters that precede the example's first
- prompt.
-\end{memberdesc}
-
-\begin{memberdesc}{options}
- A dictionary mapping from option flags to \code{True} or
- \code{False}, which is used to override default options for this
- example. Any option flags not contained in this dictionary are
- left at their default value (as specified by the
- \class{DocTestRunner}'s \member{optionflags}).
- By default, no options are set.
-\end{memberdesc}
-
-\subsubsection{DocTestFinder objects\label{doctest-DocTestFinder}}
-\begin{classdesc}{DocTestFinder}{\optional{verbose}\optional{,
- parser}\optional{, recurse}\optional{,
- exclude_empty}}
- A processing class used to extract the \class{DocTest}s that are
- relevant to a given object, from its docstring and the docstrings
- of its contained objects. \class{DocTest}s can currently be
- extracted from the following object types: modules, functions,
- classes, methods, staticmethods, classmethods, and properties.
-
- The optional argument \var{verbose} can be used to display the
- objects searched by the finder. It defaults to \code{False} (no
- output).
-
- The optional argument \var{parser} specifies the
- \class{DocTestParser} object (or a drop-in replacement) that is
- used to extract doctests from docstrings.
-
- If the optional argument \var{recurse} is false, then
- \method{DocTestFinder.find()} will only examine the given object,
- and not any contained objects.
-
- If the optional argument \var{exclude_empty} is false, then
- \method{DocTestFinder.find()} will include tests for objects with
- empty docstrings.
-
- \versionadded{2.4}
-\end{classdesc}
-
-\class{DocTestFinder} defines the following method:
-
-\begin{methoddesc}{find}{obj\optional{, name}\optional{,
- module}\optional{, globs}\optional{, extraglobs}}
- Return a list of the \class{DocTest}s that are defined by
- \var{obj}'s docstring, or by any of its contained objects'
- docstrings.
-
- The optional argument \var{name} specifies the object's name; this
- name will be used to construct names for the returned
- \class{DocTest}s. If \var{name} is not specified, then
- \code{\var{obj}.__name__} is used.
-
- The optional parameter \var{module} is the module that contains
- the given object. If the module is not specified or is None, then
- the test finder will attempt to automatically determine the
- correct module. The object's module is used:
-
- \begin{itemize}
- \item As a default namespace, if \var{globs} is not specified.
- \item To prevent the DocTestFinder from extracting DocTests
- from objects that are imported from other modules. (Contained
- objects with modules other than \var{module} are ignored.)
- \item To find the name of the file containing the object.
- \item To help find the line number of the object within its file.
- \end{itemize}
-
- If \var{module} is \code{False}, no attempt to find the module
- will be made. This is obscure, of use mostly in testing doctest
- itself: if \var{module} is \code{False}, or is \code{None} but
- cannot be found automatically, then all objects are considered to
- belong to the (non-existent) module, so all contained objects will
- (recursively) be searched for doctests.
-
- The globals for each \class{DocTest} is formed by combining
- \var{globs} and \var{extraglobs} (bindings in \var{extraglobs}
- override bindings in \var{globs}). A new shallow copy of the globals
- dictionary is created for each \class{DocTest}. If \var{globs} is
- not specified, then it defaults to the module's \var{__dict__}, if
- specified, or \code{\{\}} otherwise. If \var{extraglobs} is not
- specified, then it defaults to \code{\{\}}.
-\end{methoddesc}
-
-\subsubsection{DocTestParser objects\label{doctest-DocTestParser}}
-\begin{classdesc}{DocTestParser}{}
- A processing class used to extract interactive examples from a
- string, and use them to create a \class{DocTest} object.
- \versionadded{2.4}
-\end{classdesc}
-
-\class{DocTestParser} defines the following methods:
-
-\begin{methoddesc}{get_doctest}{string, globs, name, filename, lineno}
- Extract all doctest examples from the given string, and collect
- them into a \class{DocTest} object.
-
- \var{globs}, \var{name}, \var{filename}, and \var{lineno} are
- attributes for the new \class{DocTest} object. See the
- documentation for \class{DocTest} for more information.
-\end{methoddesc}
-
-\begin{methoddesc}{get_examples}{string\optional{, name}}
- Extract all doctest examples from the given string, and return
- them as a list of \class{Example} objects. Line numbers are
- 0-based. The optional argument \var{name} is a name identifying
- this string, and is only used for error messages.
-\end{methoddesc}
-
-\begin{methoddesc}{parse}{string\optional{, name}}
- Divide the given string into examples and intervening text, and
- return them as a list of alternating \class{Example}s and strings.
- Line numbers for the \class{Example}s are 0-based. The optional
- argument \var{name} is a name identifying this string, and is only
- used for error messages.
-\end{methoddesc}
-
-\subsubsection{DocTestRunner objects\label{doctest-DocTestRunner}}
-\begin{classdesc}{DocTestRunner}{\optional{checker}\optional{,
- verbose}\optional{, optionflags}}
- A processing class used to execute and verify the interactive
- examples in a \class{DocTest}.
-
- The comparison between expected outputs and actual outputs is done
- by an \class{OutputChecker}. This comparison may be customized
- with a number of option flags; see section~\ref{doctest-options}
- for more information. If the option flags are insufficient, then
- the comparison may also be customized by passing a subclass of
- \class{OutputChecker} to the constructor.
-
- The test runner's display output can be controlled in two ways.
- First, an output function can be passed to
- \method{TestRunner.run()}; this function will be called with
- strings that should be displayed. It defaults to
- \code{sys.stdout.write}. If capturing the output is not
- sufficient, then the display output can be also customized by
- subclassing DocTestRunner, and overriding the methods
- \method{report_start}, \method{report_success},
- \method{report_unexpected_exception}, and \method{report_failure}.
-
- The optional keyword argument \var{checker} specifies the
- \class{OutputChecker} object (or drop-in replacement) that should
- be used to compare the expected outputs to the actual outputs of
- doctest examples.
-
- The optional keyword argument \var{verbose} controls the
- \class{DocTestRunner}'s verbosity. If \var{verbose} is
- \code{True}, then information is printed about each example, as it
- is run. If \var{verbose} is \code{False}, then only failures are
- printed. If \var{verbose} is unspecified, or \code{None}, then
- verbose output is used iff the command-line switch \programopt{-v}
- is used.
-
- The optional keyword argument \var{optionflags} can be used to
- control how the test runner compares expected output to actual
- output, and how it displays failures. For more information, see
- section~\ref{doctest-options}.
-
- \versionadded{2.4}
-\end{classdesc}
-
-\class{DocTestParser} defines the following methods:
-
-\begin{methoddesc}{report_start}{out, test, example}
- Report that the test runner is about to process the given example.
- This method is provided to allow subclasses of
- \class{DocTestRunner} to customize their output; it should not be
- called directly.
-
- \var{example} is the example about to be processed. \var{test} is
- the test containing \var{example}. \var{out} is the output
- function that was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{report_success}{out, test, example, got}
- Report that the given example ran successfully. This method is
- provided to allow subclasses of \class{DocTestRunner} to customize
- their output; it should not be called directly.
-
- \var{example} is the example about to be processed. \var{got} is
- the actual output from the example. \var{test} is the test
- containing \var{example}. \var{out} is the output function that
- was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{report_failure}{out, test, example, got}
- Report that the given example failed. This method is provided to
- allow subclasses of \class{DocTestRunner} to customize their
- output; it should not be called directly.
-
- \var{example} is the example about to be processed. \var{got} is
- the actual output from the example. \var{test} is the test
- containing \var{example}. \var{out} is the output function that
- was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{report_unexpected_exception}{out, test, example, exc_info}
- Report that the given example raised an unexpected exception.
- This method is provided to allow subclasses of
- \class{DocTestRunner} to customize their output; it should not be
- called directly.
-
- \var{example} is the example about to be processed.
- \var{exc_info} is a tuple containing information about the
- unexpected exception (as returned by \function{sys.exc_info()}).
- \var{test} is the test containing \var{example}. \var{out} is the
- output function that was passed to \method{DocTestRunner.run()}.
-\end{methoddesc}
-
-\begin{methoddesc}{run}{test\optional{, compileflags}\optional{,
- out}\optional{, clear_globs}}
- Run the examples in \var{test} (a \class{DocTest} object), and
- display the results using the writer function \var{out}.
-
- The examples are run in the namespace \code{test.globs}. If
- \var{clear_globs} is true (the default), then this namespace will
- be cleared after the test runs, to help with garbage collection.
- If you would like to examine the namespace after the test
- completes, then use \var{clear_globs=False}.
-
- \var{compileflags} gives the set of flags that should be used by
- the Python compiler when running the examples. If not specified,
- then it will default to the set of future-import flags that apply
- to \var{globs}.
-
- The output of each example is checked using the
- \class{DocTestRunner}'s output checker, and the results are
- formatted by the \method{DocTestRunner.report_*} methods.
-\end{methoddesc}
-
-\begin{methoddesc}{summarize}{\optional{verbose}}
- Print a summary of all the test cases that have been run by this
- DocTestRunner, and return a tuple \samp{(\var{failure_count},
- \var{test_count})}.
-
- The optional \var{verbose} argument controls how detailed the
- summary is. If the verbosity is not specified, then the
- \class{DocTestRunner}'s verbosity is used.
-\end{methoddesc}
-
-\subsubsection{OutputChecker objects\label{doctest-OutputChecker}}
-
-\begin{classdesc}{OutputChecker}{}
- A class used to check the whether the actual output from a doctest
- example matches the expected output. \class{OutputChecker}
- defines two methods: \method{check_output}, which compares a given
- pair of outputs, and returns true if they match; and
- \method{output_difference}, which returns a string describing the
- differences between two outputs.
- \versionadded{2.4}
-\end{classdesc}
-
-\class{OutputChecker} defines the following methods:
-
-\begin{methoddesc}{check_output}{want, got, optionflags}
- Return \code{True} iff the actual output from an example
- (\var{got}) matches the expected output (\var{want}). These
- strings are always considered to match if they are identical; but
- depending on what option flags the test runner is using, several
- non-exact match types are also possible. See
- section~\ref{doctest-options} for more information about option
- flags.
-\end{methoddesc}
-
-\begin{methoddesc}{output_difference}{example, got, optionflags}
- Return a string describing the differences between the expected
- output for a given example (\var{example}) and the actual output
- (\var{got}). \var{optionflags} is the set of option flags used to
- compare \var{want} and \var{got}.
-\end{methoddesc}
-
-\subsection{Debugging\label{doctest-debugging}}
-
-Doctest provides several mechanisms for debugging doctest examples:
-
-\begin{itemize}
-\item Several functions convert doctests to executable Python
- programs, which can be run under the Python debugger, \refmodule{pdb}.
-\item The \class{DebugRunner} class is a subclass of
- \class{DocTestRunner} that raises an exception for the first
- failing example, containing information about that example.
- This information can be used to perform post-mortem debugging on
- the example.
-\item The \refmodule{unittest} cases generated by \function{DocTestSuite()}
- support the \method{debug()} method defined by
- \class{\refmodule{unittest}.TestCase}.
-\item You can add a call to \function{\refmodule{pdb}.set_trace()} in a
- doctest example, and you'll drop into the Python debugger when that
- line is executed. Then you can inspect current values of variables,
- and so on. For example, suppose \file{a.py} contains just this
- module docstring:
-
-\begin{verbatim}
-"""
->>> def f(x):
-... g(x*2)
->>> def g(x):
-... print x+3
-... import pdb; pdb.set_trace()
->>> f(3)
-9
-"""
-\end{verbatim}
-
- Then an interactive Python session may look like this:
-
-\begin{verbatim}
->>> import a, doctest
->>> doctest.testmod(a)
---Return--
-> <doctest a[1]>(3)g()->None
--> import pdb; pdb.set_trace()
-(Pdb) list
- 1 def g(x):
- 2 print x+3
- 3 -> import pdb; pdb.set_trace()
-[EOF]
-(Pdb) print x
-6
-(Pdb) step
---Return--
-> <doctest a[0]>(2)f()->None
--> g(x*2)
-(Pdb) list
- 1 def f(x):
- 2 -> g(x*2)
-[EOF]
-(Pdb) print x
-3
-(Pdb) step
---Return--
-> <doctest a[2]>(1)?()->None
--> f(3)
-(Pdb) cont
-(0, 3)
->>>
-\end{verbatim}
-
- \versionchanged[The ability to use \function{\refmodule{pdb}.set_trace()}
- usefully inside doctests was added]{2.4}
-\end{itemize}
-
-Functions that convert doctests to Python code, and possibly run
-the synthesized code under the debugger:
-
-\begin{funcdesc}{script_from_examples}{s}
- Convert text with examples to a script.
-
- Argument \var{s} is a string containing doctest examples. The string
- is converted to a Python script, where doctest examples in \var{s}
- are converted to regular code, and everything else is converted to
- Python comments. The generated script is returned as a string.
- For example,
-
- \begin{verbatim}
- import doctest
- print doctest.script_from_examples(r"""
- Set x and y to 1 and 2.
- >>> x, y = 1, 2
-
- Print their sum:
- >>> print x+y
- 3
- """)
- \end{verbatim}
-
- displays:
-
- \begin{verbatim}
- # Set x and y to 1 and 2.
- x, y = 1, 2
- #
- # Print their sum:
- print x+y
- # Expected:
- ## 3
- \end{verbatim}
-
- This function is used internally by other functions (see below), but
- can also be useful when you want to transform an interactive Python
- session into a Python script.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{testsource}{module, name}
- Convert the doctest for an object to a script.
-
- Argument \var{module} is a module object, or dotted name of a module,
- containing the object whose doctests are of interest. Argument
- \var{name} is the name (within the module) of the object with the
- doctests of interest. The result is a string, containing the
- object's docstring converted to a Python script, as described for
- \function{script_from_examples()} above. For example, if module
- \file{a.py} contains a top-level function \function{f()}, then
-
-\begin{verbatim}
-import a, doctest
-print doctest.testsource(a, "a.f")
-\end{verbatim}
-
- prints a script version of function \function{f()}'s docstring,
- with doctests converted to code, and the rest placed in comments.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{debug}{module, name\optional{, pm}}
- Debug the doctests for an object.
-
- The \var{module} and \var{name} arguments are the same as for function
- \function{testsource()} above. The synthesized Python script for the
- named object's docstring is written to a temporary file, and then that
- file is run under the control of the Python debugger, \refmodule{pdb}.
-
- A shallow copy of \code{\var{module}.__dict__} is used for both local
- and global execution context.
-
- Optional argument \var{pm} controls whether post-mortem debugging is
- used. If \var{pm} has a true value, the script file is run directly, and
- the debugger gets involved only if the script terminates via raising an
- unhandled exception. If it does, then post-mortem debugging is invoked,
- via \function{\refmodule{pdb}.post_mortem()}, passing the traceback object
- from the unhandled exception. If \var{pm} is not specified, or is false,
- the script is run under the debugger from the start, via passing an
- appropriate \function{exec()} call to \function{\refmodule{pdb}.run()}.
-
- \versionadded{2.3}
-
- \versionchanged[The \var{pm} argument was added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{debug_src}{src\optional{, pm}\optional{, globs}}
- Debug the doctests in a string.
-
- This is like function \function{debug()} above, except that
- a string containing doctest examples is specified directly, via
- the \var{src} argument.
-
- Optional argument \var{pm} has the same meaning as in function
- \function{debug()} above.
-
- Optional argument \var{globs} gives a dictionary to use as both
- local and global execution context. If not specified, or \code{None},
- an empty dictionary is used. If specified, a shallow copy of the
- dictionary is used.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-The \class{DebugRunner} class, and the special exceptions it may raise,
-are of most interest to testing framework authors, and will only be
-sketched here. See the source code, and especially \class{DebugRunner}'s
-docstring (which is a doctest!) for more details:
-
-\begin{classdesc}{DebugRunner}{\optional{checker}\optional{,
- verbose}\optional{, optionflags}}
-
- A subclass of \class{DocTestRunner} that raises an exception as
- soon as a failure is encountered. If an unexpected exception
- occurs, an \exception{UnexpectedException} exception is raised,
- containing the test, the example, and the original exception. If
- the output doesn't match, then a \exception{DocTestFailure}
- exception is raised, containing the test, the example, and the
- actual output.
-
- For information about the constructor parameters and methods, see
- the documentation for \class{DocTestRunner} in
- section~\ref{doctest-advanced-api}.
-\end{classdesc}
-
-There are two exceptions that may be raised by \class{DebugRunner}
-instances:
-
-\begin{excclassdesc}{DocTestFailure}{test, example, got}
- An exception thrown by \class{DocTestRunner} to signal that a
- doctest example's actual output did not match its expected output.
- The constructor arguments are used to initialize the member
- variables of the same names.
-\end{excclassdesc}
-\exception{DocTestFailure} defines the following member variables:
-\begin{memberdesc}{test}
- The \class{DocTest} object that was being run when the example failed.
-\end{memberdesc}
-\begin{memberdesc}{example}
- The \class{Example} that failed.
-\end{memberdesc}
-\begin{memberdesc}{got}
- The example's actual output.
-\end{memberdesc}
-
-\begin{excclassdesc}{UnexpectedException}{test, example, exc_info}
- An exception thrown by \class{DocTestRunner} to signal that a
- doctest example raised an unexpected exception. The constructor
- arguments are used to initialize the member variables of the same
- names.
-\end{excclassdesc}
-\exception{UnexpectedException} defines the following member variables:
-\begin{memberdesc}{test}
- The \class{DocTest} object that was being run when the example failed.
-\end{memberdesc}
-\begin{memberdesc}{example}
- The \class{Example} that failed.
-\end{memberdesc}
-\begin{memberdesc}{exc_info}
- A tuple containing information about the unexpected exception, as
- returned by \function{sys.exc_info()}.
-\end{memberdesc}
-
-\subsection{Soapbox\label{doctest-soapbox}}
-
-As mentioned in the introduction, \refmodule{doctest} has grown to have
-three primary uses:
-
-\begin{enumerate}
-\item Checking examples in docstrings.
-\item Regression testing.
-\item Executable documentation / literate testing.
-\end{enumerate}
-
-These uses have different requirements, and it is important to
-distinguish them. In particular, filling your docstrings with obscure
-test cases makes for bad documentation.
-
-When writing a docstring, choose docstring examples with care.
-There's an art to this that needs to be learned---it may not be
-natural at first. Examples should add genuine value to the
-documentation. A good example can often be worth many words.
-If done with care, the examples will be invaluable for your users, and
-will pay back the time it takes to collect them many times over as the
-years go by and things change. I'm still amazed at how often one of
-my \refmodule{doctest} examples stops working after a "harmless"
-change.
-
-Doctest also makes an excellent tool for regression testing, especially if
-you don't skimp on explanatory text. By interleaving prose and examples,
-it becomes much easier to keep track of what's actually being tested, and
-why. When a test fails, good prose can make it much easier to figure out
-what the problem is, and how it should be fixed. It's true that you could
-write extensive comments in code-based testing, but few programmers do.
-Many have found that using doctest approaches instead leads to much clearer
-tests. Perhaps this is simply because doctest makes writing prose a little
-easier than writing code, while writing comments in code is a little
-harder. I think it goes deeper than just that: the natural attitude
-when writing a doctest-based test is that you want to explain the fine
-points of your software, and illustrate them with examples. This in
-turn naturally leads to test files that start with the simplest features,
-and logically progress to complications and edge cases. A coherent
-narrative is the result, instead of a collection of isolated functions
-that test isolated bits of functionality seemingly at random. It's
-a different attitude, and produces different results, blurring the
-distinction between testing and explaining.
-
-Regression testing is best confined to dedicated objects or files. There
-are several options for organizing tests:
-
-\begin{itemize}
-\item Write text files containing test cases as interactive examples,
- and test the files using \function{testfile()} or
- \function{DocFileSuite()}. This is recommended, although is
- easiest to do for new projects, designed from the start to use
- doctest.
-\item Define functions named \code{_regrtest_\textit{topic}} that
- consist of single docstrings, containing test cases for the
- named topics. These functions can be included in the same file
- as the module, or separated out into a separate test file.
-\item Define a \code{__test__} dictionary mapping from regression test
- topics to docstrings containing test cases.
-\end{itemize}
diff --git a/Doc/lib/libdocxmlrpc.tex b/Doc/lib/libdocxmlrpc.tex
deleted file mode 100644
index f93b3b2..0000000
--- a/Doc/lib/libdocxmlrpc.tex
+++ /dev/null
@@ -1,109 +0,0 @@
-\section{\module{DocXMLRPCServer} ---
- Self-documenting XML-RPC server}
-
-\declaremodule{standard}{DocXMLRPCServer}
-\modulesynopsis{Self-documenting XML-RPC server implementation.}
-\moduleauthor{Brian Quinlan}{brianq@activestate.com}
-\sectionauthor{Brian Quinlan}{brianq@activestate.com}
-
-\versionadded{2.3}
-
-The \module{DocXMLRPCServer} module extends the classes found in
-\module{SimpleXMLRPCServer} to serve HTML documentation in response to
-HTTP GET requests. Servers can either be free standing, using
-\class{DocXMLRPCServer}, or embedded in a CGI environment, using
-\class{DocCGIXMLRPCRequestHandler}.
-
-\begin{classdesc}{DocXMLRPCServer}{addr\optional{,
- requestHandler\optional{,
- logRequests\optional{,
- allow_none\optional{,
- encoding\optional{,
- bind_and_activate}}}}}}
-
-Create a new server instance. All parameters have the same meaning as
-for \class{SimpleXMLRPCServer.SimpleXMLRPCServer};
-\var{requestHandler} defaults to \class{DocXMLRPCRequestHandler}.
-
-\end{classdesc}
-
-\begin{classdesc}{DocCGIXMLRPCRequestHandler}{}
-
-Create a new instance to handle XML-RPC requests in a CGI environment.
-
-\end{classdesc}
-
-\begin{classdesc}{DocXMLRPCRequestHandler}{}
-
-Create a new request handler instance. This request handler supports
-XML-RPC POST requests, documentation GET requests, and modifies
-logging so that the \var{logRequests} parameter to the
-\class{DocXMLRPCServer} constructor parameter is honored.
-
-\end{classdesc}
-
-\subsection{DocXMLRPCServer Objects \label{doc-xmlrpc-servers}}
-
-The \class{DocXMLRPCServer} class is derived from
-\class{SimpleXMLRPCServer.SimpleXMLRPCServer} and provides a means of
-creating self-documenting, stand alone XML-RPC servers. HTTP POST
-requests are handled as XML-RPC method calls. HTTP GET requests are
-handled by generating pydoc-style HTML documentation. This allows a
-server to provide its own web-based documentation.
-
-\begin{methoddesc}[DocXMLRPCServer]{set_server_title}{server_title}
-
-Set the title used in the generated HTML documentation. This title
-will be used inside the HTML "title" element.
-
-\end{methoddesc}
-
-\begin{methoddesc}[DocXMLRPCServer]{set_server_name}{server_name}
-
-Set the name used in the generated HTML documentation. This name will
-appear at the top of the generated documentation inside a "h1"
-element.
-
-\end{methoddesc}
-
-
-\begin{methoddesc}[DocXMLRPCServer]{set_server_documentation}{server_documentation}
-
-Set the description used in the generated HTML documentation. This
-description will appear as a paragraph, below the server name, in the
-documentation.
-
-\end{methoddesc}
-
-\subsection{DocCGIXMLRPCRequestHandler}
-
-The \class{DocCGIXMLRPCRequestHandler} class is derived from
-\class{SimpleXMLRPCServer.CGIXMLRPCRequestHandler} and provides a means
-of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests
-are handled as XML-RPC method calls. HTTP GET requests are handled by
-generating pydoc-style HTML documentation. This allows a server to
-provide its own web-based documentation.
-
-\begin{methoddesc}[DocCGIXMLRPCRequestHandler]{set_server_title}{server_title}
-
-Set the title used in the generated HTML documentation. This title
-will be used inside the HTML "title" element.
-
-\end{methoddesc}
-
-\begin{methoddesc}[DocCGIXMLRPCRequestHandler]{set_server_name}{server_name}
-
-Set the name used in the generated HTML documentation. This name will
-appear at the top of the generated documentation inside a "h1"
-element.
-
-\end{methoddesc}
-
-
-\begin{methoddesc}[DocCGIXMLRPCRequestHandler]{set_server_documentation}{server_documentation}
-
-Set the description used in the generated HTML documentation. This
-description will appear as a paragraph, below the server name, in the
-documentation.
-
-\end{methoddesc}
diff --git a/Doc/lib/libdumbdbm.tex b/Doc/lib/libdumbdbm.tex
deleted file mode 100644
index d0917be..0000000
--- a/Doc/lib/libdumbdbm.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{dumbdbm} ---
- Portable DBM implementation}
-
-\declaremodule{standard}{dumbdbm}
-\modulesynopsis{Portable implementation of the simple DBM interface.}
-
-\index{databases}
-
-\begin{notice}
-The \module{dumbdbm} module is intended as a last resort fallback for
-the \refmodule{anydbm} module when no more robust module is available.
-The \module{dumbdbm} module is not written for speed and is not nearly as
-heavily used as the other database modules.
-\end{notice}
-
-The \module{dumbdbm} module provides a persistent dictionary-like interface
-which is written entirely in Python. Unlike other modules such as
-\refmodule{gdbm} and \refmodule{bsddb}, no external library is required. As
-with other persistent mappings, the keys and values must always be strings.
-
-The module defines the following:
-
-\begin{excdesc}{error}
-Raised on dumbdbm-specific errors, such as I/O errors. \exception{KeyError}
-is raised for general mapping errors like specifying an incorrect key.
-\end{excdesc}
-
-\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
-Open a dumbdbm database and return a dumbdbm object. The \var{filename}
-argument is the basename of the database file (without any specific
-extensions). When a dumbdbm database is created, files with \file{.dat} and
-\file{.dir} extensions are created.
-
-The optional \var{flag} argument is currently ignored; the database is
-always opened for update, and will be created if it does not exist.
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666} (and will be modified by the prevailing umask).
-\versionchanged[The \var{mode} argument was ignored in earlier
- versions]{2.2}
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{dbm}{Similar interface to the DBM/NDBM library.}
- \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
- \seemodule{shelve}{Persistence module which stores non-string data.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
-
-
-\subsection{Dumbdbm Objects \label{dumbdbm-objects}}
-
-In addition to the methods provided by the \class{UserDict.DictMixin} class,
-\class{dumbdbm} objects provide the following methods.
-
-\begin{methoddesc}[dumbdbm]{sync}{}
-Synchronize the on-disk directory and data files. This method is called by
-the \method{sync} method of \class{Shelve} objects.
-\end{methoddesc}
diff --git a/Doc/lib/libdummythread.tex b/Doc/lib/libdummythread.tex
deleted file mode 100644
index f6b4c56..0000000
--- a/Doc/lib/libdummythread.tex
+++ /dev/null
@@ -1,22 +0,0 @@
-\section{\module{dummy_thread} ---
- Drop-in replacement for the \module{thread} module}
-
-\declaremodule[dummythread]{standard}{dummy_thread}
-\modulesynopsis{Drop-in replacement for the \refmodule{thread} module.}
-
-This module provides a duplicate interface to the \refmodule{thread}
-module. It is meant to be imported when the \refmodule{thread} module
-is not provided on a platform.
-
-Suggested usage is:
-
-\begin{verbatim}
-try:
- import thread as _thread
-except ImportError:
- import dummy_thread as _thread
-\end{verbatim}
-
-Be careful to not use this module where deadlock might occur from a thread
-being created that blocks waiting for another thread to be created. This
-often occurs with blocking I/O.
diff --git a/Doc/lib/libdummythreading.tex b/Doc/lib/libdummythreading.tex
deleted file mode 100644
index 874f596..0000000
--- a/Doc/lib/libdummythreading.tex
+++ /dev/null
@@ -1,22 +0,0 @@
-\section{\module{dummy_threading} ---
- Drop-in replacement for the \module{threading} module}
-
-\declaremodule[dummythreading]{standard}{dummy_threading}
-\modulesynopsis{Drop-in replacement for the \refmodule{threading} module.}
-
-This module provides a duplicate interface to the
-\refmodule{threading} module. It is meant to be imported when the
-\refmodule{thread} module is not provided on a platform.
-
-Suggested usage is:
-
-\begin{verbatim}
-try:
- import threading as _threading
-except ImportError:
- import dummy_threading as _threading
-\end{verbatim}
-
-Be careful to not use this module where deadlock might occur from a thread
-being created that blocks waiting for another thread to be created. This
-often occurs with blocking I/O.
diff --git a/Doc/lib/liberrno.tex b/Doc/lib/liberrno.tex
deleted file mode 100644
index c0ce6e8..0000000
--- a/Doc/lib/liberrno.tex
+++ /dev/null
@@ -1,149 +0,0 @@
-\section{\module{errno} ---
- Standard errno system symbols}
-
-\declaremodule{standard}{errno}
-\modulesynopsis{Standard errno system symbols.}
-
-
-This module makes available standard \code{errno} system symbols.
-The value of each symbol is the corresponding integer value.
-The names and descriptions are borrowed from \file{linux/include/errno.h},
-which should be pretty all-inclusive.
-
-\begin{datadesc}{errorcode}
- Dictionary providing a mapping from the errno value to the string
- name in the underlying system. For instance,
- \code{errno.errorcode[errno.EPERM]} maps to \code{'EPERM'}.
-\end{datadesc}
-
-To translate a numeric error code to an error message, use
-\function{os.strerror()}.
-
-Of the following list, symbols that are not used on the current
-platform are not defined by the module. The specific list of defined
-symbols is available as \code{errno.errorcode.keys()}. Symbols
-available can include:
-
-\begin{datadesc}{EPERM} Operation not permitted \end{datadesc}
-\begin{datadesc}{ENOENT} No such file or directory \end{datadesc}
-\begin{datadesc}{ESRCH} No such process \end{datadesc}
-\begin{datadesc}{EINTR} Interrupted system call \end{datadesc}
-\begin{datadesc}{EIO} I/O error \end{datadesc}
-\begin{datadesc}{ENXIO} No such device or address \end{datadesc}
-\begin{datadesc}{E2BIG} Arg list too long \end{datadesc}
-\begin{datadesc}{ENOEXEC} Exec format error \end{datadesc}
-\begin{datadesc}{EBADF} Bad file number \end{datadesc}
-\begin{datadesc}{ECHILD} No child processes \end{datadesc}
-\begin{datadesc}{EAGAIN} Try again \end{datadesc}
-\begin{datadesc}{ENOMEM} Out of memory \end{datadesc}
-\begin{datadesc}{EACCES} Permission denied \end{datadesc}
-\begin{datadesc}{EFAULT} Bad address \end{datadesc}
-\begin{datadesc}{ENOTBLK} Block device required \end{datadesc}
-\begin{datadesc}{EBUSY} Device or resource busy \end{datadesc}
-\begin{datadesc}{EEXIST} File exists \end{datadesc}
-\begin{datadesc}{EXDEV} Cross-device link \end{datadesc}
-\begin{datadesc}{ENODEV} No such device \end{datadesc}
-\begin{datadesc}{ENOTDIR} Not a directory \end{datadesc}
-\begin{datadesc}{EISDIR} Is a directory \end{datadesc}
-\begin{datadesc}{EINVAL} Invalid argument \end{datadesc}
-\begin{datadesc}{ENFILE} File table overflow \end{datadesc}
-\begin{datadesc}{EMFILE} Too many open files \end{datadesc}
-\begin{datadesc}{ENOTTY} Not a typewriter \end{datadesc}
-\begin{datadesc}{ETXTBSY} Text file busy \end{datadesc}
-\begin{datadesc}{EFBIG} File too large \end{datadesc}
-\begin{datadesc}{ENOSPC} No space left on device \end{datadesc}
-\begin{datadesc}{ESPIPE} Illegal seek \end{datadesc}
-\begin{datadesc}{EROFS} Read-only file system \end{datadesc}
-\begin{datadesc}{EMLINK} Too many links \end{datadesc}
-\begin{datadesc}{EPIPE} Broken pipe \end{datadesc}
-\begin{datadesc}{EDOM} Math argument out of domain of func \end{datadesc}
-\begin{datadesc}{ERANGE} Math result not representable \end{datadesc}
-\begin{datadesc}{EDEADLK} Resource deadlock would occur \end{datadesc}
-\begin{datadesc}{ENAMETOOLONG} File name too long \end{datadesc}
-\begin{datadesc}{ENOLCK} No record locks available \end{datadesc}
-\begin{datadesc}{ENOSYS} Function not implemented \end{datadesc}
-\begin{datadesc}{ENOTEMPTY} Directory not empty \end{datadesc}
-\begin{datadesc}{ELOOP} Too many symbolic links encountered \end{datadesc}
-\begin{datadesc}{EWOULDBLOCK} Operation would block \end{datadesc}
-\begin{datadesc}{ENOMSG} No message of desired type \end{datadesc}
-\begin{datadesc}{EIDRM} Identifier removed \end{datadesc}
-\begin{datadesc}{ECHRNG} Channel number out of range \end{datadesc}
-\begin{datadesc}{EL2NSYNC} Level 2 not synchronized \end{datadesc}
-\begin{datadesc}{EL3HLT} Level 3 halted \end{datadesc}
-\begin{datadesc}{EL3RST} Level 3 reset \end{datadesc}
-\begin{datadesc}{ELNRNG} Link number out of range \end{datadesc}
-\begin{datadesc}{EUNATCH} Protocol driver not attached \end{datadesc}
-\begin{datadesc}{ENOCSI} No CSI structure available \end{datadesc}
-\begin{datadesc}{EL2HLT} Level 2 halted \end{datadesc}
-\begin{datadesc}{EBADE} Invalid exchange \end{datadesc}
-\begin{datadesc}{EBADR} Invalid request descriptor \end{datadesc}
-\begin{datadesc}{EXFULL} Exchange full \end{datadesc}
-\begin{datadesc}{ENOANO} No anode \end{datadesc}
-\begin{datadesc}{EBADRQC} Invalid request code \end{datadesc}
-\begin{datadesc}{EBADSLT} Invalid slot \end{datadesc}
-\begin{datadesc}{EDEADLOCK} File locking deadlock error \end{datadesc}
-\begin{datadesc}{EBFONT} Bad font file format \end{datadesc}
-\begin{datadesc}{ENOSTR} Device not a stream \end{datadesc}
-\begin{datadesc}{ENODATA} No data available \end{datadesc}
-\begin{datadesc}{ETIME} Timer expired \end{datadesc}
-\begin{datadesc}{ENOSR} Out of streams resources \end{datadesc}
-\begin{datadesc}{ENONET} Machine is not on the network \end{datadesc}
-\begin{datadesc}{ENOPKG} Package not installed \end{datadesc}
-\begin{datadesc}{EREMOTE} Object is remote \end{datadesc}
-\begin{datadesc}{ENOLINK} Link has been severed \end{datadesc}
-\begin{datadesc}{EADV} Advertise error \end{datadesc}
-\begin{datadesc}{ESRMNT} Srmount error \end{datadesc}
-\begin{datadesc}{ECOMM} Communication error on send \end{datadesc}
-\begin{datadesc}{EPROTO} Protocol error \end{datadesc}
-\begin{datadesc}{EMULTIHOP} Multihop attempted \end{datadesc}
-\begin{datadesc}{EDOTDOT} RFS specific error \end{datadesc}
-\begin{datadesc}{EBADMSG} Not a data message \end{datadesc}
-\begin{datadesc}{EOVERFLOW} Value too large for defined data type \end{datadesc}
-\begin{datadesc}{ENOTUNIQ} Name not unique on network \end{datadesc}
-\begin{datadesc}{EBADFD} File descriptor in bad state \end{datadesc}
-\begin{datadesc}{EREMCHG} Remote address changed \end{datadesc}
-\begin{datadesc}{ELIBACC} Can not access a needed shared library \end{datadesc}
-\begin{datadesc}{ELIBBAD} Accessing a corrupted shared library \end{datadesc}
-\begin{datadesc}{ELIBSCN} .lib section in a.out corrupted \end{datadesc}
-\begin{datadesc}{ELIBMAX} Attempting to link in too many shared libraries \end{datadesc}
-\begin{datadesc}{ELIBEXEC} Cannot exec a shared library directly \end{datadesc}
-\begin{datadesc}{EILSEQ} Illegal byte sequence \end{datadesc}
-\begin{datadesc}{ERESTART} Interrupted system call should be restarted \end{datadesc}
-\begin{datadesc}{ESTRPIPE} Streams pipe error \end{datadesc}
-\begin{datadesc}{EUSERS} Too many users \end{datadesc}
-\begin{datadesc}{ENOTSOCK} Socket operation on non-socket \end{datadesc}
-\begin{datadesc}{EDESTADDRREQ} Destination address required \end{datadesc}
-\begin{datadesc}{EMSGSIZE} Message too long \end{datadesc}
-\begin{datadesc}{EPROTOTYPE} Protocol wrong type for socket \end{datadesc}
-\begin{datadesc}{ENOPROTOOPT} Protocol not available \end{datadesc}
-\begin{datadesc}{EPROTONOSUPPORT} Protocol not supported \end{datadesc}
-\begin{datadesc}{ESOCKTNOSUPPORT} Socket type not supported \end{datadesc}
-\begin{datadesc}{EOPNOTSUPP} Operation not supported on transport endpoint \end{datadesc}
-\begin{datadesc}{EPFNOSUPPORT} Protocol family not supported \end{datadesc}
-\begin{datadesc}{EAFNOSUPPORT} Address family not supported by protocol \end{datadesc}
-\begin{datadesc}{EADDRINUSE} Address already in use \end{datadesc}
-\begin{datadesc}{EADDRNOTAVAIL} Cannot assign requested address \end{datadesc}
-\begin{datadesc}{ENETDOWN} Network is down \end{datadesc}
-\begin{datadesc}{ENETUNREACH} Network is unreachable \end{datadesc}
-\begin{datadesc}{ENETRESET} Network dropped connection because of reset \end{datadesc}
-\begin{datadesc}{ECONNABORTED} Software caused connection abort \end{datadesc}
-\begin{datadesc}{ECONNRESET} Connection reset by peer \end{datadesc}
-\begin{datadesc}{ENOBUFS} No buffer space available \end{datadesc}
-\begin{datadesc}{EISCONN} Transport endpoint is already connected \end{datadesc}
-\begin{datadesc}{ENOTCONN} Transport endpoint is not connected \end{datadesc}
-\begin{datadesc}{ESHUTDOWN} Cannot send after transport endpoint shutdown \end{datadesc}
-\begin{datadesc}{ETOOMANYREFS} Too many references: cannot splice \end{datadesc}
-\begin{datadesc}{ETIMEDOUT} Connection timed out \end{datadesc}
-\begin{datadesc}{ECONNREFUSED} Connection refused \end{datadesc}
-\begin{datadesc}{EHOSTDOWN} Host is down \end{datadesc}
-\begin{datadesc}{EHOSTUNREACH} No route to host \end{datadesc}
-\begin{datadesc}{EALREADY} Operation already in progress \end{datadesc}
-\begin{datadesc}{EINPROGRESS} Operation now in progress \end{datadesc}
-\begin{datadesc}{ESTALE} Stale NFS file handle \end{datadesc}
-\begin{datadesc}{EUCLEAN} Structure needs cleaning \end{datadesc}
-\begin{datadesc}{ENOTNAM} Not a XENIX named type file \end{datadesc}
-\begin{datadesc}{ENAVAIL} No XENIX semaphores available \end{datadesc}
-\begin{datadesc}{EISNAM} Is a named type file \end{datadesc}
-\begin{datadesc}{EREMOTEIO} Remote I/O error \end{datadesc}
-\begin{datadesc}{EDQUOT} Quota exceeded \end{datadesc}
-
diff --git a/Doc/lib/libetree.tex b/Doc/lib/libetree.tex
deleted file mode 100644
index 6f20ee3..0000000
--- a/Doc/lib/libetree.tex
+++ /dev/null
@@ -1,426 +0,0 @@
-\section{\module{xml.etree.ElementTree} --- The ElementTree XML API}
-\declaremodule{standard}{xml.etree.ElementTree}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-\modulesynopsis{Implementation of the ElementTree API.}
-
-\versionadded{2.5}
-
-The Element type is a flexible container object, designed to store
-hierarchical data structures in memory. The type can be described as a
-cross between a list and a dictionary.
-
-Each element has a number of properties associated with it:
-
-\begin{itemize}
- \item a tag which is a string identifying what kind of data
- this element represents (the element type, in other words).
- \item a number of attributes, stored in a Python dictionary.
- \item a text string.
- \item an optional tail string.
- \item a number of child elements, stored in a Python sequence
-\end{itemize}
-
-To create an element instance, use the Element or SubElement factory
-functions.
-
-The \class{ElementTree} class can be used to wrap an element
-structure, and convert it from and to XML.
-
-A C implementation of this API is available as
-\module{xml.etree.cElementTree}.
-
-
-\subsection{Functions\label{elementtree-functions}}
-
-\begin{funcdesc}{Comment}{\optional{text}}
-Comment element factory. This factory function creates a special
-element that will be serialized as an XML comment.
-The comment string can be either an 8-bit ASCII string or a Unicode
-string.
-\var{text} is a string containing the comment string.
-Returns an element instance representing a comment.
-\end{funcdesc}
-
-\begin{funcdesc}{dump}{elem}
-Writes an element tree or element structure to sys.stdout. This
-function should be used for debugging only.
-
-The exact output format is implementation dependent. In this
-version, it's written as an ordinary XML file.
-
-\var{elem} is an element tree or an individual element.
-\end{funcdesc}
-
-\begin{funcdesc}{Element}{tag\optional{, attrib}\optional{, **extra}}
-Element factory. This function returns an object implementing the
-standard Element interface. The exact class or type of that object
-is implementation dependent, but it will always be compatible with
-the {\_}ElementInterface class in this module.
-
-The element name, attribute names, and attribute values can be
-either 8-bit ASCII strings or Unicode strings.
-\var{tag} is the element name.
-\var{attrib} is an optional dictionary, containing element attributes.
-\var{extra} contains additional attributes, given as keyword arguments.
-Returns an element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{fromstring}{text}
-Parses an XML section from a string constant. Same as XML.
-\var{text} is a string containing XML data.
-Returns an Element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{iselement}{element}
-Checks if an object appears to be a valid element object.
-\var{element} is an element instance.
-Returns a true value if this is an element object.
-\end{funcdesc}
-
-\begin{funcdesc}{iterparse}{source\optional{, events}}
-Parses an XML section into an element tree incrementally, and reports
-what's going on to the user.
-\var{source} is a filename or file object containing XML data.
-\var{events} is a list of events to report back. If omitted, only ``end''
-events are reported.
-Returns an iterator providing \code{(\var{event}, \var{elem})} pairs.
-\end{funcdesc}
-
-\begin{funcdesc}{parse}{source\optional{, parser}}
-Parses an XML section into an element tree.
-\var{source} is a filename or file object containing XML data.
-\var{parser} is an optional parser instance. If not given, the
-standard XMLTreeBuilder parser is used.
-Returns an ElementTree instance.
-\end{funcdesc}
-
-\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}}
-PI element factory. This factory function creates a special element
-that will be serialized as an XML processing instruction.
-\var{target} is a string containing the PI target.
-\var{text} is a string containing the PI contents, if given.
-Returns an element instance, representing a processing instruction.
-\end{funcdesc}
-
-\begin{funcdesc}{SubElement}{parent, tag\optional{,
- attrib\optional{, **extra}}}
-Subelement factory. This function creates an element instance, and
-appends it to an existing element.
-
-The element name, attribute names, and attribute values can be
-either 8-bit ASCII strings or Unicode strings.
-\var{parent} is the parent element.
-\var{tag} is the subelement name.
-\var{attrib} is an optional dictionary, containing element attributes.
-\var{extra} contains additional attributes, given as keyword arguments.
-Returns an element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{tostring}{element\optional{, encoding}}
-Generates a string representation of an XML element, including all
-subelements.
-\var{element} is an Element instance.
-\var{encoding} is the output encoding (default is US-ASCII).
-Returns an encoded string containing the XML data.
-\end{funcdesc}
-
-\begin{funcdesc}{XML}{text}
-Parses an XML section from a string constant. This function can
-be used to embed ``XML literals'' in Python code.
-\var{text} is a string containing XML data.
-Returns an Element instance.
-\end{funcdesc}
-
-\begin{funcdesc}{XMLID}{text}
-Parses an XML section from a string constant, and also returns
-a dictionary which maps from element id:s to elements.
-\var{text} is a string containing XML data.
-Returns a tuple containing an Element instance and a dictionary.
-\end{funcdesc}
-
-
-\subsection{The Element Interface\label{elementtree-element-interface}}
-
-Element objects returned by Element or SubElement have the
-following methods and attributes.
-
-\begin{memberdesc}[Element]{tag}
-A string identifying what kind of data this element represents
-(the element type, in other words).
-\end{memberdesc}
-
-\begin{memberdesc}[Element]{text}
-The \var{text} attribute can be used to hold additional data
-associated with the element.
-As the name implies this attribute is usually a string but may be any
-application-specific object.
-If the element is created from an XML file the attribute will contain
-any text found between the element tags.
-\end{memberdesc}
-
-\begin{memberdesc}[Element]{tail}
-The \var{tail} attribute can be used to hold additional data
-associated with the element.
-This attribute is usually a string but may be any application-specific object.
-If the element is created from an XML file the attribute will contain
-any text found after the element's end tag and before the next tag.
-\end{memberdesc}
-
-\begin{memberdesc}[Element]{attrib}
-A dictionary containing the element's attributes.
-Note that while the \var{attrib} value is always a real mutable Python
-dictionary, an ElementTree implementation may choose to use another
-internal representation, and create the dictionary only if someone
-asks for it. To take advantage of such implementations, use the
-dictionary methods below whenever possible.
-\end{memberdesc}
-
-The following dictionary-like methods work on the element attributes.
-
-\begin{methoddesc}[Element]{clear}{}
-Resets an element. This function removes all subelements, clears
-all attributes, and sets the text and tail attributes to None.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{get}{key\optional{, default=None}}
-Gets the element attribute named \var{key}.
-
-Returns the attribute value, or \var{default} if the
-attribute was not found.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{items}{}
-Returns the element attributes as a sequence of (name, value) pairs.
-The attributes are returned in an arbitrary order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{keys}{}
-Returns the elements attribute names as a list.
-The names are returned in an arbitrary order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{set}{key, value}
-Set the attribute \var{key} on the element to \var{value}.
-\end{methoddesc}
-
-The following methods work on the element's children (subelements).
-
-\begin{methoddesc}[Element]{append}{subelement}
-Adds the element \var{subelement} to the end of this elements internal list
-of subelements.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{find}{match}
-Finds the first subelement matching \var{match}.
-\var{match} may be a tag name or path.
-Returns an element instance or \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{findall}{match}
-Finds all subelements matching \var{match}.
-\var{match} may be a tag name or path.
-Returns an iterable yielding all matching elements in document order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{findtext}{condition\optional{, default=None}}
-Finds text for the first subelement matching \var{condition}.
-\var{condition} may be a tag name or path.
-Returns the text content of the first matching element, or
-\var{default} if no element was found. Note that if the
-matching element has no text content an empty string is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getchildren}{}
-Returns all subelements. The elements are returned in document order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getiterator}{\optional{tag=None}}
-Creates a tree iterator with the current element as the root.
-The iterator iterates over this element and all elements below it
-that match the given tag. If tag
-is \code{None} or \code{'*'} then all elements are iterated over.
-Returns an iterable that provides element objects in document (depth first)
-order.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{insert}{index, element}
-Inserts a subelement at the given position in this element.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{makeelement}{tag, attrib}
-Creates a new element object of the same type as this element.
-Do not call this method, use the SubElement factory function instead.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{remove}{subelement}
-Removes \var{subelement} from the element.
-Unlike the findXXX methods this method compares elements based on
-the instance identity, not on tag value or contents.
-\end{methoddesc}
-
-Element objects also support the following sequence type methods for
-working with subelements: \method{__delitem__()},
-\method{__getitem__()}, \method{__setitem__()}, \method{__len__()}.
-
-Caution: Because Element objects do not define a
-\method{__nonzero__()} method, elements with no subelements will test
-as \code{False}.
-
-\begin{verbatim}
-element = root.find('foo')
-
-if not element: # careful!
- print "element not found, or element has no subelements"
-
-if element is None:
- print "element not found"
-\end{verbatim}
-
-
-\subsection{ElementTree Objects\label{elementtree-elementtree-objects}}
-
-\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}}
-ElementTree wrapper class. This class represents an entire element
-hierarchy, and adds some extra support for serialization to and from
-standard XML.
-
-\var{element} is the root element.
-The tree is initialized with the contents of the XML \var{file} if given.
-\end{classdesc}
-
-\begin{methoddesc}{_setroot}{element}
-Replaces the root element for this tree. This discards the
-current contents of the tree, and replaces it with the given
-element. Use with care.
-\var{element} is an element instance.
-\end{methoddesc}
-
-\begin{methoddesc}{find}{path}
-Finds the first toplevel element with given tag.
-Same as getroot().find(path).
-\var{path} is the element to look for.
-Returns the first matching element, or \code{None} if no element was found.
-\end{methoddesc}
-
-\begin{methoddesc}{findall}{path}
-Finds all toplevel elements with the given tag.
-Same as getroot().findall(path).
-\var{path} is the element to look for.
-Returns a list or iterator containing all matching elements,
-in document order.
-\end{methoddesc}
-
-\begin{methoddesc}{findtext}{path\optional{, default}}
-Finds the element text for the first toplevel element with given
-tag. Same as getroot().findtext(path).
-\var{path} is the toplevel element to look for.
-\var{default} is the value to return if the element was not found.
-Returns the text content of the first matching element, or the
-default value no element was found. Note that if the element
-has is found, but has no text content, this method returns an
-empty string.
-\end{methoddesc}
-
-\begin{methoddesc}{getiterator}{\optional{tag}}
-Creates and returns a tree iterator for the root element. The iterator loops
-over all elements in this tree, in section order.
-\var{tag} is the tag to look for (default is to return all elements)
-\end{methoddesc}
-
-\begin{methoddesc}{getroot}{}
-Returns the root element for this tree.
-\end{methoddesc}
-
-\begin{methoddesc}{parse}{source\optional{, parser}}
-Loads an external XML section into this element tree.
-\var{source} is a file name or file object.
-\var{parser} is an optional parser instance. If not given, the
-standard XMLTreeBuilder parser is used.
-Returns the section root element.
-\end{methoddesc}
-
-\begin{methoddesc}{write}{file\optional{, encoding}}
-Writes the element tree to a file, as XML.
-\var{file} is a file name, or a file object opened for writing.
-\var{encoding} is the output encoding (default is US-ASCII).
-\end{methoddesc}
-
-
-\subsection{QName Objects\label{elementtree-qname-objects}}
-
-\begin{classdesc}{QName}{text_or_uri\optional{, tag}}
-QName wrapper. This can be used to wrap a QName attribute value, in
-order to get proper namespace handling on output.
-\var{text_or_uri} is a string containing the QName value,
-in the form {\{}uri{\}}local, or, if the tag argument is given,
-the URI part of a QName.
-If \var{tag} is given, the first argument is interpreted as
-an URI, and this argument is interpreted as a local name.
-\class{QName} instances are opaque.
-\end{classdesc}
-
-
-\subsection{TreeBuilder Objects\label{elementtree-treebuilder-objects}}
-
-\begin{classdesc}{TreeBuilder}{\optional{element_factory}}
-Generic element structure builder. This builder converts a sequence
-of start, data, and end method calls to a well-formed element structure.
-You can use this class to build an element structure using a custom XML
-parser, or a parser for some other XML-like format.
-The \var{element_factory} is called to create new Element instances when
-given.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Flushes the parser buffers, and returns the toplevel documen
-element.
-Returns an Element instance.
-\end{methoddesc}
-
-\begin{methoddesc}{data}{data}
-Adds text to the current element.
-\var{data} is a string. This should be either an 8-bit string
-containing ASCII text, or a Unicode string.
-\end{methoddesc}
-
-\begin{methoddesc}{end}{tag}
-Closes the current element.
-\var{tag} is the element name.
-Returns the closed element.
-\end{methoddesc}
-
-\begin{methoddesc}{start}{tag, attrs}
-Opens a new element.
-\var{tag} is the element name.
-\var{attrs} is a dictionary containing element attributes.
-Returns the opened element.
-\end{methoddesc}
-
-
-\subsection{XMLTreeBuilder Objects\label{elementtree-xmltreebuilder-objects}}
-
-\begin{classdesc}{XMLTreeBuilder}{\optional{html,} \optional{target}}
-Element structure builder for XML source data, based on the
-expat parser.
-\var{html} are predefined HTML entities. This flag is not supported
-by the current implementation.
-\var{target} is the target object. If omitted, the builder uses an
-instance of the standard TreeBuilder class.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Finishes feeding data to the parser.
-Returns an element structure.
-\end{methoddesc}
-
-\begin{methoddesc}{doctype}{name, pubid, system}
-Handles a doctype declaration.
-\var{name} is the doctype name.
-\var{pubid} is the public identifier.
-\var{system} is the system identifier.
-\end{methoddesc}
-
-\begin{methoddesc}{feed}{data}
-Feeds data to the parser.
-\var{data} is encoded data.
-\end{methoddesc}
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
deleted file mode 100644
index 74531d3..0000000
--- a/Doc/lib/libexcs.tex
+++ /dev/null
@@ -1,427 +0,0 @@
-\section{Built-in Exceptions}
-
-\declaremodule{standard}{exceptions}
-\modulesynopsis{Standard exception classes.}
-
-
-Exceptions should be class objects.
-The exceptions are defined in the module \module{exceptions}. This
-module never needs to be imported explicitly: the exceptions are
-provided in the built-in namespace as well as the \module{exceptions}
-module.
-
-For class exceptions, in a \keyword{try}\stindex{try} statement with
-an \keyword{except}\stindex{except} clause that mentions a particular
-class, that clause also handles any exception classes derived from
-that class (but not exception classes from which \emph{it} is
-derived). Two exception classes that are not related via subclassing
-are never equivalent, even if they have the same name.
-
-The built-in exceptions listed below can be generated by the
-interpreter or built-in functions. Except where mentioned, they have
-an ``associated value'' indicating the detailed cause of the error.
-This may be a string or a tuple containing several items of
-information (e.g., an error code and a string explaining the code).
-The associated value is the second argument to the
-\keyword{raise}\stindex{raise} statement. If the exception class is
-derived from the standard root class \exception{BaseException}, the
-associated value is present as the exception instance's \member{args}
-attribute.
-
-User code can raise built-in exceptions. This can be used to test an
-exception handler or to report an error condition ``just like'' the
-situation in which the interpreter raises the same exception; but
-beware that there is nothing to prevent user code from raising an
-inappropriate error.
-
-The built-in exception classes can be sub-classed to define new
-exceptions; programmers are encouraged to at least derive new
-exceptions from the \exception{Exception} class and not
-\exception{BaseException}. More
-information on defining exceptions is available in the
-\citetitle[../tut/tut.html]{Python Tutorial} under the heading
-``User-defined Exceptions.''
-
-\setindexsubitem{(built-in exception base class)}
-
-The following exceptions are only used as base classes for other
-exceptions.
-
-\begin{excdesc}{BaseException}
-The base class for all built-in exceptions. It is not meant to be directly
-inherited by user-defined classes (for that use \exception{Exception}). If
-\function{str()} or \function{unicode()} is called on an instance of this
-class, the representation of the argument(s) to the instance are returned or
-the emptry string when there were no arguments. All arguments are
-stored in \member{args} as a tuple.
-\versionadded{2.5}
-\end{excdesc}
-
-\begin{excdesc}{Exception}
-All built-in, non-system-exiting exceptions are derived
-from this class. All user-defined exceptions should also be derived
-from this class.
-\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{ArithmeticError}
-The base class for those built-in exceptions that are raised for
-various arithmetic errors: \exception{OverflowError},
-\exception{ZeroDivisionError}, \exception{FloatingPointError}.
-\end{excdesc}
-
-\begin{excdesc}{LookupError}
-The base class for the exceptions that are raised when a key or
-index used on a mapping or sequence is invalid: \exception{IndexError},
-\exception{KeyError}. This can be raised directly by
-\function{sys.setdefaultencoding()}.
-\end{excdesc}
-
-\begin{excdesc}{EnvironmentError}
-The base class for exceptions that
-can occur outside the Python system: \exception{IOError},
-\exception{OSError}. When exceptions of this type are created with a
-2-tuple, the first item is available on the instance's \member{errno}
-attribute (it is assumed to be an error number), and the second item
-is available on the \member{strerror} attribute (it is usually the
-associated error message). The tuple itself is also available on the
-\member{args} attribute.
-\versionadded{1.5.2}
-
-When an \exception{EnvironmentError} exception is instantiated with a
-3-tuple, the first two items are available as above, while the third
-item is available on the \member{filename} attribute. However, for
-backwards compatibility, the \member{args} attribute contains only a
-2-tuple of the first two constructor arguments.
-
-The \member{filename} attribute is \code{None} when this exception is
-created with other than 3 arguments. The \member{errno} and
-\member{strerror} attributes are also \code{None} when the instance was
-created with other than 2 or 3 arguments. In this last case,
-\member{args} contains the verbatim constructor arguments as a tuple.
-\end{excdesc}
-
-
-\setindexsubitem{(built-in exception)}
-
-The following exceptions are the exceptions that are actually raised.
-
-\begin{excdesc}{AssertionError}
-\stindex{assert}
-Raised when an \keyword{assert} statement fails.
-\end{excdesc}
-
-\begin{excdesc}{AttributeError}
-% xref to attribute reference?
- Raised when an attribute reference or assignment fails. (When an
- object does not support attribute references or attribute assignments
- at all, \exception{TypeError} is raised.)
-\end{excdesc}
-
-\begin{excdesc}{EOFError}
-% XXXJH xrefs here
- Raised when attempting to read beyond the end of a file.
-% XXXJH xrefs here
- (N.B.: the \method{read()} and \method{readline()} methods of file
- objects return an empty string when they hit \EOF.)
-\end{excdesc}
-
-\begin{excdesc}{FloatingPointError}
- Raised when a floating point operation fails. This exception is
- always defined, but can only be raised when Python is configured
- with the \longprogramopt{with-fpectl} option, or the
- \constant{WANT_SIGFPE_HANDLER} symbol is defined in the
- \file{pyconfig.h} file.
-\end{excdesc}
-
-\begin{excdesc}{GeneratorExit}
- Raise when a generator's \method{close()} method is called.
- \versionadded{2.5}
- \versionchanged[Changed to inherit from Exception instead of
- StandardError]{3.0}
-\end{excdesc}
-
-\begin{excdesc}{IOError}
-% XXXJH xrefs here
- Raised when an I/O operation (such as a \keyword{print} statement,
- the built-in \function{open()} function or a method of a file
- object) fails for an I/O-related reason, e.g., ``file not found'' or
- ``disk full''.
-
- This class is derived from \exception{EnvironmentError}. See the
- discussion above for more information on exception instance
- attributes.
-\end{excdesc}
-
-\begin{excdesc}{ImportError}
-% XXXJH xref to import statement?
- Raised when an \keyword{import} statement fails to find the module
- definition or when a \code{from \textrm{\ldots} import} fails to find a
- name that is to be imported.
-\end{excdesc}
-
-\begin{excdesc}{IndexError}
-% XXXJH xref to sequences
- Raised when a sequence subscript is out of range. (Slice indices are
- silently truncated to fall in the allowed range; if an index is not a
- plain integer, \exception{TypeError} is raised.)
-\end{excdesc}
-
-\begin{excdesc}{KeyError}
-% XXXJH xref to mapping objects?
- Raised when a mapping (dictionary) key is not found in the set of
- existing keys.
-\end{excdesc}
-
-\begin{excdesc}{KeyboardInterrupt}
- Raised when the user hits the interrupt key (normally
- \kbd{Control-C} or \kbd{Delete}). During execution, a check for
- interrupts is made regularly.
-% XXX(hylton) xrefs here
- The exception inherits from \exception{BaseException} so as to not be
- accidentally caught by code that catches \exception{Exception} and thus
- prevent the interpreter from exiting.
- \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{MemoryError}
- Raised when an operation runs out of memory but the situation may
- still be rescued (by deleting some objects). The associated value is
- a string indicating what kind of (internal) operation ran out of memory.
- Note that because of the underlying memory management architecture
- (C's \cfunction{malloc()} function), the interpreter may not
- always be able to completely recover from this situation; it
- nevertheless raises an exception so that a stack traceback can be
- printed, in case a run-away program was the cause.
-\end{excdesc}
-
-\begin{excdesc}{NameError}
- Raised when a local or global name is not found. This applies only
- to unqualified names. The associated value is an error message that
- includes the name that could not be found.
-\end{excdesc}
-
-\begin{excdesc}{NotImplementedError}
- This exception is derived from \exception{RuntimeError}. In user
- defined base classes, abstract methods should raise this exception
- when they require derived classes to override the method.
- \versionadded{1.5.2}
-\end{excdesc}
-
-\begin{excdesc}{OSError}
- %xref for os module
- This class is derived from \exception{EnvironmentError} and is used
- primarily as the \refmodule{os} module's \code{os.error} exception.
- See \exception{EnvironmentError} above for a description of the
- possible associated values.
- \versionadded{1.5.2}
-\end{excdesc}
-
-\begin{excdesc}{OverflowError}
-% XXXJH reference to long's and/or int's?
- Raised when the result of an arithmetic operation is too large to be
- represented. This cannot occur for long integers (which would rather
- raise \exception{MemoryError} than give up). Because of the lack of
- standardization of floating point exception handling in C, most
- floating point operations also aren't checked. For plain integers,
- all operations that can overflow are checked except left shift, where
- typical applications prefer to drop bits than raise an exception.
-\end{excdesc}
-
-\begin{excdesc}{ReferenceError}
- This exception is raised when a weak reference proxy, created by the
- \function{\refmodule{weakref}.proxy()} function, is used to access
- an attribute of the referent after it has been garbage collected.
- For more information on weak references, see the \refmodule{weakref}
- module.
- \versionadded[Previously known as the
- \exception{\refmodule{weakref}.ReferenceError}
- exception]{2.2}
-\end{excdesc}
-
-\begin{excdesc}{RuntimeError}
- Raised when an error is detected that doesn't fall in any of the
- other categories. The associated value is a string indicating what
- precisely went wrong. (This exception is mostly a relic from a
- previous version of the interpreter; it is not used very much any
- more.)
-\end{excdesc}
-
-\begin{excdesc}{StopIteration}
- Raised by builtin \function{next()} and an iterator's \method{__next__()}
- method to signal that there are no further values.
- \versionadded{2.2}
- \versionchanged[Changed to inherit from Exception instead of
- StandardError]{3.0}
-\end{excdesc}
-
-
-\begin{excdesc}{SyntaxError}
-% XXXJH xref to these functions?
- Raised when the parser encounters a syntax error. This may occur in
- an \keyword{import} statement, in a call to the built-in functions
- \function{exec()}, \function{eval()} or
- \function{input()}, or when reading the initial script or standard
- input (also interactively).
-
- Instances of this class have attributes \member{filename},
- \member{lineno}, \member{offset} and \member{text} for easier access
- to the details. \function{str()} of the exception instance returns
- only the message.
-\end{excdesc}
-
-\begin{excdesc}{SystemError}
- Raised when the interpreter finds an internal error, but the
- situation does not look so serious to cause it to abandon all hope.
- The associated value is a string indicating what went wrong (in
- low-level terms).
-
- You should report this to the author or maintainer of your Python
- interpreter. Be sure to report the version of the Python
- interpreter (\code{sys.version}; it is also printed at the start of an
- interactive Python session), the exact error message (the exception's
- associated value) and if possible the source of the program that
- triggered the error.
-\end{excdesc}
-
-\begin{excdesc}{SystemExit}
-% XXX(hylton) xref to module sys?
- This exception is raised by the \function{sys.exit()} function. When it
- is not handled, the Python interpreter exits; no stack traceback is
- printed. If the associated value is a plain integer, it specifies the
- system exit status (passed to C's \cfunction{exit()} function); if it is
- \code{None}, the exit status is zero; if it has another type (such as
- a string), the object's value is printed and the exit status is one.
-
- Instances have an attribute \member{code} which is set to the
- proposed exit status or error message (defaulting to \code{None}).
- Also, this exception derives directly from \exception{BaseException} and
- not \exception{Exception}, since it is not technically an error.
-
- A call to \function{sys.exit()} is translated into an exception so that
- clean-up handlers (\keyword{finally} clauses of \keyword{try} statements)
- can be executed, and so that a debugger can execute a script without
- running the risk of losing control. The \function{os._exit()} function
- can be used if it is absolutely positively necessary to exit
- immediately (for example, in the child process after a call to
- \function{fork()}).
-
- The exception inherits from \exception{BaseException} instead of
- \exception{Exception} so that it is not
- accidentally caught by code that catches \exception{Exception}. This allows
- the exception to properly propagate up and cause the interpreter to exit.
- \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{TypeError}
- Raised when an operation or function is applied to an object
- of inappropriate type. The associated value is a string giving
- details about the type mismatch.
-\end{excdesc}
-
-\begin{excdesc}{UnboundLocalError}
- Raised when a reference is made to a local variable in a function or
- method, but no value has been bound to that variable. This is a
- subclass of \exception{NameError}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeError}
- Raised when a Unicode-related encoding or decoding error occurs. It
- is a subclass of \exception{ValueError}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeEncodeError}
- Raised when a Unicode-related error occurs during encoding. It
- is a subclass of \exception{UnicodeError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeDecodeError}
- Raised when a Unicode-related error occurs during decoding. It
- is a subclass of \exception{UnicodeError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeTranslateError}
- Raised when a Unicode-related error occurs during translating. It
- is a subclass of \exception{UnicodeError}.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{ValueError}
- Raised when a built-in operation or function receives an argument
- that has the right type but an inappropriate value, and the
- situation is not described by a more precise exception such as
- \exception{IndexError}.
-\end{excdesc}
-
-\begin{excdesc}{WindowsError}
- Raised when a Windows-specific error occurs or when the error number
- does not correspond to an \cdata{errno} value. The
- \member{winerror} and \member{strerror} values are created from the
- return values of the \cfunction{GetLastError()} and
- \cfunction{FormatMessage()} functions from the Windows Platform API.
- The \member{errno} value maps the \member{winerror} value to
- corresponding \code{errno.h} values.
- This is a subclass of \exception{OSError}.
-\versionadded{2.0}
-\versionchanged[Previous versions put the \cfunction{GetLastError()}
-codes into \member{errno}]{2.5}
-\end{excdesc}
-
-\begin{excdesc}{ZeroDivisionError}
- Raised when the second argument of a division or modulo operation is
- zero. The associated value is a string indicating the type of the
- operands and the operation.
-\end{excdesc}
-
-
-\setindexsubitem{(built-in warning)}
-
-The following exceptions are used as warning categories; see the
-\refmodule{warnings} module for more information.
-
-\begin{excdesc}{Warning}
-Base class for warning categories.
-\end{excdesc}
-
-\begin{excdesc}{UserWarning}
-Base class for warnings generated by user code.
-\end{excdesc}
-
-\begin{excdesc}{DeprecationWarning}
-Base class for warnings about deprecated features.
-\end{excdesc}
-
-\begin{excdesc}{PendingDeprecationWarning}
-Base class for warnings about features which will be deprecated in the future.
-\end{excdesc}
-
-\begin{excdesc}{SyntaxWarning}
-Base class for warnings about dubious syntax
-\end{excdesc}
-
-\begin{excdesc}{RuntimeWarning}
-Base class for warnings about dubious runtime behavior.
-\end{excdesc}
-
-\begin{excdesc}{FutureWarning}
-Base class for warnings about constructs that will change semantically
-in the future.
-\end{excdesc}
-
-\begin{excdesc}{ImportWarning}
-Base class for warnings about probable mistakes in module imports.
-\versionadded{2.5}
-\end{excdesc}
-
-\begin{excdesc}{UnicodeWarning}
-Base class for warnings related to Unicode.
-\versionadded{2.5}
-\end{excdesc}
-
-The class hierarchy for built-in exceptions is:
-
-\verbatiminput{../../Lib/test/exception_hierarchy.txt}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
deleted file mode 100644
index dc76da3..0000000
--- a/Doc/lib/libfcntl.tex
+++ /dev/null
@@ -1,174 +0,0 @@
-\section{\module{fcntl} ---
- The \function{fcntl()} and \function{ioctl()} system calls}
-
-\declaremodule{builtin}{fcntl}
- \platform{Unix}
-\modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.}
-\sectionauthor{Jaap Vermeulen}{}
-
-\indexii{UNIX@\UNIX}{file control}
-\indexii{UNIX@\UNIX}{I/O control}
-
-This module performs file control and I/O control on file descriptors.
-It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()}
-\UNIX{} routines.
-
-All functions in this module take a file descriptor \var{fd} as their
-first argument. This can be an integer file descriptor, such as
-returned by \code{sys.stdin.fileno()}, or a file object, such as
-\code{sys.stdin} itself, which provides a \method{fileno()} which
-returns a genuine file descriptor.
-
-The module defines the following functions:
-
-
-\begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
- Perform the requested operation on file descriptor \var{fd} (file
- objects providing a \method{fileno()} method are accepted as well).
- The operation is defined by \var{op} and is operating system
- dependent. These codes are also found in the \module{fcntl}
- module. The argument \var{arg} is optional, and defaults to the
- integer value \code{0}. When present, it can either be an integer
- value, or a string. With the argument missing or an integer value,
- the return value of this function is the integer return value of the
- C \cfunction{fcntl()} call. When the argument is a string it
- represents a binary structure, e.g.\ created by
- \function{\refmodule{struct}.pack()}. The binary data is copied to a buffer
- whose address is passed to the C \cfunction{fcntl()} call. The
- return value after a successful call is the contents of the buffer,
- converted to a string object. The length of the returned string
- will be the same as the length of the \var{arg} argument. This is
- limited to 1024 bytes. If the information returned in the buffer by
- the operating system is larger than 1024 bytes, this is most likely
- to result in a segmentation violation or a more subtle data
- corruption.
-
- If the \cfunction{fcntl()} fails, an \exception{IOError} is
- raised.
-\end{funcdesc}
-
-\begin{funcdesc}{ioctl}{fd, op\optional{, arg\optional{, mutate_flag}}}
- This function is identical to the \function{fcntl()} function,
- except that the operations are typically defined in the library
- module \refmodule{termios} and the argument handling is even more
- complicated.
-
- The parameter \var{arg} can be one of an integer, absent (treated
- identically to the integer \code{0}), an object supporting the
- read-only buffer interface (most likely a plain Python string) or an
- object supporting the read-write buffer interface.
-
- In all but the last case, behaviour is as for the \function{fcntl()}
- function.
-
- If a mutable buffer is passed, then the behaviour is determined by
- the value of the \var{mutate_flag} parameter.
-
- If it is false, the buffer's mutability is ignored and behaviour is
- as for a read-only buffer, except that the 1024 byte limit mentioned
- above is avoided -- so long as the buffer you pass is as least as
- long as what the operating system wants to put there, things should
- work.
-
- If \var{mutate_flag} is true, then the buffer is (in effect) passed
- to the underlying \function{ioctl()} system call, the latter's
- return code is passed back to the calling Python, and the buffer's
- new contents reflect the action of the \function{ioctl()}. This is a
- slight simplification, because if the supplied buffer is less than
- 1024 bytes long it is first copied into a static buffer 1024 bytes
- long which is then passed to \function{ioctl()} and copied back into
- the supplied buffer.
-
- If \var{mutate_flag} is not supplied, then from Python 2.5 it
- defaults to true, which is a change from versions 2.3 and 2.4.
- Supply the argument explicitly if version portability is a priority.
-
- An example:
-
-\begin{verbatim}
->>> import array, fcntl, struct, termios, os
->>> os.getpgrp()
-13341
->>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
-13341
->>> buf = array.array('h', [0])
->>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
-0
->>> buf
-array('h', [13341])
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{flock}{fd, op}
-Perform the lock operation \var{op} on file descriptor \var{fd} (file
- objects providing a \method{fileno()} method are accepted as well).
-See the \UNIX{} manual \manpage{flock}{3} for details. (On some
-systems, this function is emulated using \cfunction{fcntl()}.)
-\end{funcdesc}
-
-\begin{funcdesc}{lockf}{fd, operation,
- \optional{length, \optional{start, \optional{whence}}}}
-This is essentially a wrapper around the \function{fcntl()} locking
-calls. \var{fd} is the file descriptor of the file to lock or unlock,
-and \var{operation} is one of the following values:
-
-\begin{itemize}
-\item \constant{LOCK_UN} -- unlock
-\item \constant{LOCK_SH} -- acquire a shared lock
-\item \constant{LOCK_EX} -- acquire an exclusive lock
-\end{itemize}
-
-When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it
-can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on
-lock acquisition. If \constant{LOCK_NB} is used and the lock cannot
-be acquired, an \exception{IOError} will be raised and the exception
-will have an \var{errno} attribute set to \constant{EACCES} or
-\constant{EAGAIN} (depending on the operating system; for portability,
-check for both values). On at least some systems, \constant{LOCK_EX}
-can only be used if the file descriptor refers to a file opened for
-writing.
-
-\var{length} is the number of bytes to lock, \var{start} is the byte
-offset at which the lock starts, relative to \var{whence}, and
-\var{whence} is as with \function{fileobj.seek()}, specifically:
-
-\begin{itemize}
-\item \constant{0} -- relative to the start of the file
- (\constant{SEEK_SET})
-\item \constant{1} -- relative to the current buffer position
- (\constant{SEEK_CUR})
-\item \constant{2} -- relative to the end of the file
- (\constant{SEEK_END})
-\end{itemize}
-
-The default for \var{start} is 0, which means to start at the
-beginning of the file. The default for \var{length} is 0 which means
-to lock to the end of the file. The default for \var{whence} is also
-0.
-\end{funcdesc}
-
-Examples (all on a SVR4 compliant system):
-
-\begin{verbatim}
-import struct, fcntl, os
-
-f = open(...)
-rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
-
-lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
-rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
-\end{verbatim}
-
-Note that in the first example the return value variable \var{rv} will
-hold an integer value; in the second example it will hold a string
-value. The structure lay-out for the \var{lockdata} variable is
-system dependent --- therefore using the \function{flock()} call may be
-better.
-
-\begin{seealso}
- \seemodule{os}{If the locking flags \constant{O_SHLOCK} and
- \constant{O_EXLOCK} are present in the \module{os} module,
- the \function{os.open()} function provides a more
- platform-independent alternative to the \function{lockf()}
- and \function{flock()} functions.}
-\end{seealso}
diff --git a/Doc/lib/libfilecmp.tex b/Doc/lib/libfilecmp.tex
deleted file mode 100644
index 42b4b8c..0000000
--- a/Doc/lib/libfilecmp.tex
+++ /dev/null
@@ -1,142 +0,0 @@
-\section{\module{filecmp} ---
- File and Directory Comparisons}
-
-\declaremodule{standard}{filecmp}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Compare files efficiently.}
-
-
-The \module{filecmp} module defines functions to compare files and
-directories, with various optional time/correctness trade-offs.
-
-The \module{filecmp} module defines the following functions:
-
-\begin{funcdesc}{cmp}{f1, f2\optional{, shallow}}
-Compare the files named \var{f1} and \var{f2}, returning \code{True} if
-they seem equal, \code{False} otherwise.
-
-Unless \var{shallow} is given and is false, files with identical
-\function{os.stat()} signatures are taken to be equal.
-
-Files that were compared using this function will not be compared again
-unless their \function{os.stat()} signature changes.
-
-Note that no external programs are called from this function, giving it
-portability and efficiency.
-\end{funcdesc}
-
-\begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{,
- shallow}}
-Returns three lists of file names: \var{match}, \var{mismatch},
-\var{errors}. \var{match} contains the list of files match in both
-directories, \var{mismatch} includes the names of those that don't,
-and \var{errros} lists the names of files which could not be
-compared. Files may be listed in \var{errors} because the user may
-lack permission to read them or many other reasons, but always that
-the comparison could not be done for some reason.
-
-The \var{common} parameter is a list of file names found in both directories.
-The \var{shallow} parameter has the same
-meaning and default value as for \function{filecmp.cmp()}.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import filecmp
->>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
-True
->>> filecmp.cmp('libundoc.tex', 'lib.tex')
-False
-\end{verbatim}
-
-
-\subsection{The \protect\class{dircmp} class \label{dircmp-objects}}
-
-\class{dircmp} instances are built using this constructor:
-
-\begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}}
-Construct a new directory comparison object, to compare the
-directories \var{a} and \var{b}. \var{ignore} is a list of names to
-ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a
-list of names to hide, and defaults to \code{[os.curdir, os.pardir]}.
-\end{classdesc}
-
-The \class{dircmp} class provides the following methods:
-
-\begin{methoddesc}[dircmp]{report}{}
-Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}.
-\end{methoddesc}
-
-\begin{methoddesc}[dircmp]{report_partial_closure}{}
-Print a comparison between \var{a} and \var{b} and common immediate
-subdirectories.
-\end{methoddesc}
-
-\begin{methoddesc}[dircmp]{report_full_closure}{}
-Print a comparison between \var{a} and \var{b} and common
-subdirectories (recursively).
-\end{methoddesc}
-
-
-The \class{dircmp} offers a number of interesting attributes that may
-be used to get various bits of information about the directory trees
-being compared.
-
-Note that via \method{__getattr__()} hooks, all attributes are
-computed lazily, so there is no speed penalty if only those
-attributes which are lightweight to compute are used.
-
-\begin{memberdesc}[dircmp]{left_list}
-Files and subdirectories in \var{a}, filtered by \var{hide} and
-\var{ignore}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{right_list}
-Files and subdirectories in \var{b}, filtered by \var{hide} and
-\var{ignore}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common}
-Files and subdirectories in both \var{a} and \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{left_only}
-Files and subdirectories only in \var{a}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{right_only}
-Files and subdirectories only in \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common_dirs}
-Subdirectories in both \var{a} and \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common_files}
-Files in both \var{a} and \var{b}
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{common_funny}
-Names in both \var{a} and \var{b}, such that the type differs between
-the directories, or names for which \function{os.stat()} reports an
-error.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{same_files}
-Files which are identical in both \var{a} and \var{b}.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{diff_files}
-Files which are in both \var{a} and \var{b}, whose contents differ.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{funny_files}
-Files which are in both \var{a} and \var{b}, but could not be
-compared.
-\end{memberdesc}
-
-\begin{memberdesc}[dircmp]{subdirs}
-A dictionary mapping names in \member{common_dirs} to
-\class{dircmp} objects.
-\end{memberdesc}
diff --git a/Doc/lib/libfileinput.tex b/Doc/lib/libfileinput.tex
deleted file mode 100644
index 3cfb7bc..0000000
--- a/Doc/lib/libfileinput.tex
+++ /dev/null
@@ -1,192 +0,0 @@
-\section{\module{fileinput} ---
- Iterate over lines from multiple input streams}
-\declaremodule{standard}{fileinput}
-\moduleauthor{Guido van Rossum}{guido@python.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\modulesynopsis{Perl-like iteration over lines from multiple input
-streams, with ``save in place'' capability.}
-
-
-This module implements a helper class and functions to quickly write a
-loop over standard input or a list of files.
-
-The typical use is:
-
-\begin{verbatim}
-import fileinput
-for line in fileinput.input():
- process(line)
-\end{verbatim}
-
-This iterates over the lines of all files listed in
-\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is
-empty. If a filename is \code{'-'}, it is also replaced by
-\code{sys.stdin}. To specify an alternative list of filenames, pass
-it as the first argument to \function{input()}. A single file name is
-also allowed.
-
-All files are opened in text mode by default, but you can override this by
-specifying the \var{mode} parameter in the call to \function{input()}
-or \class{FileInput()}. If an I/O error occurs during opening or reading
-a file, \exception{IOError} is raised.
-
-If \code{sys.stdin} is used more than once, the second and further use
-will return no lines, except perhaps for interactive use, or if it has
-been explicitly reset (e.g. using \code{sys.stdin.seek(0)}).
-
-Empty files are opened and immediately closed; the only time their
-presence in the list of filenames is noticeable at all is when the
-last file opened is empty.
-
-It is possible that the last line of a file does not end in a newline
-character; lines are returned including the trailing newline when it
-is present.
-
-You can control how files are opened by providing an opening hook via the
-\var{openhook} parameter to \function{input()} or \class{FileInput()}.
-The hook must be a function that takes two arguments, \var{filename}
-and \var{mode}, and returns an accordingly opened file-like object.
-Two useful hooks are already provided by this module.
-
-The following function is the primary interface of this module:
-
-\begin{funcdesc}{input}{\optional{files\optional{, inplace\optional{,
- backup\optional{, mode\optional{, openhook}}}}}}
- Create an instance of the \class{FileInput} class. The instance
- will be used as global state for the functions of this module, and
- is also returned to use during iteration. The parameters to this
- function will be passed along to the constructor of the
- \class{FileInput} class.
-
- \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5}
-\end{funcdesc}
-
-
-The following functions use the global state created by
-\function{input()}; if there is no active state,
-\exception{RuntimeError} is raised.
-
-\begin{funcdesc}{filename}{}
- Return the name of the file currently being read. Before the first
- line has been read, returns \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{fileno}{}
- Return the integer ``file descriptor'' for the current file. When no
- file is opened (before the first line and between files), returns
- \code{-1}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{lineno}{}
- Return the cumulative line number of the line that has just been
- read. Before the first line has been read, returns \code{0}. After
- the last line of the last file has been read, returns the line
- number of that line.
-\end{funcdesc}
-
-\begin{funcdesc}{filelineno}{}
- Return the line number in the current file. Before the first line
- has been read, returns \code{0}. After the last line of the last
- file has been read, returns the line number of that line within the
- file.
-\end{funcdesc}
-
-\begin{funcdesc}{isfirstline}{}
- Returns true if the line just read is the first line of its file,
- otherwise returns false.
-\end{funcdesc}
-
-\begin{funcdesc}{isstdin}{}
- Returns true if the last line was read from \code{sys.stdin},
- otherwise returns false.
-\end{funcdesc}
-
-\begin{funcdesc}{nextfile}{}
- Close the current file so that the next iteration will read the
- first line from the next file (if any); lines not read from the file
- will not count towards the cumulative line count. The filename is
- not changed until after the first line of the next file has been
- read. Before the first line has been read, this function has no
- effect; it cannot be used to skip the first file. After the last
- line of the last file has been read, this function has no effect.
-\end{funcdesc}
-
-\begin{funcdesc}{close}{}
- Close the sequence.
-\end{funcdesc}
-
-
-The class which implements the sequence behavior provided by the
-module is available for subclassing as well:
-
-\begin{classdesc}{FileInput}{\optional{files\optional{,
- inplace\optional{, backup\optional{,
- mode\optional{, openhook}}}}}}
- Class \class{FileInput} is the implementation; its methods
- \method{filename()}, \method{fileno()}, \method{lineno()},
- \method{fileline()}, \method{isfirstline()}, \method{isstdin()},
- \method{nextfile()} and \method{close()} correspond to the functions
- of the same name in the module.
- In addition it has a \method{readline()} method which
- returns the next input line, and a \method{__getitem__()} method
- which implements the sequence behavior. The sequence must be
- accessed in strictly sequential order; random access and
- \method{readline()} cannot be mixed.
-
- With \var{mode} you can specify which file mode will be passed to
- \function{open()}. It must be one of \code{'r'}, \code{'rU'},
- \code{'U'} and \code{'rb'}.
-
- The \var{openhook}, when given, must be a function that takes two arguments,
- \var{filename} and \var{mode}, and returns an accordingly opened
- file-like object.
- You cannot use \var{inplace} and \var{openhook} together.
-
- \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5}
-\end{classdesc}
-
-\strong{Optional in-place filtering:} if the keyword argument
-\code{\var{inplace}=1} is passed to \function{input()} or to the
-\class{FileInput} constructor, the file is moved to a backup file and
-standard output is directed to the input file (if a file of the same
-name as the backup file already exists, it will be replaced silently).
-This makes it possible to write a filter that rewrites its input file
-in place. If the keyword argument \code{\var{backup}='.<some
-extension>'} is also given, it specifies the extension for the backup
-file, and the backup file remains around; by default, the extension is
-\code{'.bak'} and it is deleted when the output file is closed. In-place
-filtering is disabled when standard input is read.
-
-\strong{Caveat:} The current implementation does not work for MS-DOS
-8+3 filesystems.
-
-
-The two following opening hooks are provided by this module:
-
-\begin{funcdesc}{hook_compressed}{filename, mode}
- Transparently opens files compressed with gzip and bzip2 (recognized
- by the extensions \code{'.gz'} and \code{'.bz2'}) using the \module{gzip}
- and \module{bz2} modules. If the filename extension is not \code{'.gz'}
- or \code{'.bz2'}, the file is opened normally (ie,
- using \function{open()} without any decompression).
-
- Usage example:
- \samp{fi = fileinput.FileInput(openhook=fileinput.hook_compressed)}
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{hook_encoded}{encoding}
- Returns a hook which opens each file with \function{codecs.open()},
- using the given \var{encoding} to read the file.
-
- Usage example:
- \samp{fi = fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))}
-
- \note{With this hook, \class{FileInput} might return Unicode strings
- depending on the specified \var{encoding}.}
- \versionadded{2.5}
-\end{funcdesc}
-
diff --git a/Doc/lib/libfnmatch.tex b/Doc/lib/libfnmatch.tex
deleted file mode 100644
index 1ac46bd..0000000
--- a/Doc/lib/libfnmatch.tex
+++ /dev/null
@@ -1,86 +0,0 @@
-\section{\module{fnmatch} ---
- \UNIX{} filename pattern matching}
-
-\declaremodule{standard}{fnmatch}
-\modulesynopsis{\UNIX\ shell style filename pattern matching.}
-
-
-\index{filenames!wildcard expansion}
-
-This module provides support for \UNIX{} shell-style wildcards, which
-are \emph{not} the same as regular expressions (which are documented
-in the \refmodule{re}\refstmodindex{re} module). The special
-characters used in shell-style wildcards are:
-
-\begin{tableii}{c|l}{code}{Pattern}{Meaning}
- \lineii{*}{matches everything}
- \lineii{?}{matches any single character}
- \lineii{[\var{seq}]}{matches any character in \var{seq}}
- \lineii{[!\var{seq}]}{matches any character not in \var{seq}}
-\end{tableii}
-
-Note that the filename separator (\code{'/'} on \UNIX) is \emph{not}
-special to this module. See module
-\refmodule{glob}\refstmodindex{glob} for pathname expansion
-(\refmodule{glob} uses \function{fnmatch()} to match pathname
-segments). Similarly, filenames starting with a period are
-not special for this module, and are matched by the \code{*} and
-\code{?} patterns.
-
-
-\begin{funcdesc}{fnmatch}{filename, pattern}
-Test whether the \var{filename} string matches the \var{pattern}
-string, returning true or false. If the operating system is
-case-insensitive, then both parameters will be normalized to all
-lower- or upper-case before the comparison is performed. If you
-require a case-sensitive comparison regardless of whether that's
-standard for your operating system, use \function{fnmatchcase()}
-instead.
-
-This example will print all file names in the current directory with the
-extension \code{.txt}:
-
-\begin{verbatim}
-import fnmatch
-import os
-
-for file in os.listdir('.'):
- if fnmatch.fnmatch(file, '*.txt'):
- print file
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{fnmatchcase}{filename, pattern}
-Test whether \var{filename} matches \var{pattern}, returning true or
-false; the comparison is case-sensitive.
-\end{funcdesc}
-
-\begin{funcdesc}{filter}{names, pattern}
-Return the subset of the list of \var{names} that match \var{pattern}.
-It is the same as \code{[n for n in names if fnmatch(n, pattern)]}, but
-implemented more efficiently.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{translate}{pattern}
-Return the shell-style \var{pattern} converted to a regular
-expression.
-
-Example:
-
-\begin{verbatim}
->>> import fnmatch, re
->>>
->>> regex = fnmatch.translate('*.txt')
->>> regex
-'.*\\.txt$'
->>> reobj = re.compile(regex)
->>> print reobj.match('foobar.txt')
-<_sre.SRE_Match object at 0x...>
-\end{verbatim}
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{glob}{\UNIX{} shell-style path expansion.}
-\end{seealso}
diff --git a/Doc/lib/libformatter.tex b/Doc/lib/libformatter.tex
deleted file mode 100644
index d7c5a6b..0000000
--- a/Doc/lib/libformatter.tex
+++ /dev/null
@@ -1,329 +0,0 @@
-\section{\module{formatter} ---
- Generic output formatting}
-
-\declaremodule{standard}{formatter}
-\modulesynopsis{Generic output formatter and device interface.}
-
-
-
-This module supports two interface definitions, each with multiple
-implementations. The \emph{formatter} interface is used by the
-\class{HTMLParser} class of the \refmodule{htmllib} module, and the
-\emph{writer} interface is required by the formatter interface.
-\withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
-
-Formatter objects transform an abstract flow of formatting events into
-specific output events on writer objects. Formatters manage several
-stack structures to allow various properties of a writer object to be
-changed and restored; writers need not be able to handle relative
-changes nor any sort of ``change back'' operation. Specific writer
-properties which may be controlled via formatter objects are
-horizontal alignment, font, and left margin indentations. A mechanism
-is provided which supports providing arbitrary, non-exclusive style
-settings to a writer as well. Additional interfaces facilitate
-formatting events which are not reversible, such as paragraph
-separation.
-
-Writer objects encapsulate device interfaces. Abstract devices, such
-as file formats, are supported as well as physical devices. The
-provided implementations all work with abstract devices. The
-interface makes available mechanisms for setting the properties which
-formatter objects manage and inserting data into the output.
-
-
-\subsection{The Formatter Interface \label{formatter-interface}}
-
-Interfaces to create formatters are dependent on the specific
-formatter class being instantiated. The interfaces described below
-are the required interfaces which all formatters must support once
-initialized.
-
-One data element is defined at the module level:
-
-
-\begin{datadesc}{AS_IS}
-Value which can be used in the font specification passed to the
-\code{push_font()} method described below, or as the new value to any
-other \code{push_\var{property}()} method. Pushing the \code{AS_IS}
-value allows the corresponding \code{pop_\var{property}()} method to
-be called without having to track whether the property was changed.
-\end{datadesc}
-
-The following attributes are defined for formatter instance objects:
-
-
-\begin{memberdesc}[formatter]{writer}
-The writer instance with which the formatter interacts.
-\end{memberdesc}
-
-
-\begin{methoddesc}[formatter]{end_paragraph}{blanklines}
-Close any open paragraphs and insert at least \var{blanklines}
-before the next paragraph.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_line_break}{}
-Add a hard line break if one does not already exist. This does not
-break the logical paragraph.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_hor_rule}{*args, **kw}
-Insert a horizontal rule in the output. A hard break is inserted if
-there is data in the current paragraph, but the logical paragraph is
-not broken. The arguments and keywords are passed on to the writer's
-\method{send_line_break()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_flowing_data}{data}
-Provide data which should be formatted with collapsed whitespace.
-Whitespace from preceding and successive calls to
-\method{add_flowing_data()} is considered as well when the whitespace
-collapse is performed. The data which is passed to this method is
-expected to be word-wrapped by the output device. Note that any
-word-wrapping still must be performed by the writer object due to the
-need to rely on device and font information.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_literal_data}{data}
-Provide data which should be passed to the writer unchanged.
-Whitespace, including newline and tab characters, are considered legal
-in the value of \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{add_label_data}{format, counter}
-Insert a label which should be placed to the left of the current left
-margin. This should be used for constructing bulleted or numbered
-lists. If the \var{format} value is a string, it is interpreted as a
-format specification for \var{counter}, which should be an integer.
-The result of this formatting becomes the value of the label; if
-\var{format} is not a string it is used as the label value directly.
-The label value is passed as the only argument to the writer's
-\method{send_label_data()} method. Interpretation of non-string label
-values is dependent on the associated writer.
-
-Format specifications are strings which, in combination with a counter
-value, are used to compute label values. Each character in the format
-string is copied to the label value, with some characters recognized
-to indicate a transform on the counter value. Specifically, the
-character \character{1} represents the counter value formatter as an
-Arabic number, the characters \character{A} and \character{a}
-represent alphabetic representations of the counter value in upper and
-lower case, respectively, and \character{I} and \character{i}
-represent the counter value in Roman numerals, in upper and lower
-case. Note that the alphabetic and roman transforms require that the
-counter value be greater than zero.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{flush_softspace}{}
-Send any pending whitespace buffered from a previous call to
-\method{add_flowing_data()} to the associated writer object. This
-should be called before any direct manipulation of the writer object.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_alignment}{align}
-Push a new alignment setting onto the alignment stack. This may be
-\constant{AS_IS} if no change is desired. If the alignment value is
-changed from the previous setting, the writer's \method{new_alignment()}
-method is called with the \var{align} value.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_alignment}{}
-Restore the previous alignment.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
-Change some or all font properties of the writer object. Properties
-which are not set to \constant{AS_IS} are set to the values passed in
-while others are maintained at their current settings. The writer's
-\method{new_font()} method is called with the fully resolved font
-specification.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_font}{}
-Restore the previous font.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_margin}{margin}
-Increase the number of left margin indentations by one, associating
-the logical tag \var{margin} with the new indentation. The initial
-margin level is \code{0}. Changed values of the logical tag must be
-true values; false values other than \constant{AS_IS} are not
-sufficient to change the margin.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_margin}{}
-Restore the previous margin.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{push_style}{*styles}
-Push any number of arbitrary style specifications. All styles are
-pushed onto the styles stack in order. A tuple representing the
-entire stack, including \constant{AS_IS} values, is passed to the
-writer's \method{new_styles()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
-Pop the last \var{n} style specifications passed to
-\method{push_style()}. A tuple representing the revised stack,
-including \constant{AS_IS} values, is passed to the writer's
-\method{new_styles()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{set_spacing}{spacing}
-Set the spacing style for the writer.
-\end{methoddesc}
-
-\begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 1}}}
-Inform the formatter that data has been added to the current paragraph
-out-of-band. This should be used when the writer has been manipulated
-directly. The optional \var{flag} argument can be set to false if
-the writer manipulations produced a hard line break at the end of the
-output.
-\end{methoddesc}
-
-
-\subsection{Formatter Implementations \label{formatter-impls}}
-
-Two implementations of formatter objects are provided by this module.
-Most applications may use one of these classes without modification or
-subclassing.
-
-\begin{classdesc}{NullFormatter}{\optional{writer}}
-A formatter which does nothing. If \var{writer} is omitted, a
-\class{NullWriter} instance is created. No methods of the writer are
-called by \class{NullFormatter} instances. Implementations should
-inherit from this class if implementing a writer interface but don't
-need to inherit any implementation.
-\end{classdesc}
-
-\begin{classdesc}{AbstractFormatter}{writer}
-The standard formatter. This implementation has demonstrated wide
-applicability to many writers, and may be used directly in most
-circumstances. It has been used to implement a full-featured
-World Wide Web browser.
-\end{classdesc}
-
-
-
-\subsection{The Writer Interface \label{writer-interface}}
-
-Interfaces to create writers are dependent on the specific writer
-class being instantiated. The interfaces described below are the
-required interfaces which all writers must support once initialized.
-Note that while most applications can use the
-\class{AbstractFormatter} class as a formatter, the writer must
-typically be provided by the application.
-
-
-\begin{methoddesc}[writer]{flush}{}
-Flush any buffered output or device control events.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_alignment}{align}
-Set the alignment style. The \var{align} value can be any object,
-but by convention is a string or \code{None}, where \code{None}
-indicates that the writer's ``preferred'' alignment should be used.
-Conventional \var{align} values are \code{'left'}, \code{'center'},
-\code{'right'}, and \code{'justify'}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_font}{font}
-Set the font style. The value of \var{font} will be \code{None},
-indicating that the device's default font should be used, or a tuple
-of the form \code{(}\var{size}, \var{italic}, \var{bold},
-\var{teletype}\code{)}. Size will be a string indicating the size of
-font that should be used; specific strings and their interpretation
-must be defined by the application. The \var{italic}, \var{bold}, and
-\var{teletype} values are Boolean values specifying which of those
-font attributes should be used.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_margin}{margin, level}
-Set the margin level to the integer \var{level} and the logical tag
-to \var{margin}. Interpretation of the logical tag is at the
-writer's discretion; the only restriction on the value of the logical
-tag is that it not be a false value for non-zero values of
-\var{level}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_spacing}{spacing}
-Set the spacing style to \var{spacing}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{new_styles}{styles}
-Set additional styles. The \var{styles} value is a tuple of
-arbitrary values; the value \constant{AS_IS} should be ignored. The
-\var{styles} tuple may be interpreted either as a set or as a stack
-depending on the requirements of the application and writer
-implementation.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_line_break}{}
-Break the current line.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_paragraph}{blankline}
-Produce a paragraph separation of at least \var{blankline} blank
-lines, or the equivalent. The \var{blankline} value will be an
-integer. Note that the implementation will receive a call to
-\method{send_line_break()} before this call if a line break is needed;
-this method should not include ending the last line of the paragraph.
-It is only responsible for vertical spacing between paragraphs.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_hor_rule}{*args, **kw}
-Display a horizontal rule on the output device. The arguments to this
-method are entirely application- and writer-specific, and should be
-interpreted with care. The method implementation may assume that a
-line break has already been issued via \method{send_line_break()}.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_flowing_data}{data}
-Output character data which may be word-wrapped and re-flowed as
-needed. Within any sequence of calls to this method, the writer may
-assume that spans of multiple whitespace characters have been
-collapsed to single space characters.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_literal_data}{data}
-Output character data which has already been formatted
-for display. Generally, this should be interpreted to mean that line
-breaks indicated by newline characters should be preserved and no new
-line breaks should be introduced. The data may contain embedded
-newline and tab characters, unlike data provided to the
-\method{send_formatted_data()} interface.
-\end{methoddesc}
-
-\begin{methoddesc}[writer]{send_label_data}{data}
-Set \var{data} to the left of the current left margin, if possible.
-The value of \var{data} is not restricted; treatment of non-string
-values is entirely application- and writer-dependent. This method
-will only be called at the beginning of a line.
-\end{methoddesc}
-
-
-\subsection{Writer Implementations \label{writer-impls}}
-
-Three implementations of the writer object interface are provided as
-examples by this module. Most applications will need to derive new
-writer classes from the \class{NullWriter} class.
-
-\begin{classdesc}{NullWriter}{}
-A writer which only provides the interface definition; no actions are
-taken on any methods. This should be the base class for all writers
-which do not need to inherit any implementation methods.
-\end{classdesc}
-
-\begin{classdesc}{AbstractWriter}{}
-A writer which can be used in debugging formatters, but not much
-else. Each method simply announces itself by printing its name and
-arguments on standard output.
-\end{classdesc}
-
-\begin{classdesc}{DumbWriter}{\optional{file\optional{, maxcol\code{ = 72}}}}
-Simple writer class which writes output on the file object passed in
-as \var{file} or, if \var{file} is omitted, on standard output. The
-output is simply word-wrapped to the number of columns specified by
-\var{maxcol}. This class is suitable for reflowing a sequence of
-paragraphs.
-\end{classdesc}
diff --git a/Doc/lib/libfpectl.tex b/Doc/lib/libfpectl.tex
deleted file mode 100644
index cca2314..0000000
--- a/Doc/lib/libfpectl.tex
+++ /dev/null
@@ -1,127 +0,0 @@
-\section{\module{fpectl} ---
- Floating point exception control}
-
-\declaremodule{extension}{fpectl}
- \platform{Unix}
-\moduleauthor{Lee Busby}{busby1@llnl.gov}
-\sectionauthor{Lee Busby}{busby1@llnl.gov}
-\modulesynopsis{Provide control for floating point exception handling.}
-
-\note{The \module{fpectl} module is not built by default, and its usage
- is discouraged and may be dangerous except in the hands of
- experts. See also the section \ref{fpectl-limitations} on
- limitations for more details.}
-
-Most computers carry out floating point operations\index{IEEE-754}
-in conformance with the so-called IEEE-754 standard.
-On any real computer,
-some floating point operations produce results that cannot
-be expressed as a normal floating point value.
-For example, try
-
-\begin{verbatim}
->>> import math
->>> math.exp(1000)
-inf
->>> math.exp(1000) / math.exp(1000)
-nan
-\end{verbatim}
-
-(The example above will work on many platforms.
-DEC Alpha may be one exception.)
-"Inf" is a special, non-numeric value in IEEE-754 that
-stands for "infinity", and "nan" means "not a number."
-Note that,
-other than the non-numeric results,
-nothing special happened when you asked Python
-to carry out those calculations.
-That is in fact the default behaviour prescribed in the IEEE-754 standard,
-and if it works for you,
-stop reading now.
-
-In some circumstances,
-it would be better to raise an exception and stop processing
-at the point where the faulty operation was attempted.
-The \module{fpectl} module
-is for use in that situation.
-It provides control over floating point
-units from several hardware manufacturers,
-allowing the user to turn on the generation
-of \constant{SIGFPE} whenever any of the
-IEEE-754 exceptions Division by Zero, Overflow, or
-Invalid Operation occurs.
-In tandem with a pair of wrapper macros that are inserted
-into the C code comprising your python system,
-\constant{SIGFPE} is trapped and converted into the Python
-\exception{FloatingPointError} exception.
-
-The \module{fpectl} module defines the following functions and
-may raise the given exception:
-
-\begin{funcdesc}{turnon_sigfpe}{}
-Turn on the generation of \constant{SIGFPE},
-and set up an appropriate signal handler.
-\end{funcdesc}
-
-\begin{funcdesc}{turnoff_sigfpe}{}
-Reset default handling of floating point exceptions.
-\end{funcdesc}
-
-\begin{excdesc}{FloatingPointError}
-After \function{turnon_sigfpe()} has been executed,
-a floating point operation that raises one of the
-IEEE-754 exceptions
-Division by Zero, Overflow, or Invalid operation
-will in turn raise this standard Python exception.
-\end{excdesc}
-
-
-\subsection{Example \label{fpectl-example}}
-
-The following example demonstrates how to start up and test operation of
-the \module{fpectl} module.
-
-\begin{verbatim}
->>> import fpectl
->>> import fpetest
->>> fpectl.turnon_sigfpe()
->>> fpetest.test()
-overflow PASS
-FloatingPointError: Overflow
-
-div by 0 PASS
-FloatingPointError: Division by zero
- [ more output from test elided ]
->>> import math
->>> math.exp(1000)
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-FloatingPointError: in math_1
-\end{verbatim}
-
-
-\subsection{Limitations and other considerations \label{fpectl-limitations}}
-
-Setting up a given processor to trap IEEE-754 floating point
-errors currently requires custom code on a per-architecture basis.
-You may have to modify \module{fpectl} to control your particular hardware.
-
-Conversion of an IEEE-754 exception to a Python exception requires
-that the wrapper macros \code{PyFPE_START_PROTECT} and
-\code{PyFPE_END_PROTECT} be inserted into your code in an appropriate
-fashion. Python itself has been modified to support the
-\module{fpectl} module, but many other codes of interest to numerical
-analysts have not.
-
-The \module{fpectl} module is not thread-safe.
-
-\begin{seealso}
- \seetext{Some files in the source distribution may be interesting in
- learning more about how this module operates.
- The include file \file{Include/pyfpe.h} discusses the
- implementation of this module at some length.
- \file{Modules/fpetestmodule.c} gives several examples of
- use.
- Many additional examples can be found in
- \file{Objects/floatobject.c}.}
-\end{seealso}
diff --git a/Doc/lib/libfpformat.tex b/Doc/lib/libfpformat.tex
deleted file mode 100644
index a3a6282..0000000
--- a/Doc/lib/libfpformat.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{fpformat} ---
- Floating point conversions}
-
-\declaremodule{standard}{fpformat}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{General floating point formatting functions.}
-
-
-The \module{fpformat} module defines functions for dealing with
-floating point numbers representations in 100\% pure
-Python. \note{This module is unneeded: everything here could
-be done via the \code{\%} string interpolation operator.}
-
-The \module{fpformat} module defines the following functions and an
-exception:
-
-
-\begin{funcdesc}{fix}{x, digs}
-Format \var{x} as \code{[-]ddd.ddd} with \var{digs} digits after the
-point and at least one digit before.
-If \code{\var{digs} <= 0}, the decimal point is suppressed.
-
-\var{x} can be either a number or a string that looks like
-one. \var{digs} is an integer.
-
-Return value is a string.
-\end{funcdesc}
-
-\begin{funcdesc}{sci}{x, digs}
-Format \var{x} as \code{[-]d.dddE[+-]ddd} with \var{digs} digits after the
-point and exactly one digit before.
-If \code{\var{digs} <= 0}, one digit is kept and the point is suppressed.
-
-\var{x} can be either a real number, or a string that looks like
-one. \var{digs} is an integer.
-
-Return value is a string.
-\end{funcdesc}
-
-\begin{excdesc}{NotANumber}
-Exception raised when a string passed to \function{fix()} or
-\function{sci()} as the \var{x} parameter does not look like a number.
-This is a subclass of \exception{ValueError} when the standard
-exceptions are strings. The exception value is the improperly
-formatted string that caused the exception to be raised.
-\end{excdesc}
-
-Example:
-
-\begin{verbatim}
->>> import fpformat
->>> fpformat.fix(1.23, 1)
-'1.2'
-\end{verbatim}
diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex
deleted file mode 100644
index 1ce5f9b..0000000
--- a/Doc/lib/libftplib.tex
+++ /dev/null
@@ -1,300 +0,0 @@
-\section{\module{ftplib} ---
- FTP protocol client}
-
-\declaremodule{standard}{ftplib}
-\modulesynopsis{FTP protocol client (requires sockets).}
-
-\indexii{FTP}{protocol}
-\index{FTP!\module{ftplib} (standard module)}
-
-This module defines the class \class{FTP} and a few related items.
-The \class{FTP} class implements the client side of the FTP
-protocol. You can use this to write Python
-programs that perform a variety of automated FTP jobs, such as
-mirroring other ftp servers. It is also used by the module
-\refmodule{urllib} to handle URLs that use FTP. For more information
-on FTP (File Transfer Protocol), see Internet \rfc{959}.
-
-Here's a sample session using the \module{ftplib} module:
-
-\begin{verbatim}
->>> from ftplib import FTP
->>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
->>> ftp.login() # user anonymous, passwd anonymous@
->>> ftp.retrlines('LIST') # list directory contents
-total 24418
-drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
-dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
--rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
- .
- .
- .
->>> ftp.retrbinary('RETR README', open('README', 'wb').write)
-'226 Transfer complete.'
->>> ftp.quit()
-\end{verbatim}
-
-The module defines the following items:
-
-\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{,
- passwd\optional{, acct\optional{, timeout}}}}}}
-Return a new instance of the \class{FTP} class. When
-\var{host} is given, the method call \code{connect(\var{host})} is
-made. When \var{user} is given, additionally the method call
-\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
-\var{passwd} and \var{acct} default to the empty string when not given).
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if is not specified, or passed as None, the global
-default timeout setting will be used).
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{datadesc}{all_errors}
-The set of all exceptions (as a tuple) that methods of \class{FTP}
-instances may raise as a result of problems with the FTP connection
-(as opposed to programming errors made by the caller). This set
-includes the four exceptions listed below as well as
-\exception{socket.error} and \exception{IOError}.
-\end{datadesc}
-
-\begin{excdesc}{error_reply}
-Exception raised when an unexpected reply is received from the server.
-\end{excdesc}
-
-\begin{excdesc}{error_temp}
-Exception raised when an error code in the range 400--499 is received.
-\end{excdesc}
-
-\begin{excdesc}{error_perm}
-Exception raised when an error code in the range 500--599 is received.
-\end{excdesc}
-
-\begin{excdesc}{error_proto}
-Exception raised when a reply is received from the server that does
-not begin with a digit in the range 1--5.
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{netrc}{Parser for the \file{.netrc} file format. The file
- \file{.netrc} is typically used by FTP clients to
- load user authentication information before prompting
- the user.}
- \seetext{The file \file{Tools/scripts/ftpmirror.py}\index{ftpmirror.py}
- in the Python source distribution is a script that can mirror
- FTP sites, or portions thereof, using the \module{ftplib} module.
- It can be used as an extended example that applies this module.}
-\end{seealso}
-
-
-\subsection{FTP Objects \label{ftp-objects}}
-
-Several methods are available in two flavors: one for handling text
-files and another for binary files. These are named for the command
-which is used followed by \samp{lines} for the text version or
-\samp{binary} for the binary version.
-
-\class{FTP} instances have the following methods:
-
-\begin{methoddesc}[FTP]{set_debuglevel}{level}
-Set the instance's debugging level. This controls the amount of
-debugging output printed. The default, \code{0}, produces no
-debugging output. A value of \code{1} produces a moderate amount of
-debugging output, generally a single line per request. A value of
-\code{2} or higher produces the maximum amount of debugging output,
-logging each line sent and received on the control connection.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{connect}{host\optional{, port\optional{, timeout}}}
-Connect to the given host and port. The default port number is \code{21}, as
-specified by the FTP protocol specification. It is rarely needed to
-specify a different port number. This function should be called only
-once for each instance; it should not be called at all if a host was
-given when the instance was created. All other methods can only be
-used after a connection has been made.
-
-The optional \var{timeout} parameter specifies a timeout in seconds for
-the connection attempt. If is not specified, or passed as None, the
-object timeout is used (the timeout that you passed when instantiating the
-class); if the object timeout is also None, the global default timeout
-setting will be used.
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{getwelcome}{}
-Return the welcome message sent by the server in reply to the initial
-connection. (This message sometimes contains disclaimers or help
-information that may be relevant to the user.)
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{login}{\optional{user\optional{, passwd\optional{, acct}}}}
-Log in as the given \var{user}. The \var{passwd} and \var{acct}
-parameters are optional and default to the empty string. If no
-\var{user} is specified, it defaults to \code{'anonymous'}. If
-\var{user} is \code{'anonymous'}, the default \var{passwd} is
-\code{'anonymous@'}. This function should be called only
-once for each instance, after a connection has been established; it
-should not be called at all if a host and user were given when the
-instance was created. Most FTP commands are only allowed after the
-client has logged in.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{abort}{}
-Abort a file transfer that is in progress. Using this does not always
-work, but it's worth a try.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{sendcmd}{command}
-Send a simple command string to the server and return the response
-string.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{voidcmd}{command}
-Send a simple command string to the server and handle the response.
-Return nothing if a response code in the range 200--299 is received.
-Raise an exception otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{retrbinary}{command,
- callback\optional{, maxblocksize\optional{, rest}}}
-Retrieve a file in binary transfer mode. \var{command} should be an
-appropriate \samp{RETR} command: \code{'RETR \var{filename}'}.
-The \var{callback} function is called for each block of data received,
-with a single string argument giving the data block.
-The optional \var{maxblocksize} argument specifies the maximum chunk size to
-read on the low-level socket object created to do the actual transfer
-(which will also be the largest size of the data blocks passed to
-\var{callback}). A reasonable default is chosen. \var{rest} means the
-same thing as in the \method{transfercmd()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{retrlines}{command\optional{, callback}}
-Retrieve a file or directory listing in \ASCII{} transfer mode.
-\var{command} should be an appropriate \samp{RETR} command (see
-\method{retrbinary()}) or a \samp{LIST} command (usually just the string
-\code{'LIST'}). The \var{callback} function is called for each line,
-with the trailing CRLF stripped. The default \var{callback} prints
-the line to \code{sys.stdout}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{set_pasv}{boolean}
-Enable ``passive'' mode if \var{boolean} is true, other disable
-passive mode. (In Python 2.0 and before, passive mode was off by
-default; in Python 2.1 and later, it is on by default.)
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{storbinary}{command, file\optional{, blocksize}}
-Store a file in binary transfer mode. \var{command} should be an
-appropriate \samp{STOR} command: \code{"STOR \var{filename}"}.
-\var{file} is an open file object which is read until \EOF{} using its
-\method{read()} method in blocks of size \var{blocksize} to provide the
-data to be stored. The \var{blocksize} argument defaults to 8192.
-\versionchanged[default for \var{blocksize} added]{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{storlines}{command, file}
-Store a file in \ASCII{} transfer mode. \var{command} should be an
-appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
-read until \EOF{} from the open file object \var{file} using its
-\method{readline()} method to provide the data to be stored.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{transfercmd}{cmd\optional{, rest}}
-Initiate a transfer over the data connection. If the transfer is
-active, send a \samp{EPRT} or \samp{PORT} command and the transfer command specified
-by \var{cmd}, and accept the connection. If the server is passive,
-send a \samp{EPSV} or \samp{PASV} command, connect to it, and start the transfer
-command. Either way, return the socket for the connection.
-
-If optional \var{rest} is given, a \samp{REST} command is
-sent to the server, passing \var{rest} as an argument. \var{rest} is
-usually a byte offset into the requested file, telling the server to
-restart sending the file's bytes at the requested offset, skipping
-over the initial bytes. Note however that RFC
-959 requires only that \var{rest} be a string containing characters
-in the printable range from ASCII code 33 to ASCII code 126. The
-\method{transfercmd()} method, therefore, converts
-\var{rest} to a string, but no check is
-performed on the string's contents. If the server does
-not recognize the \samp{REST} command, an
-\exception{error_reply} exception will be raised. If this happens,
-simply call \method{transfercmd()} without a \var{rest} argument.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{ntransfercmd}{cmd\optional{, rest}}
-Like \method{transfercmd()}, but returns a tuple of the data
-connection and the expected size of the data. If the expected size
-could not be computed, \code{None} will be returned as the expected
-size. \var{cmd} and \var{rest} means the same thing as in
-\method{transfercmd()}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{nlst}{argument\optional{, \ldots}}
-Return a list of files as returned by the \samp{NLST} command. The
-optional \var{argument} is a directory to list (default is the current
-server directory). Multiple arguments can be used to pass
-non-standard options to the \samp{NLST} command.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{dir}{argument\optional{, \ldots}}
-Produce a directory listing as returned by the \samp{LIST} command,
-printing it to standard output. The optional \var{argument} is a
-directory to list (default is the current server directory). Multiple
-arguments can be used to pass non-standard options to the \samp{LIST}
-command. If the last argument is a function, it is used as a
-\var{callback} function as for \method{retrlines()}; the default
-prints to \code{sys.stdout}. This method returns \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{rename}{fromname, toname}
-Rename file \var{fromname} on the server to \var{toname}.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{delete}{filename}
-Remove the file named \var{filename} from the server. If successful,
-returns the text of the response, otherwise raises
-\exception{error_perm} on permission errors or
-\exception{error_reply} on other errors.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{cwd}{pathname}
-Set the current directory on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{mkd}{pathname}
-Create a new directory on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{pwd}{}
-Return the pathname of the current directory on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{rmd}{dirname}
-Remove the directory named \var{dirname} on the server.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{size}{filename}
-Request the size of the file named \var{filename} on the server. On
-success, the size of the file is returned as an integer, otherwise
-\code{None} is returned. Note that the \samp{SIZE} command is not
-standardized, but is supported by many common server implementations.
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{quit}{}
-Send a \samp{QUIT} command to the server and close the connection.
-This is the ``polite'' way to close a connection, but it may raise an
-exception of the server reponds with an error to the
-\samp{QUIT} command. This implies a call to the \method{close()}
-method which renders the \class{FTP} instance useless for subsequent
-calls (see below).
-\end{methoddesc}
-
-\begin{methoddesc}[FTP]{close}{}
-Close the connection unilaterally. This should not be applied to an
-already closed connection such as after a successful call to
-\method{quit()}. After this call the \class{FTP} instance should not
-be used any more (after a call to \method{close()} or
-\method{quit()} you cannot reopen the connection by issuing another
-\method{login()} method).
-\end{methoddesc}
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
deleted file mode 100644
index 0fcc4f4..0000000
--- a/Doc/lib/libfuncs.tex
+++ /dev/null
@@ -1,1125 +0,0 @@
-\section{Built-in Functions \label{built-in-funcs}}
-
-The Python interpreter has a number of functions built into it that
-are always available. They are listed here in alphabetical order.
-
-
-\setindexsubitem{(built-in function)}
-
-\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist\optional{, level}}}}}
- This function is invoked by the \keyword{import}\stindex{import}
- statement. It mainly exists so that you can replace it with another
- function that has a compatible interface, in order to change the
- semantics of the \keyword{import} statement. For examples of why
- and how you would do this, see the standard library modules
- \module{ihooks}\refstmodindex{ihooks} and
- \refmodule{rexec}\refstmodindex{rexec}. See also the built-in
- module \refmodule{imp}\refbimodindex{imp}, which defines some useful
- operations out of which you can build your own
- \function{__import__()} function.
-
- For example, the statement \samp{import spam} results in the
- following call: \code{__import__('spam',} \code{globals(),}
- \code{locals(), [], -1)}; the statement \samp{from spam.ham import eggs}
- results in \samp{__import__('spam.ham', globals(), locals(),
- ['eggs'], -1)}. Note that even though \code{locals()} and
- \code{['eggs']} are passed in as arguments, the
- \function{__import__()} function does not set the local variable
- named \code{eggs}; this is done by subsequent code that is generated
- for the import statement. (In fact, the standard implementation
- does not use its \var{locals} argument at all, and uses its
- \var{globals} only to determine the package context of the
- \keyword{import} statement.)
-
- When the \var{name} variable is of the form \code{package.module},
- normally, the top-level package (the name up till the first dot) is
- returned, \emph{not} the module named by \var{name}. However, when
- a non-empty \var{fromlist} argument is given, the module named by
- \var{name} is returned. This is done for compatibility with the
- bytecode generated for the different kinds of import statement; when
- using \samp{import spam.ham.eggs}, the top-level package \module{spam}
- must be placed in the importing namespace, but when using \samp{from
- spam.ham import eggs}, the \code{spam.ham} subpackage must be used
- to find the \code{eggs} variable. As a workaround for this
- behavior, use \function{getattr()} to extract the desired
- components. For example, you could define the following helper:
-
-\begin{verbatim}
-def my_import(name):
- mod = __import__(name)
- components = name.split('.')
- for comp in components[1:]:
- mod = getattr(mod, comp)
- return mod
-\end{verbatim}
-
- \var{level} specifies whether to use absolute or relative imports.
- The default is \code{-1} which indicates both absolute and relative
- imports will be attempted. \code{0} means only perform absolute imports.
- Positive values for \var{level} indicate the number of parent directories
- to search relative to the directory of the module calling
- \function{__import__}.
-\versionchanged[The level parameter was added]{2.5}
-\versionchanged[Keyword support for parameters was added]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{abs}{x}
- Return the absolute value of a number. The argument may be a plain
- or long integer or a floating point number. If the argument is a
- complex number, its magnitude is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{all}{iterable}
- Return True if all elements of the \var{iterable} are true.
- Equivalent to:
- \begin{verbatim}
- def all(iterable):
- for element in iterable:
- if not element:
- return False
- return True
- \end{verbatim}
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{any}{iterable}
- Return True if any element of the \var{iterable} is true.
- Equivalent to:
- \begin{verbatim}
- def any(iterable):
- for element in iterable:
- if element:
- return True
- return False
- \end{verbatim}
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{basestring}{}
- This abstract type is the superclass for \class{str}.
- It cannot be called or instantiated, but it can be used to test whether
- an object is an instance of \class{str}.
- \code{isinstance(obj, basestring)} is equivalent to
- \code{isinstance(obj, str)}.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{bin}{x}
- Convert an integer number to a binary string.
- The result is a valid Python expression. If \var{x} is not a Python
- \class{int} object, it has to define an \method{__index__} method
- that returns an integer.
- \versionadded{3.0}
-\end{funcdesc}
-
-\begin{funcdesc}{bool}{\optional{x}}
- Convert a value to a Boolean, using the standard truth testing
- procedure. If \var{x} is false or omitted, this returns
- \constant{False}; otherwise it returns \constant{True}.
- \class{bool} is also a class, which is a subclass of \class{int}.
- Class \class{bool} cannot be subclassed further. Its only instances
- are \constant{False} and \constant{True}.
-
- \indexii{Boolean}{type}
- \versionadded{2.2.1}
- \versionchanged[If no argument is given, this function returns
- \constant{False}]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{chr}{i}
- Return the Unicode string of one character whose Unicode code is the
- integer \var{i}. For example, \code{unichr(97)} returns the string
- \code{u'a'}. This is the inverse of \function{ord()} for Unicode
- strings. The valid range for the argument depends how Python was
- configured -- it may be either UCS2 [0..0xFFFF] or UCS4 [0..0x10FFFF].
- \exception{ValueError} is raised otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{classmethod}{function}
- Return a class method for \var{function}.
-
- A class method receives the class as implicit first argument,
- just like an instance method receives the instance.
- To declare a class method, use this idiom:
-
-\begin{verbatim}
-class C:
- @classmethod
- def f(cls, arg1, arg2, ...): ...
-\end{verbatim}
-
- The \code{@classmethod} form is a function decorator -- see the description
- of function definitions in chapter 7 of the
- \citetitle[../ref/ref.html]{Python Reference Manual} for details.
-
- It can be called either on the class (such as \code{C.f()}) or on an
- instance (such as \code{C().f()}). The instance is ignored except for
- its class.
- If a class method is called for a derived class, the derived class
- object is passed as the implied first argument.
-
- Class methods are different than \Cpp{} or Java static methods.
- If you want those, see \function{staticmethod()} in this section.
-
- For more information on class methods, consult the documentation on the
- standard type hierarchy in chapter 3 of the
- \citetitle[../ref/types.html]{Python Reference Manual} (at the bottom).
- \versionadded{2.2}
- \versionchanged[Function decorator syntax added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{cmp}{x, y}
- Compare the two objects \var{x} and \var{y} and return an integer
- according to the outcome. The return value is negative if \code{\var{x}
- < \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
- \code{\var{x} > \var{y}}.
-\end{funcdesc}
-
-\begin{funcdesc}{compile}{source, filename, mode\optional{,
- flags\optional{, dont_inherit}}}
- Compile the \var{source} into a code object. Code objects can be
- executed by a call to \function{exec()} or evaluated by a call to
- \function{eval()}. The \var{filename} argument should
- give the file from which the code was read; pass some recognizable value
- if it wasn't read from a file (\code{'<string>'} is commonly used).
- The \var{mode} argument specifies what kind of code must be
- compiled; it can be \code{'exec'} if \var{source} consists of a
- sequence of statements, \code{'eval'} if it consists of a single
- expression, or \code{'single'} if it consists of a single
- interactive statement (in the latter case, expression statements
- that evaluate to something else than \code{None} will be printed).
-
- When compiling multi-line statements, two caveats apply: line
- endings must be represented by a single newline character
- (\code{'\e n'}), and the input must be terminated by at least one
- newline character. If line endings are represented by
- \code{'\e r\e n'}, use the string \method{replace()} method to
- change them into \code{'\e n'}.
-
- The optional arguments \var{flags} and \var{dont_inherit}
- (which are new in Python 2.2) control which future statements (see
- \pep{236}) affect the compilation of \var{source}. If neither is
- present (or both are zero) the code is compiled with those future
- statements that are in effect in the code that is calling compile.
- If the \var{flags} argument is given and \var{dont_inherit} is not
- (or is zero) then the future statements specified by the \var{flags}
- argument are used in addition to those that would be used anyway.
- If \var{dont_inherit} is a non-zero integer then the \var{flags}
- argument is it -- the future statements in effect around the call to
- compile are ignored.
-
- Future statements are specified by bits which can be bitwise or-ed
- together to specify multiple statements. The bitfield required to
- specify a given feature can be found as the \member{compiler_flag}
- attribute on the \class{_Feature} instance in the
- \module{__future__} module.
-\end{funcdesc}
-
-\begin{funcdesc}{complex}{\optional{real\optional{, imag}}}
- Create a complex number with the value \var{real} + \var{imag}*j or
- convert a string or number to a complex number. If the first
- parameter is a string, it will be interpreted as a complex number
- and the function must be called without a second parameter. The
- second parameter can never be a string.
- Each argument may be any numeric type (including complex).
- If \var{imag} is omitted, it defaults to zero and the function
- serves as a numeric conversion function like \function{int()},
- \function{long()} and \function{float()}. If both arguments
- are omitted, returns \code{0j}.
-\end{funcdesc}
-
-\begin{funcdesc}{delattr}{object, name}
- This is a relative of \function{setattr()}. The arguments are an
- object and a string. The string must be the name
- of one of the object's attributes. The function deletes
- the named attribute, provided the object allows it. For example,
- \code{delattr(\var{x}, '\var{foobar}')} is equivalent to
- \code{del \var{x}.\var{foobar}}.
-\end{funcdesc}
-
-\begin{funcdesc}{dict}{\optional{arg}}
- Return a new dictionary initialized from an optional positional
- argument or from a set of keyword arguments.
- If no arguments are given, return a new empty dictionary.
- If the positional argument \var{arg} is a mapping object, return a dictionary
- mapping the same keys to the same values as does the mapping object.
- Otherwise the positional argument must be a sequence, a container that
- supports iteration, or an iterator object. The elements of the argument
- must each also be of one of those kinds, and each must in turn contain
- exactly two objects. The first is used as a key in the new dictionary,
- and the second as the key's value. If a given key is seen more than
- once, the last value associated with it is retained in the new
- dictionary.
-
- If keyword arguments are given, the keywords themselves with their
- associated values are added as items to the dictionary. If a key
- is specified both in the positional argument and as a keyword argument,
- the value associated with the keyword is retained in the dictionary.
- For example, these all return a dictionary equal to
- \code{\{"one": 2, "two": 3\}}:
-
- \begin{itemize}
- \item \code{dict(\{'one': 2, 'two': 3\})}
- \item \code{dict(\{'one': 2, 'two': 3\}.items())}
- \item \code{dict(\{'one': 2, 'two': 3\}.iteritems())}
- \item \code{dict(zip(('one', 'two'), (2, 3)))}
- \item \code{dict([['two', 3], ['one', 2]])}
- \item \code{dict(one=2, two=3)}
- \item \code{dict([(['one', 'two'][i-2], i) for i in (2, 3)])}
- \end{itemize}
-
- \versionadded{2.2}
- \versionchanged[Support for building a dictionary from keyword
- arguments added]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{dir}{\optional{object}}
- Without arguments, return the list of names in the current local scope. With
- an argument, attempt to return a list of valid attributes for that object.
-
- If the object has a method named \method{__dir__()}, this method will be
- called and must return the list of attributes. This allows objects that
- implement a custom \function{__getattr__()} or \function{__getattribute__()}
- function to customize the way \function{dir()} reports their attributes.
-
- If the object does not provide \method{__dir__()}, the function tries its best
- to gather information from the object's \member{__dict__} attribute, if
- defined, and from its type object. The resulting list is not necessarily
- complete, and may be inaccurate when the object has a custom
- \function{__getattr__()}.
-
- The default \function{dir()} mechanism behaves differently with different
- types of objects, as it attempts to produce the most relevant, rather than
- complete, information:
- \begin{itemize}
- \item If the object is a module object, the list contains the names of the
- module's attributes.
- \item If the object is a type or class object, the list contains the names of
- its attributes, and recursively of the attributes of its bases.
- \item Otherwise, the list contains the object's attributes' names, the names
- of its class's attributes, and recursively of the attributes of its class's
- base classes.
- \end{itemize}
-
- The resulting list is sorted alphabetically. For example:
-
-\begin{verbatim}
->>> import struct
->>> dir()
-['__builtins__', '__doc__', '__name__', 'struct']
->>> dir(struct)
-['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']
->>> class Foo(object):
-... def __dir__(self):
-... return ["kan", "ga", "roo"]
-...
->>> f = Foo()
->>> dir(f)
-['ga', 'kan', 'roo']
-\end{verbatim}
-
- \note{Because \function{dir()} is supplied primarily as a convenience for use
- at an interactive prompt, it tries to supply an interesting set of names
- more than it tries to supply a rigorously or consistently defined set of
- names, and its detailed behavior may change across releases.}
-\end{funcdesc}
-
-\begin{funcdesc}{divmod}{a, b}
- Take two (non complex) numbers as arguments and return a pair of numbers
- consisting of their quotient and remainder when using long division. With
- mixed operand types, the rules for binary arithmetic operators apply. For
- plain and long integers, the result is the same as
- \code{(\var{a} // \var{b}, \var{a} \%{} \var{b})}.
- For floating point numbers the result is \code{(\var{q}, \var{a} \%{}
- \var{b})}, where \var{q} is usually \code{math.floor(\var{a} /
- \var{b})} but may be 1 less than that. In any case \code{\var{q} *
- \var{b} + \var{a} \%{} \var{b}} is very close to \var{a}, if
- \code{\var{a} \%{} \var{b}} is non-zero it has the same sign as
- \var{b}, and \code{0 <= abs(\var{a} \%{} \var{b}) < abs(\var{b})}.
-
- \versionchanged[Using \function{divmod()} with complex numbers is
- deprecated]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{enumerate}{iterable}
- Return an enumerate object. \var{iterable} must be a sequence, an iterator, or
- some other object which supports iteration. The \method{__next__()} method of
- the iterator returned by \function{enumerate()} returns a tuple containing a
- count (from zero) and the corresponding value obtained from iterating over
- \var{iterable}. \function{enumerate()} is useful for obtaining an indexed
- series: \code{(0, seq[0])}, \code{(1, seq[1])}, \code{(2, seq[2])}, \ldots.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{eval}{expression\optional{, globals\optional{, locals}}}
- The arguments are a string and optional globals and locals. If provided,
- \var{globals} must be a dictionary. If provided, \var{locals} can be
- any mapping object. \versionchanged[formerly \var{locals} was required
- to be a dictionary]{2.4}
-
- The \var{expression} argument is parsed and evaluated as a Python
- expression (technically speaking, a condition list) using the
- \var{globals} and \var{locals} dictionaries as global and local name
- space. If the \var{globals} dictionary is present and lacks
- '__builtins__', the current globals are copied into \var{globals} before
- \var{expression} is parsed. This means that \var{expression}
- normally has full access to the standard
- \refmodule[builtin]{__builtin__} module and restricted environments
- are propagated. If the \var{locals} dictionary is omitted it defaults to
- the \var{globals} dictionary. If both dictionaries are omitted, the
- expression is executed in the environment where \keyword{eval} is
- called. The return value is the result of the evaluated expression.
- Syntax errors are reported as exceptions. Example:
-
-\begin{verbatim}
->>> x = 1
->>> print eval('x+1')
-2
-\end{verbatim}
-
- This function can also be used to execute arbitrary code objects
- (such as those created by \function{compile()}). In this case pass
- a code object instead of a string. The code object must have been
- compiled passing \code{'eval'} as the \var{kind} argument.
-
- Hints: dynamic execution of statements is supported by the
- \function{exec()} function. The
- \function{globals()} and \function{locals()} functions returns the
- current global and local dictionary, respectively, which may be
- useful to pass around for use by \function{eval()} or
- \function{exec()}.
-\end{funcdesc}
-
-\begin{funcdesc}{exec}{object\optional{, globals\optional{, locals}}}
- This function supports dynamic execution of Python code.
- \var{object} must be either a string, an open file object, or
- a code object. If it is a string, the string is parsed as a suite of
- Python statements which is then executed (unless a syntax error
- occurs). If it is an open file, the file is parsed until \EOF{} and
- executed. If it is a code object, it is simply executed. In all
- cases, the code that's executed is expected to be valid as file
- input (see the section ``File input'' in the Reference Manual).
- Be aware that the \keyword{return} and \keyword{yield} statements may
- not be used outside of function definitions even within the context of
- code passed to the \function{exec()} function.
- The return value is \code{None}.
-
- In all cases, if the optional parts are omitted, the code is executed
- in the current scope. If only \var{globals} is provided, it must be
- a dictionary, which will be used for both the global and the local
- variables. If \var{globals} and \var{locals} are given, they are used
- for the global and local variables, respectively. If provided,
- \var{locals} can be any mapping object.
-
- If the \var{globals} dictionary does not contain a value for the
- key \code{__builtins__}, a reference to the dictionary of the built-in
- module \module{__builtin__} is inserted under that key. That way you
- can control what builtins are available to the executed code by
- inserting your own \code{__builtins__} dictionary into \var{globals}
- before passing it to \function{exec()}.
-
- \note{The built-in functions \function{globals()} and \function{locals()}
- return the current global and local dictionary, respectively, which
- may be useful to pass around for use as the second and third
- argument to \function{exec()}.}
-\end{funcdesc}
-
-\begin{funcdesc}{filter}{function, iterable}
- Construct a list from those elements of \var{iterable} for which
- \var{function} returns true. \var{iterable} may be either a sequence, a
- container which supports iteration, or an iterator, If \var{iterable}
- is a string or a tuple, the result
- also has that type; otherwise it is always a list. If \var{function} is
- \code{None}, the identity function is assumed, that is, all elements of
- \var{iterable} that are false are removed.
-
- Note that \code{filter(function, \var{iterable})} is equivalent to
- \code{[item for item in \var{iterable} if function(item)]} if function is
- not \code{None} and \code{[item for item in \var{iterable} if item]} if
- function is \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{float}{\optional{x}}
- Convert a string or a number to floating point. If the argument is a
- string, it must contain a possibly signed decimal or floating point
- number, possibly embedded in whitespace. Otherwise, the argument may be a plain
- or long integer or a floating point number, and a floating point
- number with the same value (within Python's floating point
- precision) is returned. If no argument is given, returns \code{0.0}.
-
- \note{When passing in a string, values for NaN\index{NaN}
- and Infinity\index{Infinity} may be returned, depending on the
- underlying C library. The specific set of strings accepted which
- cause these values to be returned depends entirely on the C library
- and is known to vary.}
-\end{funcdesc}
-
-\begin{funcdesc}{frozenset}{\optional{iterable}}
- Return a frozenset object whose elements are taken from \var{iterable}.
- Frozensets are sets that have no update methods but can be hashed and
- used as members of other sets or as dictionary keys. The elements of
- a frozenset must be immutable themselves. To represent sets of sets,
- the inner sets should also be \class{frozenset} objects. If
- \var{iterable} is not specified, returns a new empty set,
- \code{frozenset([])}.
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{getattr}{object, name\optional{, default}}
- Return the value of the named attributed of \var{object}. \var{name}
- must be a string. If the string is the name of one of the object's
- attributes, the result is the value of that attribute. For example,
- \code{getattr(x, 'foobar')} is equivalent to \code{x.foobar}. If the
- named attribute does not exist, \var{default} is returned if provided,
- otherwise \exception{AttributeError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{globals}{}
- Return a dictionary representing the current global symbol table.
- This is always the dictionary of the current module (inside a
- function or method, this is the module where it is defined, not the
- module from which it is called).
-\end{funcdesc}
-
-\begin{funcdesc}{hasattr}{object, name}
- The arguments are an object and a string. The result is \code{True} if the
- string is the name of one of the object's attributes, \code{False} if not.
- (This is implemented by calling \code{getattr(\var{object},
- \var{name})} and seeing whether it raises an exception or not.)
-\end{funcdesc}
-
-\begin{funcdesc}{hash}{object}
- Return the hash value of the object (if it has one). Hash values
- are integers. They are used to quickly compare dictionary
- keys during a dictionary lookup. Numeric values that compare equal
- have the same hash value (even if they are of different types, as is
- the case for 1 and 1.0).
-\end{funcdesc}
-
-\begin{funcdesc}{help}{\optional{object}}
- Invoke the built-in help system. (This function is intended for
- interactive use.) If no argument is given, the interactive help
- system starts on the interpreter console. If the argument is a
- string, then the string is looked up as the name of a module,
- function, class, method, keyword, or documentation topic, and a
- help page is printed on the console. If the argument is any other
- kind of object, a help page on the object is generated.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{hex}{x}
- Convert an integer number to a hexadecimal string.
- The result is a valid Python expression. If \var{x} is not a Python
- \class{int} object, it has to define an \method{__index__} method
- that returns an integer.
- \versionchanged[Formerly only returned an unsigned literal]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{id}{object}
- Return the ``identity'' of an object. This is an integer (or long
- integer) which is guaranteed to be unique and constant for this
- object during its lifetime. Two objects with non-overlapping lifetimes
- may have the same \function{id()} value. (Implementation
- note: this is the address of the object.)
-\end{funcdesc}
-
-\begin{funcdesc}{int}{\optional{x\optional{, radix}}}
- Convert a string or number to a long integer. If the argument is a
- string, it must contain a possibly signed number of
- arbitrary size, possibly embedded in whitespace. The
- \var{radix} argument is interpreted in the same way as for
- \function{int()}, and may only be given when \var{x} is a string.
- Otherwise, the argument may be another
- integer or a floating point number, and an integer with
- the same value is returned. Conversion of floating
- point numbers to integers truncates (towards zero). If no arguments
- are given, returns \code{0}.
-\end{funcdesc}
-
-\begin{funcdesc}{isinstance}{object, classinfo}
- Return true if the \var{object} argument is an instance of the
- \var{classinfo} argument, or of a (direct or indirect) subclass
- thereof. Also return true if \var{classinfo} is a type object
- (new-style class) and \var{object} is an object of that type or of a
- (direct or indirect) subclass thereof. If \var{object} is not a
- class instance or an object of the given type, the function always
- returns false. If \var{classinfo} is neither a class object nor a
- type object, it may be a tuple of class or type objects, or may
- recursively contain other such tuples (other sequence types are not
- accepted). If \var{classinfo} is not a class, type, or tuple of
- classes, types, and such tuples, a \exception{TypeError} exception
- is raised.
- \versionchanged[Support for a tuple of type information was added]{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{issubclass}{class, classinfo}
- Return true if \var{class} is a subclass (direct or indirect) of
- \var{classinfo}. A class is considered a subclass of itself.
- \var{classinfo} may be a tuple of class objects, in which case every
- entry in \var{classinfo} will be checked. In any other case, a
- \exception{TypeError} exception is raised.
- \versionchanged[Support for a tuple of type information was added]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{iter}{o\optional{, sentinel}}
- Return an iterator object. The first argument is interpreted very
- differently depending on the presence of the second argument.
- Without a second argument, \var{o} must be a collection object which
- supports the iteration protocol (the \method{__iter__()} method), or
- it must support the sequence protocol (the \method{__getitem__()}
- method with integer arguments starting at \code{0}). If it does not
- support either of those protocols, \exception{TypeError} is raised.
- If the second argument, \var{sentinel}, is given, then \var{o} must
- be a callable object. The iterator created in this case will call
- \var{o} with no arguments for each call to its \method{__next__()}
- method; if the value returned is equal to \var{sentinel},
- \exception{StopIteration} will be raised, otherwise the value will
- be returned.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{len}{s}
- Return the length (the number of items) of an object. The argument
- may be a sequence (string, tuple or list) or a mapping (dictionary).
-\end{funcdesc}
-
-\begin{funcdesc}{list}{\optional{iterable}}
- Return a list whose items are the same and in the same order as
- \var{iterable}'s items. \var{iterable} may be either a sequence, a
- container that supports iteration, or an iterator object. If
- \var{iterable} is already a list, a copy is made and returned,
- similar to \code{\var{iterable}[:]}. For instance,
- \code{list('abc')} returns \code{['a', 'b', 'c']} and \code{list(
- (1, 2, 3) )} returns \code{[1, 2, 3]}. If no argument is given,
- returns a new empty list, \code{[]}.
-\end{funcdesc}
-
-\begin{funcdesc}{locals}{}
- Update and return a dictionary representing the current local symbol table.
- \warning{The contents of this dictionary should not be modified;
- changes may not affect the values of local variables used by the
- interpreter.}
-
- Free variables are returned by \var{locals} when it is called in
- a function block. Modifications of free variables may not affect
- the values used by the interpreter. Free variables are not
- returned in class blocks.
-\end{funcdesc}
-
-\begin{funcdesc}{map}{function, iterable, ...}
- Apply \var{function} to every item of \var{iterable} and return a list
- of the results. If additional \var{iterable} arguments are passed,
- \var{function} must take that many arguments and is applied to the
- items from all iterables in parallel. If one iterable is shorter than another it
- is assumed to be extended with \code{None} items. If \var{function}
- is \code{None}, the identity function is assumed; if there are
- multiple arguments, \function{map()} returns a list consisting
- of tuples containing the corresponding items from all iterables (a kind
- of transpose operation). The \var{iterable} arguments may be a sequence
- or any iterable object; the result is always a list.
-\end{funcdesc}
-
-\begin{funcdesc}{max}{iterable\optional{, args...}\optional{key}}
- With a single argument \var{iterable}, return the largest item of a
- non-empty iterable (such as a string, tuple or list). With more
- than one argument, return the largest of the arguments.
-
- The optional \var{key} argument specifies a one-argument ordering
- function like that used for \method{list.sort()}. The \var{key}
- argument, if supplied, must be in keyword form (for example,
- \samp{max(a,b,c,key=func)}).
- \versionchanged[Added support for the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{min}{iterable\optional{, args...}\optional{key}}
- With a single argument \var{iterable}, return the smallest item of a
- non-empty iterable (such as a string, tuple or list). With more
- than one argument, return the smallest of the arguments.
-
- The optional \var{key} argument specifies a one-argument ordering
- function like that used for \method{list.sort()}. The \var{key}
- argument, if supplied, must be in keyword form (for example,
- \samp{min(a,b,c,key=func)}).
- \versionchanged[Added support for the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{next}{iterator\optional{, default}}
- Retrieve the next item from the \var{iterable} by calling its
- \method{__next__()} method. If \var{default} is given, it is returned if the
- iterator is exhausted, otherwise \exception{StopIteration} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{object}{}
- Return a new featureless object. \class{object} is a base
- for all new style classes. It has the methods that are common
- to all instances of new style classes.
- \versionadded{2.2}
-
- \versionchanged[This function does not accept any arguments.
- Formerly, it accepted arguments but ignored them]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{oct}{x}
- Convert an integer number to an octal string. The
- result is a valid Python expression. If \var{x} is not a Python
- \class{int} object, it has to define an \method{__index__} method
- that returns an integer.
- \versionchanged[Formerly only returned an unsigned literal]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
- Open a file, returning an object of the \class{file} type described
- in section~\ref{bltin-file-objects}, ``\ulink{File
- Objects}{bltin-file-objects.html}''. If the file cannot be opened,
- \exception{IOError} is raised. When opening a file, it's
- preferable to use \function{open()} instead of invoking the
- \class{file} constructor directly.
-
- The first two arguments are the same as for \code{stdio}'s
- \cfunction{fopen()}: \var{filename} is the file name to be opened,
- and \var{mode} is a string indicating how the file is to be opened.
-
- The most commonly-used values of \var{mode} are \code{'r'} for
- reading, \code{'w'} for writing (truncating the file if it already
- exists), and \code{'a'} for appending (which on \emph{some} \UNIX{}
- systems means that \emph{all} writes append to the end of the file
- regardless of the current seek position). If \var{mode} is omitted,
- it defaults to \code{'r'}. When opening a binary file, you should
- append \code{'b'} to the \var{mode} value to open the file in binary
- mode, which will improve portability. (Appending \code{'b'} is
- useful even on systems that don't treat binary and text files
- differently, where it serves as documentation.) See below for more
- possible values of \var{mode}.
-
- \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O}
- \index{I/O control!buffering}
- The optional \var{bufsize} argument specifies the
- file's desired buffer size: 0 means unbuffered, 1 means line
- buffered, any other positive value means use a buffer of
- (approximately) that size. A negative \var{bufsize} means to use
- the system default, which is usually line buffered for tty
- devices and fully buffered for other files. If omitted, the system
- default is used.\footnote{
- Specifying a buffer size currently has no effect on systems that
- don't have \cfunction{setvbuf()}. The interface to specify the
- buffer size is not done using a method that calls
- \cfunction{setvbuf()}, because that may dump core when called
- after any I/O has been performed, and there's no reliable way to
- determine whether this is the case.}
-
- Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for
- updating (note that \code{'w+'} truncates the file). Append
- \code{'b'} to the mode to open the file in binary mode, on systems
- that differentiate between binary and text files; on systems
- that don't have this distinction, adding the \code{'b'} has no effect.
-
- In addition to the standard \cfunction{fopen()} values \var{mode}
- may be \code{'U'} or \code{'rU'}. Python is usually built with universal
- newline support; supplying \code{'U'} opens the file as a text file, but
- lines may be terminated by any of the following: the \UNIX{} end-of-line
- convention \code{'\e n'},
- the Macintosh convention \code{'\e r'}, or the Windows
- convention \code{'\e r\e n'}. All of these external representations are seen as
- \code{'\e n'}
- by the Python program. If Python is built without universal newline support
- a \var{mode} with \code{'U'} is the same as normal text mode. Note that
- file objects so opened also have an attribute called
- \member{newlines} which has a value of \code{None} (if no newlines
- have yet been seen), \code{'\e n'}, \code{'\e r'}, \code{'\e r\e n'},
- or a tuple containing all the newline types seen.
-
- Python enforces that the mode, after stripping \code{'U'}, begins with
- \code{'r'}, \code{'w'} or \code{'a'}.
-
- \versionchanged[Restriction on first letter of mode string
- introduced]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ord}{c}
- Given a string of length one, return an integer representing the
- Unicode code point of the character when the argument is a unicode object,
- or the value of the byte when the argument is an 8-bit string.
- For example, \code{ord('a')} returns the integer \code{97},
- \code{ord(u'\e u2020')} returns \code{8224}. This is the inverse of
- \function{chr()} for strings.
- If Python was built with
- UCS2 Unicode, then the character's code point must be in the range
- [0..65535] inclusive; otherwise the string length is two, and a
- \exception{TypeError} will be raised.
-\end{funcdesc}
-
-\begin{funcdesc}{pow}{x, y\optional{, z}}
- Return \var{x} to the power \var{y}; if \var{z} is present, return
- \var{x} to the power \var{y}, modulo \var{z} (computed more
- efficiently than \code{pow(\var{x}, \var{y}) \%\ \var{z}}).
- The two-argument form \code{pow(\var{x}, \var{y})} is equivalent to using
- the power operator: \code{\var{x}**\var{y}}.
-
- The arguments must have numeric types. With mixed operand types, the
- coercion rules for binary arithmetic operators apply. For int and
- long int operands, the result has the same type as the operands
- (after coercion) unless the second argument is negative; in that
- case, all arguments are converted to float and a float result is
- delivered. For example, \code{10**2} returns \code{100}, but
- \code{10**-2} returns \code{0.01}. (This last feature was added in
- Python 2.2. In Python 2.1 and before, if both arguments were of integer
- types and the second argument was negative, an exception was raised.)
- If the second argument is negative, the third argument must be omitted.
- If \var{z} is present, \var{x} and \var{y} must be of integer types,
- and \var{y} must be non-negative. (This restriction was added in
- Python 2.2. In Python 2.1 and before, floating 3-argument \code{pow()}
- returned platform-dependent results depending on floating-point
- rounding accidents.)
-\end{funcdesc}
-
-\begin{funcdesc}{property}{\optional{fget\optional{, fset\optional{,
- fdel\optional{, doc}}}}}
- Return a property attribute for new-style classes (classes that
- derive from \class{object}).
-
- \var{fget} is a function for getting an attribute value, likewise
- \var{fset} is a function for setting, and \var{fdel} a function
- for del'ing, an attribute. Typical use is to define a managed attribute x:
-
-\begin{verbatim}
-class C(object):
- def __init__(self): self._x = None
- def getx(self): return self._x
- def setx(self, value): self._x = value
- def delx(self): del self._x
- x = property(getx, setx, delx, "I'm the 'x' property.")
-\end{verbatim}
-
- If given, \var{doc} will be the docstring of the property attribute.
- Otherwise, the property will copy \var{fget}'s docstring (if it
- exists). This makes it possible to create read-only properties
- easily using \function{property()} as a decorator:
-
-\begin{verbatim}
-class Parrot(object):
- def __init__(self):
- self._voltage = 100000
-
- @property
- def voltage(self):
- """Get the current voltage."""
- return self._voltage
-\end{verbatim}
-
- turns the \method{voltage()} method into a ``getter'' for a read-only
- attribute with the same name.
-
- \versionadded{2.2}
- \versionchanged[Use \var{fget}'s docstring if no \var{doc} given]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
- This is a versatile function to create sequences containing arithmetic
- progressions. It is most often used in \keyword{for} loops. The
- arguments must be plain integers. If the \var{step} argument is
- omitted, it defaults to \code{1}. If the \var{start} argument is
- omitted, it defaults to \code{0}. The full form returns a list of
- plain integers \code{[\var{start}, \var{start} + \var{step},
- \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
- the last element is the largest \code{\var{start} + \var{i} *
- \var{step}} less than \var{stop}; if \var{step} is negative, the last
- element is the smallest \code{\var{start} + \var{i} * \var{step}}
- greater than \var{stop}. \var{step} must not be zero (or else
- \exception{ValueError} is raised). Example:
-
-\begin{verbatim}
->>> list(range(10))
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
->>> list(range(1, 11))
-[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
->>> list(range(0, 30, 5))
-[0, 5, 10, 15, 20, 25]
->>> list(range(0, 10, 3))
-[0, 3, 6, 9]
->>> list(range(0, -10, -1))
-[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
->>> list(range(0))
-[]
->>> list(range(1, 0))
-[]
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{repr}{object}
- Return a string containing a printable representation of an object.
- This is the same value yielded by conversions (reverse quotes).
- It is sometimes useful to be able to access this operation as an
- ordinary function. For many types, this function makes an attempt
- to return a string that would yield an object with the same value
- when passed to \function{eval()}.
-\end{funcdesc}
-
-\begin{funcdesc}{reversed}{seq}
- Return a reverse iterator. \var{seq} must be an object which
- supports the sequence protocol (the \method{__len__()} method and the
- \method{__getitem__()} method with integer arguments starting at
- \code{0}).
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{round}{x\optional{, n}}
- Return the floating point value \var{x} rounded to \var{n} digits
- after the decimal point. If \var{n} is omitted, it defaults to zero.
- The result is a floating point number. Values are rounded to the
- closest multiple of 10 to the power minus \var{n}; if two multiples
- are equally close, rounding is done away from 0 (so. for example,
- \code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
-\end{funcdesc}
-
-\begin{funcdesc}{set}{\optional{iterable}}
- Return a set whose elements are taken from \var{iterable}. The elements
- must be immutable. To represent sets of sets, the inner sets should
- be \class{frozenset} objects. If \var{iterable} is not specified,
- returns a new empty set, \code{set([])}.
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{setattr}{object, name, value}
- This is the counterpart of \function{getattr()}. The arguments are an
- object, a string and an arbitrary value. The string may name an
- existing attribute or a new attribute. The function assigns the
- value to the attribute, provided the object allows it. For example,
- \code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
- \code{\var{x}.\var{foobar} = 123}.
-\end{funcdesc}
-
-\begin{funcdesc}{slice}{\optional{start,} stop\optional{, step}}
- Return a slice object representing the set of indices specified by
- \code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
- and \var{step} arguments default to \code{None}. Slice objects have
- read-only data attributes \member{start}, \member{stop} and
- \member{step} which merely return the argument values (or their
- default). They have no other explicit functionality; however they
- are used by Numerical Python\index{Numerical Python} and other third
- party extensions. Slice objects are also generated when extended
- indexing syntax is used. For example: \samp{a[start:stop:step]} or
- \samp{a[start:stop, i]}.
-\end{funcdesc}
-
-\begin{funcdesc}{sorted}{iterable\optional{, cmp\optional{,
- key\optional{, reverse}}}}
- Return a new sorted list from the items in \var{iterable}.
-
- The optional arguments \var{cmp}, \var{key}, and \var{reverse} have
- the same meaning as those for the \method{list.sort()} method
- (described in section~\ref{typesseq-mutable}).
-
- \var{cmp} specifies a custom comparison function of two arguments
- (iterable elements) which should return a negative, zero or positive
- number depending on whether the first argument is considered smaller
- than, equal to, or larger than the second argument:
- \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
- \function{cmp}(x.lower(), y.lower())}
-
- \var{key} specifies a function of one argument that is used to
- extract a comparison key from each list element:
- \samp{\var{key}=\function{str.lower}}
-
- \var{reverse} is a boolean value. If set to \code{True}, then the
- list elements are sorted as if each comparison were reversed.
-
- In general, the \var{key} and \var{reverse} conversion processes are
- much faster than specifying an equivalent \var{cmp} function. This is
- because \var{cmp} is called multiple times for each list element while
- \var{key} and \var{reverse} touch each element only once.
-
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{staticmethod}{function}
- Return a static method for \var{function}.
-
- A static method does not receive an implicit first argument.
- To declare a static method, use this idiom:
-
-\begin{verbatim}
-class C:
- @staticmethod
- def f(arg1, arg2, ...): ...
-\end{verbatim}
-
- The \code{@staticmethod} form is a function decorator -- see the description
- of function definitions in chapter 7 of the
- \citetitle[../ref/function.html]{Python Reference Manual} for details.
-
- It can be called either on the class (such as \code{C.f()}) or on an
- instance (such as \code{C().f()}). The instance is ignored except
- for its class.
-
- Static methods in Python are similar to those found in Java or \Cpp.
- For a more advanced concept, see \function{classmethod()} in this
- section.
-
- For more information on static methods, consult the documentation on the
- standard type hierarchy in chapter 3 of the
- \citetitle[../ref/types.html]{Python Reference Manual} (at the bottom).
- \versionadded{2.2}
- \versionchanged[Function decorator syntax added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{str}{\optional{object\optional{, encoding
- \optional{, errors}}}}
- Return the Unicode string version of \var{object} using one of the
- following modes:
-
- If \var{encoding} and/or \var{errors} are given, \code{unicode()}
- will decode the object which can either be an 8-bit string or a
- character buffer using the codec for \var{encoding}. The
- \var{encoding} parameter is a string giving the name of an encoding;
- if the encoding is not known, \exception{LookupError} is raised.
- Error handling is done according to \var{errors}; this specifies the
- treatment of characters which are invalid in the input encoding. If
- \var{errors} is \code{'strict'} (the default), a
- \exception{ValueError} is raised on errors, while a value of
- \code{'ignore'} causes errors to be silently ignored, and a value of
- \code{'replace'} causes the official Unicode replacement character,
- \code{U+FFFD}, to be used to replace input characters which cannot
- be decoded. See also the \refmodule{codecs} module.
-
- If no optional parameters are given, \code{unicode()} will mimic the
- behaviour of \code{str()} except that it returns Unicode strings
- instead of 8-bit strings. More precisely, if \var{object} is a
- Unicode string or subclass it will return that Unicode string without
- any additional decoding applied.
-
- For objects which provide a \method{__unicode__()} method, it will
- call this method without arguments to create a Unicode string. For
- all other objects, the 8-bit string version or representation is
- requested and then converted to a Unicode string using the codec for
- the default encoding in \code{'strict'} mode.
-
- \versionadded{2.0}
- \versionchanged[Support for \method{__unicode__()} added]{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{sum}{iterable\optional{, start}}
- Sums \var{start} and the items of an \var{iterable} from left to
- right and returns the total. \var{start} defaults to \code{0}.
- The \var{iterable}'s items are normally numbers, and are not allowed
- to be strings. The fast, correct way to concatenate a sequence of
- strings is by calling \code{''.join(\var{sequence})}.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{super}{type\optional{, object-or-type}}
- Return the superclass of \var{type}. If the second argument is omitted
- the super object returned is unbound. If the second argument is an
- object, \code{isinstance(\var{obj}, \var{type})} must be true. If
- the second argument is a type, \code{issubclass(\var{type2},
- \var{type})} must be true.
- \function{super()} only works for new-style classes.
-
- A typical use for calling a cooperative superclass method is:
-\begin{verbatim}
-class C(B):
- def meth(self, arg):
- super(C, self).meth(arg)
-\end{verbatim}
-
- Note that \function{super} is implemented as part of the binding process for
- explicit dotted attribute lookups such as
- \samp{super(C, self).__getitem__(name)}. Accordingly, \function{super} is
- undefined for implicit lookups using statements or operators such as
- \samp{super(C, self)[name]}.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{tuple}{\optional{iterable}}
- Return a tuple whose items are the same and in the same order as
- \var{iterable}'s items. \var{iterable} may be a sequence, a
- container that supports iteration, or an iterator object.
- If \var{iterable} is already a tuple, it
- is returned unchanged. For instance, \code{tuple('abc')} returns
- \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
- \code{(1, 2, 3)}. If no argument is given, returns a new empty
- tuple, \code{()}.
-\end{funcdesc}
-
-\begin{funcdesc}{type}{object}
- Return the type of an \var{object}. The return value is a
- type\obindex{type} object. The \function{isinstance()} built-in
- function is recommended for testing the type of an object.
-
- With three arguments, \function{type} functions as a constructor
- as detailed below.
-\end{funcdesc}
-
-\begin{funcdescni}{type}{name, bases, dict}
- Return a new type object. This is essentially a dynamic form of the
- \keyword{class} statement. The \var{name} string is the class name
- and becomes the \member{__name__} attribute; the \var{bases} tuple
- itemizes the base classes and becomes the \member{__bases__}
- attribute; and the \var{dict} dictionary is the namespace containing
- definitions for class body and becomes the \member{__dict__}
- attribute. For example, the following two statements create
- identical \class{type} objects:
-
-\begin{verbatim}
- >>> class X(object):
- ... a = 1
- ...
- >>> X = type('X', (object,), dict(a=1))
-\end{verbatim}
-\versionadded{2.2}
-\end{funcdescni}
-
-\begin{funcdesc}{vars}{\optional{object}}
- Without arguments, return a dictionary corresponding to the current
- local symbol table. With a module, class or class instance object
- as argument (or anything else that has a \member{__dict__}
- attribute), returns a dictionary corresponding to the object's
- symbol table. The returned dictionary should not be modified: the
- effects on the corresponding symbol table are undefined.\footnote{
- In the current implementation, local variable bindings cannot
- normally be affected this way, but variables retrieved from
- other scopes (such as modules) can be. This may change.}
-\end{funcdesc}
-
-\begin{funcdesc}{zip}{\optional{iterable, \moreargs}}
- This function returns a list of tuples, where the \var{i}-th tuple contains
- the \var{i}-th element from each of the argument sequences or iterables.
- The returned list is truncated in length to the length of
- the shortest argument sequence. When there are multiple arguments
- which are all of the same length, \function{zip()} is
- similar to \function{map()} with an initial argument of \code{None}.
- With a single sequence argument, it returns a list of 1-tuples.
- With no arguments, it returns an empty list.
- \versionadded{2.0}
-
- \versionchanged[Formerly, \function{zip()} required at least one argument
- and \code{zip()} raised a \exception{TypeError} instead of returning
- an empty list]{2.4}
-\end{funcdesc}
-
-
-% ---------------------------------------------------------------------------
-
-
-\section{Non-essential Built-in Functions \label{non-essential-built-in-funcs}}
-
-There are several built-in functions that are no longer essential to learn,
-know or use in modern Python programming. They have been kept here to
-maintain backwards compatibility with programs written for older versions
-of Python.
-
-Python programmers, trainers, students and bookwriters should feel free to
-bypass these functions without concerns about missing something important.
-
-
-\setindexsubitem{(non-essential built-in functions)}
-
-\begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
- The \var{object} argument must be an object that supports the buffer
- call interface (such as strings, arrays, and buffers). A new buffer
- object will be created which references the \var{object} argument.
- The buffer object will be a slice from the beginning of \var{object}
- (or from the specified \var{offset}). The slice will extend to the
- end of \var{object} (or will have a length given by the \var{size}
- argument).
-\end{funcdesc}
-
diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex
deleted file mode 100644
index 654a5b1..0000000
--- a/Doc/lib/libfunctools.tex
+++ /dev/null
@@ -1,145 +0,0 @@
-\section{\module{functools} ---
- Higher order functions and operations on callable objects.}
-
-\declaremodule{standard}{functools} % standard library, in Python
-
-\moduleauthor{Peter Harris}{scav@blueyonder.co.uk}
-\moduleauthor{Raymond Hettinger}{python@rcn.com}
-\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com}
-\sectionauthor{Peter Harris}{scav@blueyonder.co.uk}
-
-\modulesynopsis{Higher-order functions and operations on callable objects.}
-
-\versionadded{2.5}
-
-The \module{functools} module is for higher-order functions: functions
-that act on or return other functions. In general, any callable object can
-be treated as a function for the purposes of this module.
-
-
-The \module{functools} module defines the following function:
-
-\begin{funcdesc}{partial}{func\optional{,*args}\optional{, **keywords}}
-Return a new \class{partial} object which when called will behave like
-\var{func} called with the positional arguments \var{args} and keyword
-arguments \var{keywords}. If more arguments are supplied to the call, they
-are appended to \var{args}. If additional keyword arguments are supplied,
-they extend and override \var{keywords}. Roughly equivalent to:
- \begin{verbatim}
- def partial(func, *args, **keywords):
- def newfunc(*fargs, **fkeywords):
- newkeywords = keywords.copy()
- newkeywords.update(fkeywords)
- return func(*(args + fargs), **newkeywords)
- newfunc.func = func
- newfunc.args = args
- newfunc.keywords = keywords
- return newfunc
- \end{verbatim}
-
-The \function{partial} is used for partial function application which
-``freezes'' some portion of a function's arguments and/or keywords
-resulting in a new object with a simplified signature. For example,
-\function{partial} can be used to create a callable that behaves like
-the \function{int} function where the \var{base} argument defaults to
-two:
- \begin{verbatim}
- >>> basetwo = partial(int, base=2)
- >>> basetwo.__doc__ = 'Convert base 2 string to an int.'
- >>> basetwo('10010')
- 18
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{reduce}{function, sequence\optional{, initializer}}
- Apply \var{function} of two arguments cumulatively to the items of
- \var{sequence}, from left to right, so as to reduce the sequence to
- a single value. For example, \code{reduce(lambda x, y: x+y, [1, 2,
- 3, 4, 5])} calculates \code{((((1+2)+3)+4)+5)}. The left argument,
- \var{x}, is the accumulated value and the right argument, \var{y},
- is the update value from the \var{sequence}. If the optional
- \var{initializer} is present, it is placed before the items of the
- sequence in the calculation, and serves as a default when the
- sequence is empty. If \var{initializer} is not given and
- \var{sequence} contains only one item, the first item is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{update_wrapper}
-{wrapper, wrapped\optional{, assigned}\optional{, updated}}
-Update a \var{wrapper} function to look like the \var{wrapped} function.
-The optional arguments are tuples to specify which attributes of the original
-function are assigned directly to the matching attributes on the wrapper
-function and which attributes of the wrapper function are updated with
-the corresponding attributes from the original function. The default
-values for these arguments are the module level constants
-\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's
-\var{__name__}, \var{__module__} and \var{__doc__}, the documentation string)
-and \var{WRAPPER_UPDATES} (which updates the wrapper function's \var{__dict__},
-i.e. the instance dictionary).
-
-The main intended use for this function is in decorator functions
-which wrap the decorated function and return the wrapper. If the
-wrapper function is not updated, the metadata of the returned function
-will reflect the wrapper definition rather than the original function
-definition, which is typically less than helpful.
-\end{funcdesc}
-
-\begin{funcdesc}{wraps}
-{wrapped\optional{, assigned}\optional{, updated}}
-This is a convenience function for invoking
-\code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)}
-as a function decorator when defining a wrapper function. For example:
- \begin{verbatim}
- >>> def my_decorator(f):
- ... @wraps(f)
- ... def wrapper(*args, **kwds):
- ... print 'Calling decorated function'
- ... return f(*args, **kwds)
- ... return wrapper
- ...
- >>> @my_decorator
- ... def example():
- ... """Docstring"""
- ... print 'Called example function'
- ...
- >>> example()
- Calling decorated function
- Called example function
- >>> example.__name__
- 'example'
- >>> example.__doc__
- 'Docstring'
- \end{verbatim}
-Without the use of this decorator factory, the name of the example
-function would have been \code{'wrapper'}, and the docstring of the
-original \function{example()} would have been lost.
-\end{funcdesc}
-
-
-\subsection{\class{partial} Objects \label{partial-objects}}
-
-
-\class{partial} objects are callable objects created by \function{partial()}.
-They have three read-only attributes:
-
-\begin{memberdesc}[callable]{func}{}
-A callable object or function. Calls to the \class{partial} object will
-be forwarded to \member{func} with new arguments and keywords.
-\end{memberdesc}
-
-\begin{memberdesc}[tuple]{args}{}
-The leftmost positional arguments that will be prepended to the
-positional arguments provided to a \class{partial} object call.
-\end{memberdesc}
-
-\begin{memberdesc}[dict]{keywords}{}
-The keyword arguments that will be supplied when the \class{partial} object
-is called.
-\end{memberdesc}
-
-\class{partial} objects are like \class{function} objects in that they are
-callable, weak referencable, and can have attributes. There are some
-important differences. For instance, the \member{__name__} and
-\member{__doc__} attributes are not created automatically. Also,
-\class{partial} objects defined in classes behave like static methods and
-do not transform into bound methods during instance attribute look-up.
diff --git a/Doc/lib/libfuture.tex b/Doc/lib/libfuture.tex
deleted file mode 100644
index f1ba064..0000000
--- a/Doc/lib/libfuture.tex
+++ /dev/null
@@ -1,69 +0,0 @@
-\section{\module{__future__} ---
- Future statement definitions}
-
-\declaremodule[future]{standard}{__future__}
-\modulesynopsis{Future statement definitions}
-
-\module{__future__} is a real module, and serves three purposes:
-
-\begin{itemize}
-
-\item To avoid confusing existing tools that analyze import statements
- and expect to find the modules they're importing.
-
-\item To ensure that future_statements run under releases prior to 2.1
- at least yield runtime exceptions (the import of
- \module{__future__} will fail, because there was no module of
- that name prior to 2.1).
-
-\item To document when incompatible changes were introduced, and when they
- will be --- or were --- made mandatory. This is a form of executable
- documentation, and can be inspected programatically via importing
- \module{__future__} and examining its contents.
-
-\end{itemize}
-
-Each statement in \file{__future__.py} is of the form:
-
-\begin{alltt}
-FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} ","
- \var{CompilerFlag} ")"
-\end{alltt}
-
-where, normally, \var{OptionalRelease} is less than
-\var{MandatoryRelease}, and both are 5-tuples of the same form as
-\code{sys.version_info}:
-
-\begin{verbatim}
- (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
- PY_MINOR_VERSION, # the 1; an int
- PY_MICRO_VERSION, # the 0; an int
- PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
- PY_RELEASE_SERIAL # the 3; an int
- )
-\end{verbatim}
-
-\var{OptionalRelease} records the first release in which the feature
-was accepted.
-
-In the case of a \var{MandatoryRelease} that has not yet occurred,
-\var{MandatoryRelease} predicts the release in which the feature will
-become part of the language.
-
-Else \var{MandatoryRelease} records when the feature became part of
-the language; in releases at or after that, modules no longer need a
-future statement to use the feature in question, but may continue to
-use such imports.
-
-\var{MandatoryRelease} may also be \code{None}, meaning that a planned
-feature got dropped.
-
-Instances of class \class{_Feature} have two corresponding methods,
-\method{getOptionalRelease()} and \method{getMandatoryRelease()}.
-
-\var{CompilerFlag} is the (bitfield) flag that should be passed in the
-fourth argument to the builtin function \function{compile()} to enable
-the feature in dynamically compiled code. This flag is stored in the
-\member{compiler_flag} attribute on \class{_Feature} instances.
-
-No feature description will ever be deleted from \module{__future__}.
diff --git a/Doc/lib/libgc.tex b/Doc/lib/libgc.tex
deleted file mode 100644
index 0d3408b..0000000
--- a/Doc/lib/libgc.tex
+++ /dev/null
@@ -1,196 +0,0 @@
-\section{\module{gc} ---
- Garbage Collector interface}
-
-\declaremodule{extension}{gc}
-\modulesynopsis{Interface to the cycle-detecting garbage collector.}
-\moduleauthor{Neil Schemenauer}{nas@arctrix.com}
-\sectionauthor{Neil Schemenauer}{nas@arctrix.com}
-
-This module provides an interface to the optional garbage collector. It
-provides the ability to disable the collector, tune the collection
-frequency, and set debugging options. It also provides access to
-unreachable objects that the collector found but cannot free. Since the
-collector supplements the reference counting already used in Python, you
-can disable the collector if you are sure your program does not create
-reference cycles. Automatic collection can be disabled by calling
-\code{gc.disable()}. To debug a leaking program call
-\code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes
-\code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be
-saved in gc.garbage for inspection.
-
-The \module{gc} module provides the following functions:
-
-\begin{funcdesc}{enable}{}
-Enable automatic garbage collection.
-\end{funcdesc}
-
-\begin{funcdesc}{disable}{}
-Disable automatic garbage collection.
-\end{funcdesc}
-
-\begin{funcdesc}{isenabled}{}
-Returns true if automatic collection is enabled.
-\end{funcdesc}
-
-\begin{funcdesc}{collect}{\optional{generation}}
-With no arguments, run a full collection. The optional argument
-\var{generation} may be an integer specifying which generation to collect
-(from 0 to 2). A \exception{ValueError} is raised if the generation number
-is invalid.
-The number of unreachable objects found is returned.
-
-\versionchanged[The optional \var{generation} argument was added]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{set_debug}{flags}
-Set the garbage collection debugging flags.
-Debugging information will be written to \code{sys.stderr}. See below
-for a list of debugging flags which can be combined using bit
-operations to control debugging.
-\end{funcdesc}
-
-\begin{funcdesc}{get_debug}{}
-Return the debugging flags currently set.
-\end{funcdesc}
-
-\begin{funcdesc}{get_objects}{}
-Returns a list of all objects tracked by the collector, excluding the
-list returned.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{set_threshold}{threshold0\optional{,
- threshold1\optional{, threshold2}}}
-Set the garbage collection thresholds (the collection frequency).
-Setting \var{threshold0} to zero disables collection.
-
-The GC classifies objects into three generations depending on how many
-collection sweeps they have survived. New objects are placed in the
-youngest generation (generation \code{0}). If an object survives a
-collection it is moved into the next older generation. Since
-generation \code{2} is the oldest generation, objects in that
-generation remain there after a collection. In order to decide when
-to run, the collector keeps track of the number object allocations and
-deallocations since the last collection. When the number of
-allocations minus the number of deallocations exceeds
-\var{threshold0}, collection starts. Initially only generation
-\code{0} is examined. If generation \code{0} has been examined more
-than \var{threshold1} times since generation \code{1} has been
-examined, then generation \code{1} is examined as well. Similarly,
-\var{threshold2} controls the number of collections of generation
-\code{1} before collecting generation \code{2}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_count}{}
-Return the current collection counts as a tuple of
-\code{(\var{count0}, \var{count1}, \var{count2})}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{get_threshold}{}
-Return the current collection thresholds as a tuple of
-\code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_referrers}{*objs}
-Return the list of objects that directly refer to any of objs. This
-function will only locate those containers which support garbage
-collection; extension types which do refer to other objects but do not
-support garbage collection will not be found.
-
-Note that objects which have already been dereferenced, but which live
-in cycles and have not yet been collected by the garbage collector can
-be listed among the resulting referrers. To get only currently live
-objects, call \function{collect()} before calling
-\function{get_referrers()}.
-
-Care must be taken when using objects returned by
-\function{get_referrers()} because some of them could still be under
-construction and hence in a temporarily invalid state. Avoid using
-\function{get_referrers()} for any purpose other than debugging.
-
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{get_referents}{*objs}
-Return a list of objects directly referred to by any of the arguments.
-The referents returned are those objects visited by the arguments'
-C-level \member{tp_traverse} methods (if any), and may not be all
-objects actually directly reachable. \member{tp_traverse} methods
-are supported only by objects that support garbage collection, and are
-only required to visit objects that may be involved in a cycle. So,
-for example, if an integer is directly reachable from an argument, that
-integer object may or may not appear in the result list.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-The following variable is provided for read-only access (you can
-mutate its value but should not rebind it):
-
-\begin{datadesc}{garbage}
-A list of objects which the collector found to be unreachable
-but could not be freed (uncollectable objects). By default, this list
-contains only objects with \method{__del__()} methods.\footnote{Prior to
- Python 2.2, the list contained all instance objects in unreachable
- cycles, not only those with \method{__del__()} methods.}
-Objects that have
-\method{__del__()} methods and are part of a reference cycle cause
-the entire reference cycle to be uncollectable, including objects
-not necessarily in the cycle but reachable only from it. Python doesn't
-collect such cycles automatically because, in general, it isn't possible
-for Python to guess a safe order in which to run the \method{__del__()}
-methods. If you know a safe order, you can force the issue by examining
-the \var{garbage} list, and explicitly breaking cycles due to your
-objects within the list. Note that these objects are kept alive even
-so by virtue of being in the \var{garbage} list, so they should be
-removed from \var{garbage} too. For example, after breaking cycles, do
-\code{del gc.garbage[:]} to empty the list. It's generally better
-to avoid the issue by not creating cycles containing objects with
-\method{__del__()} methods, and \var{garbage} can be examined in that
-case to verify that no such cycles are being created.
-
-If \constant{DEBUG_SAVEALL} is set, then all unreachable objects will
-be added to this list rather than freed.
-\end{datadesc}
-
-
-The following constants are provided for use with
-\function{set_debug()}:
-
-\begin{datadesc}{DEBUG_STATS}
-Print statistics during collection. This information can
-be useful when tuning the collection frequency.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_COLLECTABLE}
-Print information on collectable objects found.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_UNCOLLECTABLE}
-Print information of uncollectable objects found (objects which are
-not reachable but cannot be freed by the collector). These objects
-will be added to the \code{garbage} list.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_INSTANCES}
-When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
-set, print information about instance objects found.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_OBJECTS}
-When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
-set, print information about objects other than instance objects found.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_SAVEALL}
-When set, all unreachable objects found will be appended to
-\var{garbage} rather than being freed. This can be useful for debugging
-a leaking program.
-\end{datadesc}
-
-\begin{datadesc}{DEBUG_LEAK}
-The debugging flags necessary for the collector to print
-information about a leaking program (equal to \code{DEBUG_COLLECTABLE |
-DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL}).
-\end{datadesc}
diff --git a/Doc/lib/libgdbm.tex b/Doc/lib/libgdbm.tex
deleted file mode 100644
index 0c36677..0000000
--- a/Doc/lib/libgdbm.tex
+++ /dev/null
@@ -1,100 +0,0 @@
-\section{\module{gdbm} ---
- GNU's reinterpretation of dbm}
-
-\declaremodule{builtin}{gdbm}
- \platform{Unix}
-\modulesynopsis{GNU's reinterpretation of dbm.}
-
-
-This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm}
-module, but uses \code{gdbm} instead to provide some additional
-functionality. Please note that the file formats created by
-\code{gdbm} and \code{dbm} are incompatible.
-
-The \module{gdbm} module provides an interface to the GNU DBM
-library. \code{gdbm} objects behave like mappings
-(dictionaries), except that keys and values are always strings.
-Printing a \code{gdbm} object doesn't print the keys and values, and
-the \method{items()} and \method{values()} methods are not supported.
-
-The module defines the following constant and functions:
-
-\begin{excdesc}{error}
-Raised on \code{gdbm}-specific errors, such as I/O errors.
-\exception{KeyError} is raised for general mapping errors like
-specifying an incorrect key.
-\end{excdesc}
-
-\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
-Open a \code{gdbm} database and return a \code{gdbm} object. The
-\var{filename} argument is the name of the database file.
-
-The optional \var{flag} argument can be
-\code{'r'} (to open an existing database for reading only --- default),
-\code{'w'} (to open an existing database for reading and writing),
-\code{'c'} (which creates the database if it doesn't exist), or
-\code{'n'} (which always creates a new empty database).
-
-The following additional characters may be appended to the flag to
-control how the database is opened:
-
-\begin{itemize}
-\item \code{'f'} --- Open the database in fast mode. Writes to the database
- will not be synchronized.
-\item \code{'s'} --- Synchronized mode. This will cause changes to the database
- will be immediately written to the file.
-\item \code{'u'} --- Do not lock database.
-\end{itemize}
-
-Not all flags are valid for all versions of \code{gdbm}. The
-module constant \code{open_flags} is a string of supported flag
-characters. The exception \exception{error} is raised if an invalid
-flag is specified.
-
-The optional \var{mode} argument is the \UNIX{} mode of the file, used
-only when the database has to be created. It defaults to octal
-\code{0666}.
-\end{funcdesc}
-
-In addition to the dictionary-like methods, \code{gdbm} objects have the
-following methods:
-
-\begin{funcdesc}{firstkey}{}
-It's possible to loop over every key in the database using this method
-and the \method{nextkey()} method. The traversal is ordered by
-\code{gdbm}'s internal hash values, and won't be sorted by the key
-values. This method returns the starting key.
-\end{funcdesc}
-
-\begin{funcdesc}{nextkey}{key}
-Returns the key that follows \var{key} in the traversal. The
-following code prints every key in the database \code{db}, without
-having to create a list in memory that contains them all:
-
-\begin{verbatim}
-k = db.firstkey()
-while k != None:
- print k
- k = db.nextkey(k)
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{reorganize}{}
-If you have carried out a lot of deletions and would like to shrink
-the space used by the \code{gdbm} file, this routine will reorganize
-the database. \code{gdbm} will not shorten the length of a database
-file except by using this reorganization; otherwise, deleted file
-space will be kept and reused as new (key, value) pairs are added.
-\end{funcdesc}
-
-\begin{funcdesc}{sync}{}
-When the database has been opened in fast mode, this method forces any
-unwritten data to be written to the disk.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{whichdb}{Utility module used to determine the type of an
- existing database.}
-\end{seealso}
diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex
deleted file mode 100644
index 7930acd..0000000
--- a/Doc/lib/libgetopt.tex
+++ /dev/null
@@ -1,154 +0,0 @@
-\section{\module{getopt} ---
- Parser for command line options}
-
-\declaremodule{standard}{getopt}
-\modulesynopsis{Portable parser for command line options; support both
- short and long option names.}
-
-
-This module helps scripts to parse the command line arguments in
-\code{sys.argv}.
-It supports the same conventions as the \UNIX{} \cfunction{getopt()}
-function (including the special meanings of arguments of the form
-`\code{-}' and `\code{-}\code{-}').
-% That's to fool latex2html into leaving the two hyphens alone!
-Long options similar to those supported by
-GNU software may be used as well via an optional third argument.
-This module provides a single function and an exception:
-
-\begin{funcdesc}{getopt}{args, options\optional{, long_options}}
-Parses command line options and parameter list. \var{args} is the
-argument list to be parsed, without the leading reference to the
-running program. Typically, this means \samp{sys.argv[1:]}.
-\var{options} is the string of option letters that the script wants to
-recognize, with options that require an argument followed by a colon
-(\character{:}; i.e., the same format that \UNIX{}
-\cfunction{getopt()} uses).
-
-\note{Unlike GNU \cfunction{getopt()}, after a non-option
-argument, all further arguments are considered also non-options.
-This is similar to the way non-GNU \UNIX{} systems work.}
-
-\var{long_options}, if specified, must be a list of strings with the
-names of the long options which should be supported. The leading
-\code{'-}\code{-'} characters should not be included in the option
-name. Long options which require an argument should be followed by an
-equal sign (\character{=}). To accept only long options,
-\var{options} should be an empty string. Long options on the command
-line can be recognized so long as they provide a prefix of the option
-name that matches exactly one of the accepted options. For example,
-if \var{long_options} is \code{['foo', 'frob']}, the option
-\longprogramopt{fo} will match as \longprogramopt{foo}, but
-\longprogramopt{f} will not match uniquely, so \exception{GetoptError}
-will be raised.
-
-The return value consists of two elements: the first is a list of
-\code{(\var{option}, \var{value})} pairs; the second is the list of
-program arguments left after the option list was stripped (this is a
-trailing slice of \var{args}). Each option-and-value pair returned
-has the option as its first element, prefixed with a hyphen for short
-options (e.g., \code{'-x'}) or two hyphens for long options (e.g.,
-\code{'-}\code{-long-option'}), and the option argument as its second
-element, or an empty string if the option has no argument. The
-options occur in the list in the same order in which they were found,
-thus allowing multiple occurrences. Long and short options may be
-mixed.
-\end{funcdesc}
-
-\begin{funcdesc}{gnu_getopt}{args, options\optional{, long_options}}
-This function works like \function{getopt()}, except that GNU style
-scanning mode is used by default. This means that option and
-non-option arguments may be intermixed. The \function{getopt()}
-function stops processing options as soon as a non-option argument is
-encountered.
-
-If the first character of the option string is `+', or if the
-environment variable POSIXLY_CORRECT is set, then option processing
-stops as soon as a non-option argument is encountered.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{excdesc}{GetoptError}
-This is raised when an unrecognized option is found in the argument
-list or when an option requiring an argument is given none.
-The argument to the exception is a string indicating the cause of the
-error. For long options, an argument given to an option which does
-not require one will also cause this exception to be raised. The
-attributes \member{msg} and \member{opt} give the error message and
-related option; if there is no specific option to which the exception
-relates, \member{opt} is an empty string.
-
-\versionchanged[Introduced \exception{GetoptError} as a synonym for
- \exception{error}]{1.6}
-\end{excdesc}
-
-\begin{excdesc}{error}
-Alias for \exception{GetoptError}; for backward compatibility.
-\end{excdesc}
-
-
-An example using only \UNIX{} style options:
-
-\begin{verbatim}
->>> import getopt
->>> args = '-a -b -cfoo -d bar a1 a2'.split()
->>> args
-['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
->>> optlist, args = getopt.getopt(args, 'abc:d:')
->>> optlist
-[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
->>> args
-['a1', 'a2']
-\end{verbatim}
-
-Using long option names is equally easy:
-
-\begin{verbatim}
->>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
->>> args = s.split()
->>> args
-['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
->>> optlist, args = getopt.getopt(args, 'x', [
-... 'condition=', 'output-file=', 'testing'])
->>> optlist
-[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
- '')]
->>> args
-['a1', 'a2']
-\end{verbatim}
-
-In a script, typical usage is something like this:
-
-\begin{verbatim}
-import getopt, sys
-
-def main():
- try:
- opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
- except getopt.GetoptError as err:
- # print help information and exit:
- print str(err) # will print something like "option -a not recognized"
- usage()
- sys.exit(2)
- output = None
- verbose = False
- for o, a in opts:
- if o == "-v":
- verbose = True
- elif o in ("-h", "--help"):
- usage()
- sys.exit()
- elif o in ("-o", "--output"):
- output = a
- else:
- assert False, "unhandled option"
- # ...
-
-if __name__ == "__main__":
- main()
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{optparse}{More object-oriented command line option parsing.}
-\end{seealso}
diff --git a/Doc/lib/libgetpass.tex b/Doc/lib/libgetpass.tex
deleted file mode 100644
index a742439..0000000
--- a/Doc/lib/libgetpass.tex
+++ /dev/null
@@ -1,36 +0,0 @@
-\section{\module{getpass}
- --- Portable password input}
-
-\declaremodule{standard}{getpass}
-\modulesynopsis{Portable reading of passwords and retrieval of the userid.}
-\moduleauthor{Piers Lauder}{piers@cs.su.oz.au}
-% Windows (& Mac?) support by Guido van Rossum.
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{getpass} module provides two functions:
-
-
-\begin{funcdesc}{getpass}{\optional{prompt\optional{, stream}}}
- Prompt the user for a password without echoing. The user is
- prompted using the string \var{prompt}, which defaults to
- \code{'Password: '}. On \UNIX, the prompt is written to the
- file-like object \var{stream}, which defaults to
- \code{sys.stdout} (this argument is ignored on Windows).
-
- Availability: Macintosh, \UNIX, Windows.
- \versionchanged[The \var{stream} parameter was added]{2.5}
-\end{funcdesc}
-
-
-\begin{funcdesc}{getuser}{}
- Return the ``login name'' of the user.
- Availability: \UNIX, Windows.
-
- This function checks the environment variables \envvar{LOGNAME},
- \envvar{USER}, \envvar{LNAME} and \envvar{USERNAME}, in order, and
- returns the value of the first one which is set to a non-empty
- string. If none are set, the login name from the password database
- is returned on systems which support the \refmodule{pwd} module,
- otherwise, an exception is raised.
-\end{funcdesc}
diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex
deleted file mode 100644
index 6aee255..0000000
--- a/Doc/lib/libgettext.tex
+++ /dev/null
@@ -1,773 +0,0 @@
-\section{\module{gettext} ---
- Multilingual internationalization services}
-
-\declaremodule{standard}{gettext}
-\modulesynopsis{Multilingual internationalization services.}
-\moduleauthor{Barry A. Warsaw}{barry@zope.com}
-\sectionauthor{Barry A. Warsaw}{barry@zope.com}
-
-
-The \module{gettext} module provides internationalization (I18N) and
-localization (L10N) services for your Python modules and applications.
-It supports both the GNU \code{gettext} message catalog API and a
-higher level, class-based API that may be more appropriate for Python
-files. The interface described below allows you to write your
-module and application messages in one natural language, and provide a
-catalog of translated messages for running under different natural
-languages.
-
-Some hints on localizing your Python modules and applications are also
-given.
-
-\subsection{GNU \program{gettext} API}
-
-The \module{gettext} module defines the following API, which is very
-similar to the GNU \program{gettext} API. If you use this API you
-will affect the translation of your entire application globally. Often
-this is what you want if your application is monolingual, with the choice
-of language dependent on the locale of your user. If you are
-localizing a Python module, or if your application needs to switch
-languages on the fly, you probably want to use the class-based API
-instead.
-
-\begin{funcdesc}{bindtextdomain}{domain\optional{, localedir}}
-Bind the \var{domain} to the locale directory
-\var{localedir}. More concretely, \module{gettext} will look for
-binary \file{.mo} files for the given domain using the path (on \UNIX):
-\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo},
-where \var{languages} is searched for in the environment variables
-\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and
-\envvar{LANG} respectively.
-
-If \var{localedir} is omitted or \code{None}, then the current binding
-for \var{domain} is returned.\footnote{
- The default locale directory is system dependent; for example,
- on RedHat Linux it is \file{/usr/share/locale}, but on Solaris
- it is \file{/usr/lib/locale}. The \module{gettext} module
- does not try to support these system dependent defaults;
- instead its default is \file{\code{sys.prefix}/share/locale}.
- For this reason, it is always best to call
- \function{bindtextdomain()} with an explicit absolute path at
- the start of your application.}
-\end{funcdesc}
-
-\begin{funcdesc}{bind_textdomain_codeset}{domain\optional{, codeset}}
-Bind the \var{domain} to \var{codeset}, changing the encoding of
-strings returned by the \function{gettext()} family of functions.
-If \var{codeset} is omitted, then the current binding is returned.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{textdomain}{\optional{domain}}
-Change or query the current global domain. If \var{domain} is
-\code{None}, then the current global domain is returned, otherwise the
-global domain is set to \var{domain}, which is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{gettext}{message}
-Return the localized translation of \var{message}, based on the
-current global domain, language, and locale directory. This function
-is usually aliased as \function{_} in the local namespace (see
-examples below).
-\end{funcdesc}
-
-\begin{funcdesc}{lgettext}{message}
-Equivalent to \function{gettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{dgettext}{domain, message}
-Like \function{gettext()}, but look the message up in the specified
-\var{domain}.
-\end{funcdesc}
-
-\begin{funcdesc}{ldgettext}{domain, message}
-Equivalent to \function{dgettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{ngettext}{singular, plural, n}
-
-Like \function{gettext()}, but consider plural forms. If a translation
-is found, apply the plural formula to \var{n}, and return the
-resulting message (some languages have more than two plural forms).
-If no translation is found, return \var{singular} if \var{n} is 1;
-return \var{plural} otherwise.
-
-The Plural formula is taken from the catalog header. It is a C or
-Python expression that has a free variable \var{n}; the expression evaluates
-to the index of the plural in the catalog. See the GNU gettext
-documentation for the precise syntax to be used in \file{.po} files and the
-formulas for a variety of languages.
-
-\versionadded{2.3}
-
-\end{funcdesc}
-
-\begin{funcdesc}{lngettext}{singular, plural, n}
-Equivalent to \function{ngettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{dngettext}{domain, singular, plural, n}
-Like \function{ngettext()}, but look the message up in the specified
-\var{domain}.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{ldngettext}{domain, singular, plural, n}
-Equivalent to \function{dngettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \function{bind_textdomain_codeset()}.
-
-\versionadded{2.4}
-\end{funcdesc}
-
-
-
-Note that GNU \program{gettext} also defines a \function{dcgettext()}
-method, but this was deemed not useful and so it is currently
-unimplemented.
-
-Here's an example of typical usage for this API:
-
-\begin{verbatim}
-import gettext
-gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
-gettext.textdomain('myapplication')
-_ = gettext.gettext
-# ...
-print _('This is a translatable string.')
-\end{verbatim}
-
-\subsection{Class-based API}
-
-The class-based API of the \module{gettext} module gives you more
-flexibility and greater convenience than the GNU \program{gettext}
-API. It is the recommended way of localizing your Python applications and
-modules. \module{gettext} defines a ``translations'' class which
-implements the parsing of GNU \file{.mo} format files, and has methods
-for returning either standard 8-bit strings or Unicode strings.
-Instances of this ``translations'' class can also install themselves
-in the built-in namespace as the function \function{_()}.
-
-\begin{funcdesc}{find}{domain\optional{, localedir\optional{,
- languages\optional{, all}}}}
-This function implements the standard \file{.mo} file search
-algorithm. It takes a \var{domain}, identical to what
-\function{textdomain()} takes. Optional \var{localedir} is as in
-\function{bindtextdomain()} Optional \var{languages} is a list of
-strings, where each string is a language code.
-
-If \var{localedir} is not given, then the default system locale
-directory is used.\footnote{See the footnote for
-\function{bindtextdomain()} above.} If \var{languages} is not given,
-then the following environment variables are searched: \envvar{LANGUAGE},
-\envvar{LC_ALL}, \envvar{LC_MESSAGES}, and \envvar{LANG}. The first one
-returning a non-empty value is used for the \var{languages} variable.
-The environment variables should contain a colon separated list of
-languages, which will be split on the colon to produce the expected
-list of language code strings.
-
-\function{find()} then expands and normalizes the languages, and then
-iterates through them, searching for an existing file built of these
-components:
-
-\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo}
-
-The first such file name that exists is returned by \function{find()}.
-If no such file is found, then \code{None} is returned. If \var{all}
-is given, it returns a list of all file names, in the order in which
-they appear in the languages list or the environment variables.
-\end{funcdesc}
-
-\begin{funcdesc}{translation}{domain\optional{, localedir\optional{,
- languages\optional{, class_\optional{,
- fallback\optional{, codeset}}}}}}
-Return a \class{Translations} instance based on the \var{domain},
-\var{localedir}, and \var{languages}, which are first passed to
-\function{find()} to get a list of the
-associated \file{.mo} file paths. Instances with
-identical \file{.mo} file names are cached. The actual class instantiated
-is either \var{class_} if provided, otherwise
-\class{GNUTranslations}. The class's constructor must take a single
-file object argument. If provided, \var{codeset} will change the
-charset used to encode translated strings.
-
-If multiple files are found, later files are used as fallbacks for
-earlier ones. To allow setting the fallback, \function{copy.copy}
-is used to clone each translation object from the cache; the actual
-instance data is still shared with the cache.
-
-If no \file{.mo} file is found, this function raises
-\exception{IOError} if \var{fallback} is false (which is the default),
-and returns a \class{NullTranslations} instance if \var{fallback} is
-true.
-
-\versionchanged[Added the \var{codeset} parameter]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode
- \optional{, codeset\optional{, names}}}}}
-This installs the function \function{_} in Python's builtin namespace,
-based on \var{domain}, \var{localedir}, and \var{codeset} which are
-passed to the function \function{translation()}. The \var{unicode}
-flag is passed to the resulting translation object's \method{install}
-method.
-
-For the \var{names} parameter, please see the description of the
-translation object's \method{install} method.
-
-As seen below, you usually mark the strings in your application that are
-candidates for translation, by wrapping them in a call to the
-\function{_()} function, like this:
-
-\begin{verbatim}
-print _('This string will be translated.')
-\end{verbatim}
-
-For convenience, you want the \function{_()} function to be installed in
-Python's builtin namespace, so it is easily accessible in all modules
-of your application.
-
-\versionchanged[Added the \var{codeset} parameter]{2.4}
-\versionchanged[Added the \var{names} parameter]{2.5}
-\end{funcdesc}
-
-\subsubsection{The \class{NullTranslations} class}
-Translation classes are what actually implement the translation of
-original source file message strings to translated message strings.
-The base class used by all translation classes is
-\class{NullTranslations}; this provides the basic interface you can use
-to write your own specialized translation classes. Here are the
-methods of \class{NullTranslations}:
-
-\begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}}
-Takes an optional file object \var{fp}, which is ignored by the base
-class. Initializes ``protected'' instance variables \var{_info} and
-\var{_charset} which are set by derived classes, as well as \var{_fallback},
-which is set through \method{add_fallback}. It then calls
-\code{self._parse(fp)} if \var{fp} is not \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{_parse}{fp}
-No-op'd in the base class, this method takes file object \var{fp}, and
-reads the data from the file, initializing its message catalog. If
-you have an unsupported message catalog file format, you should
-override this method to parse your format.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{add_fallback}{fallback}
-Add \var{fallback} as the fallback object for the current translation
-object. A translation object should consult the fallback if it cannot
-provide a translation for a given message.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{gettext}{message}
-If a fallback has been set, forward \method{gettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{lgettext}{message}
-If a fallback has been set, forward \method{lgettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{ugettext}{message}
-If a fallback has been set, forward \method{ugettext()} to the fallback.
-Otherwise, return the translated message as a Unicode string.
-Overridden in derived classes.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n}
-If a fallback has been set, forward \method{ngettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{lngettext}{singular, plural, n}
-If a fallback has been set, forward \method{ngettext()} to the fallback.
-Otherwise, return the translated message. Overridden in derived classes.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n}
-If a fallback has been set, forward \method{ungettext()} to the fallback.
-Otherwise, return the translated message as a Unicode string.
-Overridden in derived classes.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{info}{}
-Return the ``protected'' \member{_info} variable.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{charset}{}
-Return the ``protected'' \member{_charset} variable.
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{output_charset}{}
-Return the ``protected'' \member{_output_charset} variable, which
-defines the encoding used to return translated messages.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{set_output_charset}{charset}
-Change the ``protected'' \member{_output_charset} variable, which
-defines the encoding used to return translated messages.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NullTranslations]{install}{\optional{unicode
- \optional{, names}}}
-If the \var{unicode} flag is false, this method installs
-\method{self.gettext()} into the built-in namespace, binding it to
-\samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()}
-instead. By default, \var{unicode} is false.
-
-If the \var{names} parameter is given, it must be a sequence containing
-the names of functions you want to install in the builtin namespace in
-addition to \function{_()}. Supported names are \code{'gettext'} (bound
-to \method{self.gettext()} or \method{self.ugettext()} according to the
-\var{unicode} flag), \code{'ngettext'} (bound to \method{self.ngettext()}
-or \method{self.ungettext()} according to the \var{unicode} flag),
-\code{'lgettext'} and \code{'lngettext'}.
-
-Note that this is only one way, albeit the most convenient way, to
-make the \function{_} function available to your application. Because it
-affects the entire application globally, and specifically the built-in
-namespace, localized modules should never install \function{_}.
-Instead, they should use this code to make \function{_} available to
-their module:
-
-\begin{verbatim}
-import gettext
-t = gettext.translation('mymodule', ...)
-_ = t.gettext
-\end{verbatim}
-
-This puts \function{_} only in the module's global namespace and so
-only affects calls within this module.
-
-\versionchanged[Added the \var{names} parameter]{2.5}
-\end{methoddesc}
-
-\subsubsection{The \class{GNUTranslations} class}
-
-The \module{gettext} module provides one additional class derived from
-\class{NullTranslations}: \class{GNUTranslations}. This class
-overrides \method{_parse()} to enable reading GNU \program{gettext}
-format \file{.mo} files in both big-endian and little-endian format.
-It also coerces both message ids and message strings to Unicode.
-
-\class{GNUTranslations} parses optional meta-data out of the
-translation catalog. It is convention with GNU \program{gettext} to
-include meta-data as the translation for the empty string. This
-meta-data is in \rfc{822}-style \code{key: value} pairs, and should
-contain the \code{Project-Id-Version} key. If the key
-\code{Content-Type} is found, then the \code{charset} property is used
-to initialize the ``protected'' \member{_charset} instance variable,
-defaulting to \code{None} if not found. If the charset encoding is
-specified, then all message ids and message strings read from the
-catalog are converted to Unicode using this encoding. The
-\method{ugettext()} method always returns a Unicode, while the
-\method{gettext()} returns an encoded 8-bit string. For the message
-id arguments of both methods, either Unicode strings or 8-bit strings
-containing only US-ASCII characters are acceptable. Note that the
-Unicode version of the methods (i.e. \method{ugettext()} and
-\method{ungettext()}) are the recommended interface to use for
-internationalized Python programs.
-
-The entire set of key/value pairs are placed into a dictionary and set
-as the ``protected'' \member{_info} instance variable.
-
-If the \file{.mo} file's magic number is invalid, or if other problems
-occur while reading the file, instantiating a \class{GNUTranslations} class
-can raise \exception{IOError}.
-
-The following methods are overridden from the base class implementation:
-
-\begin{methoddesc}[GNUTranslations]{gettext}{message}
-Look up the \var{message} id in the catalog and return the
-corresponding message string, as an 8-bit string encoded with the
-catalog's charset encoding, if known. If there is no entry in the
-catalog for the \var{message} id, and a fallback has been set, the
-look up is forwarded to the fallback's \method{gettext()} method.
-Otherwise, the \var{message} id is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{lgettext}{message}
-Equivalent to \method{gettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \method{set_output_charset()}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{ugettext}{message}
-Look up the \var{message} id in the catalog and return the
-corresponding message string, as a Unicode string. If there is no
-entry in the catalog for the \var{message} id, and a fallback has been
-set, the look up is forwarded to the fallback's \method{ugettext()}
-method. Otherwise, the \var{message} id is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{ngettext}{singular, plural, n}
-Do a plural-forms lookup of a message id. \var{singular} is used as
-the message id for purposes of lookup in the catalog, while \var{n} is
-used to determine which plural form to use. The returned message
-string is an 8-bit string encoded with the catalog's charset encoding,
-if known.
-
-If the message id is not found in the catalog, and a fallback is
-specified, the request is forwarded to the fallback's
-\method{ngettext()} method. Otherwise, when \var{n} is 1 \var{singular} is
-returned, and \var{plural} is returned in all other cases.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{lngettext}{singular, plural, n}
-Equivalent to \method{gettext()}, but the translation is returned
-in the preferred system encoding, if no other encoding was explicitly
-set with \method{set_output_charset()}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n}
-Do a plural-forms lookup of a message id. \var{singular} is used as
-the message id for purposes of lookup in the catalog, while \var{n} is
-used to determine which plural form to use. The returned message
-string is a Unicode string.
-
-If the message id is not found in the catalog, and a fallback is
-specified, the request is forwarded to the fallback's
-\method{ungettext()} method. Otherwise, when \var{n} is 1 \var{singular} is
-returned, and \var{plural} is returned in all other cases.
-
-Here is an example:
-
-\begin{verbatim}
-n = len(os.listdir('.'))
-cat = GNUTranslations(somefile)
-message = cat.ungettext(
- 'There is %(num)d file in this directory',
- 'There are %(num)d files in this directory',
- n) % {'num': n}
-\end{verbatim}
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\subsubsection{Solaris message catalog support}
-
-The Solaris operating system defines its own binary
-\file{.mo} file format, but since no documentation can be found on
-this format, it is not supported at this time.
-
-\subsubsection{The Catalog constructor}
-
-GNOME\index{GNOME} uses a version of the \module{gettext} module by
-James Henstridge, but this version has a slightly different API. Its
-documented usage was:
-
-\begin{verbatim}
-import gettext
-cat = gettext.Catalog(domain, localedir)
-_ = cat.gettext
-print _('hello world')
-\end{verbatim}
-
-For compatibility with this older module, the function
-\function{Catalog()} is an alias for the \function{translation()}
-function described above.
-
-One difference between this module and Henstridge's: his catalog
-objects supported access through a mapping API, but this appears to be
-unused and so is not currently supported.
-
-\subsection{Internationalizing your programs and modules}
-Internationalization (I18N) refers to the operation by which a program
-is made aware of multiple languages. Localization (L10N) refers to
-the adaptation of your program, once internationalized, to the local
-language and cultural habits. In order to provide multilingual
-messages for your Python programs, you need to take the following
-steps:
-
-\begin{enumerate}
- \item prepare your program or module by specially marking
- translatable strings
- \item run a suite of tools over your marked files to generate raw
- messages catalogs
- \item create language specific translations of the message catalogs
- \item use the \module{gettext} module so that message strings are
- properly translated
-\end{enumerate}
-
-In order to prepare your code for I18N, you need to look at all the
-strings in your files. Any string that needs to be translated
-should be marked by wrapping it in \code{_('...')} --- that is, a call
-to the function \function{_()}. For example:
-
-\begin{verbatim}
-filename = 'mylog.txt'
-message = _('writing a log message')
-fp = open(filename, 'w')
-fp.write(message)
-fp.close()
-\end{verbatim}
-
-In this example, the string \code{'writing a log message'} is marked as
-a candidate for translation, while the strings \code{'mylog.txt'} and
-\code{'w'} are not.
-
-The Python distribution comes with two tools which help you generate
-the message catalogs once you've prepared your source code. These may
-or may not be available from a binary distribution, but they can be
-found in a source distribution, in the \file{Tools/i18n} directory.
-
-The \program{pygettext}\footnote{Fran\c cois Pinard has
-written a program called
-\program{xpot} which does a similar job. It is available as part of
-his \program{po-utils} package at
-\url{http://po-utils.progiciels-bpi.ca/}.} program
-scans all your Python source code looking for the strings you
-previously marked as translatable. It is similar to the GNU
-\program{gettext} program except that it understands all the
-intricacies of Python source code, but knows nothing about C or \Cpp
-source code. You don't need GNU \code{gettext} unless you're also
-going to be translating C code (such as C extension modules).
-
-\program{pygettext} generates textual Uniforum-style human readable
-message catalog \file{.pot} files, essentially structured human
-readable files which contain every marked string in the source code,
-along with a placeholder for the translation strings.
-\program{pygettext} is a command line script that supports a similar
-command line interface as \program{xgettext}; for details on its use,
-run:
-
-\begin{verbatim}
-pygettext.py --help
-\end{verbatim}
-
-Copies of these \file{.pot} files are then handed over to the
-individual human translators who write language-specific versions for
-every supported natural language. They send you back the filled in
-language-specific versions as a \file{.po} file. Using the
-\program{msgfmt.py}\footnote{\program{msgfmt.py} is binary
-compatible with GNU \program{msgfmt} except that it provides a
-simpler, all-Python implementation. With this and
-\program{pygettext.py}, you generally won't need to install the GNU
-\program{gettext} package to internationalize your Python
-applications.} program (in the \file{Tools/i18n} directory), you take the
-\file{.po} files from your translators and generate the
-machine-readable \file{.mo} binary catalog files. The \file{.mo}
-files are what the \module{gettext} module uses for the actual
-translation processing during run-time.
-
-How you use the \module{gettext} module in your code depends on
-whether you are internationalizing a single module or your entire application.
-The next two sections will discuss each case.
-
-\subsubsection{Localizing your module}
-
-If you are localizing your module, you must take care not to make
-global changes, e.g. to the built-in namespace. You should not use
-the GNU \code{gettext} API but instead the class-based API.
-
-Let's say your module is called ``spam'' and the module's various
-natural language translation \file{.mo} files reside in
-\file{/usr/share/locale} in GNU \program{gettext} format. Here's what
-you would put at the top of your module:
-
-\begin{verbatim}
-import gettext
-t = gettext.translation('spam', '/usr/share/locale')
-_ = t.lgettext
-\end{verbatim}
-
-If your translators were providing you with Unicode strings in their
-\file{.po} files, you'd instead do:
-
-\begin{verbatim}
-import gettext
-t = gettext.translation('spam', '/usr/share/locale')
-_ = t.ugettext
-\end{verbatim}
-
-\subsubsection{Localizing your application}
-
-If you are localizing your application, you can install the \function{_()}
-function globally into the built-in namespace, usually in the main driver file
-of your application. This will let all your application-specific
-files just use \code{_('...')} without having to explicitly install it in
-each file.
-
-In the simple case then, you need only add the following bit of code
-to the main driver file of your application:
-
-\begin{verbatim}
-import gettext
-gettext.install('myapplication')
-\end{verbatim}
-
-If you need to set the locale directory or the \var{unicode} flag,
-you can pass these into the \function{install()} function:
-
-\begin{verbatim}
-import gettext
-gettext.install('myapplication', '/usr/share/locale', unicode=1)
-\end{verbatim}
-
-\subsubsection{Changing languages on the fly}
-
-If your program needs to support many languages at the same time, you
-may want to create multiple translation instances and then switch
-between them explicitly, like so:
-
-\begin{verbatim}
-import gettext
-
-lang1 = gettext.translation('myapplication', languages=['en'])
-lang2 = gettext.translation('myapplication', languages=['fr'])
-lang3 = gettext.translation('myapplication', languages=['de'])
-
-# start by using language1
-lang1.install()
-
-# ... time goes by, user selects language 2
-lang2.install()
-
-# ... more time goes by, user selects language 3
-lang3.install()
-\end{verbatim}
-
-\subsubsection{Deferred translations}
-
-In most coding situations, strings are translated where they are coded.
-Occasionally however, you need to mark strings for translation, but
-defer actual translation until later. A classic example is:
-
-\begin{verbatim}
-animals = ['mollusk',
- 'albatross',
- 'rat',
- 'penguin',
- 'python',
- ]
-# ...
-for a in animals:
- print a
-\end{verbatim}
-
-Here, you want to mark the strings in the \code{animals} list as being
-translatable, but you don't actually want to translate them until they
-are printed.
-
-Here is one way you can handle this situation:
-
-\begin{verbatim}
-def _(message): return message
-
-animals = [_('mollusk'),
- _('albatross'),
- _('rat'),
- _('penguin'),
- _('python'),
- ]
-
-del _
-
-# ...
-for a in animals:
- print _(a)
-\end{verbatim}
-
-This works because the dummy definition of \function{_()} simply returns
-the string unchanged. And this dummy definition will temporarily
-override any definition of \function{_()} in the built-in namespace
-(until the \keyword{del} command).
-Take care, though if you have a previous definition of \function{_} in
-the local namespace.
-
-Note that the second use of \function{_()} will not identify ``a'' as
-being translatable to the \program{pygettext} program, since it is not
-a string.
-
-Another way to handle this is with the following example:
-
-\begin{verbatim}
-def N_(message): return message
-
-animals = [N_('mollusk'),
- N_('albatross'),
- N_('rat'),
- N_('penguin'),
- N_('python'),
- ]
-
-# ...
-for a in animals:
- print _(a)
-\end{verbatim}
-
-In this case, you are marking translatable strings with the function
-\function{N_()},\footnote{The choice of \function{N_()} here is totally
-arbitrary; it could have just as easily been
-\function{MarkThisStringForTranslation()}.
-} which won't conflict with any definition of
-\function{_()}. However, you will need to teach your message extraction
-program to look for translatable strings marked with \function{N_()}.
-\program{pygettext} and \program{xpot} both support this through the
-use of command line switches.
-
-\subsubsection{\function{gettext()} vs. \function{lgettext()}}
-In Python 2.4 the \function{lgettext()} family of functions were
-introduced. The intention of these functions is to provide an
-alternative which is more compliant with the current
-implementation of GNU gettext. Unlike \function{gettext()}, which
-returns strings encoded with the same codeset used in the
-translation file, \function{lgettext()} will return strings
-encoded with the preferred system encoding, as returned by
-\function{locale.getpreferredencoding()}. Also notice that
-Python 2.4 introduces new functions to explicitly choose
-the codeset used in translated strings. If a codeset is explicitly
-set, even \function{lgettext()} will return translated strings in
-the requested codeset, as would be expected in the GNU gettext
-implementation.
-
-\subsection{Acknowledgements}
-
-The following people contributed code, feedback, design suggestions,
-previous implementations, and valuable experience to the creation of
-this module:
-
-\begin{itemize}
- \item Peter Funk
- \item James Henstridge
- \item Juan David Ib\'a\~nez Palomar
- \item Marc-Andr\'e Lemburg
- \item Martin von L\"owis
- \item Fran\c cois Pinard
- \item Barry Warsaw
- \item Gustavo Niemeyer
-\end{itemize}
diff --git a/Doc/lib/libglob.tex b/Doc/lib/libglob.tex
deleted file mode 100644
index f3f4fb7..0000000
--- a/Doc/lib/libglob.tex
+++ /dev/null
@@ -1,51 +0,0 @@
-\section{\module{glob} ---
- \UNIX{} style pathname pattern expansion}
-
-\declaremodule{standard}{glob}
-\modulesynopsis{\UNIX\ shell style pathname pattern expansion.}
-
-
-The \module{glob} module finds all the pathnames matching a specified
-pattern according to the rules used by the \UNIX{} shell. No tilde
-expansion is done, but \code{*}, \code{?}, and character ranges
-expressed with \code{[]} will be correctly matched. This is done by
-using the \function{os.listdir()} and \function{fnmatch.fnmatch()}
-functions in concert, and not by actually invoking a subshell. (For
-tilde and shell variable expansion, use \function{os.path.expanduser()}
-and \function{os.path.expandvars()}.)
-\index{filenames!pathname expansion}
-
-\begin{funcdesc}{glob}{pathname}
-Return a possibly-empty list of path names that match \var{pathname},
-which must be a string containing a path specification.
-\var{pathname} can be either absolute (like
-\file{/usr/src/Python-1.5/Makefile}) or relative (like
-\file{../../Tools/*/*.gif}), and can contain shell-style wildcards.
-Broken symlinks are included in the results (as in the shell).
-\end{funcdesc}
-
-\begin{funcdesc}{iglob}{pathname}
-Return an iterator which yields the same values as \function{glob()}
-without actually storing them all simultaneously.
-\versionadded{2.5}
-\end{funcdesc}
-
-For example, consider a directory containing only the following files:
-\file{1.gif}, \file{2.txt}, and \file{card.gif}. \function{glob()}
-will produce the following results. Notice how any leading components
-of the path are preserved.
-
-\begin{verbatim}
->>> import glob
->>> glob.glob('./[0-9].*')
-['./1.gif', './2.txt']
->>> glob.glob('*.gif')
-['1.gif', 'card.gif']
->>> glob.glob('?.gif')
-['1.gif']
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule{fnmatch}{Shell-style filename (not path) expansion}
-\end{seealso}
diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex
deleted file mode 100644
index 3eed7d0..0000000
--- a/Doc/lib/libgrp.tex
+++ /dev/null
@@ -1,49 +0,0 @@
-\section{\module{grp} ---
- The group database}
-
-\declaremodule{builtin}{grp}
- \platform{Unix}
-\modulesynopsis{The group database (\function{getgrnam()} and friends).}
-
-
-This module provides access to the \UNIX{} group database.
-It is available on all \UNIX{} versions.
-
-Group database entries are reported as a tuple-like object, whose
-attributes correspond to the members of the \code{group} structure
-(Attribute field below, see \code{<pwd.h>}):
-
-\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
- \lineiii{0}{gr_name}{the name of the group}
- \lineiii{1}{gr_passwd}{the (encrypted) group password; often empty}
- \lineiii{2}{gr_gid}{the numerical group ID}
- \lineiii{3}{gr_mem}{all the group member's user names}
-\end{tableiii}
-
-The gid is an integer, name and password are strings, and the member
-list is a list of strings.
-(Note that most users are not explicitly listed as members of the
-group they are in according to the password database. Check both
-databases to get complete membership information.)
-
-It defines the following items:
-
-\begin{funcdesc}{getgrgid}{gid}
-Return the group database entry for the given numeric group ID.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getgrnam}{name}
-Return the group database entry for the given group name.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-\end{funcdesc}
-
-\begin{funcdesc}{getgrall}{}
-Return a list of all available group entries, in arbitrary order.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{pwd}{An interface to the user database, similar to this.}
- \seemodule{spwd}{An interface to the shadow password database, similar to this.}
-\end{seealso}
diff --git a/Doc/lib/libgzip.tex b/Doc/lib/libgzip.tex
deleted file mode 100644
index b4cc659..0000000
--- a/Doc/lib/libgzip.tex
+++ /dev/null
@@ -1,70 +0,0 @@
-\section{\module{gzip} ---
- Support for \program{gzip} files}
-
-\declaremodule{standard}{gzip}
-\modulesynopsis{Interfaces for \program{gzip} compression and
-decompression using file objects.}
-
-
-The data compression provided by the \code{zlib} module is compatible
-with that used by the GNU compression program \program{gzip}.
-Accordingly, the \module{gzip} module provides the \class{GzipFile}
-class to read and write \program{gzip}-format files, automatically
-compressing or decompressing the data so it looks like an ordinary
-file object. Note that additional file formats which can be
-decompressed by the \program{gzip} and \program{gunzip} programs, such
-as those produced by \program{compress} and \program{pack}, are not
-supported by this module.
-
-The module defines the following items:
-
-\begin{classdesc}{GzipFile}{\optional{filename\optional{, mode\optional{,
- compresslevel\optional{, fileobj}}}}}
-Constructor for the \class{GzipFile} class, which simulates most of
-the methods of a file object, with the exception of the \method{readinto()}
-and \method{truncate()} methods. At least one of
-\var{fileobj} and \var{filename} must be given a non-trivial value.
-
-The new class instance is based on \var{fileobj}, which can be a
-regular file, a \class{StringIO} object, or any other object which
-simulates a file. It defaults to \code{None}, in which case
-\var{filename} is opened to provide a file object.
-
-When \var{fileobj} is not \code{None}, the \var{filename} argument is
-only used to be included in the \program{gzip} file header, which may
-includes the original filename of the uncompressed file. It defaults
-to the filename of \var{fileobj}, if discernible; otherwise, it
-defaults to the empty string, and in this case the original filename
-is not included in the header.
-
-The \var{mode} argument can be any of \code{'r'}, \code{'rb'},
-\code{'a'}, \code{'ab'}, \code{'w'}, or \code{'wb'}, depending on
-whether the file will be read or written. The default is the mode of
-\var{fileobj} if discernible; otherwise, the default is \code{'rb'}.
-If not given, the 'b' flag will be added to the mode to ensure the
-file is opened in binary mode for cross-platform portability.
-
-The \var{compresslevel} argument is an integer from \code{1} to
-\code{9} controlling the level of compression; \code{1} is fastest and
-produces the least compression, and \code{9} is slowest and produces
-the most compression. The default is \code{9}.
-
-Calling a \class{GzipFile} object's \method{close()} method does not
-close \var{fileobj}, since you might wish to append more material
-after the compressed data. This also allows you to pass a
-\class{StringIO} object opened for writing as \var{fileobj}, and
-retrieve the resulting memory buffer using the \class{StringIO}
-object's \method{getvalue()} method.
-\end{classdesc}
-
-\begin{funcdesc}{open}{filename\optional{, mode\optional{, compresslevel}}}
-This is a shorthand for \code{GzipFile(\var{filename},}
-\code{\var{mode},} \code{\var{compresslevel})}. The \var{filename}
-argument is required; \var{mode} defaults to \code{'rb'} and
-\var{compresslevel} defaults to \code{9}.
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{zlib}{The basic data compression module needed to support
- the \program{gzip} file format.}
-\end{seealso}
diff --git a/Doc/lib/libhashlib.tex b/Doc/lib/libhashlib.tex
deleted file mode 100644
index 17f5179..0000000
--- a/Doc/lib/libhashlib.tex
+++ /dev/null
@@ -1,114 +0,0 @@
-\section{\module{hashlib} ---
- Secure hashes and message digests}
-
-\declaremodule{builtin}{hashlib}
-\modulesynopsis{Secure hash and message digest algorithms.}
-\moduleauthor{Gregory P. Smith}{greg@users.sourceforge.net}
-\sectionauthor{Gregory P. Smith}{greg@users.sourceforge.net}
-
-\versionadded{2.5}
-
-\index{message digest, MD5}
-\index{secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512}
-
-This module implements a common interface to many different secure hash and
-message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
-SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
-algorithm (defined in Internet \rfc{1321}).
-The terms secure hash and message digest are interchangeable. Older
-algorithms were called message digests. The modern term is secure hash.
-
-\warning{Some algorithms have known hash collision weaknesses, see the FAQ at the end.}
-
-There is one constructor method named for each type of \dfn{hash}. All return
-a hash object with the same simple interface.
-For example: use \function{sha1()} to create a SHA1 hash object.
-You can now feed this object with arbitrary strings using the \method{update()}
-method. At any point you can ask it for the \dfn{digest} of the concatenation
-of the strings fed to it so far using the \method{digest()} or
-\method{hexdigest()} methods.
-
-Constructors for hash algorithms that are always present in this module are
-\function{md5()}, \function{sha1()}, \function{sha224()}, \function{sha256()},
-\function{sha384()}, and \function{sha512()}. Additional algorithms may also
-be available depending upon the OpenSSL library that Python uses on your platform.
-\index{OpenSSL}
-
-For example, to obtain the digest of the string \code{'Nobody inspects
-the spammish repetition'}:
-
-\begin{verbatim}
->>> import hashlib
->>> m = hashlib.md5()
->>> m.update("Nobody inspects")
->>> m.update(" the spammish repetition")
->>> m.digest()
-'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
-\end{verbatim}
-
-More condensed:
-
-\begin{verbatim}
->>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
-'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
-\end{verbatim}
-
-A generic \function{new()} constructor that takes the string name of the
-desired algorithm as its first parameter also exists to allow access to the
-above listed hashes as well as any other algorithms that your OpenSSL library
-may offer. The named constructors are much faster than \function{new()} and
-should be preferred.
-
-Using \function{new()} with an algorithm provided by OpenSSL:
-
-\begin{verbatim}
->>> h = hashlib.new('ripemd160')
->>> h.update("Nobody inspects the spammish repetition")
->>> h.hexdigest()
-'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
-\end{verbatim}
-
-The following values are provided as constant attributes of the hash objects
-returned by the constructors:
-
-\begin{datadesc}{digest_size}
- The size of the resulting digest in bytes.
-\end{datadesc}
-
-A hash object has the following methods:
-
-\begin{methoddesc}[hash]{update}{arg}
-Update the hash object with the string \var{arg}. Repeated calls are
-equivalent to a single call with the concatenation of all the
-arguments: \code{m.update(a); m.update(b)} is equivalent to
-\code{m.update(a+b)}.
-\end{methoddesc}
-
-\begin{methoddesc}[hash]{digest}{}
-Return the digest of the strings passed to the \method{update()}
-method so far. This is a string of \member{digest_size} bytes which may
-contain non-\ASCII{} characters, including null bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[hash]{hexdigest}{}
-Like \method{digest()} except the digest is returned as a string of
-double length, containing only hexadecimal digits. This may
-be used to exchange the value safely in email or other non-binary
-environments.
-\end{methoddesc}
-
-\begin{methoddesc}[hash]{copy}{}
-Return a copy (``clone'') of the hash object. This can be used to
-efficiently compute the digests of strings that share a common initial
-substring.
-\end{methoddesc}
-
-\begin{seealso}
- \seemodule{hmac}{A module to generate message authentication codes using hashes.}
- \seemodule{base64}{Another way to encode binary hashes for non-binary environments.}
- \seeurl{http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}
- {The FIPS 180-2 publication on Secure Hash Algorithms.}
- \seeurl{http://www.cryptography.com/cnews/hash.html}
- {Hash Collision FAQ with information on which algorithms have known issues and
- what that means regarding their use.}
-\end{seealso}
diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex
deleted file mode 100644
index e403a3a..0000000
--- a/Doc/lib/libheapq.tex
+++ /dev/null
@@ -1,225 +0,0 @@
-\section{\module{heapq} ---
- Heap queue algorithm}
-
-\declaremodule{standard}{heapq}
-\modulesynopsis{Heap queue algorithm (a.k.a. priority queue).}
-\moduleauthor{Kevin O'Connor}{}
-\sectionauthor{Guido van Rossum}{guido@python.org}
-% Theoretical explanation:
-\sectionauthor{Fran\c cois Pinard}{}
-\versionadded{2.3}
-
-
-This module provides an implementation of the heap queue algorithm,
-also known as the priority queue algorithm.
-
-Heaps are arrays for which
-\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+1]} and
-\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+2]}
-for all \var{k}, counting elements from zero. For the sake of
-comparison, non-existing elements are considered to be infinite. The
-interesting property of a heap is that \code{\var{heap}[0]} is always
-its smallest element.
-
-The API below differs from textbook heap algorithms in two aspects:
-(a) We use zero-based indexing. This makes the relationship between the
-index for a node and the indexes for its children slightly less
-obvious, but is more suitable since Python uses zero-based indexing.
-(b) Our pop method returns the smallest item, not the largest (called a
-"min heap" in textbooks; a "max heap" is more common in texts because
-of its suitability for in-place sorting).
-
-These two make it possible to view the heap as a regular Python list
-without surprises: \code{\var{heap}[0]} is the smallest item, and
-\code{\var{heap}.sort()} maintains the heap invariant!
-
-To create a heap, use a list initialized to \code{[]}, or you can
-transform a populated list into a heap via function \function{heapify()}.
-
-The following functions are provided:
-
-\begin{funcdesc}{heappush}{heap, item}
-Push the value \var{item} onto the \var{heap}, maintaining the
-heap invariant.
-\end{funcdesc}
-
-\begin{funcdesc}{heappop}{heap}
-Pop and return the smallest item from the \var{heap}, maintaining the
-heap invariant. If the heap is empty, \exception{IndexError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{heapify}{x}
-Transform list \var{x} into a heap, in-place, in linear time.
-\end{funcdesc}
-
-\begin{funcdesc}{heapreplace}{heap, item}
-Pop and return the smallest item from the \var{heap}, and also push
-the new \var{item}. The heap size doesn't change.
-If the heap is empty, \exception{IndexError} is raised.
-This is more efficient than \function{heappop()} followed
-by \function{heappush()}, and can be more appropriate when using
-a fixed-size heap. Note that the value returned may be larger
-than \var{item}! That constrains reasonable uses of this routine
-unless written as part of a conditional replacement:
-\begin{verbatim}
- if item > heap[0]:
- item = heapreplace(heap, item)
-\end{verbatim}
-\end{funcdesc}
-
-Example of use:
-
-\begin{verbatim}
->>> from heapq import heappush, heappop
->>> heap = []
->>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
->>> for item in data:
-... heappush(heap, item)
-...
->>> ordered = []
->>> while heap:
-... ordered.append(heappop(heap))
-...
->>> print ordered
-[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
->>> data.sort()
->>> print data == ordered
-True
->>>
-\end{verbatim}
-
-The module also offers three general purpose functions based on heaps.
-
-\begin{funcdesc}{merge}{*iterables}
-Merge multiple sorted inputs into a single sorted output (for example, merge
-timestamped entries from multiple log files). Returns an iterator over
-over the sorted values.
-
-Similar to \code{sorted(itertools.chain(*iterables))} but returns an iterable,
-does not pull the data into memory all at once, and assumes that each of the
-input streams is already sorted (smallest to largest).
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{nlargest}{n, iterable\optional{, key}}
-Return a list with the \var{n} largest elements from the dataset defined
-by \var{iterable}. \var{key}, if provided, specifies a function of one
-argument that is used to extract a comparison key from each element
-in the iterable: \samp{\var{key}=\function{str.lower}}
-Equivalent to: \samp{sorted(iterable, key=key, reverse=True)[:n]}
-\versionadded{2.4}
-\versionchanged[Added the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{nsmallest}{n, iterable\optional{, key}}
-Return a list with the \var{n} smallest elements from the dataset defined
-by \var{iterable}. \var{key}, if provided, specifies a function of one
-argument that is used to extract a comparison key from each element
-in the iterable: \samp{\var{key}=\function{str.lower}}
-Equivalent to: \samp{sorted(iterable, key=key)[:n]}
-\versionadded{2.4}
-\versionchanged[Added the optional \var{key} argument]{2.5}
-\end{funcdesc}
-
-The latter two functions perform best for smaller values of \var{n}. For larger
-values, it is more efficient to use the \function{sorted()} function. Also,
-when \code{n==1}, it is more efficient to use the builtin \function{min()}
-and \function{max()} functions.
-
-
-\subsection{Theory}
-
-(This explanation is due to François Pinard. The Python
-code for this module was contributed by Kevin O'Connor.)
-
-Heaps are arrays for which \code{a[\var{k}] <= a[2*\var{k}+1]} and
-\code{a[\var{k}] <= a[2*\var{k}+2]}
-for all \var{k}, counting elements from 0. For the sake of comparison,
-non-existing elements are considered to be infinite. The interesting
-property of a heap is that \code{a[0]} is always its smallest element.
-
-The strange invariant above is meant to be an efficient memory
-representation for a tournament. The numbers below are \var{k}, not
-\code{a[\var{k}]}:
-
-\begin{verbatim}
- 0
-
- 1 2
-
- 3 4 5 6
-
- 7 8 9 10 11 12 13 14
-
- 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
-\end{verbatim}
-
-In the tree above, each cell \var{k} is topping \code{2*\var{k}+1} and
-\code{2*\var{k}+2}.
-In an usual binary tournament we see in sports, each cell is the winner
-over the two cells it tops, and we can trace the winner down the tree
-to see all opponents s/he had. However, in many computer applications
-of such tournaments, we do not need to trace the history of a winner.
-To be more memory efficient, when a winner is promoted, we try to
-replace it by something else at a lower level, and the rule becomes
-that a cell and the two cells it tops contain three different items,
-but the top cell "wins" over the two topped cells.
-
-If this heap invariant is protected at all time, index 0 is clearly
-the overall winner. The simplest algorithmic way to remove it and
-find the "next" winner is to move some loser (let's say cell 30 in the
-diagram above) into the 0 position, and then percolate this new 0 down
-the tree, exchanging values, until the invariant is re-established.
-This is clearly logarithmic on the total number of items in the tree.
-By iterating over all items, you get an O(n log n) sort.
-
-A nice feature of this sort is that you can efficiently insert new
-items while the sort is going on, provided that the inserted items are
-not "better" than the last 0'th element you extracted. This is
-especially useful in simulation contexts, where the tree holds all
-incoming events, and the "win" condition means the smallest scheduled
-time. When an event schedule other events for execution, they are
-scheduled into the future, so they can easily go into the heap. So, a
-heap is a good structure for implementing schedulers (this is what I
-used for my MIDI sequencer :-).
-
-Various structures for implementing schedulers have been extensively
-studied, and heaps are good for this, as they are reasonably speedy,
-the speed is almost constant, and the worst case is not much different
-than the average case. However, there are other representations which
-are more efficient overall, yet the worst cases might be terrible.
-
-Heaps are also very useful in big disk sorts. You most probably all
-know that a big sort implies producing "runs" (which are pre-sorted
-sequences, which size is usually related to the amount of CPU memory),
-followed by a merging passes for these runs, which merging is often
-very cleverly organised\footnote{The disk balancing algorithms which
-are current, nowadays, are
-more annoying than clever, and this is a consequence of the seeking
-capabilities of the disks. On devices which cannot seek, like big
-tape drives, the story was quite different, and one had to be very
-clever to ensure (far in advance) that each tape movement will be the
-most effective possible (that is, will best participate at
-"progressing" the merge). Some tapes were even able to read
-backwards, and this was also used to avoid the rewinding time.
-Believe me, real good tape sorts were quite spectacular to watch!
-From all times, sorting has always been a Great Art! :-)}.
-It is very important that the initial
-sort produces the longest runs possible. Tournaments are a good way
-to that. If, using all the memory available to hold a tournament, you
-replace and percolate items that happen to fit the current run, you'll
-produce runs which are twice the size of the memory for random input,
-and much better for input fuzzily ordered.
-
-Moreover, if you output the 0'th item on disk and get an input which
-may not fit in the current tournament (because the value "wins" over
-the last output value), it cannot fit in the heap, so the size of the
-heap decreases. The freed memory could be cleverly reused immediately
-for progressively building a second heap, which grows at exactly the
-same rate the first heap is melting. When the first heap completely
-vanishes, you switch heaps and start a new run. Clever and quite
-effective!
-
-In a word, heaps are useful memory structures to know. I use them in
-a few applications, and I think it is good to keep a `heap' module
-around. :-)
diff --git a/Doc/lib/libhmac.tex b/Doc/lib/libhmac.tex
deleted file mode 100644
index 5329cb5..0000000
--- a/Doc/lib/libhmac.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\section{\module{hmac} ---
- Keyed-Hashing for Message Authentication}
-
-\declaremodule{standard}{hmac}
-\modulesynopsis{Keyed-Hashing for Message Authentication (HMAC)
- implementation for Python.}
-\moduleauthor{Gerhard H{\"a}ring}{ghaering@users.sourceforge.net}
-\sectionauthor{Gerhard H{\"a}ring}{ghaering@users.sourceforge.net}
-
-\versionadded{2.2}
-
-This module implements the HMAC algorithm as described by \rfc{2104}.
-
-\begin{funcdesc}{new}{key\optional{, msg\optional{, digestmod}}}
- Return a new hmac object. If \var{msg} is present, the method call
- \code{update(\var{msg})} is made. \var{digestmod} is the digest
- constructor or module for the HMAC object to use. It defaults to
- the \function{\refmodule{hashlib}.md5} constructor. \note{The md5 hash
- has known weaknesses but remains the default for backwards compatibility.
- Choose a better one for your application.}
-\end{funcdesc}
-
-An HMAC object has the following methods:
-
-\begin{methoddesc}[hmac]{update}{msg}
- Update the hmac object with the string \var{msg}. Repeated calls
- are equivalent to a single call with the concatenation of all the
- arguments: \code{m.update(a); m.update(b)} is equivalent to
- \code{m.update(a + b)}.
-\end{methoddesc}
-
-\begin{methoddesc}[hmac]{digest}{}
- Return the digest of the strings passed to the \method{update()}
- method so far. This string will be the same length as the
- \var{digest_size} of the digest given to the constructor. It
- may contain non-\ASCII{} characters, including NUL bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[hmac]{hexdigest}{}
- Like \method{digest()} except the digest is returned as a string
- twice the length containing
- only hexadecimal digits. This may be used to exchange the value
- safely in email or other non-binary environments.
-\end{methoddesc}
-
-\begin{methoddesc}[hmac]{copy}{}
- Return a copy (``clone'') of the hmac object. This can be used to
- efficiently compute the digests of strings that share a common
- initial substring.
-\end{methoddesc}
-
-\begin{seealso}
- \seemodule{hashlib}{The python module providing secure hash functions.}
-\end{seealso}
diff --git a/Doc/lib/libhotshot.tex b/Doc/lib/libhotshot.tex
deleted file mode 100644
index 0004e37..0000000
--- a/Doc/lib/libhotshot.tex
+++ /dev/null
@@ -1,137 +0,0 @@
-\section{\module{hotshot} ---
- High performance logging profiler}
-
-\declaremodule{standard}{hotshot}
-\modulesynopsis{High performance logging profiler, mostly written in C.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Anthony Baxter}{anthony@interlink.com.au}
-
-\versionadded{2.2}
-
-
-This module provides a nicer interface to the \module{_hotshot} C module.
-Hotshot is a replacement for the existing \refmodule{profile} module. As it's
-written mostly in C, it should result in a much smaller performance impact
-than the existing \refmodule{profile} module.
-
-\begin{notice}[note]
- The \module{hotshot} module focuses on minimizing the overhead
- while profiling, at the expense of long data post-processing times.
- For common usages it is recommended to use \module{cProfile} instead.
- \module{hotshot} is not maintained and might be removed from the
- standard library in the future.
-\end{notice}
-
-\versionchanged[the results should be more meaningful than in the
-past: the timing core contained a critical bug]{2.5}
-
-\begin{notice}[warning]
- The \module{hotshot} profiler does not yet work well with threads.
- It is useful to use an unthreaded script to run the profiler over
- the code you're interested in measuring if at all possible.
-\end{notice}
-
-
-\begin{classdesc}{Profile}{logfile\optional{, lineevents\optional{,
- linetimings}}}
-The profiler object. The argument \var{logfile} is the name of a log
-file to use for logged profile data. The argument \var{lineevents}
-specifies whether to generate events for every source line, or just on
-function call/return. It defaults to \code{0} (only log function
-call/return). The argument \var{linetimings} specifies whether to
-record timing information. It defaults to \code{1} (store timing
-information).
-\end{classdesc}
-
-
-\subsection{Profile Objects \label{hotshot-objects}}
-
-Profile objects have the following methods:
-
-\begin{methoddesc}[Profile]{addinfo}{key, value}
-Add an arbitrary labelled value to the profile output.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{close}{}
-Close the logfile and terminate the profiler.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{fileno}{}
-Return the file descriptor of the profiler's log file.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{run}{cmd}
-Profile an \function{exec()}-compatible string in the script environment.
-The globals from the \refmodule[main]{__main__} module are used as
-both the globals and locals for the script.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{runcall}{func, *args, **keywords}
-Profile a single call of a callable.
-Additional positional and keyword arguments may be passed
-along; the result of the call is returned, and exceptions are
-allowed to propagate cleanly, while ensuring that profiling is
-disabled on the way out.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Profile]{runctx}{cmd, globals, locals}
-Profile an \function{exec()}-compatible string in a specific environment.
-The string is compiled before profiling begins.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{start}{}
-Start the profiler.
-\end{methoddesc}
-
-\begin{methoddesc}[Profile]{stop}{}
-Stop the profiler.
-\end{methoddesc}
-
-
-\subsection{Using hotshot data}
-
-\declaremodule{standard}{hotshot.stats}
-\modulesynopsis{Statistical analysis for Hotshot}
-
-\versionadded{2.2}
-
-This module loads hotshot profiling data into the standard \module{pstats}
-Stats objects.
-
-\begin{funcdesc}{load}{filename}
-Load hotshot data from \var{filename}. Returns an instance
-of the \class{pstats.Stats} class.
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{profile}{The \module{profile} module's \class{Stats} class}
-\end{seealso}
-
-
-\subsection{Example Usage \label{hotshot-example}}
-
-Note that this example runs the python ``benchmark'' pystones. It can
-take some time to run, and will produce large output files.
-
-\begin{verbatim}
->>> import hotshot, hotshot.stats, test.pystone
->>> prof = hotshot.Profile("stones.prof")
->>> benchtime, stones = prof.runcall(test.pystone.pystones)
->>> prof.close()
->>> stats = hotshot.stats.load("stones.prof")
->>> stats.strip_dirs()
->>> stats.sort_stats('time', 'calls')
->>> stats.print_stats(20)
- 850004 function calls in 10.090 CPU seconds
-
- Ordered by: internal time, call count
-
- ncalls tottime percall cumtime percall filename:lineno(function)
- 1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0)
- 150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7)
- 50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2)
- .
- .
- .
-\end{verbatim}
diff --git a/Doc/lib/libhtmllib.tex b/Doc/lib/libhtmllib.tex
deleted file mode 100644
index e51dfcb..0000000
--- a/Doc/lib/libhtmllib.tex
+++ /dev/null
@@ -1,181 +0,0 @@
-\section{\module{htmllib} ---
- A parser for HTML documents}
-
-\declaremodule{standard}{htmllib}
-\modulesynopsis{A parser for HTML documents.}
-
-\index{HTML}
-\index{hypertext}
-
-
-This module defines a class which can serve as a base for parsing text
-files formatted in the HyperText Mark-up Language (HTML). The class
-is not directly concerned with I/O --- it must be provided with input
-in string form via a method, and makes calls to methods of a
-``formatter'' object in order to produce output. The
-\class{HTMLParser} class is designed to be used as a base class for
-other classes in order to add functionality, and allows most of its
-methods to be extended or overridden. In turn, this class is derived
-from and extends the \class{SGMLParser} class defined in module
-\refmodule{sgmllib}\refstmodindex{sgmllib}. The \class{HTMLParser}
-implementation supports the HTML 2.0 language as described in
-\rfc{1866}. Two implementations of formatter objects are provided in
-the \refmodule{formatter}\refstmodindex{formatter}\ module; refer to the
-documentation for that module for information on the formatter
-interface.
-\withsubitem{(in module sgmllib)}{\ttindex{SGMLParser}}
-
-The following is a summary of the interface defined by
-\class{sgmllib.SGMLParser}:
-
-\begin{itemize}
-
-\item
-The interface to feed data to an instance is through the \method{feed()}
-method, which takes a string argument. This can be called with as
-little or as much text at a time as desired; \samp{p.feed(a);
-p.feed(b)} has the same effect as \samp{p.feed(a+b)}. When the data
-contains complete HTML markup constructs, these are processed immediately;
-incomplete constructs are saved in a buffer. To force processing of all
-unprocessed data, call the \method{close()} method.
-
-For example, to parse the entire contents of a file, use:
-\begin{verbatim}
-parser.feed(open('myfile.html').read())
-parser.close()
-\end{verbatim}
-
-\item
-The interface to define semantics for HTML tags is very simple: derive
-a class and define methods called \method{start_\var{tag}()},
-\method{end_\var{tag}()}, or \method{do_\var{tag}()}. The parser will
-call these at appropriate moments: \method{start_\var{tag}} or
-\method{do_\var{tag}()} is called when an opening tag of the form
-\code{<\var{tag} ...>} is encountered; \method{end_\var{tag}()} is called
-when a closing tag of the form \code{<\var{tag}>} is encountered. If
-an opening tag requires a corresponding closing tag, like \code{<H1>}
-... \code{</H1>}, the class should define the \method{start_\var{tag}()}
-method; if a tag requires no closing tag, like \code{<P>}, the class
-should define the \method{do_\var{tag}()} method.
-
-\end{itemize}
-
-The module defines a parser class and an exception:
-
-\begin{classdesc}{HTMLParser}{formatter}
-This is the basic HTML parser class. It supports all entity names
-required by the XHTML 1.0 Recommendation (\url{http://www.w3.org/TR/xhtml1}).
-It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
-\end{classdesc}
-
-\begin{excdesc}{HTMLParseError}
-Exception raised by the \class{HTMLParser} class when it encounters an
-error while parsing.
-\versionadded{2.4}
-\end{excdesc}
-
-
-\begin{seealso}
- \seemodule{formatter}{Interface definition for transforming an
- abstract flow of formatting events into
- specific output events on writer objects.}
- \seemodule{HTMLParser}{Alternate HTML parser that offers a slightly
- lower-level view of the input, but is
- designed to work with XHTML, and does not
- implement some of the SGML syntax not used in
- ``HTML as deployed'' and which isn't legal
- for XHTML.}
- \seemodule{htmlentitydefs}{Definition of replacement text for XHTML 1.0
- entities.}
- \seemodule{sgmllib}{Base class for \class{HTMLParser}.}
-\end{seealso}
-
-
-\subsection{HTMLParser Objects \label{html-parser-objects}}
-
-In addition to tag methods, the \class{HTMLParser} class provides some
-additional methods and instance variables for use within tag methods.
-
-\begin{memberdesc}[HTMLParser]{formatter}
-This is the formatter instance associated with the parser.
-\end{memberdesc}
-
-\begin{memberdesc}[HTMLParser]{nofill}
-Boolean flag which should be true when whitespace should not be
-collapsed, or false when it should be. In general, this should only
-be true when character data is to be treated as ``preformatted'' text,
-as within a \code{<PRE>} element. The default value is false. This
-affects the operation of \method{handle_data()} and \method{save_end()}.
-\end{memberdesc}
-
-
-\begin{methoddesc}[HTMLParser]{anchor_bgn}{href, name, type}
-This method is called at the start of an anchor region. The arguments
-correspond to the attributes of the \code{<A>} tag with the same
-names. The default implementation maintains a list of hyperlinks
-(defined by the \code{HREF} attribute for \code{<A>} tags) within the
-document. The list of hyperlinks is available as the data attribute
-\member{anchorlist}.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{anchor_end}{}
-This method is called at the end of an anchor region. The default
-implementation adds a textual footnote marker using an index into the
-list of hyperlinks created by \method{anchor_bgn()}.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{handle_image}{source, alt\optional{, ismap\optional{,
- align\optional{, width\optional{, height}}}}}
-This method is called to handle images. The default implementation
-simply passes the \var{alt} value to the \method{handle_data()}
-method.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{save_bgn}{}
-Begins saving character data in a buffer instead of sending it to the
-formatter object. Retrieve the stored data via \method{save_end()}.
-Use of the \method{save_bgn()} / \method{save_end()} pair may not be
-nested.
-\end{methoddesc}
-
-\begin{methoddesc}[HTMLParser]{save_end}{}
-Ends buffering character data and returns all data saved since the
-preceding call to \method{save_bgn()}. If the \member{nofill} flag is
-false, whitespace is collapsed to single spaces. A call to this
-method without a preceding call to \method{save_bgn()} will raise a
-\exception{TypeError} exception.
-\end{methoddesc}
-
-
-
-\section{\module{htmlentitydefs} ---
- Definitions of HTML general entities}
-
-\declaremodule{standard}{htmlentitydefs}
-\modulesynopsis{Definitions of HTML general entities.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-This module defines three dictionaries, \code{name2codepoint},
-\code{codepoint2name}, and \code{entitydefs}. \code{entitydefs} is
-used by the \refmodule{htmllib} module to provide the
-\member{entitydefs} member of the \class{HTMLParser} class. The
-definition provided here contains all the entities defined by XHTML 1.0
-that can be handled using simple textual substitution in the Latin-1
-character set (ISO-8859-1).
-
-
-\begin{datadesc}{entitydefs}
- A dictionary mapping XHTML 1.0 entity definitions to their
- replacement text in ISO Latin-1.
-
-\end{datadesc}
-
-\begin{datadesc}{name2codepoint}
- A dictionary that maps HTML entity names to the Unicode codepoints.
- \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{codepoint2name}
- A dictionary that maps Unicode codepoints to HTML entity names.
- \versionadded{2.3}
-\end{datadesc}
diff --git a/Doc/lib/libhtmlparser.tex b/Doc/lib/libhtmlparser.tex
deleted file mode 100644
index 5e99f27..0000000
--- a/Doc/lib/libhtmlparser.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{HTMLParser} ---
- Simple HTML and XHTML parser}
-
-\declaremodule{standard}{HTMLParser}
-\modulesynopsis{A simple parser that can handle HTML and XHTML.}
-
-\versionadded{2.2}
-
-This module defines a class \class{HTMLParser} which serves as the
-basis for parsing text files formatted in HTML\index{HTML} (HyperText
-Mark-up Language) and XHTML.\index{XHTML} Unlike the parser in
-\refmodule{htmllib}, this parser is not based on the SGML parser in
-\refmodule{sgmllib}.
-
-
-\begin{classdesc}{HTMLParser}{}
-The \class{HTMLParser} class is instantiated without arguments.
-
-An HTMLParser instance is fed HTML data and calls handler functions
-when tags begin and end. The \class{HTMLParser} class is meant to be
-overridden by the user to provide a desired behavior.
-
-Unlike the parser in \refmodule{htmllib}, this parser does not check
-that end tags match start tags or call the end-tag handler for
-elements which are closed implicitly by closing an outer element.
-\end{classdesc}
-
-An exception is defined as well:
-
-\begin{excdesc}{HTMLParseError}
-Exception raised by the \class{HTMLParser} class when it encounters an
-error while parsing. This exception provides three attributes:
-\member{msg} is a brief message explaining the error, \member{lineno}
-is the number of the line on which the broken construct was detected,
-and \member{offset} is the number of characters into the line at which
-the construct starts.
-\end{excdesc}
-
-
-\class{HTMLParser} instances have the following methods:
-
-\begin{methoddesc}{reset}{}
-Reset the instance. Loses all unprocessed data. This is called
-implicitly at instantiation time.
-\end{methoddesc}
-
-\begin{methoddesc}{feed}{data}
-Feed some text to the parser. It is processed insofar as it consists
-of complete elements; incomplete data is buffered until more data is
-fed or \method{close()} is called.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Force processing of all buffered data as if it were followed by an
-end-of-file mark. This method may be redefined by a derived class to
-define additional processing at the end of the input, but the
-redefined version should always call the \class{HTMLParser} base class
-method \method{close()}.
-\end{methoddesc}
-
-\begin{methoddesc}{getpos}{}
-Return current line number and offset.
-\end{methoddesc}
-
-\begin{methoddesc}{get_starttag_text}{}
-Return the text of the most recently opened start tag. This should
-not normally be needed for structured processing, but may be useful in
-dealing with HTML ``as deployed'' or for re-generating input with
-minimal changes (whitespace between attributes can be preserved,
-etc.).
-\end{methoddesc}
-
-\begin{methoddesc}{handle_starttag}{tag, attrs}
-This method is called to handle the start of a tag. It is intended to
-be overridden by a derived class; the base class implementation does
-nothing.
-
-The \var{tag} argument is the name of the tag converted to lower case.
-The \var{attrs} argument is a list of \code{(\var{name}, \var{value})}
-pairs containing the attributes found inside the tag's \code{<>}
-brackets. The \var{name} will be translated to lower case, and quotes
-in the \var{value} have been removed, and character and entity
-references have been replaced. For instance, for the tag \code{<A
- HREF="http://www.cwi.nl/">}, this method would be called as
-\samp{handle_starttag('a', [('href', 'http://www.cwi.nl/')])}.
-
-\versionchanged[All entity references from htmlentitydefs are now
-replaced in the attribute values]{2.6}
-
-\end{methoddesc}
-
-\begin{methoddesc}{handle_startendtag}{tag, attrs}
-Similar to \method{handle_starttag()}, but called when the parser
-encounters an XHTML-style empty tag (\code{<a .../>}). This method
-may be overridden by subclasses which require this particular lexical
-information; the default implementation simple calls
-\method{handle_starttag()} and \method{handle_endtag()}.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_endtag}{tag}
-This method is called to handle the end tag of an element. It is
-intended to be overridden by a derived class; the base class
-implementation does nothing. The \var{tag} argument is the name of
-the tag converted to lower case.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_data}{data}
-This method is called to process arbitrary data. It is intended to be
-overridden by a derived class; the base class implementation does
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_charref}{name} This method is called to
-process a character reference of the form \samp{\&\#\var{ref};}. It
-is intended to be overridden by a derived class; the base class
-implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_entityref}{name}
-This method is called to process a general entity reference of the
-form \samp{\&\var{name};} where \var{name} is an general entity
-reference. It is intended to be overridden by a derived class; the
-base class implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_comment}{data}
-This method is called when a comment is encountered. The
-\var{comment} argument is a string containing the text between the
-\samp{--} and \samp{--} delimiters, but not the delimiters
-themselves. For example, the comment \samp{<!--text-->} will
-cause this method to be called with the argument \code{'text'}. It is
-intended to be overridden by a derived class; the base class
-implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_decl}{decl}
-Method called when an SGML declaration is read by the parser. The
-\var{decl} parameter will be the entire contents of the declaration
-inside the \code{<!}...\code{>} markup. It is intended to be overridden
-by a derived class; the base class implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_pi}{data}
-Method called when a processing instruction is encountered. The
-\var{data} parameter will contain the entire processing instruction.
-For example, for the processing instruction \code{<?proc color='red'>},
-this method would be called as \code{handle_pi("proc color='red'")}. It
-is intended to be overridden by a derived class; the base class
-implementation does nothing.
-
-\note{The \class{HTMLParser} class uses the SGML syntactic rules for
-processing instructions. An XHTML processing instruction using the
-trailing \character{?} will cause the \character{?} to be included in
-\var{data}.}
-\end{methoddesc}
-
-
-\subsection{Example HTML Parser Application \label{htmlparser-example}}
-
-As a basic example, below is a very basic HTML parser that uses the
-\class{HTMLParser} class to print out tags as they are encountered:
-
-\begin{verbatim}
-from HTMLParser import HTMLParser
-
-class MyHTMLParser(HTMLParser):
-
- def handle_starttag(self, tag, attrs):
- print "Encountered the beginning of a %s tag" % tag
-
- def handle_endtag(self, tag):
- print "Encountered the end of a %s tag" % tag
-\end{verbatim}
diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex
deleted file mode 100644
index 37a442d..0000000
--- a/Doc/lib/libhttplib.tex
+++ /dev/null
@@ -1,452 +0,0 @@
-\section{\module{httplib} ---
- HTTP protocol client}
-
-\declaremodule{standard}{httplib}
-\modulesynopsis{HTTP and HTTPS protocol client (requires sockets).}
-
-\indexii{HTTP}{protocol}
-\index{HTTP!\module{httplib} (standard module)}
-
-This module defines classes which implement the client side of the
-HTTP and HTTPS protocols. It is normally not used directly --- the
-module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs
-that use HTTP and HTTPS.
-
-\begin{notice}
- HTTPS support is only available if the \refmodule{socket} module was
- compiled with SSL support.
-\end{notice}
-
-\begin{notice}
- The public interface for this module changed substantially in Python
- 2.0. The \class{HTTP} class is retained only for backward
- compatibility with 1.5.2. It should not be used in new code. Refer
- to the online docstrings for usage.
-\end{notice}
-
-The module provides the following classes:
-
-\begin{classdesc}{HTTPConnection}{host\optional{, port\optional{,
- strict\optional{, timeout}}}}
-An \class{HTTPConnection} instance represents one transaction with an HTTP
-server. It should be instantiated passing it a host and optional port number.
-If no port number is passed, the port is extracted from the host string if it
-has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is
-used. When True, the optional parameter \var{strict}
-causes \code{BadStatusLine} to be raised if the status line can't be parsed
-as a valid HTTP/1.0 or 1.1 status line. If the optional \var{timeout}
-parameter is given, connection attempts will timeout after that many
-seconds (if it is not given or \code{None}, the global default
-timeout setting is used).
-
-For example, the following calls all create instances that connect to
-the server at the same host and port:
-
-\begin{verbatim}
->>> h1 = httplib.HTTPConnection('www.cwi.nl')
->>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
->>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
->>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
-\end{verbatim}
-\versionadded{2.0}
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{HTTPSConnection}{host\optional{, port\optional{,
- key_file\optional{, cert_file\optional{,
- strict\optional{, timeout}}}}}}
-A subclass of \class{HTTPConnection} that uses SSL for communication with
-secure servers. Default port is \code{443}.
-\var{key_file} is
-the name of a PEM formatted file that contains your private
-key. \var{cert_file} is a PEM formatted certificate chain file.
-
-\warning{This does not do any certificate verification!}
-
-\versionadded{2.0}
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}}
-Class whose instances are returned upon successful connection. Not
-instantiated directly by user.
-\versionadded{2.0}
-\end{classdesc}
-
-The following exceptions are raised as appropriate:
-
-\begin{excdesc}{HTTPException}
-The base class of the other exceptions in this module. It is a
-subclass of \exception{Exception}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{NotConnected}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{InvalidURL}
-A subclass of \exception{HTTPException}, raised if a port is given and is
-either non-numeric or empty.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{excdesc}{UnknownProtocol}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnknownTransferEncoding}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{UnimplementedFileMode}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{IncompleteRead}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{ImproperConnectionState}
-A subclass of \exception{HTTPException}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{CannotSendRequest}
-A subclass of \exception{ImproperConnectionState}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{CannotSendHeader}
-A subclass of \exception{ImproperConnectionState}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{ResponseNotReady}
-A subclass of \exception{ImproperConnectionState}.
-\versionadded{2.0}
-\end{excdesc}
-
-\begin{excdesc}{BadStatusLine}
-A subclass of \exception{HTTPException}. Raised if a server responds with a
-HTTP status code that we don't understand.
-\versionadded{2.0}
-\end{excdesc}
-
-The constants defined in this module are:
-
-\begin{datadesc}{HTTP_PORT}
- The default port for the HTTP protocol (always \code{80}).
-\end{datadesc}
-
-\begin{datadesc}{HTTPS_PORT}
- The default port for the HTTPS protocol (always \code{443}).
-\end{datadesc}
-
-and also the following constants for integer status codes:
-
-\begin{tableiii}{l|c|l}{constant}{Constant}{Value}{Definition}
- \lineiii{CONTINUE}{\code{100}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.1.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1}}
- \lineiii{SWITCHING_PROTOCOLS}{\code{101}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.1.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2}}
- \lineiii{PROCESSING}{\code{102}}
- {WEBDAV, \ulink{RFC 2518, Section 10.1}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_102}}
-
- \lineiii{OK}{\code{200}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1}}
- \lineiii{CREATED}{\code{201}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2}}
- \lineiii{ACCEPTED}{\code{202}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3}}
- \lineiii{NON_AUTHORITATIVE_INFORMATION}{\code{203}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4}}
- \lineiii{NO_CONTENT}{\code{204}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5}}
- \lineiii{RESET_CONTENT}{\code{205}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6}}
- \lineiii{PARTIAL_CONTENT}{\code{206}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.2.7}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7}}
- \lineiii{MULTI_STATUS}{\code{207}}
- {WEBDAV \ulink{RFC 2518, Section 10.2}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_207}}
- \lineiii{IM_USED}{\code{226}}
- {Delta encoding in HTTP, \rfc{3229}, Section 10.4.1}
-
- \lineiii{MULTIPLE_CHOICES}{\code{300}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1}}
- \lineiii{MOVED_PERMANENTLY}{\code{301}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2}}
- \lineiii{FOUND}{\code{302}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3}}
- \lineiii{SEE_OTHER}{\code{303}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4}}
- \lineiii{NOT_MODIFIED}{\code{304}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5}}
- \lineiii{USE_PROXY}{\code{305}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6}}
- \lineiii{TEMPORARY_REDIRECT}{\code{307}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.3.8}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8}}
-
- \lineiii{BAD_REQUEST}{\code{400}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1}}
- \lineiii{UNAUTHORIZED}{\code{401}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2}}
- \lineiii{PAYMENT_REQUIRED}{\code{402}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3}}
- \lineiii{FORBIDDEN}{\code{403}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4}}
- \lineiii{NOT_FOUND}{\code{404}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5}}
- \lineiii{METHOD_NOT_ALLOWED}{\code{405}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6}}
- \lineiii{NOT_ACCEPTABLE}{\code{406}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.7}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7}}
- \lineiii{PROXY_AUTHENTICATION_REQUIRED}
- {\code{407}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.8}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8}}
- \lineiii{REQUEST_TIMEOUT}{\code{408}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.9}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9}}
- \lineiii{CONFLICT}{\code{409}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.10}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10}}
- \lineiii{GONE}{\code{410}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.11}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11}}
- \lineiii{LENGTH_REQUIRED}{\code{411}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.12}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12}}
- \lineiii{PRECONDITION_FAILED}{\code{412}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.13}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13}}
- \lineiii{REQUEST_ENTITY_TOO_LARGE}
- {\code{413}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.14}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14}}
- \lineiii{REQUEST_URI_TOO_LONG}{\code{414}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.15}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15}}
- \lineiii{UNSUPPORTED_MEDIA_TYPE}{\code{415}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.16}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16}}
- \lineiii{REQUESTED_RANGE_NOT_SATISFIABLE}{\code{416}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.17}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17}}
- \lineiii{EXPECTATION_FAILED}{\code{417}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.4.18}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18}}
- \lineiii{UNPROCESSABLE_ENTITY}{\code{422}}
- {WEBDAV, \ulink{RFC 2518, Section 10.3}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_422}}
- \lineiii{LOCKED}{\code{423}}
- {WEBDAV \ulink{RFC 2518, Section 10.4}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_423}}
- \lineiii{FAILED_DEPENDENCY}{\code{424}}
- {WEBDAV, \ulink{RFC 2518, Section 10.5}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_424}}
- \lineiii{UPGRADE_REQUIRED}{\code{426}}
- {HTTP Upgrade to TLS, \rfc{2817}, Section 6}
-
- \lineiii{INTERNAL_SERVER_ERROR}{\code{500}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.1}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1}}
- \lineiii{NOT_IMPLEMENTED}{\code{501}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.2}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2}}
- \lineiii{BAD_GATEWAY}{\code{502}}
- {HTTP/1.1 \ulink{RFC 2616, Section 10.5.3}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3}}
- \lineiii{SERVICE_UNAVAILABLE}{\code{503}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.4}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4}}
- \lineiii{GATEWAY_TIMEOUT}{\code{504}}
- {HTTP/1.1 \ulink{RFC 2616, Section 10.5.5}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5}}
- \lineiii{HTTP_VERSION_NOT_SUPPORTED}{\code{505}}
- {HTTP/1.1, \ulink{RFC 2616, Section 10.5.6}
- {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6}}
- \lineiii{INSUFFICIENT_STORAGE}{\code{507}}
- {WEBDAV, \ulink{RFC 2518, Section 10.6}
- {http://www.webdav.org/specs/rfc2518.html#STATUS_507}}
- \lineiii{NOT_EXTENDED}{\code{510}}
- {An HTTP Extension Framework, \rfc{2774}, Section 7}
-\end{tableiii}
-
-\begin{datadesc}{responses}
-This dictionary maps the HTTP 1.1 status codes to the W3C names.
-
-Example: \code{httplib.responses[httplib.NOT_FOUND]} is \code{'Not Found'}.
-\versionadded{2.5}
-\end{datadesc}
-
-
-\subsection{HTTPConnection Objects \label{httpconnection-objects}}
-
-\class{HTTPConnection} instances have the following methods:
-
-\begin{methoddesc}[HTTPConnection]{request}{method, url\optional{, body\optional{, headers}}}
-This will send a request to the server using the HTTP request method
-\var{method} and the selector \var{url}. If the \var{body} argument is
-present, it should be a string of data to send after the headers are finished.
-Alternatively, it may be an open file object, in which case the
-contents of the file is sent; this file object should support
-\code{fileno()} and \code{read()} methods.
-The header Content-Length is automatically set to the correct value.
-The \var{headers} argument should be a mapping of extra HTTP headers to send
-with the request.
-
-\versionchanged[\var{body} can be a file object]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{getresponse}{}
-Should be called after a request is sent to get the response from the server.
-Returns an \class{HTTPResponse} instance.
-\note{Note that you must have read the whole response before you can send a new
-request to the server.}
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{set_debuglevel}{level}
-Set the debugging level (the amount of debugging output printed).
-The default debug level is \code{0}, meaning no debugging output is
-printed.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{connect}{}
-Connect to the server specified when the object was created.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{close}{}
-Close the connection to the server.
-\end{methoddesc}
-
-As an alternative to using the \method{request()} method described above,
-you can also send your request step by step, by using the four functions
-below.
-
-\begin{methoddesc}[HTTPConnection]{putrequest}{request, selector\optional{,
-skip\_host\optional{, skip_accept_encoding}}}
-This should be the first call after the connection to the server has
-been made. It sends a line to the server consisting of the
-\var{request} string, the \var{selector} string, and the HTTP version
-(\code{HTTP/1.1}). To disable automatic sending of \code{Host:} or
-\code{Accept-Encoding:} headers (for example to accept additional
-content encodings), specify \var{skip_host} or \var{skip_accept_encoding}
-with non-False values.
-\versionchanged[\var{skip_accept_encoding} argument added]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{putheader}{header, argument\optional{, ...}}
-Send an \rfc{822}-style header to the server. It sends a line to the
-server consisting of the header, a colon and a space, and the first
-argument. If more arguments are given, continuation lines are sent,
-each consisting of a tab and an argument.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{endheaders}{}
-Send a blank line to the server, signalling the end of the headers.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPConnection]{send}{data}
-Send data to the server. This should be used directly only after the
-\method{endheaders()} method has been called and before
-\method{getresponse()} is called.
-\end{methoddesc}
-
-\subsection{HTTPResponse Objects \label{httpresponse-objects}}
-
-\class{HTTPResponse} instances have the following methods and attributes:
-
-\begin{methoddesc}[HTTPResponse]{read}{\optional{amt}}
-Reads and returns the response body, or up to the next \var{amt} bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPResponse]{getheader}{name\optional{, default}}
-Get the contents of the header \var{name}, or \var{default} if there is no
-matching header.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPResponse]{getheaders}{}
-Return a list of (header, value) tuples. \versionadded{2.4}
-\end{methoddesc}
-
-\begin{memberdesc}[HTTPResponse]{msg}
- A \class{mimetools.Message} instance containing the response headers.
-\end{memberdesc}
-
-\begin{memberdesc}[HTTPResponse]{version}
- HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
-\end{memberdesc}
-
-\begin{memberdesc}[HTTPResponse]{status}
- Status code returned by server.
-\end{memberdesc}
-
-\begin{memberdesc}[HTTPResponse]{reason}
- Reason phrase returned by server.
-\end{memberdesc}
-
-
-\subsection{Examples \label{httplib-examples}}
-
-Here is an example session that uses the \samp{GET} method:
-
-\begin{verbatim}
->>> import httplib
->>> conn = httplib.HTTPConnection("www.python.org")
->>> conn.request("GET", "/index.html")
->>> r1 = conn.getresponse()
->>> print r1.status, r1.reason
-200 OK
->>> data1 = r1.read()
->>> conn.request("GET", "/parrot.spam")
->>> r2 = conn.getresponse()
->>> print r2.status, r2.reason
-404 Not Found
->>> data2 = r2.read()
->>> conn.close()
-\end{verbatim}
-
-Here is an example session that shows how to \samp{POST} requests:
-
-\begin{verbatim}
->>> import httplib, urllib
->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
->>> headers = {"Content-type": "application/x-www-form-urlencoded",
-... "Accept": "text/plain"}
->>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
->>> conn.request("POST", "/cgi-bin/query", params, headers)
->>> response = conn.getresponse()
->>> print response.status, response.reason
-200 OK
->>> data = response.read()
->>> conn.close()
-\end{verbatim}
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex
deleted file mode 100644
index e34caaa..0000000
--- a/Doc/lib/libimaplib.tex
+++ /dev/null
@@ -1,507 +0,0 @@
-\section{\module{imaplib} ---
- IMAP4 protocol client}
-
-\declaremodule{standard}{imaplib}
-\modulesynopsis{IMAP4 protocol client (requires sockets).}
-\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au}
-\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au}
-
-% Based on HTML documentation by Piers Lauder
-% <piers@communitysolutions.com.au>;
-% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
-% Revised by ESR, January 2000.
-% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
-% Changes for IMAP4_stream by Piers Lauder
-% <piers@communitysolutions.com.au>, November 2002
-
-\indexii{IMAP4}{protocol}
-\indexii{IMAP4_SSL}{protocol}
-\indexii{IMAP4_stream}{protocol}
-
-This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL}
-and \class{IMAP4_stream}, which encapsulate a
-connection to an IMAP4 server and implement a large subset of the
-IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward
-compatible with IMAP4 (\rfc{1730}) servers, but note that the
-\samp{STATUS} command is not supported in IMAP4.
-
-Three classes are provided by the \module{imaplib} module,
-\class{IMAP4} is the base class:
-
-\begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
-This class implements the actual IMAP4 protocol. The connection is
-created and protocol version (IMAP4 or IMAP4rev1) is determined when
-the instance is initialized.
-If \var{host} is not specified, \code{''} (the local host) is used.
-If \var{port} is omitted, the standard IMAP4 port (143) is used.
-\end{classdesc}
-
-Three exceptions are defined as attributes of the \class{IMAP4} class:
-
-\begin{excdesc}{IMAP4.error}
-Exception raised on any errors. The reason for the exception is
-passed to the constructor as a string.
-\end{excdesc}
-
-\begin{excdesc}{IMAP4.abort}
-IMAP4 server errors cause this exception to be raised. This is a
-sub-class of \exception{IMAP4.error}. Note that closing the instance
-and instantiating a new one will usually allow recovery from this
-exception.
-\end{excdesc}
-
-\begin{excdesc}{IMAP4.readonly}
-This exception is raised when a writable mailbox has its status
-changed by the server. This is a sub-class of
-\exception{IMAP4.error}. Some other client now has write permission,
-and the mailbox will need to be re-opened to re-obtain write
-permission.
-\end{excdesc}
-
-There's also a subclass for secure connections:
-
-\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{,
- keyfile\optional{, certfile}}}}}
-This is a subclass derived from \class{IMAP4} that connects over an
-SSL encrypted socket (to use this class you need a socket module that
-was compiled with SSL support). If \var{host} is not specified,
-\code{''} (the local host) is used. If \var{port} is omitted, the
-standard IMAP4-over-SSL port (993) is used. \var{keyfile} and
-\var{certfile} are also optional - they can contain a PEM formatted
-private key and certificate chain file for the SSL connection.
-\end{classdesc}
-
-The second subclass allows for connections created by a child process:
-
-\begin{classdesc}{IMAP4_stream}{command}
-This is a subclass derived from \class{IMAP4} that connects
-to the \code{stdin/stdout} file descriptors created by passing
-\var{command} to \code{os.popen2()}.
-\versionadded{2.3}
-\end{classdesc}
-
-The following utility functions are defined:
-
-\begin{funcdesc}{Internaldate2tuple}{datestr}
- Converts an IMAP4 INTERNALDATE string to Coordinated Universal
- Time. Returns a \refmodule{time} module tuple.
-\end{funcdesc}
-
-\begin{funcdesc}{Int2AP}{num}
- Converts an integer into a string representation using characters
- from the set [\code{A} .. \code{P}].
-\end{funcdesc}
-
-\begin{funcdesc}{ParseFlags}{flagstr}
- Converts an IMAP4 \samp{FLAGS} response to a tuple of individual
- flags.
-\end{funcdesc}
-
-\begin{funcdesc}{Time2Internaldate}{date_time}
- Converts a \refmodule{time} module tuple to an IMAP4
- \samp{INTERNALDATE} representation. Returns a string in the form:
- \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes).
-\end{funcdesc}
-
-
-Note that IMAP4 message numbers change as the mailbox changes; in
-particular, after an \samp{EXPUNGE} command performs deletions the
-remaining messages are renumbered. So it is highly advisable to use
-UIDs instead, with the UID command.
-
-At the end of the module, there is a test section that contains a more
-extensive example of usage.
-
-\begin{seealso}
- \seetext{Documents describing the protocol, and sources and binaries
- for servers implementing it, can all be found at the
- University of Washington's \emph{IMAP Information Center}
- (\url{http://www.cac.washington.edu/imap/}).}
-\end{seealso}
-
-
-\subsection{IMAP4 Objects \label{imap4-objects}}
-
-All IMAP4rev1 commands are represented by methods of the same name,
-either upper-case or lower-case.
-
-All arguments to commands are converted to strings, except for
-\samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is
-passed as an IMAP4 literal. If necessary (the string contains IMAP4
-protocol-sensitive characters and isn't enclosed with either
-parentheses or double quotes) each string is quoted. However, the
-\var{password} argument to the \samp{LOGIN} command is always quoted.
-If you want to avoid having an argument string quoted
-(eg: the \var{flags} argument to \samp{STORE}) then enclose the string in
-parentheses (eg: \code{r'(\e Deleted)'}).
-
-Each command returns a tuple: \code{(\var{type}, [\var{data},
-...])} where \var{type} is usually \code{'OK'} or \code{'NO'},
-and \var{data} is either the text from the command response, or
-mandated results from the command. Each \var{data}
-is either a string, or a tuple. If a tuple, then the first part
-is the header of the response, and the second part contains
-the data (ie: 'literal' value).
-
-The \var{message_set} options to commands below is a string specifying one
-or more messages to be acted upon. It may be a simple message number
-(\code{'1'}), a range of message numbers (\code{'2:4'}), or a group of
-non-contiguous ranges separated by commas (\code{'1:3,6:9'}). A range
-can contain an asterisk to indicate an infinite upper bound
-(\code{'3:*'}).
-
-An \class{IMAP4} instance has the following methods:
-
-
-\begin{methoddesc}[IMAP4]{append}{mailbox, flags, date_time, message}
- Append \var{message} to named mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{authenticate}{mechanism, authobject}
- Authenticate command --- requires response processing.
-
- \var{mechanism} specifies which authentication mechanism is to be
- used - it should appear in the instance variable \code{capabilities}
- in the form \code{AUTH=mechanism}.
-
- \var{authobject} must be a callable object:
-
-\begin{verbatim}
-data = authobject(response)
-\end{verbatim}
-
- It will be called to process server continuation responses.
- It should return \code{data} that will be encoded and sent to server.
- It should return \code{None} if the client abort response \samp{*} should
- be sent instead.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{check}{}
- Checkpoint mailbox on server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{close}{}
- Close currently selected mailbox. Deleted messages are removed from
- writable mailbox. This is the recommended command before
- \samp{LOGOUT}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{copy}{message_set, new_mailbox}
- Copy \var{message_set} messages onto end of \var{new_mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{create}{mailbox}
- Create new mailbox named \var{mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{delete}{mailbox}
- Delete old mailbox named \var{mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{deleteacl}{mailbox, who}
- Delete the ACLs (remove any rights) set for who on mailbox.
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{expunge}{}
- Permanently remove deleted items from selected mailbox. Generates an
- \samp{EXPUNGE} response for each deleted message. Returned data
- contains a list of \samp{EXPUNGE} message numbers in order
- received.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{fetch}{message_set, message_parts}
- Fetch (parts of) messages. \var{message_parts} should be
- a string of message part names enclosed within parentheses,
- eg: \samp{"(UID BODY[TEXT])"}. Returned data are tuples
- of message part envelope and data.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getacl}{mailbox}
- Get the \samp{ACL}s for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getannotation}{mailbox, entry, attribute}
- Retrieve the specified \samp{ANNOTATION}s for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getquota}{root}
- Get the \samp{quota} \var{root}'s resource usage and limits.
- This method is part of the IMAP4 QUOTA extension defined in rfc2087.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{getquotaroot}{mailbox}
- Get the list of \samp{quota} \samp{roots} for the named \var{mailbox}.
- This method is part of the IMAP4 QUOTA extension defined in rfc2087.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{list}{\optional{directory\optional{, pattern}}}
- List mailbox names in \var{directory} matching
- \var{pattern}. \var{directory} defaults to the top-level mail
- folder, and \var{pattern} defaults to match anything. Returned data
- contains a list of \samp{LIST} responses.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{login}{user, password}
- Identify the client using a plaintext password.
- The \var{password} will be quoted.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{login_cram_md5}{user, password}
- Force use of \samp{CRAM-MD5} authentication when identifying the
- client to protect the password. Will only work if the server
- \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{logout}{}
- Shutdown connection to server. Returns server \samp{BYE} response.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{lsub}{\optional{directory\optional{, pattern}}}
- List subscribed mailbox names in directory matching pattern.
- \var{directory} defaults to the top level directory and
- \var{pattern} defaults to match any mailbox.
- Returned data are tuples of message part envelope and data.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{myrights}{mailbox}
- Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{namespace}{}
- Returns IMAP namespaces as defined in RFC2342.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{noop}{}
- Send \samp{NOOP} to server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{open}{host, port}
- Opens socket to \var{port} at \var{host}.
- The connection objects established by this method
- will be used in the \code{read}, \code{readline}, \code{send}, and
- \code{shutdown} methods.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{partial}{message_num, message_part, start, length}
- Fetch truncated part of a message.
- Returned data is a tuple of message part envelope and data.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{proxyauth}{user}
- Assume authentication as \var{user}.
- Allows an authorised administrator to proxy into any user's mailbox.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{read}{size}
- Reads \var{size} bytes from the remote server.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{readline}{}
- Reads one line from the remote server.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{recent}{}
- Prompt server for an update. Returned data is \code{None} if no new
- messages, else value of \samp{RECENT} response.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{rename}{oldmailbox, newmailbox}
- Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{response}{code}
- Return data for response \var{code} if received, or
- \code{None}. Returns the given code, instead of the usual type.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{search}{charset, criterion\optional{, ...}}
- Search mailbox for matching messages. \var{charset} may be
- \code{None}, in which case no \samp{CHARSET} will be specified in the
- request to the server. The IMAP protocol requires that at least one
- criterion be specified; an exception will be raised when the server
- returns an error.
-
- Example:
-
-\begin{verbatim}
-# M is a connected IMAP4 instance...
-typ, msgnums = M.search(None, 'FROM', '"LDJ"')
-
-# or:
-typ, msgnums = M.search(None, '(FROM "LDJ")')
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{select}{\optional{mailbox\optional{, readonly}}}
- Select a mailbox. Returned data is the count of messages in
- \var{mailbox} (\samp{EXISTS} response). The default \var{mailbox}
- is \code{'INBOX'}. If the \var{readonly} flag is set, modifications
- to the mailbox are not allowed.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{send}{data}
- Sends \code{data} to the remote server.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{setacl}{mailbox, who, what}
- Set an \samp{ACL} for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{setannotation}{mailbox, entry, attribute\optional{, ...}}
- Set \samp{ANNOTATION}s for \var{mailbox}.
- The method is non-standard, but is supported by the \samp{Cyrus} server.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{setquota}{root, limits}
- Set the \samp{quota} \var{root}'s resource \var{limits}.
- This method is part of the IMAP4 QUOTA extension defined in rfc2087.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{shutdown}{}
- Close connection established in \code{open}.
- You may override this method.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{socket}{}
- Returns socket instance used to connect to server.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{sort}{sort_criteria, charset, search_criterion\optional{, ...}}
- The \code{sort} command is a variant of \code{search} with sorting
- semantics for the results. Returned data contains a space separated
- list of matching message numbers.
-
- Sort has two arguments before the \var{search_criterion}
- argument(s); a parenthesized list of \var{sort_criteria}, and the
- searching \var{charset}. Note that unlike \code{search}, the
- searching \var{charset} argument is mandatory. There is also a
- \code{uid sort} command which corresponds to \code{sort} the way
- that \code{uid search} corresponds to \code{search}. The
- \code{sort} command first searches the mailbox for messages that
- match the given searching criteria using the charset argument for
- the interpretation of strings in the searching criteria. It then
- returns the numbers of matching messages.
-
- This is an \samp{IMAP4rev1} extension command.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{status}{mailbox, names}
- Request named status conditions for \var{mailbox}.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{store}{message_set, command, flag_list}
- Alters flag dispositions for messages in mailbox. \var{command} is
- specified by section 6.4.6 of \rfc{2060} as being one of "FLAGS", "+FLAGS",
- or "-FLAGS", optionally with a suffix of ".SILENT".
-
- For example, to set the delete flag on all messages:
-
-\begin{verbatim}
-typ, data = M.search(None, 'ALL')
-for num in data[0].split():
- M.store(num, '+FLAGS', '\\Deleted')
-M.expunge()
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{subscribe}{mailbox}
- Subscribe to new mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{thread}{threading_algorithm, charset,
- search_criterion\optional{, ...}}
- The \code{thread} command is a variant of \code{search} with
- threading semantics for the results. Returned data contains a space
- separated list of thread members.
-
- Thread members consist of zero or more messages numbers, delimited
- by spaces, indicating successive parent and child.
-
- Thread has two arguments before the \var{search_criterion}
- argument(s); a \var{threading_algorithm}, and the searching
- \var{charset}. Note that unlike \code{search}, the searching
- \var{charset} argument is mandatory. There is also a \code{uid
- thread} command which corresponds to \code{thread} the way that
- \code{uid search} corresponds to \code{search}. The \code{thread}
- command first searches the mailbox for messages that match the given
- searching criteria using the charset argument for the interpretation
- of strings in the searching criteria. It then returns the matching
- messages threaded according to the specified threading algorithm.
-
- This is an \samp{IMAP4rev1} extension command. \versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{uid}{command, arg\optional{, ...}}
- Execute command args with messages identified by UID, rather than
- message number. Returns response appropriate to command. At least
- one argument must be supplied; if none are provided, the server will
- return an error and an exception will be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{unsubscribe}{mailbox}
- Unsubscribe from old mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[IMAP4]{xatom}{name\optional{, arg\optional{, ...}}}
- Allow simple extension commands notified by server in
- \samp{CAPABILITY} response.
-\end{methoddesc}
-
-
-Instances of \class{IMAP4_SSL} have just one additional method:
-
-\begin{methoddesc}[IMAP4_SSL]{ssl}{}
- Returns SSLObject instance used for the secure connection with the server.
-\end{methoddesc}
-
-
-The following attributes are defined on instances of \class{IMAP4}:
-
-
-\begin{memberdesc}[IMAP4]{PROTOCOL_VERSION}
-The most recent supported protocol in the
-\samp{CAPABILITY} response from the server.
-\end{memberdesc}
-
-\begin{memberdesc}[IMAP4]{debug}
-Integer value to control debugging output. The initialize value is
-taken from the module variable \code{Debug}. Values greater than
-three trace each command.
-\end{memberdesc}
-
-
-\subsection{IMAP4 Example \label{imap4-example}}
-
-Here is a minimal example (without error checking) that opens a
-mailbox and retrieves and prints all messages:
-
-\begin{verbatim}
-import getpass, imaplib
-
-M = imaplib.IMAP4()
-M.login(getpass.getuser(), getpass.getpass())
-M.select()
-typ, data = M.search(None, 'ALL')
-for num in data[0].split():
- typ, data = M.fetch(num, '(RFC822)')
- print 'Message %s\n%s\n' % (num, data[0][1])
-M.close()
-M.logout()
-\end{verbatim}
diff --git a/Doc/lib/libimghdr.tex b/Doc/lib/libimghdr.tex
deleted file mode 100644
index 4a4f368..0000000
--- a/Doc/lib/libimghdr.tex
+++ /dev/null
@@ -1,60 +0,0 @@
-\section{\module{imghdr} ---
- Determine the type of an image}
-
-\declaremodule{standard}{imghdr}
-\modulesynopsis{Determine the type of image contained in a file or
- byte stream.}
-
-
-The \module{imghdr} module determines the type of image contained in a
-file or byte stream.
-
-The \module{imghdr} module defines the following function:
-
-
-\begin{funcdesc}{what}{filename\optional{, h}}
-Tests the image data contained in the file named by \var{filename},
-and returns a string describing the image type. If optional \var{h}
-is provided, the \var{filename} is ignored and \var{h} is assumed to
-contain the byte stream to test.
-\end{funcdesc}
-
-The following image types are recognized, as listed below with the
-return value from \function{what()}:
-
-\begin{tableii}{l|l}{code}{Value}{Image format}
- \lineii{'rgb'}{SGI ImgLib Files}
- \lineii{'gif'}{GIF 87a and 89a Files}
- \lineii{'pbm'}{Portable Bitmap Files}
- \lineii{'pgm'}{Portable Graymap Files}
- \lineii{'ppm'}{Portable Pixmap Files}
- \lineii{'tiff'}{TIFF Files}
- \lineii{'rast'}{Sun Raster Files}
- \lineii{'xbm'}{X Bitmap Files}
- \lineii{'jpeg'}{JPEG data in JFIF or Exif formats}
- \lineii{'bmp'}{BMP files}
- \lineii{'png'}{Portable Network Graphics}
-\end{tableii}
-
-\versionadded[Exif detection]{2.5}
-
-You can extend the list of file types \module{imghdr} can recognize by
-appending to this variable:
-
-\begin{datadesc}{tests}
-A list of functions performing the individual tests. Each function
-takes two arguments: the byte-stream and an open file-like object.
-When \function{what()} is called with a byte-stream, the file-like
-object will be \code{None}.
-
-The test function should return a string describing the image type if
-the test succeeded, or \code{None} if it failed.
-\end{datadesc}
-
-Example:
-
-\begin{verbatim}
->>> import imghdr
->>> imghdr.what('/tmp/bass.gif')
-'gif'
-\end{verbatim}
diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex
deleted file mode 100644
index 6396605..0000000
--- a/Doc/lib/libimp.tex
+++ /dev/null
@@ -1,291 +0,0 @@
-\section{\module{imp} ---
- Access the \keyword{import} internals}
-
-\declaremodule{builtin}{imp}
-\modulesynopsis{Access the implementation of the \keyword{import} statement.}
-
-
-This\stindex{import} module provides an interface to the mechanisms
-used to implement the \keyword{import} statement. It defines the
-following constants and functions:
-
-
-\begin{funcdesc}{get_magic}{}
-\indexii{file}{byte-code}
-Return the magic string value used to recognize byte-compiled code
-files (\file{.pyc} files). (This value may be different for each
-Python version.)
-\end{funcdesc}
-
-\begin{funcdesc}{get_suffixes}{}
-Return a list of triples, each describing a particular type of module.
-Each triple has the form \code{(\var{suffix}, \var{mode},
-\var{type})}, where \var{suffix} is a string to be appended to the
-module name to form the filename to search for, \var{mode} is the mode
-string to pass to the built-in \function{open()} function to open the
-file (this can be \code{'r'} for text files or \code{'rb'} for binary
-files), and \var{type} is the file type, which has one of the values
-\constant{PY_SOURCE}, \constant{PY_COMPILED}, or
-\constant{C_EXTENSION}, described below.
-\end{funcdesc}
-
-\begin{funcdesc}{find_module}{name\optional{, path}}
-Try to find the module \var{name} on the search path \var{path}. If
-\var{path} is a list of directory names, each directory is searched
-for files with any of the suffixes returned by \function{get_suffixes()}
-above. Invalid names in the list are silently ignored (but all list
-items must be strings). If \var{path} is omitted or \code{None}, the
-list of directory names given by \code{sys.path} is searched, but
-first it searches a few special places: it tries to find a built-in
-module with the given name (\constant{C_BUILTIN}), then a frozen module
-(\constant{PY_FROZEN}), and on some systems some other places are looked
-in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE});
-on Windows, it looks in the registry which may point to a specific
-file).
-
-If search is successful, the return value is a triple
-\code{(\var{file}, \var{pathname}, \var{description})} where
-\var{file} is an open file object positioned at the beginning,
-\var{pathname} is the pathname of the
-file found, and \var{description} is a triple as contained in the list
-returned by \function{get_suffixes()} describing the kind of module found.
-If the module does not live in a file, the returned \var{file} is
-\code{None}, \var{filename} is the empty string, and the
-\var{description} tuple contains empty strings for its suffix and
-mode; the module type is as indicate in parentheses above. If the
-search is unsuccessful, \exception{ImportError} is raised. Other
-exceptions indicate problems with the arguments or environment.
-
-This function does not handle hierarchical module names (names
-containing dots). In order to find \var{P}.\var{M}, that is, submodule
-\var{M} of package \var{P}, use \function{find_module()} and
-\function{load_module()} to find and load package \var{P}, and then use
-\function{find_module()} with the \var{path} argument set to
-\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply
-this recipe recursively.
-\end{funcdesc}
-
-\begin{funcdesc}{load_module}{name, file, filename, description}
-Load a module that was previously found by \function{find_module()} (or by
-an otherwise conducted search yielding compatible results). This
-function does more than importing the module: if the module was
-already imported, it will reload the module! The \var{name} argument
-indicates the full module name (including the package name, if this is
-a submodule of a package). The \var{file} argument is an open file,
-and \var{filename} is the corresponding file name; these can be
-\code{None} and \code{''}, respectively, when the module is not being
-loaded from a file. The \var{description} argument is a tuple, as
-would be returned by \function{get_suffixes()}, describing what kind
-of module must be loaded.
-
-If the load is successful, the return value is the module object;
-otherwise, an exception (usually \exception{ImportError}) is raised.
-
-\strong{Important:} the caller is responsible for closing the
-\var{file} argument, if it was not \code{None}, even when an exception
-is raised. This is best done using a \keyword{try}
-... \keyword{finally} statement.
-\end{funcdesc}
-
-\begin{funcdesc}{new_module}{name}
-Return a new empty module object called \var{name}. This object is
-\emph{not} inserted in \code{sys.modules}.
-\end{funcdesc}
-
-\begin{funcdesc}{lock_held}{}
-Return \code{True} if the import lock is currently held, else \code{False}.
-On platforms without threads, always return \code{False}.
-
-On platforms with threads, a thread executing an import holds an internal
-lock until the import is complete.
-This lock blocks other threads from doing an import until the original
-import completes, which in turn prevents other threads from seeing
-incomplete module objects constructed by the original thread while in
-the process of completing its import (and the imports, if any,
-triggered by that).
-\end{funcdesc}
-
-\begin{funcdesc}{acquire_lock}{}
-Acquires the interpreter's import lock for the current thread. This lock
-should be used by import hooks to ensure thread-safety when importing modules.
-On platforms without threads, this function does nothing.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{release_lock}{}
-Release the interpreter's import lock.
-On platforms without threads, this function does nothing.
-\versionadded{2.3}
-\end{funcdesc}
-
-The following constants with integer values, defined in this module,
-are used to indicate the search result of \function{find_module()}.
-
-\begin{datadesc}{PY_SOURCE}
-The module was found as a source file.
-\end{datadesc}
-
-\begin{datadesc}{PY_COMPILED}
-The module was found as a compiled code object file.
-\end{datadesc}
-
-\begin{datadesc}{C_EXTENSION}
-The module was found as dynamically loadable shared library.
-\end{datadesc}
-
-\begin{datadesc}{PY_RESOURCE}
-The module was found as a Mac OS 9 resource. This value can only be
-returned on a Mac OS 9 or earlier Macintosh.
-\end{datadesc}
-
-\begin{datadesc}{PKG_DIRECTORY}
-The module was found as a package directory.
-\end{datadesc}
-
-\begin{datadesc}{C_BUILTIN}
-The module was found as a built-in module.
-\end{datadesc}
-
-\begin{datadesc}{PY_FROZEN}
-The module was found as a frozen module (see \function{init_frozen()}).
-\end{datadesc}
-
-The following constant and functions are obsolete; their functionality
-is available through \function{find_module()} or \function{load_module()}.
-They are kept around for backward compatibility:
-
-\begin{datadesc}{SEARCH_ERROR}
-Unused.
-\end{datadesc}
-
-\begin{funcdesc}{init_builtin}{name}
-Initialize the built-in module called \var{name} and return its module
-object along with storing it in \code{sys.modules}. If the module was already
-initialized, it will be initialized \emph{again}. Re-initialization involves
-the copying of the built-in module's \code{__dict__} from the cached
-module over the module's entry in \code{sys.modules}. If there is no
-built-in module called \var{name}, \code{None} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{init_frozen}{name}
-Initialize the frozen module called \var{name} and return its module
-object. If the module was already initialized, it will be initialized
-\emph{again}. If there is no frozen module called \var{name},
-\code{None} is returned. (Frozen modules are modules written in
-Python whose compiled byte-code object is incorporated into a
-custom-built Python interpreter by Python's \program{freeze} utility.
-See \file{Tools/freeze/} for now.)
-\end{funcdesc}
-
-\begin{funcdesc}{is_builtin}{name}
-Return \code{1} if there is a built-in module called \var{name} which
-can be initialized again. Return \code{-1} if there is a built-in
-module called \var{name} which cannot be initialized again (see
-\function{init_builtin()}). Return \code{0} if there is no built-in
-module called \var{name}.
-\end{funcdesc}
-
-\begin{funcdesc}{is_frozen}{name}
-Return \code{True} if there is a frozen module (see
-\function{init_frozen()}) called \var{name}, or \code{False} if there is
-no such module.
-\end{funcdesc}
-
-\begin{funcdesc}{load_compiled}{name, pathname, \optional{file}}
-\indexii{file}{byte-code}
-Load and initialize a module implemented as a byte-compiled code file
-and return its module object. If the module was already initialized,
-it will be initialized \emph{again}. The \var{name} argument is used
-to create or access a module object. The \var{pathname} argument
-points to the byte-compiled code file. The \var{file}
-argument is the byte-compiled code file, open for reading in binary
-mode, from the beginning.
-It must currently be a real file object, not a
-user-defined class emulating a file.
-\end{funcdesc}
-
-\begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}}
-Load and initialize a module implemented as a dynamically loadable
-shared library and return its module object. If the module was
-already initialized, it will be initialized \emph{again}.
-Re-initialization involves copying the \code{__dict__} attribute of the cached
-instance of the module over the value used in the module cached in
-\code{sys.modules}. The \var{pathname} argument must point to the shared
-library. The \var{name} argument is used to construct the name of the
-initialization function: an external C function called
-\samp{init\var{name}()} in the shared library is called. The optional
-\var{file} argument is ignored. (Note: using shared libraries is highly
-system dependent, and not all systems support it.)
-\end{funcdesc}
-
-\begin{funcdesc}{load_source}{name, pathname\optional{, file}}
-Load and initialize a module implemented as a Python source file and
-return its module object. If the module was already initialized, it
-will be initialized \emph{again}. The \var{name} argument is used to
-create or access a module object. The \var{pathname} argument points
-to the source file. The \var{file} argument is the source
-file, open for reading as text, from the beginning.
-It must currently be a real file
-object, not a user-defined class emulating a file. Note that if a
-properly matching byte-compiled file (with suffix \file{.pyc} or
-\file{.pyo}) exists, it will be used instead of parsing the given
-source file.
-\end{funcdesc}
-
-\begin{classdesc}{NullImporter}{path_string}
-The \class{NullImporter} type is a \pep{302} import hook that handles
-non-directory path strings by failing to find any modules. Calling this
-type with an existing directory or empty string raises
-\exception{ImportError}. Otherwise, a \class{NullImporter} instance is
-returned.
-
-Python adds instances of this type to \code{sys.path_importer_cache} for
-any path entries that are not directories and are not handled by any other
-path hooks on \code{sys.path_hooks}. Instances have only one method:
-
-\begin{methoddesc}{find_module}{fullname \optional{, path}}
-This method always returns \code{None}, indicating that the requested
-module could not be found.
-\end{methoddesc}
-
-\versionadded{2.5}
-\end{classdesc}
-
-\subsection{Examples}
-\label{examples-imp}
-
-The following function emulates what was the standard import statement
-up to Python 1.4 (no hierarchical module names). (This
-\emph{implementation} wouldn't work in that version, since
-\function{find_module()} has been extended and
-\function{load_module()} has been added in 1.4.)
-
-\begin{verbatim}
-import imp
-import sys
-
-def __import__(name, globals=None, locals=None, fromlist=None):
- # Fast path: see if the module has already been imported.
- try:
- return sys.modules[name]
- except KeyError:
- pass
-
- # If any of the following calls raises an exception,
- # there's a problem we can't handle -- let the caller handle it.
-
- fp, pathname, description = imp.find_module(name)
-
- try:
- return imp.load_module(name, fp, pathname, description)
- finally:
- # Since we may exit via an exception, close fp explicitly.
- if fp:
- fp.close()
-\end{verbatim}
-
-A more complete example that implements hierarchical module names and
-includes a \function{reload()} function can be
-found in the module \module{knee}\refmodindex{knee}. The
-\module{knee} module can be found in \file{Demo/imputil/} in the
-Python source distribution.
diff --git a/Doc/lib/libinspect.tex b/Doc/lib/libinspect.tex
deleted file mode 100644
index c9a63fc..0000000
--- a/Doc/lib/libinspect.tex
+++ /dev/null
@@ -1,391 +0,0 @@
-\section{\module{inspect} ---
- Inspect live objects}
-
-\declaremodule{standard}{inspect}
-\modulesynopsis{Extract information and source code from live objects.}
-\moduleauthor{Ka-Ping Yee}{ping@lfw.org}
-\sectionauthor{Ka-Ping Yee}{ping@lfw.org}
-
-\versionadded{2.1}
-
-The \module{inspect} module provides several useful functions
-to help get information about live objects such as modules,
-classes, methods, functions, tracebacks, frame objects, and
-code objects. For example, it can help you examine the
-contents of a class, retrieve the source code of a method,
-extract and format the argument list for a function, or
-get all the information you need to display a detailed traceback.
-
-There are four main kinds of services provided by this module:
-type checking, getting source code, inspecting classes
-and functions, and examining the interpreter stack.
-
-\subsection{Types and members
- \label{inspect-types}}
-
-The \function{getmembers()} function retrieves the members
-of an object such as a class or module.
-The eleven functions whose names begin with ``is'' are mainly
-provided as convenient choices for the second argument to
-\function{getmembers()}. They also help you determine when
-you can expect to find the following special attributes:
-
-\begin{tableiv}{c|l|l|c}{}{Type}{Attribute}{Description}{Notes}
- \lineiv{module}{__doc__}{documentation string}{}
- \lineiv{}{__file__}{filename (missing for built-in modules)}{}
- \hline
- \lineiv{class}{__doc__}{documentation string}{}
- \lineiv{}{__module__}{name of module in which this class was defined}{}
- \hline
- \lineiv{method}{__doc__}{documentation string}{}
- \lineiv{}{__name__}{name with which this method was defined}{}
- \lineiv{}{im_class}{class object that asked for this method}{(1)}
- \lineiv{}{im_func}{function object containing implementation of method}{}
- \lineiv{}{im_self}{instance to which this method is bound, or \code{None}}{}
- \hline
- \lineiv{function}{__doc__}{documentation string}{}
- \lineiv{}{__name__}{name with which this function was defined}{}
- \lineiv{}{__code__}{code object containing compiled function bytecode}{}
- \lineiv{}{__defaults__}{tuple of any default values for arguments}{}
- \lineiv{}{__globals__}{global namespace in which this function was defined}{}
- \hline
- \lineiv{traceback}{tb_frame}{frame object at this level}{}
- \lineiv{}{tb_lasti}{index of last attempted instruction in bytecode}{}
- \lineiv{}{tb_lineno}{current line number in Python source code}{}
- \lineiv{}{tb_next}{next inner traceback object (called by this level)}{}
- \hline
- \lineiv{frame}{f_back}{next outer frame object (this frame's caller)}{}
- \lineiv{}{f_builtins}{built-in namespace seen by this frame}{}
- \lineiv{}{f_code}{code object being executed in this frame}{}
- \lineiv{}{f_exc_traceback}{traceback if raised in this frame, or \code{None}}{}
- \lineiv{}{f_exc_type}{exception type if raised in this frame, or \code{None}}{}
- \lineiv{}{f_exc_value}{exception value if raised in this frame, or \code{None}}{}
- \lineiv{}{f_globals}{global namespace seen by this frame}{}
- \lineiv{}{f_lasti}{index of last attempted instruction in bytecode}{}
- \lineiv{}{f_lineno}{current line number in Python source code}{}
- \lineiv{}{f_locals}{local namespace seen by this frame}{}
- \lineiv{}{f_restricted}{0 or 1 if frame is in restricted execution mode}{}
- \lineiv{}{f_trace}{tracing function for this frame, or \code{None}}{}
- \hline
- \lineiv{code}{co_argcount}{number of arguments (not including * or ** args)}{}
- \lineiv{}{co_code}{string of raw compiled bytecode}{}
- \lineiv{}{co_consts}{tuple of constants used in the bytecode}{}
- \lineiv{}{co_filename}{name of file in which this code object was created}{}
- \lineiv{}{co_firstlineno}{number of first line in Python source code}{}
- \lineiv{}{co_flags}{bitmap: 1=optimized \code{|} 2=newlocals \code{|} 4=*arg \code{|} 8=**arg}{}
- \lineiv{}{co_lnotab}{encoded mapping of line numbers to bytecode indices}{}
- \lineiv{}{co_name}{name with which this code object was defined}{}
- \lineiv{}{co_names}{tuple of names of local variables}{}
- \lineiv{}{co_nlocals}{number of local variables}{}
- \lineiv{}{co_stacksize}{virtual machine stack space required}{}
- \lineiv{}{co_varnames}{tuple of names of arguments and local variables}{}
- \hline
- \lineiv{builtin}{__doc__}{documentation string}{}
- \lineiv{}{__name__}{original name of this function or method}{}
- \lineiv{}{__self__}{instance to which a method is bound, or \code{None}}{}
-\end{tableiv}
-
-\noindent
-Note:
-\begin{description}
-\item[(1)]
-\versionchanged[\member{im_class} used to refer to the class that
- defined the method]{2.2}
-\end{description}
-
-
-\begin{funcdesc}{getmembers}{object\optional{, predicate}}
- Return all the members of an object in a list of (name, value) pairs
- sorted by name. If the optional \var{predicate} argument is supplied,
- only members for which the predicate returns a true value are included.
-\end{funcdesc}
-
-\begin{funcdesc}{getmoduleinfo}{path}
- Return a tuple of values that describe how Python will interpret the
- file identified by \var{path} if it is a module, or \code{None} if
- it would not be identified as a module. The return tuple is
- \code{(\var{name}, \var{suffix}, \var{mode}, \var{mtype})}, where
- \var{name} is the name of the module without the name of any
- enclosing package, \var{suffix} is the trailing part of the file
- name (which may not be a dot-delimited extension), \var{mode} is the
- \function{open()} mode that would be used (\code{'r'} or
- \code{'rb'}), and \var{mtype} is an integer giving the type of the
- module. \var{mtype} will have a value which can be compared to the
- constants defined in the \refmodule{imp} module; see the
- documentation for that module for more information on module types.
-\end{funcdesc}
-
-\begin{funcdesc}{getmodulename}{path}
- Return the name of the module named by the file \var{path}, without
- including the names of enclosing packages. This uses the same
- algorithm as the interpreter uses when searching for modules. If
- the name cannot be matched according to the interpreter's rules,
- \code{None} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{ismodule}{object}
- Return true if the object is a module.
-\end{funcdesc}
-
-\begin{funcdesc}{isclass}{object}
- Return true if the object is a class.
-\end{funcdesc}
-
-\begin{funcdesc}{ismethod}{object}
- Return true if the object is a method.
-\end{funcdesc}
-
-\begin{funcdesc}{isfunction}{object}
- Return true if the object is a Python function or unnamed (lambda) function.
-\end{funcdesc}
-
-\begin{funcdesc}{istraceback}{object}
- Return true if the object is a traceback.
-\end{funcdesc}
-
-\begin{funcdesc}{isframe}{object}
- Return true if the object is a frame.
-\end{funcdesc}
-
-\begin{funcdesc}{iscode}{object}
- Return true if the object is a code.
-\end{funcdesc}
-
-\begin{funcdesc}{isbuiltin}{object}
- Return true if the object is a built-in function.
-\end{funcdesc}
-
-\begin{funcdesc}{isroutine}{object}
- Return true if the object is a user-defined or built-in function or method.
-\end{funcdesc}
-
-\begin{funcdesc}{ismethoddescriptor}{object}
- Return true if the object is a method descriptor, but not if ismethod() or
- isclass() or isfunction() are true.
-
- This is new as of Python 2.2, and, for example, is true of int.__add__.
- An object passing this test has a __get__ attribute but not a __set__
- attribute, but beyond that the set of attributes varies. __name__ is
- usually sensible, and __doc__ often is.
-
- Methods implemented via descriptors that also pass one of the other
- tests return false from the ismethoddescriptor() test, simply because
- the other tests promise more -- you can, e.g., count on having the
- im_func attribute (etc) when an object passes ismethod().
-\end{funcdesc}
-
-\begin{funcdesc}{isdatadescriptor}{object}
- Return true if the object is a data descriptor.
-
- Data descriptors have both a __get__ and a __set__ attribute. Examples are
- properties (defined in Python), getsets, and members. The latter two are
- defined in C and there are more specific tests available for those types,
- which is robust across Python implementations. Typically, data descriptors
- will also have __name__ and __doc__ attributes (properties, getsets, and
- members have both of these attributes), but this is not guaranteed.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{isgetsetdescriptor}{object}
- Return true if the object is a getset descriptor.
-
- getsets are attributes defined in extension modules via \code{PyGetSetDef}
- structures. For Python implementations without such types, this method will
- always return \code{False}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ismemberdescriptor}{object}
- Return true if the object is a member descriptor.
-
- Member descriptors are attributes defined in extension modules via
- \code{PyMemberDef} structures. For Python implementations without such
- types, this method will always return \code{False}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\subsection{Retrieving source code
- \label{inspect-source}}
-
-\begin{funcdesc}{getdoc}{object}
- Get the documentation string for an object.
- All tabs are expanded to spaces. To clean up docstrings that are
- indented to line up with blocks of code, any whitespace than can be
- uniformly removed from the second line onwards is removed.
-\end{funcdesc}
-
-\begin{funcdesc}{getcomments}{object}
- Return in a single string any lines of comments immediately preceding
- the object's source code (for a class, function, or method), or at the
- top of the Python source file (if the object is a module).
-\end{funcdesc}
-
-\begin{funcdesc}{getfile}{object}
- Return the name of the (text or binary) file in which an object was
- defined. This will fail with a \exception{TypeError} if the object
- is a built-in module, class, or function.
-\end{funcdesc}
-
-\begin{funcdesc}{getmodule}{object}
- Try to guess which module an object was defined in.
-\end{funcdesc}
-
-\begin{funcdesc}{getsourcefile}{object}
- Return the name of the Python source file in which an object was
- defined. This will fail with a \exception{TypeError} if the object
- is a built-in module, class, or function.
-\end{funcdesc}
-
-\begin{funcdesc}{getsourcelines}{object}
- Return a list of source lines and starting line number for an object.
- The argument may be a module, class, method, function, traceback, frame,
- or code object. The source code is returned as a list of the lines
- corresponding to the object and the line number indicates where in the
- original source file the first line of code was found. An
- \exception{IOError} is raised if the source code cannot be retrieved.
-\end{funcdesc}
-
-\begin{funcdesc}{getsource}{object}
- Return the text of the source code for an object.
- The argument may be a module, class, method, function, traceback, frame,
- or code object. The source code is returned as a single string. An
- \exception{IOError} is raised if the source code cannot be retrieved.
-\end{funcdesc}
-
-\subsection{Classes and functions
- \label{inspect-classes-functions}}
-
-\begin{funcdesc}{getclasstree}{classes\optional{, unique}}
- Arrange the given list of classes into a hierarchy of nested lists.
- Where a nested list appears, it contains classes derived from the class
- whose entry immediately precedes the list. Each entry is a 2-tuple
- containing a class and a tuple of its base classes. If the \var{unique}
- argument is true, exactly one entry appears in the returned structure
- for each class in the given list. Otherwise, classes using multiple
- inheritance and their descendants will appear multiple times.
-\end{funcdesc}
-
-\begin{funcdesc}{getargspec}{func}
- Get the names and default values of a function's arguments.
- A tuple of four things is returned: \code{(\var{args},
- \var{varargs}, \var{varkw}, \var{defaults})}.
- \var{args} is a list of the argument names (it may contain nested lists).
- \var{varargs} and \var{varkw} are the names of the \code{*} and
- \code{**} arguments or \code{None}.
- \var{defaults} is a tuple of default argument values or None if there are no
- default arguments; if this tuple has \var{n} elements, they correspond to
- the last \var{n} elements listed in \var{args}.
-\end{funcdesc}
-
-\begin{funcdesc}{getargvalues}{frame}
- Get information about arguments passed into a particular frame.
- A tuple of four things is returned: \code{(\var{args},
- \var{varargs}, \var{varkw}, \var{locals})}.
- \var{args} is a list of the argument names (it may contain nested
- lists).
- \var{varargs} and \var{varkw} are the names of the \code{*} and
- \code{**} arguments or \code{None}.
- \var{locals} is the locals dictionary of the given frame.
-\end{funcdesc}
-
-\begin{funcdesc}{formatargspec}{args\optional{, varargs, varkw, defaults,
- formatarg, formatvarargs, formatvarkw, formatvalue, join}}
-
- Format a pretty argument spec from the four values returned by
- \function{getargspec()}. The format* arguments are the
- corresponding optional formatting functions that are called to turn
- names and values into strings.
-\end{funcdesc}
-
-\begin{funcdesc}{formatargvalues}{args\optional{, varargs, varkw, locals,
- formatarg, formatvarargs, formatvarkw, formatvalue, join}}
- Format a pretty argument spec from the four values returned by
- \function{getargvalues()}. The format* arguments are the
- corresponding optional formatting functions that are called to turn
- names and values into strings.
-\end{funcdesc}
-
-\begin{funcdesc}{getmro}{cls}
- Return a tuple of class cls's base classes, including cls, in
- method resolution order. No class appears more than once in this tuple.
- Note that the method resolution order depends on cls's type. Unless a
- very peculiar user-defined metatype is in use, cls will be the first
- element of the tuple.
-\end{funcdesc}
-
-\subsection{The interpreter stack
- \label{inspect-stack}}
-
-When the following functions return ``frame records,'' each record
-is a tuple of six items: the frame object, the filename,
-the line number of the current line, the function name, a list of
-lines of context from the source code, and the index of the current
-line within that list.
-
-\begin{notice}[warning]
-Keeping references to frame objects, as found in
-the first element of the frame records these functions return, can
-cause your program to create reference cycles. Once a reference cycle
-has been created, the lifespan of all objects which can be accessed
-from the objects which form the cycle can become much longer even if
-Python's optional cycle detector is enabled. If such cycles must be
-created, it is important to ensure they are explicitly broken to avoid
-the delayed destruction of objects and increased memory consumption
-which occurs.
-
-Though the cycle detector will catch these, destruction of the frames
-(and local variables) can be made deterministic by removing the cycle
-in a \keyword{finally} clause. This is also important if the cycle
-detector was disabled when Python was compiled or using
-\function{\refmodule{gc}.disable()}. For example:
-
-\begin{verbatim}
-def handle_stackframe_without_leak():
- frame = inspect.currentframe()
- try:
- # do something with the frame
- finally:
- del frame
-\end{verbatim}
-\end{notice}
-
-The optional \var{context} argument supported by most of these
-functions specifies the number of lines of context to return, which
-are centered around the current line.
-
-\begin{funcdesc}{getframeinfo}{frame\optional{, context}}
- Get information about a frame or traceback object. A 5-tuple
- is returned, the last five elements of the frame's frame record.
-\end{funcdesc}
-
-\begin{funcdesc}{getouterframes}{frame\optional{, context}}
- Get a list of frame records for a frame and all outer frames. These
- frames represent the calls that lead to the creation of \var{frame}.
- The first entry in the returned list represents \var{frame}; the
- last entry represents the outermost call on \var{frame}'s stack.
-\end{funcdesc}
-
-\begin{funcdesc}{getinnerframes}{traceback\optional{, context}}
- Get a list of frame records for a traceback's frame and all inner
- frames. These frames represent calls made as a consequence of
- \var{frame}. The first entry in the list represents
- \var{traceback}; the last entry represents where the exception was
- raised.
-\end{funcdesc}
-
-\begin{funcdesc}{currentframe}{}
- Return the frame object for the caller's stack frame.
-\end{funcdesc}
-
-\begin{funcdesc}{stack}{\optional{context}}
- Return a list of frame records for the caller's stack. The first
- entry in the returned list represents the caller; the last entry
- represents the outermost call on the stack.
-\end{funcdesc}
-
-\begin{funcdesc}{trace}{\optional{context}}
- Return a list of frame records for the stack between the current
- frame and the frame in which an exception currently being handled
- was raised in. The first entry in the list represents the caller;
- the last entry represents where the exception was raised.
-\end{funcdesc}
diff --git a/Doc/lib/libintro.tex b/Doc/lib/libintro.tex
deleted file mode 100644
index 62434cd..0000000
--- a/Doc/lib/libintro.tex
+++ /dev/null
@@ -1,53 +0,0 @@
-\chapter{Introduction}
-\label{intro}
-
-The ``Python library'' contains several different kinds of components.
-
-It contains data types that would normally be considered part of the
-``core'' of a language, such as numbers and lists. For these types,
-the Python language core defines the form of literals and places some
-constraints on their semantics, but does not fully define the
-semantics. (On the other hand, the language core does define
-syntactic properties like the spelling and priorities of operators.)
-
-The library also contains built-in functions and exceptions ---
-objects that can be used by all Python code without the need of an
-\keyword{import} statement. Some of these are defined by the core
-language, but many are not essential for the core semantics and are
-only described here.
-
-The bulk of the library, however, consists of a collection of modules.
-There are many ways to dissect this collection. Some modules are
-written in C and built in to the Python interpreter; others are
-written in Python and imported in source form. Some modules provide
-interfaces that are highly specific to Python, like printing a stack
-trace; some provide interfaces that are specific to particular
-operating systems, such as access to specific hardware; others provide
-interfaces that are
-specific to a particular application domain, like the World Wide Web.
-Some modules are available in all versions and ports of Python; others
-are only available when the underlying system supports or requires
-them; yet others are available only when a particular configuration
-option was chosen at the time when Python was compiled and installed.
-
-This manual is organized ``from the inside out:'' it first describes
-the built-in data types, then the built-in functions and exceptions,
-and finally the modules, grouped in chapters of related modules. The
-ordering of the chapters as well as the ordering of the modules within
-each chapter is roughly from most relevant to least important.
-
-This means that if you start reading this manual from the start, and
-skip to the next chapter when you get bored, you will get a reasonable
-overview of the available modules and application areas that are
-supported by the Python library. Of course, you don't \emph{have} to
-read it like a novel --- you can also browse the table of contents (in
-front of the manual), or look for a specific function, module or term
-in the index (in the back). And finally, if you enjoy learning about
-random subjects, you choose a random page number (see module
-\refmodule{random}) and read a section or two. Regardless of the
-order in which you read the sections of this manual, it helps to start
-with chapter \ref{builtin}, ``Built-in Types, Exceptions and
-Functions,'' as the remainder of the manual assumes familiarity with
-this material.
-
-Let the show begin!
diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex
deleted file mode 100644
index b4784a8..0000000
--- a/Doc/lib/libitertools.tex
+++ /dev/null
@@ -1,575 +0,0 @@
-\section{\module{itertools} ---
- Functions creating iterators for efficient looping}
-
-\declaremodule{standard}{itertools}
-\modulesynopsis{Functions creating iterators for efficient looping.}
-\moduleauthor{Raymond Hettinger}{python@rcn.com}
-\sectionauthor{Raymond Hettinger}{python@rcn.com}
-\versionadded{2.3}
-
-
-This module implements a number of iterator building blocks inspired
-by constructs from the Haskell and SML programming languages. Each
-has been recast in a form suitable for Python.
-
-The module standardizes a core set of fast, memory efficient tools
-that are useful by themselves or in combination. Standardization helps
-avoid the readability and reliability problems which arise when many
-different individuals create their own slightly varying implementations,
-each with their own quirks and naming conventions.
-
-The tools are designed to combine readily with one another. This makes
-it easy to construct more specialized tools succinctly and efficiently
-in pure Python.
-
-For instance, SML provides a tabulation tool: \code{tabulate(f)}
-which produces a sequence \code{f(0), f(1), ...}. This toolbox
-provides \function{imap()} and \function{count()} which can be combined
-to form \code{imap(f, count())} and produce an equivalent result.
-
-Likewise, the functional tools are designed to work well with the
-high-speed functions provided by the \refmodule{operator} module.
-
-The module author welcomes suggestions for other basic building blocks
-to be added to future versions of the module.
-
-Whether cast in pure python form or compiled code, tools that use iterators
-are more memory efficient (and faster) than their list based counterparts.
-Adopting the principles of just-in-time manufacturing, they create
-data when and where needed instead of consuming memory with the
-computer equivalent of ``inventory''.
-
-The performance advantage of iterators becomes more acute as the number
-of elements increases -- at some point, lists grow large enough to
-severely impact memory cache performance and start running slowly.
-
-\begin{seealso}
- \seetext{The Standard ML Basis Library,
- \citetitle[http://www.standardml.org/Basis/]
- {The Standard ML Basis Library}.}
-
- \seetext{Haskell, A Purely Functional Language,
- \citetitle[http://www.haskell.org/definition/]
- {Definition of Haskell and the Standard Libraries}.}
-\end{seealso}
-
-
-\subsection{Itertool functions \label{itertools-functions}}
-
-The following module functions all construct and return iterators.
-Some provide streams of infinite length, so they should only be accessed
-by functions or loops that truncate the stream.
-
-\begin{funcdesc}{chain}{*iterables}
- Make an iterator that returns elements from the first iterable until
- it is exhausted, then proceeds to the next iterable, until all of the
- iterables are exhausted. Used for treating consecutive sequences as
- a single sequence. Equivalent to:
-
- \begin{verbatim}
- def chain(*iterables):
- for it in iterables:
- for element in it:
- yield element
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{count}{\optional{n}}
- Make an iterator that returns consecutive integers starting with \var{n}.
- If not specified \var{n} defaults to zero.
- Does not currently support python long integers. Often used as an
- argument to \function{imap()} to generate consecutive data points.
- Also, used with \function{izip()} to add sequence numbers. Equivalent to:
-
- \begin{verbatim}
- def count(n=0):
- while True:
- yield n
- n += 1
- \end{verbatim}
-
- Note, \function{count()} does not check for overflow and will return
- negative numbers after exceeding \code{sys.maxint}. This behavior
- may change in the future.
-\end{funcdesc}
-
-\begin{funcdesc}{cycle}{iterable}
- Make an iterator returning elements from the iterable and saving a
- copy of each. When the iterable is exhausted, return elements from
- the saved copy. Repeats indefinitely. Equivalent to:
-
- \begin{verbatim}
- def cycle(iterable):
- saved = []
- for element in iterable:
- yield element
- saved.append(element)
- while saved:
- for element in saved:
- yield element
- \end{verbatim}
-
- Note, this member of the toolkit may require significant
- auxiliary storage (depending on the length of the iterable).
-\end{funcdesc}
-
-\begin{funcdesc}{dropwhile}{predicate, iterable}
- Make an iterator that drops elements from the iterable as long as
- the predicate is true; afterwards, returns every element. Note,
- the iterator does not produce \emph{any} output until the predicate
- first becomes false, so it may have a lengthy start-up time. Equivalent to:
-
- \begin{verbatim}
- def dropwhile(predicate, iterable):
- iterable = iter(iterable)
- for x in iterable:
- if not predicate(x):
- yield x
- break
- for x in iterable:
- yield x
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{groupby}{iterable\optional{, key}}
- Make an iterator that returns consecutive keys and groups from the
- \var{iterable}. The \var{key} is a function computing a key value for each
- element. If not specified or is \code{None}, \var{key} defaults to an
- identity function and returns the element unchanged. Generally, the
- iterable needs to already be sorted on the same key function.
-
- The operation of \function{groupby()} is similar to the \code{uniq} filter
- in \UNIX{}. It generates a break or new group every time the value
- of the key function changes (which is why it is usually necessary
- to have sorted the data using the same key function). That behavior
- differs from SQL's GROUP BY which aggregates common elements regardless
- of their input order.
-
- The returned group is itself an iterator that shares the underlying
- iterable with \function{groupby()}. Because the source is shared, when
- the \function{groupby} object is advanced, the previous group is no
- longer visible. So, if that data is needed later, it should be stored
- as a list:
-
- \begin{verbatim}
- groups = []
- uniquekeys = []
- data = sorted(data, key=keyfunc)
- for k, g in groupby(data, keyfunc):
- groups.append(list(g)) # Store group iterator as a list
- uniquekeys.append(k)
- \end{verbatim}
-
- \function{groupby()} is equivalent to:
-
- \begin{verbatim}
- class groupby(object):
- def __init__(self, iterable, key=None):
- if key is None:
- key = lambda x: x
- self.keyfunc = key
- self.it = iter(iterable)
- self.tgtkey = self.currkey = self.currvalue = []
- def __iter__(self):
- return self
- def __next__(self):
- while self.currkey == self.tgtkey:
- self.currvalue = next(self.it) # Exit on StopIteration
- self.currkey = self.keyfunc(self.currvalue)
- self.tgtkey = self.currkey
- return (self.currkey, self._grouper(self.tgtkey))
- def _grouper(self, tgtkey):
- while self.currkey == tgtkey:
- yield self.currvalue
- self.currvalue = next(self.it) # Exit on StopIteration
- self.currkey = self.keyfunc(self.currvalue)
- \end{verbatim}
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{ifilter}{predicate, iterable}
- Make an iterator that filters elements from iterable returning only
- those for which the predicate is \code{True}.
- If \var{predicate} is \code{None}, return the items that are true.
- Equivalent to:
-
- \begin{verbatim}
- def ifilter(predicate, iterable):
- if predicate is None:
- predicate = bool
- for x in iterable:
- if predicate(x):
- yield x
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{ifilterfalse}{predicate, iterable}
- Make an iterator that filters elements from iterable returning only
- those for which the predicate is \code{False}.
- If \var{predicate} is \code{None}, return the items that are false.
- Equivalent to:
-
- \begin{verbatim}
- def ifilterfalse(predicate, iterable):
- if predicate is None:
- predicate = bool
- for x in iterable:
- if not predicate(x):
- yield x
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{imap}{function, *iterables}
- Make an iterator that computes the function using arguments from
- each of the iterables. If \var{function} is set to \code{None}, then
- \function{imap()} returns the arguments as a tuple. Like
- \function{map()} but stops when the shortest iterable is exhausted
- instead of filling in \code{None} for shorter iterables. The reason
- for the difference is that infinite iterator arguments are typically
- an error for \function{map()} (because the output is fully evaluated)
- but represent a common and useful way of supplying arguments to
- \function{imap()}.
- Equivalent to:
-
- \begin{verbatim}
- def imap(function, *iterables):
- iterables = map(iter, iterables)
- while True:
- args = [next(i) for i in iterables]
- if function is None:
- yield tuple(args)
- else:
- yield function(*args)
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{islice}{iterable, \optional{start,} stop \optional{, step}}
- Make an iterator that returns selected elements from the iterable.
- If \var{start} is non-zero, then elements from the iterable are skipped
- until start is reached. Afterward, elements are returned consecutively
- unless \var{step} is set higher than one which results in items being
- skipped. If \var{stop} is \code{None}, then iteration continues until
- the iterator is exhausted, if at all; otherwise, it stops at the specified
- position. Unlike regular slicing,
- \function{islice()} does not support negative values for \var{start},
- \var{stop}, or \var{step}. Can be used to extract related fields
- from data where the internal structure has been flattened (for
- example, a multi-line report may list a name field on every
- third line). Equivalent to:
-
- \begin{verbatim}
- def islice(iterable, *args):
- s = slice(*args)
- it = iter(range(s.start or 0, s.stop or sys.maxint, s.step or 1))
- nexti = next(it)
- for i, element in enumerate(iterable):
- if i == nexti:
- yield element
- nexti = next(it)
- \end{verbatim}
-
- If \var{start} is \code{None}, then iteration starts at zero.
- If \var{step} is \code{None}, then the step defaults to one.
- \versionchanged[accept \code{None} values for default \var{start} and
- \var{step}]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{izip}{*iterables}
- Make an iterator that aggregates elements from each of the iterables.
- Like \function{zip()} except that it returns an iterator instead of
- a list. Used for lock-step iteration over several iterables at a
- time. Equivalent to:
-
- \begin{verbatim}
- def izip(*iterables):
- iterables = map(iter, iterables)
- while iterables:
- result = [next(it) for it in iterables]
- yield tuple(result)
- \end{verbatim}
-
- \versionchanged[When no iterables are specified, returns a zero length
- iterator instead of raising a \exception{TypeError}
- exception]{2.4}
-
- Note, the left-to-right evaluation order of the iterables is guaranteed.
- This makes possible an idiom for clustering a data series into n-length
- groups using \samp{izip(*[iter(s)]*n)}. For data that doesn't fit
- n-length groups exactly, the last tuple can be pre-padded with fill
- values using \samp{izip(*[chain(s, [None]*(n-1))]*n)}.
-
- Note, when \function{izip()} is used with unequal length inputs, subsequent
- iteration over the longer iterables cannot reliably be continued after
- \function{izip()} terminates. Potentially, up to one entry will be missing
- from each of the left-over iterables. This occurs because a value is fetched
- from each iterator in-turn, but the process ends when one of the iterators
- terminates. This leaves the last fetched values in limbo (they cannot be
- returned in a final, incomplete tuple and they are cannot be pushed back
- into the iterator for retrieval with \code{next(it)}). In general,
- \function{izip()} should only be used with unequal length inputs when you
- don't care about trailing, unmatched values from the longer iterables.
-\end{funcdesc}
-
-\begin{funcdesc}{izip_longest}{*iterables\optional{, fillvalue}}
- Make an iterator that aggregates elements from each of the iterables.
- If the iterables are of uneven length, missing values are filled-in
- with \var{fillvalue}. Iteration continues until the longest iterable
- is exhausted. Equivalent to:
-
- \begin{verbatim}
- def izip_longest(*args, **kwds):
- fillvalue = kwds.get('fillvalue')
- def sentinel(counter = ([fillvalue]*(len(args)-1)).pop):
- yield counter() # yields the fillvalue, or raises IndexError
- fillers = repeat(fillvalue)
- iters = [chain(it, sentinel(), fillers) for it in args]
- try:
- for tup in izip(*iters):
- yield tup
- except IndexError:
- pass
- \end{verbatim}
-
- If one of the iterables is potentially infinite, then the
- \function{izip_longest()} function should be wrapped with something
- that limits the number of calls (for example \function{islice()} or
- \function{take()}).
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{repeat}{object\optional{, times}}
- Make an iterator that returns \var{object} over and over again.
- Runs indefinitely unless the \var{times} argument is specified.
- Used as argument to \function{imap()} for invariant parameters
- to the called function. Also used with \function{izip()} to create
- an invariant part of a tuple record. Equivalent to:
-
- \begin{verbatim}
- def repeat(object, times=None):
- if times is None:
- while True:
- yield object
- else:
- for i in range(times):
- yield object
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{starmap}{function, iterable}
- Make an iterator that computes the function using arguments tuples
- obtained from the iterable. Used instead of \function{imap()} when
- argument parameters are already grouped in tuples from a single iterable
- (the data has been ``pre-zipped''). The difference between
- \function{imap()} and \function{starmap()} parallels the distinction
- between \code{function(a,b)} and \code{function(*c)}.
- Equivalent to:
-
- \begin{verbatim}
- def starmap(function, iterable):
- iterable = iter(iterable)
- while True:
- yield function(*next(iterable))
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{takewhile}{predicate, iterable}
- Make an iterator that returns elements from the iterable as long as
- the predicate is true. Equivalent to:
-
- \begin{verbatim}
- def takewhile(predicate, iterable):
- for x in iterable:
- if predicate(x):
- yield x
- else:
- break
- \end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{tee}{iterable\optional{, n=2}}
- Return \var{n} independent iterators from a single iterable.
- The case where \code{n==2} is equivalent to:
-
- \begin{verbatim}
- def tee(iterable):
- def gen(next, data={}, cnt=[0]):
- for i in count():
- if i == cnt[0]:
- item = data[i] = next()
- cnt[0] += 1
- else:
- item = data.pop(i)
- yield item
- it = iter(iterable)
- return (gen(it.__next__), gen(it.__next__))
- \end{verbatim}
-
- Note, once \function{tee()} has made a split, the original \var{iterable}
- should not be used anywhere else; otherwise, the \var{iterable} could get
- advanced without the tee objects being informed.
-
- Note, this member of the toolkit may require significant auxiliary
- storage (depending on how much temporary data needs to be stored).
- In general, if one iterator is going to use most or all of the data before
- the other iterator, it is faster to use \function{list()} instead of
- \function{tee()}.
- \versionadded{2.4}
-\end{funcdesc}
-
-
-\subsection{Examples \label{itertools-example}}
-
-The following examples show common uses for each tool and
-demonstrate ways they can be combined.
-
-\begin{verbatim}
-
->>> amounts = [120.15, 764.05, 823.14]
->>> for checknum, amount in izip(count(1200), amounts):
-... print 'Check %d is for $%.2f' % (checknum, amount)
-...
-Check 1200 is for $120.15
-Check 1201 is for $764.05
-Check 1202 is for $823.14
-
->>> import operator
->>> for cube in imap(operator.pow, range(1,5), repeat(3)):
-... print cube
-...
-1
-8
-27
-64
-
->>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura',
- '', 'martin', '', 'walter', '', 'mark']
->>> for name in islice(reportlines, 3, None, 2):
-... print name.title()
-...
-Alex
-Laura
-Martin
-Walter
-Mark
-
-# Show a dictionary sorted and grouped by value
->>> from operator import itemgetter
->>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3)
->>> di = sorted(d.iteritems(), key=itemgetter(1))
->>> for k, g in groupby(di, key=itemgetter(1)):
-... print k, map(itemgetter(0), g)
-...
-1 ['a', 'c', 'e']
-2 ['b', 'd', 'f']
-3 ['g']
-
-# Find runs of consecutive numbers using groupby. The key to the solution
-# is differencing with a range so that consecutive numbers all appear in
-# same group.
->>> data = [ 1, 4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
->>> for k, g in groupby(enumerate(data), lambda t:t[0]-t[1]):
-... print map(operator.itemgetter(1), g)
-...
-[1]
-[4, 5, 6]
-[10]
-[15, 16, 17, 18]
-[22]
-[25, 26, 27, 28]
-
-\end{verbatim}
-
-
-\subsection{Recipes \label{itertools-recipes}}
-
-This section shows recipes for creating an extended toolset using the
-existing itertools as building blocks.
-
-The extended tools offer the same high performance as the underlying
-toolset. The superior memory performance is kept by processing elements one
-at a time rather than bringing the whole iterable into memory all at once.
-Code volume is kept small by linking the tools together in a functional style
-which helps eliminate temporary variables. High speed is retained by
-preferring ``vectorized'' building blocks over the use of for-loops and
-generators which incur interpreter overhead.
-
-
-\begin{verbatim}
-def take(n, seq):
- return list(islice(seq, n))
-
-def enumerate(iterable):
- return izip(count(), iterable)
-
-def tabulate(function):
- "Return function(0), function(1), ..."
- return imap(function, count())
-
-def iteritems(mapping):
- return izip(mapping.iterkeys(), mapping.itervalues())
-
-def nth(iterable, n):
- "Returns the nth item or raise StopIteration"
- return islice(iterable, n, None).next()
-
-def all(seq, pred=None):
- "Returns True if pred(x) is true for every element in the iterable"
- for elem in ifilterfalse(pred, seq):
- return False
- return True
-
-def any(seq, pred=None):
- "Returns True if pred(x) is true for at least one element in the iterable"
- for elem in ifilter(pred, seq):
- return True
- return False
-
-def no(seq, pred=None):
- "Returns True if pred(x) is false for every element in the iterable"
- for elem in ifilter(pred, seq):
- return False
- return True
-
-def quantify(seq, pred=None):
- "Count how many times the predicate is true in the sequence"
- return sum(imap(pred, seq))
-
-def padnone(seq):
- """Returns the sequence elements and then returns None indefinitely.
-
- Useful for emulating the behavior of the built-in map() function.
- """
- return chain(seq, repeat(None))
-
-def ncycles(seq, n):
- "Returns the sequence elements n times"
- return chain(*repeat(seq, n))
-
-def dotproduct(vec1, vec2):
- return sum(imap(operator.mul, vec1, vec2))
-
-def flatten(listOfLists):
- return list(chain(*listOfLists))
-
-def repeatfunc(func, times=None, *args):
- """Repeat calls to func with specified arguments.
-
- Example: repeatfunc(random.random)
- """
- if times is None:
- return starmap(func, repeat(args))
- else:
- return starmap(func, repeat(args, times))
-
-def pairwise(iterable):
- "s -> (s0,s1), (s1,s2), (s2, s3), ..."
- a, b = tee(iterable)
- next(b, None)
- return izip(a, b)
-
-def grouper(n, iterable, padvalue=None):
- "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')"
- return izip(*[chain(iterable, repeat(padvalue, n-1))]*n)
-
-
-\end{verbatim}
diff --git a/Doc/lib/libkeyword.tex b/Doc/lib/libkeyword.tex
deleted file mode 100644
index 0c07cec..0000000
--- a/Doc/lib/libkeyword.tex
+++ /dev/null
@@ -1,20 +0,0 @@
-\section{\module{keyword} ---
- Testing for Python keywords}
-
-\declaremodule{standard}{keyword}
-\modulesynopsis{Test whether a string is a keyword in Python.}
-
-
-This module allows a Python program to determine if a string is a
-keyword.
-
-\begin{funcdesc}{iskeyword}{s}
-Return true if \var{s} is a Python keyword.
-\end{funcdesc}
-
-\begin{datadesc}{kwlist}
-Sequence containing all the keywords defined for the interpreter. If
-any keywords are defined to only be active when particular
-\module{__future__} statements are in effect, these will be included
-as well.
-\end{datadesc}
diff --git a/Doc/lib/liblinecache.tex b/Doc/lib/liblinecache.tex
deleted file mode 100644
index 72c7743..0000000
--- a/Doc/lib/liblinecache.tex
+++ /dev/null
@@ -1,50 +0,0 @@
-\section{\module{linecache} ---
- Random access to text lines}
-
-\declaremodule{standard}{linecache}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{This module provides random access to individual lines
- from text files.}
-
-
-The \module{linecache} module allows one to get any line from any file,
-while attempting to optimize internally, using a cache, the common case
-where many lines are read from a single file. This is used by the
-\refmodule{traceback} module to retrieve source lines for inclusion in
-the formatted traceback.
-
-The \module{linecache} module defines the following functions:
-
-\begin{funcdesc}{getline}{filename, lineno\optional{, module_globals}}
-Get line \var{lineno} from file named \var{filename}. This function
-will never throw an exception --- it will return \code{''} on errors
-(the terminating newline character will be included for lines that are
-found).
-
-If a file named \var{filename} is not found, the function will look
-for it in the module\indexiii{module}{search}{path} search path,
-\code{sys.path}, after first checking for a \pep{302} \code{__loader__}
-in \var{module_globals}, in case the module was imported from a zipfile
-or other non-filesystem import source.
-
-\versionadded[The \var{module_globals} parameter was added]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{clearcache}{}
-Clear the cache. Use this function if you no longer need lines from
-files previously read using \function{getline()}.
-\end{funcdesc}
-
-\begin{funcdesc}{checkcache}{\optional{filename}}
-Check the cache for validity. Use this function if files in the cache
-may have changed on disk, and you require the updated version. If
-\var{filename} is omitted, it will check all the entries in the cache.
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import linecache
->>> linecache.getline('/etc/passwd', 4)
-'sys:x:3:3:sys:/dev:/bin/sh\n'
-\end{verbatim}
diff --git a/Doc/lib/liblocale.tex b/Doc/lib/liblocale.tex
deleted file mode 100644
index 319d893..0000000
--- a/Doc/lib/liblocale.tex
+++ /dev/null
@@ -1,527 +0,0 @@
-\section{\module{locale} ---
- Internationalization services}
-
-\declaremodule{standard}{locale}
-\modulesynopsis{Internationalization services.}
-\moduleauthor{Martin von L\"owis}{martin@v.loewis.de}
-\sectionauthor{Martin von L\"owis}{martin@v.loewis.de}
-
-
-The \module{locale} module opens access to the \POSIX{} locale
-database and functionality. The \POSIX{} locale mechanism allows
-programmers to deal with certain cultural issues in an application,
-without requiring the programmer to know all the specifics of each
-country where the software is executed.
-
-The \module{locale} module is implemented on top of the
-\module{_locale}\refbimodindex{_locale} module, which in turn uses an
-ANSI C locale implementation if available.
-
-The \module{locale} module defines the following exception and
-functions:
-
-
-\begin{excdesc}{Error}
- Exception raised when \function{setlocale()} fails.
-\end{excdesc}
-
-\begin{funcdesc}{setlocale}{category\optional{, locale}}
- If \var{locale} is specified, it may be a string, a tuple of the
- form \code{(\var{language code}, \var{encoding})}, or \code{None}.
- If it is a tuple, it is converted to a string using the locale
- aliasing engine. If \var{locale} is given and not \code{None},
- \function{setlocale()} modifies the locale setting for the
- \var{category}. The available categories are listed in the data
- description below. The value is the name of a locale. An empty
- string specifies the user's default settings. If the modification of
- the locale fails, the exception \exception{Error} is raised. If
- successful, the new locale setting is returned.
-
- If \var{locale} is omitted or \code{None}, the current setting for
- \var{category} is returned.
-
- \function{setlocale()} is not thread safe on most systems.
- Applications typically start with a call of
-
-\begin{verbatim}
-import locale
-locale.setlocale(locale.LC_ALL, '')
-\end{verbatim}
-
- This sets the locale for all categories to the user's default
- setting (typically specified in the \envvar{LANG} environment
- variable). If the locale is not changed thereafter, using
- multithreading should not cause problems.
-
- \versionchanged[Added support for tuple values of the \var{locale}
- parameter]{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{localeconv}{}
- Returns the database of the local conventions as a dictionary.
- This dictionary has the following strings as keys:
-
- \begin{tableiii}{l|l|p{3in}}{constant}{Category}{Key}{Meaning}
- \lineiii{LC_NUMERIC}{\code{'decimal_point'}}
- {Decimal point character.}
- \lineiii{}{\code{'grouping'}}
- {Sequence of numbers specifying which relative positions
- the \code{'thousands_sep'} is expected. If the sequence is
- terminated with \constant{CHAR_MAX}, no further grouping
- is performed. If the sequence terminates with a \code{0},
- the last group size is repeatedly used.}
- \lineiii{}{\code{'thousands_sep'}}
- {Character used between groups.}\hline
- \lineiii{LC_MONETARY}{\code{'int_curr_symbol'}}
- {International currency symbol.}
- \lineiii{}{\code{'currency_symbol'}}
- {Local currency symbol.}
- \lineiii{}{\code{'p_cs_precedes/n_cs_precedes'}}
- {Whether the currency symbol precedes the value (for positive resp.
- negative values).}
- \lineiii{}{\code{'p_sep_by_space/n_sep_by_space'}}
- {Whether the currency symbol is separated from the value
- by a space (for positive resp. negative values).}
- \lineiii{}{\code{'mon_decimal_point'}}
- {Decimal point used for monetary values.}
- \lineiii{}{\code{'frac_digits'}}
- {Number of fractional digits used in local formatting
- of monetary values.}
- \lineiii{}{\code{'int_frac_digits'}}
- {Number of fractional digits used in international
- formatting of monetary values.}
- \lineiii{}{\code{'mon_thousands_sep'}}
- {Group separator used for monetary values.}
- \lineiii{}{\code{'mon_grouping'}}
- {Equivalent to \code{'grouping'}, used for monetary
- values.}
- \lineiii{}{\code{'positive_sign'}}
- {Symbol used to annotate a positive monetary value.}
- \lineiii{}{\code{'negative_sign'}}
- {Symbol used to annotate a negative monetary value.}
- \lineiii{}{\code{'p_sign_posn/n_sign_posn'}}
- {The position of the sign (for positive resp. negative values), see below.}
- \end{tableiii}
-
- All numeric values can be set to \constant{CHAR_MAX} to indicate that
- there is no value specified in this locale.
-
- The possible values for \code{'p_sign_posn'} and
- \code{'n_sign_posn'} are given below.
-
- \begin{tableii}{c|l}{code}{Value}{Explanation}
- \lineii{0}{Currency and value are surrounded by parentheses.}
- \lineii{1}{The sign should precede the value and currency symbol.}
- \lineii{2}{The sign should follow the value and currency symbol.}
- \lineii{3}{The sign should immediately precede the value.}
- \lineii{4}{The sign should immediately follow the value.}
- \lineii{\constant{CHAR_MAX}}{Nothing is specified in this locale.}
- \end{tableii}
-\end{funcdesc}
-
-\begin{funcdesc}{nl_langinfo}{option}
-
-Return some locale-specific information as a string. This function is
-not available on all systems, and the set of possible options might
-also vary across platforms. The possible argument values are numbers,
-for which symbolic constants are available in the locale module.
-
-\end{funcdesc}
-
-\begin{funcdesc}{getdefaultlocale}{\optional{envvars}}
- Tries to determine the default locale settings and returns
- them as a tuple of the form \code{(\var{language code},
- \var{encoding})}.
-
- According to \POSIX, a program which has not called
- \code{setlocale(LC_ALL, '')} runs using the portable \code{'C'}
- locale. Calling \code{setlocale(LC_ALL, '')} lets it use the
- default locale as defined by the \envvar{LANG} variable. Since we
- do not want to interfere with the current locale setting we thus
- emulate the behavior in the way described above.
-
- To maintain compatibility with other platforms, not only the
- \envvar{LANG} variable is tested, but a list of variables given as
- envvars parameter. The first found to be defined will be
- used. \var{envvars} defaults to the search path used in GNU gettext;
- it must always contain the variable name \samp{LANG}. The GNU
- gettext search path contains \code{'LANGUAGE'}, \code{'LC_ALL'},
- \code{'LC_CTYPE'}, and \code{'LANG'}, in that order.
-
- Except for the code \code{'C'}, the language code corresponds to
- \rfc{1766}. \var{language code} and \var{encoding} may be
- \code{None} if their values cannot be determined.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{getlocale}{\optional{category}}
- Returns the current setting for the given locale category as
- sequence containing \var{language code}, \var{encoding}.
- \var{category} may be one of the \constant{LC_*} values except
- \constant{LC_ALL}. It defaults to \constant{LC_CTYPE}.
-
- Except for the code \code{'C'}, the language code corresponds to
- \rfc{1766}. \var{language code} and \var{encoding} may be
- \code{None} if their values cannot be determined.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{getpreferredencoding}{\optional{do_setlocale}}
- Return the encoding used for text data, according to user
- preferences. User preferences are expressed differently on
- different systems, and might not be available programmatically on
- some systems, so this function only returns a guess.
-
- On some systems, it is necessary to invoke \function{setlocale}
- to obtain the user preferences, so this function is not thread-safe.
- If invoking setlocale is not necessary or desired, \var{do_setlocale}
- should be set to \code{False}.
-
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{normalize}{localename}
- Returns a normalized locale code for the given locale name. The
- returned locale code is formatted for use with
- \function{setlocale()}. If normalization fails, the original name
- is returned unchanged.
-
- If the given encoding is not known, the function defaults to
- the default encoding for the locale code just like
- \function{setlocale()}.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{resetlocale}{\optional{category}}
- Sets the locale for \var{category} to the default setting.
-
- The default setting is determined by calling
- \function{getdefaultlocale()}. \var{category} defaults to
- \constant{LC_ALL}.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{strcoll}{string1, string2}
- Compares two strings according to the current
- \constant{LC_COLLATE} setting. As any other compare function,
- returns a negative, or a positive value, or \code{0}, depending on
- whether \var{string1} collates before or after \var{string2} or is
- equal to it.
-\end{funcdesc}
-
-\begin{funcdesc}{strxfrm}{string}
- Transforms a string to one that can be used for the built-in
- function \function{cmp()}\bifuncindex{cmp}, and still returns
- locale-aware results. This function can be used when the same
- string is compared repeatedly, e.g. when collating a sequence of
- strings.
-\end{funcdesc}
-
-\begin{funcdesc}{format}{format, val\optional{, grouping\optional{, monetary}}}
- Formats a number \var{val} according to the current
- \constant{LC_NUMERIC} setting. The format follows the conventions
- of the \code{\%} operator. For floating point values, the decimal
- point is modified if appropriate. If \var{grouping} is true, also
- takes the grouping into account.
-
- If \var{monetary} is true, the conversion uses monetary thousands
- separator and grouping strings.
-
- Please note that this function will only work for exactly one \%char
- specifier. For whole format strings, use \function{format_string()}.
-
- \versionchanged[Added the \var{monetary} parameter]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{format_string}{format, val\optional{, grouping}}
- Processes formatting specifiers as in \code{format \% val},
- but takes the current locale settings into account.
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{currency}{val\optional{, symbol\optional{, grouping\optional{, international}}}}
- Formats a number \var{val} according to the current \constant{LC_MONETARY}
- settings.
-
- The returned string includes the currency symbol if \var{symbol} is true,
- which is the default.
- If \var{grouping} is true (which is not the default), grouping is done with
- the value.
- If \var{international} is true (which is not the default), the international
- currency symbol is used.
-
- Note that this function will not work with the `C' locale, so you have to set
- a locale via \function{setlocale()} first.
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{str}{float}
- Formats a floating point number using the same format as the
- built-in function \code{str(\var{float})}, but takes the decimal
- point into account.
-\end{funcdesc}
-
-\begin{funcdesc}{atof}{string}
- Converts a string to a floating point number, following the
- \constant{LC_NUMERIC} settings.
-\end{funcdesc}
-
-\begin{funcdesc}{atoi}{string}
- Converts a string to an integer, following the
- \constant{LC_NUMERIC} conventions.
-\end{funcdesc}
-
-\begin{datadesc}{LC_CTYPE}
-\refstmodindex{string}
- Locale category for the character type functions. Depending on the
- settings of this category, the functions of module
- \refmodule{string} dealing with case change their behaviour.
-\end{datadesc}
-
-\begin{datadesc}{LC_COLLATE}
- Locale category for sorting strings. The functions
- \function{strcoll()} and \function{strxfrm()} of the
- \module{locale} module are affected.
-\end{datadesc}
-
-\begin{datadesc}{LC_TIME}
- Locale category for the formatting of time. The function
- \function{time.strftime()} follows these conventions.
-\end{datadesc}
-
-\begin{datadesc}{LC_MONETARY}
- Locale category for formatting of monetary values. The available
- options are available from the \function{localeconv()} function.
-\end{datadesc}
-
-\begin{datadesc}{LC_MESSAGES}
- Locale category for message display. Python currently does not
- support application specific locale-aware messages. Messages
- displayed by the operating system, like those returned by
- \function{os.strerror()} might be affected by this category.
-\end{datadesc}
-
-\begin{datadesc}{LC_NUMERIC}
- Locale category for formatting numbers. The functions
- \function{format()}, \function{atoi()}, \function{atof()} and
- \function{str()} of the \module{locale} module are affected by that
- category. All other numeric formatting operations are not
- affected.
-\end{datadesc}
-
-\begin{datadesc}{LC_ALL}
- Combination of all locale settings. If this flag is used when the
- locale is changed, setting the locale for all categories is
- attempted. If that fails for any category, no category is changed at
- all. When the locale is retrieved using this flag, a string
- indicating the setting for all categories is returned. This string
- can be later used to restore the settings.
-\end{datadesc}
-
-\begin{datadesc}{CHAR_MAX}
- This is a symbolic constant used for different values returned by
- \function{localeconv()}.
-\end{datadesc}
-
-The \function{nl_langinfo} function accepts one of the following keys.
-Most descriptions are taken from the corresponding description in the
-GNU C library.
-
-\begin{datadesc}{CODESET}
-Return a string with the name of the character encoding used in the
-selected locale.
-\end{datadesc}
-
-\begin{datadesc}{D_T_FMT}
-Return a string that can be used as a format string for strftime(3) to
-represent time and date in a locale-specific way.
-\end{datadesc}
-
-\begin{datadesc}{D_FMT}
-Return a string that can be used as a format string for strftime(3) to
-represent a date in a locale-specific way.
-\end{datadesc}
-
-\begin{datadesc}{T_FMT}
-Return a string that can be used as a format string for strftime(3) to
-represent a time in a locale-specific way.
-\end{datadesc}
-
-\begin{datadesc}{T_FMT_AMPM}
-The return value can be used as a format string for `strftime' to
-represent time in the am/pm format.
-\end{datadesc}
-
-\begin{datadesc}{DAY_1 ... DAY_7}
-Return name of the n-th day of the week. \warning{This
-follows the US convention of \constant{DAY_1} being Sunday, not the
-international convention (ISO 8601) that Monday is the first day of
-the week.}
-\end{datadesc}
-
-\begin{datadesc}{ABDAY_1 ... ABDAY_7}
-Return abbreviated name of the n-th day of the week.
-\end{datadesc}
-
-\begin{datadesc}{MON_1 ... MON_12}
-Return name of the n-th month.
-\end{datadesc}
-
-\begin{datadesc}{ABMON_1 ... ABMON_12}
-Return abbreviated name of the n-th month.
-\end{datadesc}
-
-\begin{datadesc}{RADIXCHAR}
-Return radix character (decimal dot, decimal comma, etc.)
-\end{datadesc}
-
-\begin{datadesc}{THOUSEP}
-Return separator character for thousands (groups of three digits).
-\end{datadesc}
-
-\begin{datadesc}{YESEXPR}
-Return a regular expression that can be used with the regex
-function to recognize a positive response to a yes/no question.
-\warning{The expression is in the syntax suitable for the
-\cfunction{regex()} function from the C library, which might differ
-from the syntax used in \refmodule{re}.}
-\end{datadesc}
-
-\begin{datadesc}{NOEXPR}
-Return a regular expression that can be used with the regex(3)
-function to recognize a negative response to a yes/no question.
-\end{datadesc}
-
-\begin{datadesc}{CRNCYSTR}
-Return the currency symbol, preceded by "-" if the symbol should
-appear before the value, "+" if the symbol should appear after the
-value, or "." if the symbol should replace the radix character.
-\end{datadesc}
-
-\begin{datadesc}{ERA}
-The return value represents the era used in the current locale.
-
-Most locales do not define this value. An example of a locale which
-does define this value is the Japanese one. In Japan, the traditional
-representation of dates includes the name of the era corresponding to
-the then-emperor's reign.
-
-Normally it should not be necessary to use this value directly.
-Specifying the \code{E} modifier in their format strings causes the
-\function{strftime} function to use this information. The format of the
-returned string is not specified, and therefore you should not assume
-knowledge of it on different systems.
-\end{datadesc}
-
-\begin{datadesc}{ERA_YEAR}
-The return value gives the year in the relevant era of the locale.
-\end{datadesc}
-
-\begin{datadesc}{ERA_D_T_FMT}
-This return value can be used as a format string for
-\function{strftime} to represent dates and times in a locale-specific
-era-based way.
-\end{datadesc}
-
-\begin{datadesc}{ERA_D_FMT}
-This return value can be used as a format string for
-\function{strftime} to represent time in a locale-specific era-based
-way.
-\end{datadesc}
-
-\begin{datadesc}{ALT_DIGITS}
-The return value is a representation of up to 100 values used to
-represent the values 0 to 99.
-\end{datadesc}
-
-Example:
-
-\begin{verbatim}
->>> import locale
->>> loc = locale.getlocale(locale.LC_ALL) # get current locale
->>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
->>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
->>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
->>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
->>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
-\end{verbatim}
-
-
-\subsection{Background, details, hints, tips and caveats}
-
-The C standard defines the locale as a program-wide property that may
-be relatively expensive to change. On top of that, some
-implementation are broken in such a way that frequent locale changes
-may cause core dumps. This makes the locale somewhat painful to use
-correctly.
-
-Initially, when a program is started, the locale is the \samp{C} locale, no
-matter what the user's preferred locale is. The program must
-explicitly say that it wants the user's preferred locale settings by
-calling \code{setlocale(LC_ALL, '')}.
-
-It is generally a bad idea to call \function{setlocale()} in some library
-routine, since as a side effect it affects the entire program. Saving
-and restoring it is almost as bad: it is expensive and affects other
-threads that happen to run before the settings have been restored.
-
-If, when coding a module for general use, you need a locale
-independent version of an operation that is affected by the locale
-(such as \function{string.lower()}, or certain formats used with
-\function{time.strftime()}), you will have to find a way to do it
-without using the standard library routine. Even better is convincing
-yourself that using locale settings is okay. Only as a last resort
-should you document that your module is not compatible with
-non-\samp{C} locale settings.
-
-The case conversion functions in the
-\refmodule{string}\refstmodindex{string} module are affected by the
-locale settings. When a call to the \function{setlocale()} function
-changes the \constant{LC_CTYPE} settings, the variables
-\code{string.lowercase}, \code{string.uppercase} and
-\code{string.letters} are recalculated. Note that code that uses
-these variable through `\keyword{from} ... \keyword{import} ...',
-e.g.\ \code{from string import letters}, is not affected by subsequent
-\function{setlocale()} calls.
-
-The only way to perform numeric operations according to the locale
-is to use the special functions defined by this module:
-\function{atof()}, \function{atoi()}, \function{format()},
-\function{str()}.
-
-\subsection{For extension writers and programs that embed Python
- \label{embedding-locale}}
-
-Extension modules should never call \function{setlocale()}, except to
-find out what the current locale is. But since the return value can
-only be used portably to restore it, that is not very useful (except
-perhaps to find out whether or not the locale is \samp{C}).
-
-When Python code uses the \module{locale} module to change the locale,
-this also affects the embedding application. If the embedding
-application doesn't want this to happen, it should remove the
-\module{_locale} extension module (which does all the work) from the
-table of built-in modules in the \file{config.c} file, and make sure
-that the \module{_locale} module is not accessible as a shared library.
-
-
-\subsection{Access to message catalogs \label{locale-gettext}}
-
-The locale module exposes the C library's gettext interface on systems
-that provide this interface. It consists of the functions
-\function{gettext()}, \function{dgettext()}, \function{dcgettext()},
-\function{textdomain()}, \function{bindtextdomain()}, and
-\function{bind_textdomain_codeset()}. These are similar to the same
-functions in the \refmodule{gettext} module, but use the C library's
-binary format for message catalogs, and the C library's search
-algorithms for locating message catalogs.
-
-Python applications should normally find no need to invoke these
-functions, and should use \refmodule{gettext} instead. A known
-exception to this rule are applications that link use additional C
-libraries which internally invoke \cfunction{gettext()} or
-\function{dcgettext()}. For these applications, it may be necessary to
-bind the text domain, so that the libraries can properly locate their
-message catalogs.
diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex
deleted file mode 100644
index c5c3e4e..0000000
--- a/Doc/lib/liblogging.tex
+++ /dev/null
@@ -1,1768 +0,0 @@
-\section{\module{logging} ---
- Logging facility for Python}
-
-\declaremodule{standard}{logging}
-
-% These apply to all modules, and may be given more than once:
-
-\moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
-\sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
-
-\modulesynopsis{Logging module for Python based on \pep{282}.}
-
-\indexii{Errors}{logging}
-
-\versionadded{2.3}
-This module defines functions and classes which implement a flexible
-error logging system for applications.
-
-Logging is performed by calling methods on instances of the
-\class{Logger} class (hereafter called \dfn{loggers}). Each instance has a
-name, and they are conceptually arranged in a name space hierarchy
-using dots (periods) as separators. For example, a logger named
-"scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".
-Logger names can be anything you want, and indicate the area of an
-application in which a logged message originates.
-
-Logged messages also have levels of importance associated with them.
-The default levels provided are \constant{DEBUG}, \constant{INFO},
-\constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a
-convenience, you indicate the importance of a logged message by calling
-an appropriate method of \class{Logger}. The methods are
-\method{debug()}, \method{info()}, \method{warning()}, \method{error()} and
-\method{critical()}, which mirror the default levels. You are not
-constrained to use these levels: you can specify your own and use a
-more general \class{Logger} method, \method{log()}, which takes an
-explicit level argument.
-
-The numeric values of logging levels are given in the following table. These
-are primarily of interest if you want to define your own levels, and need
-them to have specific values relative to the predefined levels. If you
-define a level with the same numeric value, it overwrites the predefined
-value; the predefined name is lost.
-
-\begin{tableii}{l|l}{code}{Level}{Numeric value}
- \lineii{CRITICAL}{50}
- \lineii{ERROR}{40}
- \lineii{WARNING}{30}
- \lineii{INFO}{20}
- \lineii{DEBUG}{10}
- \lineii{NOTSET}{0}
-\end{tableii}
-
-Levels can also be associated with loggers, being set either by the
-developer or through loading a saved logging configuration. When a
-logging method is called on a logger, the logger compares its own
-level with the level associated with the method call. If the logger's
-level is higher than the method call's, no logging message is actually
-generated. This is the basic mechanism controlling the verbosity of
-logging output.
-
-Logging messages are encoded as instances of the \class{LogRecord} class.
-When a logger decides to actually log an event, a \class{LogRecord}
-instance is created from the logging message.
-
-Logging messages are subjected to a dispatch mechanism through the
-use of \dfn{handlers}, which are instances of subclasses of the
-\class{Handler} class. Handlers are responsible for ensuring that a logged
-message (in the form of a \class{LogRecord}) ends up in a particular
-location (or set of locations) which is useful for the target audience for
-that message (such as end users, support desk staff, system administrators,
-developers). Handlers are passed \class{LogRecord} instances intended for
-particular destinations. Each logger can have zero, one or more handlers
-associated with it (via the \method{addHandler()} method of \class{Logger}).
-In addition to any handlers directly associated with a logger,
-\emph{all handlers associated with all ancestors of the logger} are
-called to dispatch the message.
-
-Just as for loggers, handlers can have levels associated with them.
-A handler's level acts as a filter in the same way as a logger's level does.
-If a handler decides to actually dispatch an event, the \method{emit()} method
-is used to send the message to its destination. Most user-defined subclasses
-of \class{Handler} will need to override this \method{emit()}.
-
-In addition to the base \class{Handler} class, many useful subclasses
-are provided:
-
-\begin{enumerate}
-
-\item \class{StreamHandler} instances send error messages to
-streams (file-like objects).
-
-\item \class{FileHandler} instances send error messages to disk
-files.
-
-\item \class{BaseRotatingHandler} is the base class for handlers that
-rotate log files at a certain point. It is not meant to be instantiated
-directly. Instead, use \class{RotatingFileHandler} or
-\class{TimedRotatingFileHandler}.
-
-\item \class{RotatingFileHandler} instances send error messages to disk
-files, with support for maximum log file sizes and log file rotation.
-
-\item \class{TimedRotatingFileHandler} instances send error messages to
-disk files rotating the log file at certain timed intervals.
-
-\item \class{SocketHandler} instances send error messages to
-TCP/IP sockets.
-
-\item \class{DatagramHandler} instances send error messages to UDP
-sockets.
-
-\item \class{SMTPHandler} instances send error messages to a
-designated email address.
-
-\item \class{SysLogHandler} instances send error messages to a
-\UNIX{} syslog daemon, possibly on a remote machine.
-
-\item \class{NTEventLogHandler} instances send error messages to a
-Windows NT/2000/XP event log.
-
-\item \class{MemoryHandler} instances send error messages to a
-buffer in memory, which is flushed whenever specific criteria are
-met.
-
-\item \class{HTTPHandler} instances send error messages to an
-HTTP server using either \samp{GET} or \samp{POST} semantics.
-
-\end{enumerate}
-
-The \class{StreamHandler} and \class{FileHandler} classes are defined
-in the core logging package. The other handlers are defined in a sub-
-module, \module{logging.handlers}. (There is also another sub-module,
-\module{logging.config}, for configuration functionality.)
-
-Logged messages are formatted for presentation through instances of the
-\class{Formatter} class. They are initialized with a format string
-suitable for use with the \% operator and a dictionary.
-
-For formatting multiple messages in a batch, instances of
-\class{BufferingFormatter} can be used. In addition to the format string
-(which is applied to each message in the batch), there is provision for
-header and trailer format strings.
-
-When filtering based on logger level and/or handler level is not enough,
-instances of \class{Filter} can be added to both \class{Logger} and
-\class{Handler} instances (through their \method{addFilter()} method).
-Before deciding to process a message further, both loggers and handlers
-consult all their filters for permission. If any filter returns a false
-value, the message is not processed further.
-
-The basic \class{Filter} functionality allows filtering by specific logger
-name. If this feature is used, messages sent to the named logger and its
-children are allowed through the filter, and all others dropped.
-
-In addition to the classes described above, there are a number of module-
-level functions.
-
-\begin{funcdesc}{getLogger}{\optional{name}}
-Return a logger with the specified name or, if no name is specified, return
-a logger which is the root logger of the hierarchy. If specified, the name
-is typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"}
-or \var{"a.b.c.d"}. Choice of these names is entirely up to the developer
-who is using logging.
-
-All calls to this function with a given name return the same logger instance.
-This means that logger instances never need to be passed between different
-parts of an application.
-\end{funcdesc}
-
-\begin{funcdesc}{getLoggerClass}{}
-Return either the standard \class{Logger} class, or the last class passed to
-\function{setLoggerClass()}. This function may be called from within a new
-class definition, to ensure that installing a customised \class{Logger} class
-will not undo customisations already applied by other code. For example:
-
-\begin{verbatim}
- class MyLogger(logging.getLoggerClass()):
- # ... override behaviour here
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{DEBUG} on the root logger.
-The \var{msg} is the message format string, and the \var{args} are the
-arguments which are merged into \var{msg} using the string formatting
-operator. (Note that this means that you can use keywords in the
-format string, together with a single dictionary argument.)
-
-There are two keyword arguments in \var{kwargs} which are inspected:
-\var{exc_info} which, if it does not evaluate as false, causes exception
-information to be added to the logging message. If an exception tuple (in the
-format returned by \function{sys.exc_info()}) is provided, it is used;
-otherwise, \function{sys.exc_info()} is called to get the exception
-information.
-
-The other optional keyword argument is \var{extra} which can be used to pass
-a dictionary which is used to populate the __dict__ of the LogRecord created
-for the logging event with user-defined attributes. These custom attributes
-can then be used as you like. For example, they could be incorporated into
-logged messages. For example:
-
-\begin{verbatim}
- FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
- logging.basicConfig(format=FORMAT)
- d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
- logging.warning("Protocol problem: %s", "connection reset", extra=d)
-\end{verbatim}
-
-would print something like
-\begin{verbatim}
-2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
-\end{verbatim}
-
-The keys in the dictionary passed in \var{extra} should not clash with the keys
-used by the logging system. (See the \class{Formatter} documentation for more
-information on which keys are used by the logging system.)
-
-If you choose to use these attributes in logged messages, you need to exercise
-some care. In the above example, for instance, the \class{Formatter} has been
-set up with a format string which expects 'clientip' and 'user' in the
-attribute dictionary of the LogRecord. If these are missing, the message will
-not be logged because a string formatting exception will occur. So in this
-case, you always need to pass the \var{extra} dictionary with these keys.
-
-While this might be annoying, this feature is intended for use in specialized
-circumstances, such as multi-threaded servers where the same code executes
-in many contexts, and interesting conditions which arise are dependent on this
-context (such as remote client IP address and authenticated user name, in the
-above example). In such circumstances, it is likely that specialized
-\class{Formatter}s would be used with particular \class{Handler}s.
-
-\versionchanged[\var{extra} was added]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{INFO} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{WARNING} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{ERROR} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{CRITICAL} on the root logger.
-The arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{exception}{msg\optional{, *args}}
-Logs a message with level \constant{ERROR} on the root logger.
-The arguments are interpreted as for \function{debug()}. Exception info
-is added to the logging message. This function should only be called
-from an exception handler.
-\end{funcdesc}
-
-\begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \var{level} on the root logger.
-The other arguments are interpreted as for \function{debug()}.
-\end{funcdesc}
-
-\begin{funcdesc}{disable}{lvl}
-Provides an overriding level \var{lvl} for all loggers which takes
-precedence over the logger's own level. When the need arises to
-temporarily throttle logging output down across the whole application,
-this function can be useful.
-\end{funcdesc}
-
-\begin{funcdesc}{addLevelName}{lvl, levelName}
-Associates level \var{lvl} with text \var{levelName} in an internal
-dictionary, which is used to map numeric levels to a textual
-representation, for example when a \class{Formatter} formats a message.
-This function can also be used to define your own levels. The only
-constraints are that all levels used must be registered using this
-function, levels should be positive integers and they should increase
-in increasing order of severity.
-\end{funcdesc}
-
-\begin{funcdesc}{getLevelName}{lvl}
-Returns the textual representation of logging level \var{lvl}. If the
-level is one of the predefined levels \constant{CRITICAL},
-\constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
-then you get the corresponding string. If you have associated levels
-with names using \function{addLevelName()} then the name you have associated
-with \var{lvl} is returned. If a numeric value corresponding to one of the
-defined levels is passed in, the corresponding string representation is
-returned. Otherwise, the string "Level \%s" \% lvl is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{makeLogRecord}{attrdict}
-Creates and returns a new \class{LogRecord} instance whose attributes are
-defined by \var{attrdict}. This function is useful for taking a pickled
-\class{LogRecord} attribute dictionary, sent over a socket, and reconstituting
-it as a \class{LogRecord} instance at the receiving end.
-\end{funcdesc}
-
-\begin{funcdesc}{basicConfig}{\optional{**kwargs}}
-Does basic configuration for the logging system by creating a
-\class{StreamHandler} with a default \class{Formatter} and adding it to
-the root logger. The functions \function{debug()}, \function{info()},
-\function{warning()}, \function{error()} and \function{critical()} will call
-\function{basicConfig()} automatically if no handlers are defined for the
-root logger.
-
-\versionchanged[Formerly, \function{basicConfig} did not take any keyword
-arguments]{2.4}
-
-The following keyword arguments are supported.
-
-\begin{tableii}{l|l}{code}{Format}{Description}
-\lineii{filename}{Specifies that a FileHandler be created, using the
-specified filename, rather than a StreamHandler.}
-\lineii{filemode}{Specifies the mode to open the file, if filename is
-specified (if filemode is unspecified, it defaults to 'a').}
-\lineii{format}{Use the specified format string for the handler.}
-\lineii{datefmt}{Use the specified date/time format.}
-\lineii{level}{Set the root logger level to the specified level.}
-\lineii{stream}{Use the specified stream to initialize the StreamHandler.
-Note that this argument is incompatible with 'filename' - if both
-are present, 'stream' is ignored.}
-\end{tableii}
-
-\end{funcdesc}
-
-\begin{funcdesc}{shutdown}{}
-Informs the logging system to perform an orderly shutdown by flushing and
-closing all handlers.
-\end{funcdesc}
-
-\begin{funcdesc}{setLoggerClass}{klass}
-Tells the logging system to use the class \var{klass} when instantiating a
-logger. The class should define \method{__init__()} such that only a name
-argument is required, and the \method{__init__()} should call
-\method{Logger.__init__()}. This function is typically called before any
-loggers are instantiated by applications which need to use custom logger
-behavior.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seepep{282}{A Logging System}
- {The proposal which described this feature for inclusion in
- the Python standard library.}
- \seelink{http://www.red-dove.com/python_logging.html}
- {Original Python \module{logging} package}
- {This is the original source for the \module{logging}
- package. The version of the package available from this
- site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x,
- which do not include the \module{logging} package in the standard
- library.}
-\end{seealso}
-
-
-\subsection{Logger Objects}
-
-Loggers have the following attributes and methods. Note that Loggers are
-never instantiated directly, but always through the module-level function
-\function{logging.getLogger(name)}.
-
-\begin{memberdesc}[Logger]{propagate}
-If this evaluates to false, logging messages are not passed by this
-logger or by child loggers to higher level (ancestor) loggers. The
-constructor sets this attribute to 1.
-\end{memberdesc}
-
-\begin{methoddesc}[Logger]{setLevel}{lvl}
-Sets the threshold for this logger to \var{lvl}. Logging messages
-which are less severe than \var{lvl} will be ignored. When a logger is
-created, the level is set to \constant{NOTSET} (which causes all messages
-to be processed when the logger is the root logger, or delegation to the
-parent when the logger is a non-root logger). Note that the root logger
-is created with level \constant{WARNING}.
-
-The term "delegation to the parent" means that if a logger has a level
-of NOTSET, its chain of ancestor loggers is traversed until either an
-ancestor with a level other than NOTSET is found, or the root is
-reached.
-
-If an ancestor is found with a level other than NOTSET, then that
-ancestor's level is treated as the effective level of the logger where
-the ancestor search began, and is used to determine how a logging
-event is handled.
-
-If the root is reached, and it has a level of NOTSET, then all
-messages will be processed. Otherwise, the root's level will be used
-as the effective level.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{isEnabledFor}{lvl}
-Indicates if a message of severity \var{lvl} would be processed by
-this logger. This method checks first the module-level level set by
-\function{logging.disable(lvl)} and then the logger's effective level as
-determined by \method{getEffectiveLevel()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{getEffectiveLevel}{}
-Indicates the effective level for this logger. If a value other than
-\constant{NOTSET} has been set using \method{setLevel()}, it is returned.
-Otherwise, the hierarchy is traversed towards the root until a value
-other than \constant{NOTSET} is found, and that value is returned.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{debug}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{DEBUG} on this logger.
-The \var{msg} is the message format string, and the \var{args} are the
-arguments which are merged into \var{msg} using the string formatting
-operator. (Note that this means that you can use keywords in the
-format string, together with a single dictionary argument.)
-
-There are two keyword arguments in \var{kwargs} which are inspected:
-\var{exc_info} which, if it does not evaluate as false, causes exception
-information to be added to the logging message. If an exception tuple (in the
-format returned by \function{sys.exc_info()}) is provided, it is used;
-otherwise, \function{sys.exc_info()} is called to get the exception
-information.
-
-The other optional keyword argument is \var{extra} which can be used to pass
-a dictionary which is used to populate the __dict__ of the LogRecord created
-for the logging event with user-defined attributes. These custom attributes
-can then be used as you like. For example, they could be incorporated into
-logged messages. For example:
-
-\begin{verbatim}
- FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
- logging.basicConfig(format=FORMAT)
- dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
- logger = logging.getLogger("tcpserver")
- logger.warning("Protocol problem: %s", "connection reset", extra=d)
-\end{verbatim}
-
-would print something like
-\begin{verbatim}
-2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
-\end{verbatim}
-
-The keys in the dictionary passed in \var{extra} should not clash with the keys
-used by the logging system. (See the \class{Formatter} documentation for more
-information on which keys are used by the logging system.)
-
-If you choose to use these attributes in logged messages, you need to exercise
-some care. In the above example, for instance, the \class{Formatter} has been
-set up with a format string which expects 'clientip' and 'user' in the
-attribute dictionary of the LogRecord. If these are missing, the message will
-not be logged because a string formatting exception will occur. So in this
-case, you always need to pass the \var{extra} dictionary with these keys.
-
-While this might be annoying, this feature is intended for use in specialized
-circumstances, such as multi-threaded servers where the same code executes
-in many contexts, and interesting conditions which arise are dependent on this
-context (such as remote client IP address and authenticated user name, in the
-above example). In such circumstances, it is likely that specialized
-\class{Formatter}s would be used with particular \class{Handler}s.
-
-\versionchanged[\var{extra} was added]{2.5}
-
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{info}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{INFO} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{warning}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{WARNING} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{error}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{ERROR} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{critical}{msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with level \constant{CRITICAL} on this logger.
-The arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
-Logs a message with integer level \var{lvl} on this logger.
-The other arguments are interpreted as for \method{debug()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{exception}{msg\optional{, *args}}
-Logs a message with level \constant{ERROR} on this logger.
-The arguments are interpreted as for \method{debug()}. Exception info
-is added to the logging message. This method should only be called
-from an exception handler.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{addFilter}{filt}
-Adds the specified filter \var{filt} to this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{removeFilter}{filt}
-Removes the specified filter \var{filt} from this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{filter}{record}
-Applies this logger's filters to the record and returns a true value if
-the record is to be processed.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{addHandler}{hdlr}
-Adds the specified handler \var{hdlr} to this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{removeHandler}{hdlr}
-Removes the specified handler \var{hdlr} from this logger.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{findCaller}{}
-Finds the caller's source filename and line number. Returns the filename,
-line number and function name as a 3-element tuple.
-\versionchanged[The function name was added. In earlier versions, the
-filename and line number were returned as a 2-element tuple.]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{handle}{record}
-Handles a record by passing it to all handlers associated with this logger
-and its ancestors (until a false value of \var{propagate} is found).
-This method is used for unpickled records received from a socket, as well
-as those created locally. Logger-level filtering is applied using
-\method{filter()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Logger]{makeRecord}{name, lvl, fn, lno, msg, args, exc_info
- \optional{, func, extra}}
-This is a factory method which can be overridden in subclasses to create
-specialized \class{LogRecord} instances.
-\versionchanged[\var{func} and \var{extra} were added]{2.5}
-\end{methoddesc}
-
-\subsection{Basic example \label{minimal-example}}
-
-\versionchanged[formerly \function{basicConfig} did not take any keyword
-arguments]{2.4}
-
-The \module{logging} package provides a lot of flexibility, and its
-configuration can appear daunting. This section demonstrates that simple
-use of the logging package is possible.
-
-The simplest example shows logging to the console:
-
-\begin{verbatim}
-import logging
-
-logging.debug('A debug message')
-logging.info('Some information')
-logging.warning('A shot across the bows')
-\end{verbatim}
-
-If you run the above script, you'll see this:
-\begin{verbatim}
-WARNING:root:A shot across the bows
-\end{verbatim}
-
-Because no particular logger was specified, the system used the root logger.
-The debug and info messages didn't appear because by default, the root
-logger is configured to only handle messages with a severity of WARNING
-or above. The message format is also a configuration default, as is the output
-destination of the messages - \code{sys.stderr}. The severity level,
-the message format and destination can be easily changed, as shown in
-the example below:
-
-\begin{verbatim}
-import logging
-
-logging.basicConfig(level=logging.DEBUG,
- format='%(asctime)s %(levelname)s %(message)s',
- filename='/tmp/myapp.log',
- filemode='w')
-logging.debug('A debug message')
-logging.info('Some information')
-logging.warning('A shot across the bows')
-\end{verbatim}
-
-The \method{basicConfig()} method is used to change the configuration
-defaults, which results in output (written to \code{/tmp/myapp.log})
-which should look something like the following:
-
-\begin{verbatim}
-2004-07-02 13:00:08,743 DEBUG A debug message
-2004-07-02 13:00:08,743 INFO Some information
-2004-07-02 13:00:08,743 WARNING A shot across the bows
-\end{verbatim}
-
-This time, all messages with a severity of DEBUG or above were handled,
-and the format of the messages was also changed, and output went to the
-specified file rather than the console.
-
-Formatting uses standard Python string formatting - see section
-\ref{typesseq-strings}. The format string takes the following
-common specifiers. For a complete list of specifiers, consult the
-\class{Formatter} documentation.
-
-\begin{tableii}{l|l}{code}{Format}{Description}
-\lineii{\%(name)s} {Name of the logger (logging channel).}
-\lineii{\%(levelname)s}{Text logging level for the message
- (\code{'DEBUG'}, \code{'INFO'},
- \code{'WARNING'}, \code{'ERROR'},
- \code{'CRITICAL'}).}
-\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord}
- was created. By default this is of the form
- ``2003-07-08 16:49:45,896'' (the numbers after the
- comma are millisecond portion of the time).}
-\lineii{\%(message)s} {The logged message.}
-\end{tableii}
-
-To change the date/time format, you can pass an additional keyword parameter,
-\var{datefmt}, as in the following:
-
-\begin{verbatim}
-import logging
-
-logging.basicConfig(level=logging.DEBUG,
- format='%(asctime)s %(levelname)-8s %(message)s',
- datefmt='%a, %d %b %Y %H:%M:%S',
- filename='/temp/myapp.log',
- filemode='w')
-logging.debug('A debug message')
-logging.info('Some information')
-logging.warning('A shot across the bows')
-\end{verbatim}
-
-which would result in output like
-
-\begin{verbatim}
-Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
-Fri, 02 Jul 2004 13:06:18 INFO Some information
-Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
-\end{verbatim}
-
-The date format string follows the requirements of \function{strftime()} -
-see the documentation for the \refmodule{time} module.
-
-If, instead of sending logging output to the console or a file, you'd rather
-use a file-like object which you have created separately, you can pass it
-to \function{basicConfig()} using the \var{stream} keyword argument. Note
-that if both \var{stream} and \var{filename} keyword arguments are passed,
-the \var{stream} argument is ignored.
-
-Of course, you can put variable information in your output. To do this,
-simply have the message be a format string and pass in additional arguments
-containing the variable information, as in the following example:
-
-\begin{verbatim}
-import logging
-
-logging.basicConfig(level=logging.DEBUG,
- format='%(asctime)s %(levelname)-8s %(message)s',
- datefmt='%a, %d %b %Y %H:%M:%S',
- filename='/temp/myapp.log',
- filemode='w')
-logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')
-\end{verbatim}
-
-which would result in
-
-\begin{verbatim}
-Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs
-\end{verbatim}
-
-\subsection{Logging to multiple destinations \label{multiple-destinations}}
-
-Let's say you want to log to console and file with different message formats
-and in differing circumstances. Say you want to log messages with levels
-of DEBUG and higher to file, and those messages at level INFO and higher to
-the console. Let's also assume that the file should contain timestamps, but
-the console messages should not. Here's how you can achieve this:
-
-\begin{verbatim}
-import logging
-
-# set up logging to file - see previous section for more details
-logging.basicConfig(level=logging.DEBUG,
- format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
- datefmt='%m-%d %H:%M',
- filename='/temp/myapp.log',
- filemode='w')
-# define a Handler which writes INFO messages or higher to the sys.stderr
-console = logging.StreamHandler()
-console.setLevel(logging.INFO)
-# set a format which is simpler for console use
-formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
-# tell the handler to use this format
-console.setFormatter(formatter)
-# add the handler to the root logger
-logging.getLogger('').addHandler(console)
-
-# Now, we can log to the root logger, or any other logger. First the root...
-logging.info('Jackdaws love my big sphinx of quartz.')
-
-# Now, define a couple of other loggers which might represent areas in your
-# application:
-
-logger1 = logging.getLogger('myapp.area1')
-logger2 = logging.getLogger('myapp.area2')
-
-logger1.debug('Quick zephyrs blow, vexing daft Jim.')
-logger1.info('How quickly daft jumping zebras vex.')
-logger2.warning('Jail zesty vixen who grabbed pay from quack.')
-logger2.error('The five boxing wizards jump quickly.')
-\end{verbatim}
-
-When you run this, on the console you will see
-
-\begin{verbatim}
-root : INFO Jackdaws love my big sphinx of quartz.
-myapp.area1 : INFO How quickly daft jumping zebras vex.
-myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
-myapp.area2 : ERROR The five boxing wizards jump quickly.
-\end{verbatim}
-
-and in the file you will see something like
-
-\begin{verbatim}
-10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.
-10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
-10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.
-10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
-10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly.
-\end{verbatim}
-
-As you can see, the DEBUG message only shows up in the file. The other
-messages are sent to both destinations.
-
-This example uses console and file handlers, but you can use any number and
-combination of handlers you choose.
-
-\subsection{Sending and receiving logging events across a network
-\label{network-logging}}
-
-Let's say you want to send logging events across a network, and handle them
-at the receiving end. A simple way of doing this is attaching a
-\class{SocketHandler} instance to the root logger at the sending end:
-
-\begin{verbatim}
-import logging, logging.handlers
-
-rootLogger = logging.getLogger('')
-rootLogger.setLevel(logging.DEBUG)
-socketHandler = logging.handlers.SocketHandler('localhost',
- logging.handlers.DEFAULT_TCP_LOGGING_PORT)
-# don't bother with a formatter, since a socket handler sends the event as
-# an unformatted pickle
-rootLogger.addHandler(socketHandler)
-
-# Now, we can log to the root logger, or any other logger. First the root...
-logging.info('Jackdaws love my big sphinx of quartz.')
-
-# Now, define a couple of other loggers which might represent areas in your
-# application:
-
-logger1 = logging.getLogger('myapp.area1')
-logger2 = logging.getLogger('myapp.area2')
-
-logger1.debug('Quick zephyrs blow, vexing daft Jim.')
-logger1.info('How quickly daft jumping zebras vex.')
-logger2.warning('Jail zesty vixen who grabbed pay from quack.')
-logger2.error('The five boxing wizards jump quickly.')
-\end{verbatim}
-
-At the receiving end, you can set up a receiver using the
-\module{SocketServer} module. Here is a basic working example:
-
-\begin{verbatim}
-import cPickle
-import logging
-import logging.handlers
-import SocketServer
-import struct
-
-
-class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
- """Handler for a streaming logging request.
-
- This basically logs the record using whatever logging policy is
- configured locally.
- """
-
- def handle(self):
- """
- Handle multiple requests - each expected to be a 4-byte length,
- followed by the LogRecord in pickle format. Logs the record
- according to whatever policy is configured locally.
- """
- while 1:
- chunk = self.connection.recv(4)
- if len(chunk) < 4:
- break
- slen = struct.unpack(">L", chunk)[0]
- chunk = self.connection.recv(slen)
- while len(chunk) < slen:
- chunk = chunk + self.connection.recv(slen - len(chunk))
- obj = self.unPickle(chunk)
- record = logging.makeLogRecord(obj)
- self.handleLogRecord(record)
-
- def unPickle(self, data):
- return cPickle.loads(data)
-
- def handleLogRecord(self, record):
- # if a name is specified, we use the named logger rather than the one
- # implied by the record.
- if self.server.logname is not None:
- name = self.server.logname
- else:
- name = record.name
- logger = logging.getLogger(name)
- # N.B. EVERY record gets logged. This is because Logger.handle
- # is normally called AFTER logger-level filtering. If you want
- # to do filtering, do it at the client end to save wasting
- # cycles and network bandwidth!
- logger.handle(record)
-
-class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
- """simple TCP socket-based logging receiver suitable for testing.
- """
-
- allow_reuse_address = 1
-
- def __init__(self, host='localhost',
- port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
- handler=LogRecordStreamHandler):
- SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
- self.abort = 0
- self.timeout = 1
- self.logname = None
-
- def serve_until_stopped(self):
- import select
- abort = 0
- while not abort:
- rd, wr, ex = select.select([self.socket.fileno()],
- [], [],
- self.timeout)
- if rd:
- self.handle_request()
- abort = self.abort
-
-def main():
- logging.basicConfig(
- format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
- tcpserver = LogRecordSocketReceiver()
- print "About to start TCP server..."
- tcpserver.serve_until_stopped()
-
-if __name__ == "__main__":
- main()
-\end{verbatim}
-
-First run the server, and then the client. On the client side, nothing is
-printed on the console; on the server side, you should see something like:
-
-\begin{verbatim}
-About to start TCP server...
- 59 root INFO Jackdaws love my big sphinx of quartz.
- 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
- 69 myapp.area1 INFO How quickly daft jumping zebras vex.
- 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
- 69 myapp.area2 ERROR The five boxing wizards jump quickly.
-\end{verbatim}
-
-\subsection{Handler Objects}
-
-Handlers have the following attributes and methods. Note that
-\class{Handler} is never instantiated directly; this class acts as a
-base for more useful subclasses. However, the \method{__init__()}
-method in subclasses needs to call \method{Handler.__init__()}.
-
-\begin{methoddesc}[Handler]{__init__}{level=\constant{NOTSET}}
-Initializes the \class{Handler} instance by setting its level, setting
-the list of filters to the empty list and creating a lock (using
-\method{createLock()}) for serializing access to an I/O mechanism.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{createLock}{}
-Initializes a thread lock which can be used to serialize access to
-underlying I/O functionality which may not be threadsafe.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{acquire}{}
-Acquires the thread lock created with \method{createLock()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{release}{}
-Releases the thread lock acquired with \method{acquire()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{setLevel}{lvl}
-Sets the threshold for this handler to \var{lvl}. Logging messages which are
-less severe than \var{lvl} will be ignored. When a handler is created, the
-level is set to \constant{NOTSET} (which causes all messages to be processed).
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{setFormatter}{form}
-Sets the \class{Formatter} for this handler to \var{form}.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{addFilter}{filt}
-Adds the specified filter \var{filt} to this handler.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{removeFilter}{filt}
-Removes the specified filter \var{filt} from this handler.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{filter}{record}
-Applies this handler's filters to the record and returns a true value if
-the record is to be processed.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{flush}{}
-Ensure all logging output has been flushed. This version does
-nothing and is intended to be implemented by subclasses.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{close}{}
-Tidy up any resources used by the handler. This version does
-nothing and is intended to be implemented by subclasses.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{handle}{record}
-Conditionally emits the specified logging record, depending on
-filters which may have been added to the handler. Wraps the actual
-emission of the record with acquisition/release of the I/O thread
-lock.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{handleError}{record}
-This method should be called from handlers when an exception is
-encountered during an \method{emit()} call. By default it does nothing,
-which means that exceptions get silently ignored. This is what is
-mostly wanted for a logging system - most users will not care
-about errors in the logging system, they are more interested in
-application errors. You could, however, replace this with a custom
-handler if you wish. The specified record is the one which was being
-processed when the exception occurred.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{format}{record}
-Do formatting for a record - if a formatter is set, use it.
-Otherwise, use the default formatter for the module.
-\end{methoddesc}
-
-\begin{methoddesc}[Handler]{emit}{record}
-Do whatever it takes to actually log the specified logging record.
-This version is intended to be implemented by subclasses and so
-raises a \exception{NotImplementedError}.
-\end{methoddesc}
-
-\subsubsection{StreamHandler}
-
-The \class{StreamHandler} class, located in the core \module{logging}
-package, sends logging output to streams such as \var{sys.stdout},
-\var{sys.stderr} or any file-like object (or, more precisely, any
-object which supports \method{write()} and \method{flush()} methods).
-
-\begin{classdesc}{StreamHandler}{\optional{strm}}
-Returns a new instance of the \class{StreamHandler} class. If \var{strm} is
-specified, the instance will use it for logging output; otherwise,
-\var{sys.stderr} will be used.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-If a formatter is specified, it is used to format the record.
-The record is then written to the stream with a trailing newline.
-If exception information is present, it is formatted using
-\function{traceback.print_exception()} and appended to the stream.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-Flushes the stream by calling its \method{flush()} method. Note that
-the \method{close()} method is inherited from \class{Handler} and
-so does nothing, so an explicit \method{flush()} call may be needed
-at times.
-\end{methoddesc}
-
-\subsubsection{FileHandler}
-
-The \class{FileHandler} class, located in the core \module{logging}
-package, sends logging output to a disk file. It inherits the output
-functionality from \class{StreamHandler}.
-
-\begin{classdesc}{FileHandler}{filename\optional{, mode\optional{, encoding}}}
-Returns a new instance of the \class{FileHandler} class. The specified
-file is opened and used as the stream for logging. If \var{mode} is
-not specified, \constant{'a'} is used. If \var{encoding} is not \var{None},
-it is used to open the file with that encoding. By default, the file grows
-indefinitely.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Closes the file.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file.
-\end{methoddesc}
-
-\subsubsection{WatchedFileHandler}
-
-\versionadded{2.6}
-The \class{WatchedFileHandler} class, located in the \module{logging.handlers}
-module, is a \class{FileHandler} which watches the file it is logging to.
-If the file changes, it is closed and reopened using the file name.
-
-A file change can happen because of usage of programs such as \var{newsyslog}
-and \var{logrotate} which perform log file rotation. This handler, intended
-for use under Unix/Linux, watches the file to see if it has changed since the
-last emit. (A file is deemed to have changed if its device or inode have
-changed.) If the file has changed, the old file stream is closed, and the file
-opened to get a new stream.
-
-This handler is not appropriate for use under Windows, because under Windows
-open log files cannot be moved or renamed - logging opens the files with
-exclusive locks - and so there is no need for such a handler. Furthermore,
-\var{ST_INO} is not supported under Windows; \function{stat()} always returns
-zero for this value.
-
-\begin{classdesc}{WatchedFileHandler}{filename\optional{,mode\optional{,
- encoding}}}
-Returns a new instance of the \class{WatchedFileHandler} class. The specified
-file is opened and used as the stream for logging. If \var{mode} is
-not specified, \constant{'a'} is used. If \var{encoding} is not \var{None},
-it is used to open the file with that encoding. By default, the file grows
-indefinitely.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file, but first checks to see if the file has
-changed. If it has, the existing stream is flushed and closed and the file
-opened again, before outputting the record to the file.
-\end{methoddesc}
-
-\subsubsection{RotatingFileHandler}
-
-The \class{RotatingFileHandler} class, located in the \module{logging.handlers}
-module, supports rotation of disk log files.
-
-\begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
- maxBytes\optional{, backupCount}}}}
-Returns a new instance of the \class{RotatingFileHandler} class. The
-specified file is opened and used as the stream for logging. If
-\var{mode} is not specified, \code{'a'} is used. By default, the
-file grows indefinitely.
-
-You can use the \var{maxBytes} and
-\var{backupCount} values to allow the file to \dfn{rollover} at a
-predetermined size. When the size is about to be exceeded, the file is
-closed and a new file is silently opened for output. Rollover occurs
-whenever the current log file is nearly \var{maxBytes} in length; if
-\var{maxBytes} is zero, rollover never occurs. If \var{backupCount}
-is non-zero, the system will save old log files by appending the
-extensions ".1", ".2" etc., to the filename. For example, with
-a \var{backupCount} of 5 and a base file name of
-\file{app.log}, you would get \file{app.log},
-\file{app.log.1}, \file{app.log.2}, up to \file{app.log.5}. The file being
-written to is always \file{app.log}. When this file is filled, it is
-closed and renamed to \file{app.log.1}, and if files \file{app.log.1},
-\file{app.log.2}, etc. exist, then they are renamed to \file{app.log.2},
-\file{app.log.3} etc. respectively.
-\end{classdesc}
-
-\begin{methoddesc}{doRollover}{}
-Does a rollover, as described above.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file, catering for rollover as described previously.
-\end{methoddesc}
-
-\subsubsection{TimedRotatingFileHandler}
-
-The \class{TimedRotatingFileHandler} class, located in the
-\module{logging.handlers} module, supports rotation of disk log files
-at certain timed intervals.
-
-\begin{classdesc}{TimedRotatingFileHandler}{filename
- \optional{,when
- \optional{,interval
- \optional{,backupCount}}}}
-
-Returns a new instance of the \class{TimedRotatingFileHandler} class. The
-specified file is opened and used as the stream for logging. On rotating
-it also sets the filename suffix. Rotating happens based on the product
-of \var{when} and \var{interval}.
-
-You can use the \var{when} to specify the type of \var{interval}. The
-list of possible values is, note that they are not case sensitive:
-
-\begin{tableii}{l|l}{}{Value}{Type of interval}
- \lineii{S}{Seconds}
- \lineii{M}{Minutes}
- \lineii{H}{Hours}
- \lineii{D}{Days}
- \lineii{W}{Week day (0=Monday)}
- \lineii{midnight}{Roll over at midnight}
-\end{tableii}
-
-If \var{backupCount} is non-zero, the system will save old log files by
-appending extensions to the filename. The extensions are date-and-time
-based, using the strftime format \code{\%Y-\%m-\%d_\%H-\%M-\%S} or a leading
-portion thereof, depending on the rollover interval. At most \var{backupCount}
-files will be kept, and if more would be created when rollover occurs, the
-oldest one is deleted.
-\end{classdesc}
-
-\begin{methoddesc}{doRollover}{}
-Does a rollover, as described above.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Outputs the record to the file, catering for rollover as described
-above.
-\end{methoddesc}
-
-\subsubsection{SocketHandler}
-
-The \class{SocketHandler} class, located in the
-\module{logging.handlers} module, sends logging output to a network
-socket. The base class uses a TCP socket.
-
-\begin{classdesc}{SocketHandler}{host, port}
-Returns a new instance of the \class{SocketHandler} class intended to
-communicate with a remote machine whose address is given by \var{host}
-and \var{port}.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Closes the socket.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{}
-Pickles the record's attribute dictionary and writes it to the socket in
-binary format. If there is an error with the socket, silently drops the
-packet. If the connection was previously lost, re-establishes the connection.
-To unpickle the record at the receiving end into a \class{LogRecord}, use the
-\function{makeLogRecord()} function.
-\end{methoddesc}
-
-\begin{methoddesc}{handleError}{}
-Handles an error which has occurred during \method{emit()}. The
-most likely cause is a lost connection. Closes the socket so that
-we can retry on the next event.
-\end{methoddesc}
-
-\begin{methoddesc}{makeSocket}{}
-This is a factory method which allows subclasses to define the precise
-type of socket they want. The default implementation creates a TCP
-socket (\constant{socket.SOCK_STREAM}).
-\end{methoddesc}
-
-\begin{methoddesc}{makePickle}{record}
-Pickles the record's attribute dictionary in binary format with a length
-prefix, and returns it ready for transmission across the socket.
-\end{methoddesc}
-
-\begin{methoddesc}{send}{packet}
-Send a pickled string \var{packet} to the socket. This function allows
-for partial sends which can happen when the network is busy.
-\end{methoddesc}
-
-\subsubsection{DatagramHandler}
-
-The \class{DatagramHandler} class, located in the
-\module{logging.handlers} module, inherits from \class{SocketHandler}
-to support sending logging messages over UDP sockets.
-
-\begin{classdesc}{DatagramHandler}{host, port}
-Returns a new instance of the \class{DatagramHandler} class intended to
-communicate with a remote machine whose address is given by \var{host}
-and \var{port}.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{}
-Pickles the record's attribute dictionary and writes it to the socket in
-binary format. If there is an error with the socket, silently drops the
-packet.
-To unpickle the record at the receiving end into a \class{LogRecord}, use the
-\function{makeLogRecord()} function.
-\end{methoddesc}
-
-\begin{methoddesc}{makeSocket}{}
-The factory method of \class{SocketHandler} is here overridden to create
-a UDP socket (\constant{socket.SOCK_DGRAM}).
-\end{methoddesc}
-
-\begin{methoddesc}{send}{s}
-Send a pickled string to a socket.
-\end{methoddesc}
-
-\subsubsection{SysLogHandler}
-
-The \class{SysLogHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-a remote or local \UNIX{} syslog.
-
-\begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}}
-Returns a new instance of the \class{SysLogHandler} class intended to
-communicate with a remote \UNIX{} machine whose address is given by
-\var{address} in the form of a \code{(\var{host}, \var{port})}
-tuple. If \var{address} is not specified, \code{('localhost', 514)} is
-used. The address is used to open a UDP socket. An alternative to providing
-a \code{(\var{host}, \var{port})} tuple is providing an address as a string,
-for example "/dev/log". In this case, a Unix domain socket is used to send
-the message to the syslog. If \var{facility} is not specified,
-\constant{LOG_USER} is used.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Closes the socket to the remote host.
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-The record is formatted, and then sent to the syslog server. If
-exception information is present, it is \emph{not} sent to the server.
-\end{methoddesc}
-
-\begin{methoddesc}{encodePriority}{facility, priority}
-Encodes the facility and priority into an integer. You can pass in strings
-or integers - if strings are passed, internal mapping dictionaries are used
-to convert them to integers.
-\end{methoddesc}
-
-\subsubsection{NTEventLogHandler}
-
-The \class{NTEventLogHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-a local Windows NT, Windows 2000 or Windows XP event log. Before you
-can use it, you need Mark Hammond's Win32 extensions for Python
-installed.
-
-\begin{classdesc}{NTEventLogHandler}{appname\optional{,
- dllname\optional{, logtype}}}
-Returns a new instance of the \class{NTEventLogHandler} class. The
-\var{appname} is used to define the application name as it appears in the
-event log. An appropriate registry entry is created using this name.
-The \var{dllname} should give the fully qualified pathname of a .dll or .exe
-which contains message definitions to hold in the log (if not specified,
-\code{'win32service.pyd'} is used - this is installed with the Win32
-extensions and contains some basic placeholder message definitions.
-Note that use of these placeholders will make your event logs big, as the
-entire message source is held in the log. If you want slimmer logs, you have
-to pass in the name of your own .dll or .exe which contains the message
-definitions you want to use in the event log). The \var{logtype} is one of
-\code{'Application'}, \code{'System'} or \code{'Security'}, and
-defaults to \code{'Application'}.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-At this point, you can remove the application name from the registry as a
-source of event log entries. However, if you do this, you will not be able
-to see the events as you intended in the Event Log Viewer - it needs to be
-able to access the registry to get the .dll name. The current version does
-not do this (in fact it doesn't do anything).
-\end{methoddesc}
-
-\begin{methoddesc}{emit}{record}
-Determines the message ID, event category and event type, and then logs the
-message in the NT event log.
-\end{methoddesc}
-
-\begin{methoddesc}{getEventCategory}{record}
-Returns the event category for the record. Override this if you
-want to specify your own categories. This version returns 0.
-\end{methoddesc}
-
-\begin{methoddesc}{getEventType}{record}
-Returns the event type for the record. Override this if you want
-to specify your own types. This version does a mapping using the
-handler's typemap attribute, which is set up in \method{__init__()}
-to a dictionary which contains mappings for \constant{DEBUG},
-\constant{INFO}, \constant{WARNING}, \constant{ERROR} and
-\constant{CRITICAL}. If you are using your own levels, you will either need
-to override this method or place a suitable dictionary in the
-handler's \var{typemap} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}{getMessageID}{record}
-Returns the message ID for the record. If you are using your
-own messages, you could do this by having the \var{msg} passed to the
-logger being an ID rather than a format string. Then, in here,
-you could use a dictionary lookup to get the message ID. This
-version returns 1, which is the base message ID in
-\file{win32service.pyd}.
-\end{methoddesc}
-
-\subsubsection{SMTPHandler}
-
-The \class{SMTPHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-an email address via SMTP.
-
-\begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject\optional{,
- credentials}}
-Returns a new instance of the \class{SMTPHandler} class. The
-instance is initialized with the from and to addresses and subject
-line of the email. The \var{toaddrs} should be a list of strings. To specify a
-non-standard SMTP port, use the (host, port) tuple format for the
-\var{mailhost} argument. If you use a string, the standard SMTP port
-is used. If your SMTP server requires authentication, you can specify a
-(username, password) tuple for the \var{credentials} argument.
-\versionchanged[\var{credentials} was added]{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Formats the record and sends it to the specified addressees.
-\end{methoddesc}
-
-\begin{methoddesc}{getSubject}{record}
-If you want to specify a subject line which is record-dependent,
-override this method.
-\end{methoddesc}
-
-\subsubsection{MemoryHandler}
-
-The \class{MemoryHandler} class, located in the
-\module{logging.handlers} module, supports buffering of logging
-records in memory, periodically flushing them to a \dfn{target}
-handler. Flushing occurs whenever the buffer is full, or when an event
-of a certain severity or greater is seen.
-
-\class{MemoryHandler} is a subclass of the more general
-\class{BufferingHandler}, which is an abstract class. This buffers logging
-records in memory. Whenever each record is added to the buffer, a
-check is made by calling \method{shouldFlush()} to see if the buffer
-should be flushed. If it should, then \method{flush()} is expected to
-do the needful.
-
-\begin{classdesc}{BufferingHandler}{capacity}
-Initializes the handler with a buffer of the specified capacity.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Appends the record to the buffer. If \method{shouldFlush()} returns true,
-calls \method{flush()} to process the buffer.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-You can override this to implement custom flushing behavior. This version
-just zaps the buffer to empty.
-\end{methoddesc}
-
-\begin{methoddesc}{shouldFlush}{record}
-Returns true if the buffer is up to capacity. This method can be
-overridden to implement custom flushing strategies.
-\end{methoddesc}
-
-\begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel
-\optional{, target}}}
-Returns a new instance of the \class{MemoryHandler} class. The
-instance is initialized with a buffer size of \var{capacity}. If
-\var{flushLevel} is not specified, \constant{ERROR} is used. If no
-\var{target} is specified, the target will need to be set using
-\method{setTarget()} before this handler does anything useful.
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
-Calls \method{flush()}, sets the target to \constant{None} and
-clears the buffer.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-For a \class{MemoryHandler}, flushing means just sending the buffered
-records to the target, if there is one. Override if you want
-different behavior.
-\end{methoddesc}
-
-\begin{methoddesc}{setTarget}{target}
-Sets the target handler for this handler.
-\end{methoddesc}
-
-\begin{methoddesc}{shouldFlush}{record}
-Checks for buffer full or a record at the \var{flushLevel} or higher.
-\end{methoddesc}
-
-\subsubsection{HTTPHandler}
-
-The \class{HTTPHandler} class, located in the
-\module{logging.handlers} module, supports sending logging messages to
-a Web server, using either \samp{GET} or \samp{POST} semantics.
-
-\begin{classdesc}{HTTPHandler}{host, url\optional{, method}}
-Returns a new instance of the \class{HTTPHandler} class. The
-instance is initialized with a host address, url and HTTP method.
-The \var{host} can be of the form \code{host:port}, should you need to
-use a specific port number. If no \var{method} is specified, \samp{GET}
-is used.
-\end{classdesc}
-
-\begin{methoddesc}{emit}{record}
-Sends the record to the Web server as an URL-encoded dictionary.
-\end{methoddesc}
-
-\subsection{Formatter Objects}
-
-\class{Formatter}s have the following attributes and methods. They are
-responsible for converting a \class{LogRecord} to (usually) a string
-which can be interpreted by either a human or an external system. The
-base
-\class{Formatter} allows a formatting string to be specified. If none is
-supplied, the default value of \code{'\%(message)s'} is used.
-
-A Formatter can be initialized with a format string which makes use of
-knowledge of the \class{LogRecord} attributes - such as the default value
-mentioned above making use of the fact that the user's message and
-arguments are pre-formatted into a \class{LogRecord}'s \var{message}
-attribute. This format string contains standard python \%-style
-mapping keys. See section \ref{typesseq-strings}, ``String Formatting
-Operations,'' for more information on string formatting.
-
-Currently, the useful mapping keys in a \class{LogRecord} are:
-
-\begin{tableii}{l|l}{code}{Format}{Description}
-\lineii{\%(name)s} {Name of the logger (logging channel).}
-\lineii{\%(levelno)s} {Numeric logging level for the message
- (\constant{DEBUG}, \constant{INFO},
- \constant{WARNING}, \constant{ERROR},
- \constant{CRITICAL}).}
-\lineii{\%(levelname)s}{Text logging level for the message
- (\code{'DEBUG'}, \code{'INFO'},
- \code{'WARNING'}, \code{'ERROR'},
- \code{'CRITICAL'}).}
-\lineii{\%(pathname)s} {Full pathname of the source file where the logging
- call was issued (if available).}
-\lineii{\%(filename)s} {Filename portion of pathname.}
-\lineii{\%(module)s} {Module (name portion of filename).}
-\lineii{\%(funcName)s} {Name of function containing the logging call.}
-\lineii{\%(lineno)d} {Source line number where the logging call was issued
- (if available).}
-\lineii{\%(created)f} {Time when the \class{LogRecord} was created (as
- returned by \function{time.time()}).}
-\lineii{\%(relativeCreated)d} {Time in milliseconds when the LogRecord was
- created, relative to the time the logging module was
- loaded.}
-\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord}
- was created. By default this is of the form
- ``2003-07-08 16:49:45,896'' (the numbers after the
- comma are millisecond portion of the time).}
-\lineii{\%(msecs)d} {Millisecond portion of the time when the
- \class{LogRecord} was created.}
-\lineii{\%(thread)d} {Thread ID (if available).}
-\lineii{\%(threadName)s} {Thread name (if available).}
-\lineii{\%(process)d} {Process ID (if available).}
-\lineii{\%(message)s} {The logged message, computed as \code{msg \% args}.}
-\end{tableii}
-
-\versionchanged[\var{funcName} was added]{2.5}
-
-\begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
-Returns a new instance of the \class{Formatter} class. The
-instance is initialized with a format string for the message as a whole,
-as well as a format string for the date/time portion of a message. If
-no \var{fmt} is specified, \code{'\%(message)s'} is used. If no \var{datefmt}
-is specified, the ISO8601 date format is used.
-\end{classdesc}
-
-\begin{methoddesc}{format}{record}
-The record's attribute dictionary is used as the operand to a
-string formatting operation. Returns the resulting string.
-Before formatting the dictionary, a couple of preparatory steps
-are carried out. The \var{message} attribute of the record is computed
-using \var{msg} \% \var{args}. If the formatting string contains
-\code{'(asctime)'}, \method{formatTime()} is called to format the
-event time. If there is exception information, it is formatted using
-\method{formatException()} and appended to the message.
-\end{methoddesc}
-
-\begin{methoddesc}{formatTime}{record\optional{, datefmt}}
-This method should be called from \method{format()} by a formatter which
-wants to make use of a formatted time. This method can be overridden
-in formatters to provide for any specific requirement, but the
-basic behavior is as follows: if \var{datefmt} (a string) is specified,
-it is used with \function{time.strftime()} to format the creation time of the
-record. Otherwise, the ISO8601 format is used. The resulting
-string is returned.
-\end{methoddesc}
-
-\begin{methoddesc}{formatException}{exc_info}
-Formats the specified exception information (a standard exception tuple
-as returned by \function{sys.exc_info()}) as a string. This default
-implementation just uses \function{traceback.print_exception()}.
-The resulting string is returned.
-\end{methoddesc}
-
-\subsection{Filter Objects}
-
-\class{Filter}s can be used by \class{Handler}s and \class{Logger}s for
-more sophisticated filtering than is provided by levels. The base filter
-class only allows events which are below a certain point in the logger
-hierarchy. For example, a filter initialized with "A.B" will allow events
-logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",
-"B.A.B" etc. If initialized with the empty string, all events are passed.
-
-\begin{classdesc}{Filter}{\optional{name}}
-Returns an instance of the \class{Filter} class. If \var{name} is specified,
-it names a logger which, together with its children, will have its events
-allowed through the filter. If no name is specified, allows every event.
-\end{classdesc}
-
-\begin{methoddesc}{filter}{record}
-Is the specified record to be logged? Returns zero for no, nonzero for
-yes. If deemed appropriate, the record may be modified in-place by this
-method.
-\end{methoddesc}
-
-\subsection{LogRecord Objects}
-
-\class{LogRecord} instances are created every time something is logged. They
-contain all the information pertinent to the event being logged. The
-main information passed in is in msg and args, which are combined
-using msg \% args to create the message field of the record. The record
-also includes information such as when the record was created, the
-source line where the logging call was made, and any exception
-information to be logged.
-
-\begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
- exc_info \optional{, func}}
-Returns an instance of \class{LogRecord} initialized with interesting
-information. The \var{name} is the logger name; \var{lvl} is the
-numeric level; \var{pathname} is the absolute pathname of the source
-file in which the logging call was made; \var{lineno} is the line
-number in that file where the logging call is found; \var{msg} is the
-user-supplied message (a format string); \var{args} is the tuple
-which, together with \var{msg}, makes up the user message; and
-\var{exc_info} is the exception tuple obtained by calling
-\function{sys.exc_info() }(or \constant{None}, if no exception information
-is available). The \var{func} is the name of the function from which the
-logging call was made. If not specified, it defaults to \code{None}.
-\versionchanged[\var{func} was added]{2.5}
-\end{classdesc}
-
-\begin{methoddesc}{getMessage}{}
-Returns the message for this \class{LogRecord} instance after merging any
-user-supplied arguments with the message.
-\end{methoddesc}
-
-\subsection{Thread Safety}
-
-The logging module is intended to be thread-safe without any special work
-needing to be done by its clients. It achieves this though using threading
-locks; there is one lock to serialize access to the module's shared data,
-and each handler also creates a lock to serialize access to its underlying
-I/O.
-
-\subsection{Configuration}
-
-
-\subsubsection{Configuration functions%
- \label{logging-config-api}}
-
-The following functions configure the logging module. They are located in the
-\module{logging.config} module. Their use is optional --- you can configure
-the logging module using these functions or by making calls to the
-main API (defined in \module{logging} itself) and defining handlers
-which are declared either in \module{logging} or
-\module{logging.handlers}.
-
-\begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
-Reads the logging configuration from a ConfigParser-format file named
-\var{fname}. This function can be called several times from an application,
-allowing an end user the ability to select from various pre-canned
-configurations (if the developer provides a mechanism to present the
-choices and load the chosen configuration). Defaults to be passed to
-ConfigParser can be specified in the \var{defaults} argument.
-\end{funcdesc}
-
-\begin{funcdesc}{listen}{\optional{port}}
-Starts up a socket server on the specified port, and listens for new
-configurations. If no port is specified, the module's default
-\constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
-will be sent as a file suitable for processing by \function{fileConfig()}.
-Returns a \class{Thread} instance on which you can call \method{start()}
-to start the server, and which you can \method{join()} when appropriate.
-To stop the server, call \function{stopListening()}. To send a configuration
-to the socket, read in the configuration file and send it to the socket
-as a string of bytes preceded by a four-byte length packed in binary using
-struct.\code{pack('>L', n)}.
-\end{funcdesc}
-
-\begin{funcdesc}{stopListening}{}
-Stops the listening server which was created with a call to
-\function{listen()}. This is typically called before calling \method{join()}
-on the return value from \function{listen()}.
-\end{funcdesc}
-
-\subsubsection{Configuration file format%
- \label{logging-config-fileformat}}
-
-The configuration file format understood by \function{fileConfig()} is
-based on ConfigParser functionality. The file must contain sections
-called \code{[loggers]}, \code{[handlers]} and \code{[formatters]}
-which identify by name the entities of each type which are defined in
-the file. For each such entity, there is a separate section which
-identified how that entity is configured. Thus, for a logger named
-\code{log01} in the \code{[loggers]} section, the relevant
-configuration details are held in a section
-\code{[logger_log01]}. Similarly, a handler called \code{hand01} in
-the \code{[handlers]} section will have its configuration held in a
-section called \code{[handler_hand01]}, while a formatter called
-\code{form01} in the \code{[formatters]} section will have its
-configuration specified in a section called
-\code{[formatter_form01]}. The root logger configuration must be
-specified in a section called \code{[logger_root]}.
-
-Examples of these sections in the file are given below.
-
-\begin{verbatim}
-[loggers]
-keys=root,log02,log03,log04,log05,log06,log07
-
-[handlers]
-keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
-
-[formatters]
-keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
-\end{verbatim}
-
-The root logger must specify a level and a list of handlers. An
-example of a root logger section is given below.
-
-\begin{verbatim}
-[logger_root]
-level=NOTSET
-handlers=hand01
-\end{verbatim}
-
-The \code{level} entry can be one of \code{DEBUG, INFO, WARNING,
-ERROR, CRITICAL} or \code{NOTSET}. For the root logger only,
-\code{NOTSET} means that all messages will be logged. Level values are
-\function{eval()}uated in the context of the \code{logging} package's
-namespace.
-
-The \code{handlers} entry is a comma-separated list of handler names,
-which must appear in the \code{[handlers]} section. These names must
-appear in the \code{[handlers]} section and have corresponding
-sections in the configuration file.
-
-For loggers other than the root logger, some additional information is
-required. This is illustrated by the following example.
-
-\begin{verbatim}
-[logger_parser]
-level=DEBUG
-handlers=hand01
-propagate=1
-qualname=compiler.parser
-\end{verbatim}
-
-The \code{level} and \code{handlers} entries are interpreted as for
-the root logger, except that if a non-root logger's level is specified
-as \code{NOTSET}, the system consults loggers higher up the hierarchy
-to determine the effective level of the logger. The \code{propagate}
-entry is set to 1 to indicate that messages must propagate to handlers
-higher up the logger hierarchy from this logger, or 0 to indicate that
-messages are \strong{not} propagated to handlers up the hierarchy. The
-\code{qualname} entry is the hierarchical channel name of the logger,
-that is to say the name used by the application to get the logger.
-
-Sections which specify handler configuration are exemplified by the
-following.
-
-\begin{verbatim}
-[handler_hand01]
-class=StreamHandler
-level=NOTSET
-formatter=form01
-args=(sys.stdout,)
-\end{verbatim}
-
-The \code{class} entry indicates the handler's class (as determined by
-\function{eval()} in the \code{logging} package's namespace). The
-\code{level} is interpreted as for loggers, and \code{NOTSET} is taken
-to mean "log everything".
-
-The \code{formatter} entry indicates the key name of the formatter for
-this handler. If blank, a default formatter
-(\code{logging._defaultFormatter}) is used. If a name is specified, it
-must appear in the \code{[formatters]} section and have a
-corresponding section in the configuration file.
-
-The \code{args} entry, when \function{eval()}uated in the context of
-the \code{logging} package's namespace, is the list of arguments to
-the constructor for the handler class. Refer to the constructors for
-the relevant handlers, or to the examples below, to see how typical
-entries are constructed.
-
-\begin{verbatim}
-[handler_hand02]
-class=FileHandler
-level=DEBUG
-formatter=form02
-args=('python.log', 'w')
-
-[handler_hand03]
-class=handlers.SocketHandler
-level=INFO
-formatter=form03
-args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
-
-[handler_hand04]
-class=handlers.DatagramHandler
-level=WARN
-formatter=form04
-args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
-
-[handler_hand05]
-class=handlers.SysLogHandler
-level=ERROR
-formatter=form05
-args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
-
-[handler_hand06]
-class=handlers.NTEventLogHandler
-level=CRITICAL
-formatter=form06
-args=('Python Application', '', 'Application')
-
-[handler_hand07]
-class=handlers.SMTPHandler
-level=WARN
-formatter=form07
-args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
-
-[handler_hand08]
-class=handlers.MemoryHandler
-level=NOTSET
-formatter=form08
-target=
-args=(10, ERROR)
-
-[handler_hand09]
-class=handlers.HTTPHandler
-level=NOTSET
-formatter=form09
-args=('localhost:9022', '/log', 'GET')
-\end{verbatim}
-
-Sections which specify formatter configuration are typified by the following.
-
-\begin{verbatim}
-[formatter_form01]
-format=F1 %(asctime)s %(levelname)s %(message)s
-datefmt=
-class=logging.Formatter
-\end{verbatim}
-
-The \code{format} entry is the overall format string, and the
-\code{datefmt} entry is the \function{strftime()}-compatible date/time format
-string. If empty, the package substitutes ISO8601 format date/times, which
-is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S".
-The ISO8601 format also specifies milliseconds, which are appended to the
-result of using the above format string, with a comma separator. An example
-time in ISO8601 format is \code{2003-01-23 00:29:50,411}.
-
-The \code{class} entry is optional. It indicates the name of the
-formatter's class (as a dotted module and class name.) This option is
-useful for instantiating a \class{Formatter} subclass. Subclasses of
-\class{Formatter} can present exception tracebacks in an expanded or
-condensed format.
diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex
deleted file mode 100644
index c3e7ffd..0000000
--- a/Doc/lib/libmailbox.tex
+++ /dev/null
@@ -1,1443 +0,0 @@
-\section{\module{mailbox} ---
- Manipulate mailboxes in various formats}
-
-\declaremodule{}{mailbox}
-\moduleauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com}
-\sectionauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com}
-\modulesynopsis{Manipulate mailboxes in various formats}
-
-
-This module defines two classes, \class{Mailbox} and \class{Message}, for
-accessing and manipulating on-disk mailboxes and the messages they contain.
-\class{Mailbox} offers a dictionary-like mapping from keys to messages.
-\class{Message} extends the \module{email.Message} module's \class{Message}
-class with format-specific state and behavior. Supported mailbox formats are
-Maildir, mbox, MH, Babyl, and MMDF.
-
-\begin{seealso}
- \seemodule{email}{Represent and manipulate messages.}
-\end{seealso}
-
-\subsection{\class{Mailbox} objects}
-\label{mailbox-objects}
-
-\begin{classdesc*}{Mailbox}
-A mailbox, which may be inspected and modified.
-\end{classdesc*}
-
-The \class{Mailbox} class defines an interface and
-is not intended to be instantiated. Instead, format-specific
-subclasses should inherit from \class{Mailbox} and your code
-should instantiate a particular subclass.
-
-The \class{Mailbox} interface is dictionary-like, with small keys
-corresponding to messages. Keys are issued by the \class{Mailbox}
-instance with which they will be used and are only meaningful to that
-\class{Mailbox} instance. A key continues to identify a message even
-if the corresponding message is modified, such as by replacing it with
-another message.
-
-Messages may be added to a \class{Mailbox} instance using the set-like
-method \method{add()} and removed using a \code{del} statement or the
-set-like methods \method{remove()} and \method{discard()}.
-
-\class{Mailbox} interface semantics differ from dictionary semantics in some
-noteworthy ways. Each time a message is requested, a new
-representation (typically a \class{Message} instance) is generated
-based upon the current state of the mailbox. Similarly, when a message
-is added to a \class{Mailbox} instance, the provided message
-representation's contents are copied. In neither case is a reference
-to the message representation kept by the \class{Mailbox} instance.
-
-The default \class{Mailbox} iterator iterates over message representations, not
-keys as the default dictionary iterator does. Moreover, modification of a
-mailbox during iteration is safe and well-defined. Messages added to the
-mailbox after an iterator is created will not be seen by the iterator. Messages
-removed from the mailbox before the iterator yields them will be silently
-skipped, though using a key from an iterator may result in a
-\exception{KeyError} exception if the corresponding message is subsequently
-removed.
-
-\begin{notice}[warning]
-Be very cautious when modifying mailboxes that might be
-simultaneously changed by some other process. The safest mailbox
-format to use for such tasks is Maildir; try to avoid using
-single-file formats such as mbox for concurrent writing. If you're
-modifying a mailbox, you
-\emph{must} lock it by calling the \method{lock()} and
-\method{unlock()} methods \emph{before} reading any messages in the file
-or making any changes by adding or deleting a message. Failing to
-lock the mailbox runs the risk of losing messages or corrupting the entire
-mailbox.
-\end{notice}
-
-\class{Mailbox} instances have the following methods:
-
-\begin{methoddesc}{add}{message}
-Add \var{message} to the mailbox and return the key that has been assigned to
-it.
-
-Parameter \var{message} may be a \class{Message} instance, an
-\class{email.Message.Message} instance, a string, or a file-like object (which
-should be open in text mode). If \var{message} is an instance of the
-appropriate format-specific \class{Message} subclass (e.g., if it's an
-\class{mboxMessage} instance and this is an \class{mbox} instance), its
-format-specific information is used. Otherwise, reasonable defaults for
-format-specific information are used.
-\end{methoddesc}
-
-\begin{methoddesc}{remove}{key}
-\methodline{__delitem__}{key}
-\methodline{discard}{key}
-Delete the message corresponding to \var{key} from the mailbox.
-
-If no such message exists, a \exception{KeyError} exception is raised if the
-method was called as \method{remove()} or \method{__delitem__()} but no
-exception is raised if the method was called as \method{discard()}. The
-behavior of \method{discard()} may be preferred if the underlying mailbox
-format supports concurrent modification by other processes.
-\end{methoddesc}
-
-\begin{methoddesc}{__setitem__}{key, message}
-Replace the message corresponding to \var{key} with \var{message}. Raise a
-\exception{KeyError} exception if no message already corresponds to \var{key}.
-
-As with \method{add()}, parameter \var{message} may be a \class{Message}
-instance, an \class{email.Message.Message} instance, a string, or a file-like
-object (which should be open in text mode). If \var{message} is an instance of
-the appropriate format-specific \class{Message} subclass (e.g., if it's an
-\class{mboxMessage} instance and this is an \class{mbox} instance), its
-format-specific information is used. Otherwise, the format-specific information
-of the message that currently corresponds to \var{key} is left unchanged.
-\end{methoddesc}
-
-\begin{methoddesc}{iterkeys}{}
-\methodline{keys}{}
-Return an iterator over all keys if called as \method{iterkeys()} or return a
-list of keys if called as \method{keys()}.
-\end{methoddesc}
-
-\begin{methoddesc}{itervalues}{}
-\methodline{__iter__}{}
-\methodline{values}{}
-Return an iterator over representations of all messages if called as
-\method{itervalues()} or \method{__iter__()} or return a list of such
-representations if called as \method{values()}. The messages are represented as
-instances of the appropriate format-specific \class{Message} subclass unless a
-custom message factory was specified when the \class{Mailbox} instance was
-initialized. \note{The behavior of \method{__iter__()} is unlike that of
-dictionaries, which iterate over keys.}
-\end{methoddesc}
-
-\begin{methoddesc}{iteritems}{}
-\methodline{items}{}
-Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is a
-key and \var{message} is a message representation, if called as
-\method{iteritems()} or return a list of such pairs if called as
-\method{items()}. The messages are represented as instances of the appropriate
-format-specific \class{Message} subclass unless a custom message factory was
-specified when the \class{Mailbox} instance was initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{get}{key\optional{, default=None}}
-\methodline{__getitem__}{key}
-Return a representation of the message corresponding to \var{key}. If no such
-message exists, \var{default} is returned if the method was called as
-\method{get()} and a \exception{KeyError} exception is raised if the method was
-called as \method{__getitem__()}. The message is represented as an instance of
-the appropriate format-specific \class{Message} subclass unless a custom
-message factory was specified when the \class{Mailbox} instance was
-initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{get_message}{key}
-Return a representation of the message corresponding to \var{key} as an
-instance of the appropriate format-specific \class{Message} subclass, or raise
-a \exception{KeyError} exception if no such message exists.
-\end{methoddesc}
-
-\begin{methoddesc}{get_string}{key}
-Return a string representation of the message corresponding to \var{key}, or
-raise a \exception{KeyError} exception if no such message exists.
-\end{methoddesc}
-
-\begin{methoddesc}{get_file}{key}
-Return a file-like representation of the message corresponding to \var{key},
-or raise a \exception{KeyError} exception if no such message exists. The
-file-like object behaves as if open in binary mode. This file should be closed
-once it is no longer needed.
-
-\note{Unlike other representations of messages, file-like representations are
-not necessarily independent of the \class{Mailbox} instance that created them
-or of the underlying mailbox. More specific documentation is provided by each
-subclass.}
-\end{methoddesc}
-
-\begin{methoddesc}{has_key}{key}
-\methodline{__contains__}{key}
-Return \code{True} if \var{key} corresponds to a message, \code{False}
-otherwise.
-\end{methoddesc}
-
-\begin{methoddesc}{__len__}{}
-Return a count of messages in the mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}{clear}{}
-Delete all messages from the mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}{pop}{key\optional{, default}}
-Return a representation of the message corresponding to \var{key} and delete
-the message. If no such message exists, return \var{default} if it was supplied
-or else raise a \exception{KeyError} exception. The message is represented as
-an instance of the appropriate format-specific \class{Message} subclass unless
-a custom message factory was specified when the \class{Mailbox} instance was
-initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{popitem}{}
-Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a key
-and \var{message} is a message representation, and delete the corresponding
-message. If the mailbox is empty, raise a \exception{KeyError} exception. The
-message is represented as an instance of the appropriate format-specific
-\class{Message} subclass unless a custom message factory was specified when the
-\class{Mailbox} instance was initialized.
-\end{methoddesc}
-
-\begin{methoddesc}{update}{arg}
-Parameter \var{arg} should be a \var{key}-to-\var{message} mapping or an
-iterable of (\var{key}, \var{message}) pairs. Updates the mailbox so that, for
-each given \var{key} and \var{message}, the message corresponding to \var{key}
-is set to \var{message} as if by using \method{__setitem__()}. As with
-\method{__setitem__()}, each \var{key} must already correspond to a message in
-the mailbox or else a \exception{KeyError} exception will be raised, so in
-general it is incorrect for \var{arg} to be a \class{Mailbox} instance.
-\note{Unlike with dictionaries, keyword arguments are not supported.}
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-Write any pending changes to the filesystem. For some \class{Mailbox}
-subclasses, changes are always written immediately and \method{flush()} does
-nothing, but you should still make a habit of calling this method.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-Acquire an exclusive advisory lock on the mailbox so that other processes know
-not to modify it. An \exception{ExternalClashError} is raised if the lock is
-not available. The particular locking mechanisms used depend upon the mailbox
-format. You should \emph{always} lock the mailbox before making any
-modifications to its contents.
-\end{methoddesc}
-
-\begin{methoddesc}{unlock}{}
-Release the lock on the mailbox, if any.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Flush the mailbox, unlock it if necessary, and close any open files. For some
-\class{Mailbox} subclasses, this method does nothing.
-\end{methoddesc}
-
-
-\subsubsection{\class{Maildir}}
-\label{mailbox-maildir}
-
-\begin{classdesc}{Maildir}{dirname\optional{, factory=rfc822.Message\optional{,
-create=True}}}
-A subclass of \class{Mailbox} for mailboxes in Maildir format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{MaildirMessage} is used
-as the default message representation. If \var{create} is \code{True}, the
-mailbox is created if it does not exist.
-
-It is for historical reasons that \var{factory} defaults to
-\class{rfc822.Message} and that \var{dirname} is named as such rather than
-\var{path}. For a \class{Maildir} instance that behaves like instances of other
-\class{Mailbox} subclasses, set \var{factory} to \code{None}.
-\end{classdesc}
-
-Maildir is a directory-based mailbox format invented for the qmail mail
-transfer agent and now widely supported by other programs. Messages in a
-Maildir mailbox are stored in separate files within a common directory
-structure. This design allows Maildir mailboxes to be accessed and modified by
-multiple unrelated programs without data corruption, so file locking is
-unnecessary.
-
-Maildir mailboxes contain three subdirectories, namely: \file{tmp}, \file{new},
-and \file{cur}. Messages are created momentarily in the \file{tmp} subdirectory
-and then moved to the \file{new} subdirectory to finalize delivery. A mail user
-agent may subsequently move the message to the \file{cur} subdirectory and
-store information about the state of the message in a special "info" section
-appended to its file name.
-
-Folders of the style introduced by the Courier mail transfer agent are also
-supported. Any subdirectory of the main mailbox is considered a folder if
-\character{.} is the first character in its name. Folder names are represented
-by \class{Maildir} without the leading \character{.}. Each folder is itself a
-Maildir mailbox but should not contain other folders. Instead, a logical
-nesting is indicated using \character{.} to delimit levels, e.g.,
-"Archived.2005.07".
-
-\begin{notice}
-The Maildir specification requires the use of a colon (\character{:}) in
-certain message file names. However, some operating systems do not permit this
-character in file names, If you wish to use a Maildir-like format on such an
-operating system, you should specify another character to use instead. The
-exclamation point (\character{!}) is a popular choice. For example:
-\begin{verbatim}
-import mailbox
-mailbox.Maildir.colon = '!'
-\end{verbatim}
-The \member{colon} attribute may also be set on a per-instance basis.
-\end{notice}
-
-\class{Maildir} instances have all of the methods of \class{Mailbox} in
-addition to the following:
-
-\begin{methoddesc}{list_folders}{}
-Return a list of the names of all folders.
-\end{methoddesc}
-
-\begin{methoddesc}{get_folder}{folder}
-Return a \class{Maildir} instance representing the folder whose name is
-\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the
-folder does not exist.
-\end{methoddesc}
-
-\begin{methoddesc}{add_folder}{folder}
-Create a folder whose name is \var{folder} and return a \class{Maildir}
-instance representing it.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_folder}{folder}
-Delete the folder whose name is \var{folder}. If the folder contains any
-messages, a \exception{NotEmptyError} exception will be raised and the folder
-will not be deleted.
-\end{methoddesc}
-
-\begin{methoddesc}{clean}{}
-Delete temporary files from the mailbox that have not been accessed in the
-last 36 hours. The Maildir specification says that mail-reading programs
-should do this occasionally.
-\end{methoddesc}
-
-Some \class{Mailbox} methods implemented by \class{Maildir} deserve special
-remarks:
-
-\begin{methoddesc}{add}{message}
-\methodline[Maildir]{__setitem__}{key, message}
-\methodline[Maildir]{update}{arg}
-\warning{These methods generate unique file names based upon the current
-process ID. When using multiple threads, undetected name clashes may occur and
-cause corruption of the mailbox unless threads are coordinated to avoid using
-these methods to manipulate the same mailbox simultaneously.}
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-All changes to Maildir mailboxes are immediately applied, so this method does
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Maildir mailboxes do not support (or require) locking, so these methods do
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-\class{Maildir} instances do not keep any open files and the underlying
-mailboxes do not support locking, so this method does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{get_file}{key}
-Depending upon the host platform, it may not be possible to modify or remove
-the underlying message while the returned file remains open.
-\end{methoddesc}
-
-\begin{seealso}
- \seelink{http://www.qmail.org/man/man5/maildir.html}{maildir man page from
- qmail}{The original specification of the format.}
- \seelink{http://cr.yp.to/proto/maildir.html}{Using maildir format}{Notes
- on Maildir by its inventor. Includes an updated name-creation scheme and
- details on "info" semantics.}
- \seelink{http://www.courier-mta.org/?maildir.html}{maildir man page from
- Courier}{Another specification of the format. Describes a common extension
- for supporting folders.}
-\end{seealso}
-
-\subsubsection{\class{mbox}}
-\label{mailbox-mbox}
-
-\begin{classdesc}{mbox}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in mbox format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{mboxMessage} is used as
-the default message representation. If \var{create} is \code{True}, the mailbox
-is created if it does not exist.
-\end{classdesc}
-
-The mbox format is the classic format for storing mail on \UNIX{} systems. All
-messages in an mbox mailbox are stored in a single file with the beginning of
-each message indicated by a line whose first five characters are "From~".
-
-Several variations of the mbox format exist to address perceived shortcomings
-in the original. In the interest of compatibility, \class{mbox} implements the
-original format, which is sometimes referred to as \dfn{mboxo}. This means that
-the \mailheader{Content-Length} header, if present, is ignored and that any
-occurrences of "From~" at the beginning of a line in a message body are
-transformed to ">From~" when storing the message, although occurences of
-">From~" are not transformed to "From~" when reading the message.
-
-Some \class{Mailbox} methods implemented by \class{mbox} deserve special
-remarks:
-
-\begin{methoddesc}{get_file}{key}
-Using the file after calling \method{flush()} or \method{close()} on the
-\class{mbox} instance may yield unpredictable results or raise an exception.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls.
-\end{methoddesc}
-
-\begin{seealso}
- \seelink{http://www.qmail.org/man/man5/mbox.html}{mbox man page from
- qmail}{A specification of the format and its variations.}
- \seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mbox}{mbox man
- page from tin}{Another specification of the format, with details on
- locking.}
- \seelink{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
- {Configuring Netscape Mail on \UNIX{}: Why The Content-Length Format is
- Bad}{An argument for using the original mbox format rather than a
- variation.}
- \seelink{http://homepages.tesco.net./\tilde{}J.deBoynePollard/FGA/mail-mbox-formats.html}
- {"mbox" is a family of several mutually incompatible mailbox formats}{A
- history of mbox variations.}
-\end{seealso}
-
-\subsubsection{\class{MH}}
-\label{mailbox-mh}
-
-\begin{classdesc}{MH}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in MH format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{MHMessage} is used as
-the default message representation. If \var{create} is \code{True}, the mailbox
-is created if it does not exist.
-\end{classdesc}
-
-MH is a directory-based mailbox format invented for the MH Message Handling
-System, a mail user agent. Each message in an MH mailbox resides in its own
-file. An MH mailbox may contain other MH mailboxes (called \dfn{folders}) in
-addition to messages. Folders may be nested indefinitely. MH mailboxes also
-support \dfn{sequences}, which are named lists used to logically group messages
-without moving them to sub-folders. Sequences are defined in a file called
-\file{.mh_sequences} in each folder.
-
-The \class{MH} class manipulates MH mailboxes, but it does not attempt to
-emulate all of \program{mh}'s behaviors. In particular, it does not modify and
-is not affected by the \file{context} or \file{.mh_profile} files that are used
-by \program{mh} to store its state and configuration.
-
-\class{MH} instances have all of the methods of \class{Mailbox} in addition to
-the following:
-
-\begin{methoddesc}{list_folders}{}
-Return a list of the names of all folders.
-\end{methoddesc}
-
-\begin{methoddesc}{get_folder}{folder}
-Return an \class{MH} instance representing the folder whose name is
-\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the
-folder does not exist.
-\end{methoddesc}
-
-\begin{methoddesc}{add_folder}{folder}
-Create a folder whose name is \var{folder} and return an \class{MH} instance
-representing it.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_folder}{folder}
-Delete the folder whose name is \var{folder}. If the folder contains any
-messages, a \exception{NotEmptyError} exception will be raised and the folder
-will not be deleted.
-\end{methoddesc}
-
-\begin{methoddesc}{get_sequences}{}
-Return a dictionary of sequence names mapped to key lists. If there are no
-sequences, the empty dictionary is returned.
-\end{methoddesc}
-
-\begin{methoddesc}{set_sequences}{sequences}
-Re-define the sequences that exist in the mailbox based upon \var{sequences}, a
-dictionary of names mapped to key lists, like returned by
-\method{get_sequences()}.
-\end{methoddesc}
-
-\begin{methoddesc}{pack}{}
-Rename messages in the mailbox as necessary to eliminate gaps in numbering.
-Entries in the sequences list are updated correspondingly. \note{Already-issued
-keys are invalidated by this operation and should not be subsequently used.}
-\end{methoddesc}
-
-Some \class{Mailbox} methods implemented by \class{MH} deserve special remarks:
-
-\begin{methoddesc}{remove}{key}
-\methodline{__delitem__}{key}
-\methodline{discard}{key}
-These methods immediately delete the message. The MH convention of marking a
-message for deletion by prepending a comma to its name is not used.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls. For MH mailboxes,
-locking the mailbox means locking the \file{.mh_sequences} file and, only for
-the duration of any operations that affect them, locking individual message
-files.
-\end{methoddesc}
-
-\begin{methoddesc}{get_file}{key}
-Depending upon the host platform, it may not be possible to remove the
-underlying message while the returned file remains open.
-\end{methoddesc}
-
-\begin{methoddesc}{flush}{}
-All changes to MH mailboxes are immediately applied, so this method does
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-\class{MH} instances do not keep any open files, so this method is equivelant
-to \method{unlock()}.
-\end{methoddesc}
-
-\begin{seealso}
-\seelink{http://www.nongnu.org/nmh/}{nmh - Message Handling System}{Home page
-of \program{nmh}, an updated version of the original \program{mh}.}
-\seelink{http://www.ics.uci.edu/\tilde{}mh/book/}{MH \& nmh: Email for Users \&
-Programmers}{A GPL-licensed book on \program{mh} and \program{nmh}, with some
-information on the mailbox format.}
-\end{seealso}
-
-\subsubsection{\class{Babyl}}
-\label{mailbox-babyl}
-
-\begin{classdesc}{Babyl}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in Babyl format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{BabylMessage} is used
-as the default message representation. If \var{create} is \code{True}, the
-mailbox is created if it does not exist.
-\end{classdesc}
-
-Babyl is a single-file mailbox format used by the Rmail mail user agent
-included with Emacs. The beginning of a message is indicated by a line
-containing the two characters Control-Underscore
-(\character{\textbackslash037}) and Control-L (\character{\textbackslash014}).
-The end of a message is indicated by the start of the next message or, in the
-case of the last message, a line containing a Control-Underscore
-(\character{\textbackslash037}) character.
-
-Messages in a Babyl mailbox have two sets of headers, original headers and
-so-called visible headers. Visible headers are typically a subset of the
-original headers that have been reformatted or abridged to be more attractive.
-Each message in a Babyl mailbox also has an accompanying list of \dfn{labels},
-or short strings that record extra information about the message, and a list of
-all user-defined labels found in the mailbox is kept in the Babyl options
-section.
-
-\class{Babyl} instances have all of the methods of \class{Mailbox} in addition
-to the following:
-
-\begin{methoddesc}{get_labels}{}
-Return a list of the names of all user-defined labels used in the mailbox.
-\note{The actual messages are inspected to determine which labels exist in the
-mailbox rather than consulting the list of labels in the Babyl options section,
-but the Babyl section is updated whenever the mailbox is modified.}
-\end{methoddesc}
-
-Some \class{Mailbox} methods implemented by \class{Babyl} deserve special
-remarks:
-
-\begin{methoddesc}{get_file}{key}
-In Babyl mailboxes, the headers of a message are not stored contiguously with
-the body of the message. To generate a file-like representation, the headers
-and body are copied together into a \class{StringIO} instance (from the
-\module{StringIO} module), which has an API identical to that of a file. As a
-result, the file-like object is truly independent of the underlying mailbox but
-does not save memory compared to a string representation.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls.
-\end{methoddesc}
-
-\begin{seealso}
-\seelink{http://quimby.gnus.org/notes/BABYL}{Format of Version 5 Babyl Files}{A
-specification of the Babyl format.}
-\seelink{http://www.gnu.org/software/emacs/manual/html_node/Rmail.html}{Reading
-Mail with Rmail}{The Rmail manual, with some information on Babyl semantics.}
-\end{seealso}
-
-\subsubsection{\class{MMDF}}
-\label{mailbox-mmdf}
-
-\begin{classdesc}{MMDF}{path\optional{, factory=None\optional{, create=True}}}
-A subclass of \class{Mailbox} for mailboxes in MMDF format. Parameter
-\var{factory} is a callable object that accepts a file-like message
-representation (which behaves as if opened in binary mode) and returns a custom
-representation. If \var{factory} is \code{None}, \class{MMDFMessage} is used as
-the default message representation. If \var{create} is \code{True}, the mailbox
-is created if it does not exist.
-\end{classdesc}
-
-MMDF is a single-file mailbox format invented for the Multichannel Memorandum
-Distribution Facility, a mail transfer agent. Each message is in the same form
-as an mbox message but is bracketed before and after by lines containing four
-Control-A (\character{\textbackslash001}) characters. As with the mbox format,
-the beginning of each message is indicated by a line whose first five
-characters are "From~", but additional occurrences of "From~" are not
-transformed to ">From~" when storing messages because the extra message
-separator lines prevent mistaking such occurrences for the starts of subsequent
-messages.
-
-Some \class{Mailbox} methods implemented by \class{MMDF} deserve special
-remarks:
-
-\begin{methoddesc}{get_file}{key}
-Using the file after calling \method{flush()} or \method{close()} on the
-\class{MMDF} instance may yield unpredictable results or raise an exception.
-\end{methoddesc}
-
-\begin{methoddesc}{lock}{}
-\methodline{unlock}{}
-Three locking mechanisms are used---dot locking and, if available, the
-\cfunction{flock()} and \cfunction{lockf()} system calls.
-\end{methoddesc}
-
-\begin{seealso}
-\seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mmdf}{mmdf man page
-from tin}{A specification of MMDF format from the documentation of tin, a
-newsreader.}
-\seelink{http://en.wikipedia.org/wiki/MMDF}{MMDF}{A Wikipedia article
-describing the Multichannel Memorandum Distribution Facility.}
-\end{seealso}
-
-\subsection{\class{Message} objects}
-\label{mailbox-message-objects}
-
-\begin{classdesc}{Message}{\optional{message}}
-A subclass of the \module{email.Message} module's \class{Message}. Subclasses
-of \class{mailbox.Message} add mailbox-format-specific state and behavior.
-
-If \var{message} is omitted, the new instance is created in a default, empty
-state. If \var{message} is an \class{email.Message.Message} instance, its
-contents are copied; furthermore, any format-specific information is converted
-insofar as possible if \var{message} is a \class{Message} instance. If
-\var{message} is a string or a file, it should contain an \rfc{2822}-compliant
-message, which is read and parsed.
-\end{classdesc}
-
-The format-specific state and behaviors offered by subclasses vary, but in
-general it is only the properties that are not specific to a particular mailbox
-that are supported (although presumably the properties are specific to a
-particular mailbox format). For example, file offsets for single-file mailbox
-formats and file names for directory-based mailbox formats are not retained,
-because they are only applicable to the original mailbox. But state such as
-whether a message has been read by the user or marked as important is retained,
-because it applies to the message itself.
-
-There is no requirement that \class{Message} instances be used to represent
-messages retrieved using \class{Mailbox} instances. In some situations, the
-time and memory required to generate \class{Message} representations might not
-not acceptable. For such situations, \class{Mailbox} instances also offer
-string and file-like representations, and a custom message factory may be
-specified when a \class{Mailbox} instance is initialized.
-
-\subsubsection{\class{MaildirMessage}}
-\label{mailbox-maildirmessage}
-
-\begin{classdesc}{MaildirMessage}{\optional{message}}
-A message with Maildir-specific behaviors. Parameter \var{message}
-has the same meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-Typically, a mail user agent application moves all of the messages in the
-\file{new} subdirectory to the \file{cur} subdirectory after the first time the
-user opens and closes the mailbox, recording that the messages are old whether
-or not they've actually been read. Each message in \file{cur} has an "info"
-section added to its file name to store information about its state. (Some mail
-readers may also add an "info" section to messages in \file{new}.) The "info"
-section may take one of two forms: it may contain "2," followed by a list of
-standardized flags (e.g., "2,FR") or it may contain "1," followed by so-called
-experimental information. Standard flags for Maildir messages are as follows:
-
-\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
-\lineiii{D}{Draft}{Under composition}
-\lineiii{F}{Flagged}{Marked as important}
-\lineiii{P}{Passed}{Forwarded, resent, or bounced}
-\lineiii{R}{Replied}{Replied to}
-\lineiii{S}{Seen}{Read}
-\lineiii{T}{Trashed}{Marked for subsequent deletion}
-\end{tableiii}
-
-\class{MaildirMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_subdir}{}
-Return either "new" (if the message should be stored in the \file{new}
-subdirectory) or "cur" (if the message should be stored in the \file{cur}
-subdirectory). \note{A message is typically moved from \file{new} to \file{cur}
-after its mailbox has been accessed, whether or not the message is has been
-read. A message \code{msg} has been read if \code{"S" not in msg.get_flags()}
-is \code{True}.}
-\end{methoddesc}
-
-\begin{methoddesc}{set_subdir}{subdir}
-Set the subdirectory the message should be stored in. Parameter \var{subdir}
-must be either "new" or "cur".
-\end{methoddesc}
-
-\begin{methoddesc}{get_flags}{}
-Return a string specifying the flags that are currently set. If the message
-complies with the standard Maildir format, the result is the concatenation in
-alphabetical order of zero or one occurrence of each of \character{D},
-\character{F}, \character{P}, \character{R}, \character{S}, and \character{T}.
-The empty string is returned if no flags are set or if "info" contains
-experimental semantics.
-\end{methoddesc}
-
-\begin{methoddesc}{set_flags}{flags}
-Set the flags specified by \var{flags} and unset all others.
-\end{methoddesc}
-
-\begin{methoddesc}{add_flag}{flag}
-Set the flag(s) specified by \var{flag} without changing other flags. To add
-more than one flag at a time, \var{flag} may be a string of more than one
-character. The current "info" is overwritten whether or not it contains
-experimental information rather than
-flags.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_flag}{flag}
-Unset the flag(s) specified by \var{flag} without changing other flags. To
-remove more than one flag at a time, \var{flag} maybe a string of more than one
-character. If "info" contains experimental information rather than flags, the
-current "info" is not modified.
-\end{methoddesc}
-
-\begin{methoddesc}{get_date}{}
-Return the delivery date of the message as a floating-point number representing
-seconds since the epoch.
-\end{methoddesc}
-
-\begin{methoddesc}{set_date}{date}
-Set the delivery date of the message to \var{date}, a floating-point number
-representing seconds since the epoch.
-\end{methoddesc}
-
-\begin{methoddesc}{get_info}{}
-Return a string containing the "info" for a message. This is useful for
-accessing and modifying "info" that is experimental (i.e., not a list of
-flags).
-\end{methoddesc}
-
-\begin{methoddesc}{set_info}{info}
-Set "info" to \var{info}, which should be a string.
-\end{methoddesc}
-
-When a \class{MaildirMessage} instance is created based upon an
-\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status}
-and \mailheader{X-Status} headers are omitted and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
-\lineii{"cur" subdirectory}{O flag}
-\lineii{F flag}{F flag}
-\lineii{R flag}{A flag}
-\lineii{S flag}{R flag}
-\lineii{T flag}{D flag}
-\end{tableii}
-
-When a \class{MaildirMessage} instance is created based upon an
-\class{MHMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{"cur" subdirectory}{"unseen" sequence}
-\lineii{"cur" subdirectory and S flag}{no "unseen" sequence}
-\lineii{F flag}{"flagged" sequence}
-\lineii{R flag}{"replied" sequence}
-\end{tableii}
-
-When a \class{MaildirMessage} instance is created based upon a
-\class{BabylMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{"cur" subdirectory}{"unseen" label}
-\lineii{"cur" subdirectory and S flag}{no "unseen" label}
-\lineii{P flag}{"forwarded" or "resent" label}
-\lineii{R flag}{"answered" label}
-\lineii{T flag}{"deleted" label}
-\end{tableii}
-
-\subsubsection{\class{mboxMessage}}
-\label{mailbox-mboxmessage}
-
-\begin{classdesc}{mboxMessage}{\optional{message}}
-A message with mbox-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-Messages in an mbox mailbox are stored together in a single file. The sender's
-envelope address and the time of delivery are typically stored in a line
-beginning with "From~" that is used to indicate the start of a message, though
-there is considerable variation in the exact format of this data among mbox
-implementations. Flags that indicate the state of the message, such as whether
-it has been read or marked as important, are typically stored in
-\mailheader{Status} and \mailheader{X-Status} headers.
-
-Conventional flags for mbox messages are as follows:
-
-\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
-\lineiii{R}{Read}{Read}
-\lineiii{O}{Old}{Previously detected by MUA}
-\lineiii{D}{Deleted}{Marked for subsequent deletion}
-\lineiii{F}{Flagged}{Marked as important}
-\lineiii{A}{Answered}{Replied to}
-\end{tableiii}
-
-The "R" and "O" flags are stored in the \mailheader{Status} header, and the
-"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The
-flags and headers typically appear in the order mentioned.
-
-\class{mboxMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_from}{}
-Return a string representing the "From~" line that marks the start of the
-message in an mbox mailbox. The leading "From~" and the trailing newline are
-excluded.
-\end{methoddesc}
-
-\begin{methoddesc}{set_from}{from_\optional{, time_=None}}
-Set the "From~" line to \var{from_}, which should be specified without a
-leading "From~" or trailing newline. For convenience, \var{time_} may be
-specified and will be formatted appropriately and appended to \var{from_}. If
-\var{time_} is specified, it should be a \class{struct_time} instance, a tuple
-suitable for passing to \method{time.strftime()}, or \code{True} (to use
-\method{time.gmtime()}).
-\end{methoddesc}
-
-\begin{methoddesc}{get_flags}{}
-Return a string specifying the flags that are currently set. If the message
-complies with the conventional format, the result is the concatenation in the
-following order of zero or one occurrence of each of \character{R},
-\character{O}, \character{D}, \character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{set_flags}{flags}
-Set the flags specified by \var{flags} and unset all others. Parameter
-\var{flags} should be the concatenation in any order of zero or more
-occurrences of each of \character{R}, \character{O}, \character{D},
-\character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{add_flag}{flag}
-Set the flag(s) specified by \var{flag} without changing other flags. To add
-more than one flag at a time, \var{flag} may be a string of more than one
-character.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_flag}{flag}
-Unset the flag(s) specified by \var{flag} without changing other flags. To
-remove more than one flag at a time, \var{flag} maybe a string of more than one
-character.
-\end{methoddesc}
-
-When an \class{mboxMessage} instance is created based upon a
-\class{MaildirMessage} instance, a "From~" line is generated based upon the
-\class{MaildirMessage} instance's delivery date, and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{R flag}{S flag}
-\lineii{O flag}{"cur" subdirectory}
-\lineii{D flag}{T flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{R flag}
-\end{tableii}
-
-When an \class{mboxMessage} instance is created based upon an \class{MHMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{R flag and O flag}{no "unseen" sequence}
-\lineii{O flag}{"unseen" sequence}
-\lineii{F flag}{"flagged" sequence}
-\lineii{A flag}{"replied" sequence}
-\end{tableii}
-
-When an \class{mboxMessage} instance is created based upon a
-\class{BabylMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{R flag and O flag}{no "unseen" label}
-\lineii{O flag}{"unseen" label}
-\lineii{D flag}{"deleted" label}
-\lineii{A flag}{"answered" label}
-\end{tableii}
-
-When a \class{Message} instance is created based upon an \class{MMDFMessage}
-instance, the "From~" line is copied and all flags directly correspond:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MMDFMessage} state}
-\lineii{R flag}{R flag}
-\lineii{O flag}{O flag}
-\lineii{D flag}{D flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{A flag}
-\end{tableii}
-
-\subsubsection{\class{MHMessage}}
-\label{mailbox-mhmessage}
-
-\begin{classdesc}{MHMessage}{\optional{message}}
-A message with MH-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-MH messages do not support marks or flags in the traditional sense, but they do
-support sequences, which are logical groupings of arbitrary messages. Some mail
-reading programs (although not the standard \program{mh} and \program{nmh}) use
-sequences in much the same way flags are used with other formats, as follows:
-
-\begin{tableii}{l|l}{textrm}{Sequence}{Explanation}
-\lineii{unseen}{Not read, but previously detected by MUA}
-\lineii{replied}{Replied to}
-\lineii{flagged}{Marked as important}
-\end{tableii}
-
-\class{MHMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_sequences}{}
-Return a list of the names of sequences that include this message.
-\end{methoddesc}
-
-\begin{methoddesc}{set_sequences}{sequences}
-Set the list of sequences that include this message.
-\end{methoddesc}
-
-\begin{methoddesc}{add_sequence}{sequence}
-Add \var{sequence} to the list of sequences that include this message.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_sequence}{sequence}
-Remove \var{sequence} from the list of sequences that include this message.
-\end{methoddesc}
-
-When an \class{MHMessage} instance is created based upon a
-\class{MaildirMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{"unseen" sequence}{no S flag}
-\lineii{"replied" sequence}{R flag}
-\lineii{"flagged" sequence}{F flag}
-\end{tableii}
-
-When an \class{MHMessage} instance is created based upon an \class{mboxMessage}
-or \class{MMDFMessage} instance, the \mailheader{Status} and
-\mailheader{X-Status} headers are omitted and the following conversions take
-place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
-\lineii{"unseen" sequence}{no R flag}
-\lineii{"replied" sequence}{A flag}
-\lineii{"flagged" sequence}{F flag}
-\end{tableii}
-
-When an \class{MHMessage} instance is created based upon a \class{BabylMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{"unseen" sequence}{"unseen" label}
-\lineii{"replied" sequence}{"answered" label}
-\end{tableii}
-
-\subsubsection{\class{BabylMessage}}
-\label{mailbox-babylmessage}
-
-\begin{classdesc}{BabylMessage}{\optional{message}}
-A message with Babyl-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-Certain message labels, called \dfn{attributes}, are defined by convention to
-have special meanings. The attributes are as follows:
-
-\begin{tableii}{l|l}{textrm}{Label}{Explanation}
-\lineii{unseen}{Not read, but previously detected by MUA}
-\lineii{deleted}{Marked for subsequent deletion}
-\lineii{filed}{Copied to another file or mailbox}
-\lineii{answered}{Replied to}
-\lineii{forwarded}{Forwarded}
-\lineii{edited}{Modified by the user}
-\lineii{resent}{Resent}
-\end{tableii}
-
-By default, Rmail displays only
-visible headers. The \class{BabylMessage} class, though, uses the original
-headers because they are more complete. Visible headers may be accessed
-explicitly if desired.
-
-\class{BabylMessage} instances offer the following methods:
-
-\begin{methoddesc}{get_labels}{}
-Return a list of labels on the message.
-\end{methoddesc}
-
-\begin{methoddesc}{set_labels}{labels}
-Set the list of labels on the message to \var{labels}.
-\end{methoddesc}
-
-\begin{methoddesc}{add_label}{label}
-Add \var{label} to the list of labels on the message.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_label}{label}
-Remove \var{label} from the list of labels on the message.
-\end{methoddesc}
-
-\begin{methoddesc}{get_visible}{}
-Return an \class{Message} instance whose headers are the message's visible
-headers and whose body is empty.
-\end{methoddesc}
-
-\begin{methoddesc}{set_visible}{visible}
-Set the message's visible headers to be the same as the headers in
-\var{message}. Parameter \var{visible} should be a \class{Message} instance, an
-\class{email.Message.Message} instance, a string, or a file-like object (which
-should be open in text mode).
-\end{methoddesc}
-
-\begin{methoddesc}{update_visible}{}
-When a \class{BabylMessage} instance's original headers are modified, the
-visible headers are not automatically modified to correspond. This method
-updates the visible headers as follows: each visible header with a
-corresponding original header is set to the value of the original header, each
-visible header without a corresponding original header is removed, and any of
-\mailheader{Date}, \mailheader{From}, \mailheader{Reply-To}, \mailheader{To},
-\mailheader{CC}, and \mailheader{Subject} that are present in the original
-headers but not the visible headers are added to the visible headers.
-\end{methoddesc}
-
-When a \class{BabylMessage} instance is created based upon a
-\class{MaildirMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{"unseen" label}{no S flag}
-\lineii{"deleted" label}{T flag}
-\lineii{"answered" label}{R flag}
-\lineii{"forwarded" label}{P flag}
-\end{tableii}
-
-When a \class{BabylMessage} instance is created based upon an
-\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status}
-and \mailheader{X-Status} headers are omitted and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
-\lineii{"unseen" label}{no R flag}
-\lineii{"deleted" label}{D flag}
-\lineii{"answered" label}{A flag}
-\end{tableii}
-
-When a \class{BabylMessage} instance is created based upon an \class{MHMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{"unseen" label}{"unseen" sequence}
-\lineii{"answered" label}{"replied" sequence}
-\end{tableii}
-
-\subsubsection{\class{MMDFMessage}}
-\label{mailbox-mmdfmessage}
-
-\begin{classdesc}{MMDFMessage}{\optional{message}}
-A message with MMDF-specific behaviors. Parameter \var{message} has the same
-meaning as with the \class{Message} constructor.
-\end{classdesc}
-
-As with message in an mbox mailbox, MMDF messages are stored with the sender's
-address and the delivery date in an initial line beginning with "From ".
-Likewise, flags that indicate the state of the message are typically stored in
-\mailheader{Status} and \mailheader{X-Status} headers.
-
-Conventional flags for MMDF messages are identical to those of mbox message and
-are as follows:
-
-\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
-\lineiii{R}{Read}{Read}
-\lineiii{O}{Old}{Previously detected by MUA}
-\lineiii{D}{Deleted}{Marked for subsequent deletion}
-\lineiii{F}{Flagged}{Marked as important}
-\lineiii{A}{Answered}{Replied to}
-\end{tableiii}
-
-The "R" and "O" flags are stored in the \mailheader{Status} header, and the
-"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The
-flags and headers typically appear in the order mentioned.
-
-\class{MMDFMessage} instances offer the following methods, which are identical
-to those offered by \class{mboxMessage}:
-
-\begin{methoddesc}{get_from}{}
-Return a string representing the "From~" line that marks the start of the
-message in an mbox mailbox. The leading "From~" and the trailing newline are
-excluded.
-\end{methoddesc}
-
-\begin{methoddesc}{set_from}{from_\optional{, time_=None}}
-Set the "From~" line to \var{from_}, which should be specified without a
-leading "From~" or trailing newline. For convenience, \var{time_} may be
-specified and will be formatted appropriately and appended to \var{from_}. If
-\var{time_} is specified, it should be a \class{struct_time} instance, a tuple
-suitable for passing to \method{time.strftime()}, or \code{True} (to use
-\method{time.gmtime()}).
-\end{methoddesc}
-
-\begin{methoddesc}{get_flags}{}
-Return a string specifying the flags that are currently set. If the message
-complies with the conventional format, the result is the concatenation in the
-following order of zero or one occurrence of each of \character{R},
-\character{O}, \character{D}, \character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{set_flags}{flags}
-Set the flags specified by \var{flags} and unset all others. Parameter
-\var{flags} should be the concatenation in any order of zero or more
-occurrences of each of \character{R}, \character{O}, \character{D},
-\character{F}, and \character{A}.
-\end{methoddesc}
-
-\begin{methoddesc}{add_flag}{flag}
-Set the flag(s) specified by \var{flag} without changing other flags. To add
-more than one flag at a time, \var{flag} may be a string of more than one
-character.
-\end{methoddesc}
-
-\begin{methoddesc}{remove_flag}{flag}
-Unset the flag(s) specified by \var{flag} without changing other flags. To
-remove more than one flag at a time, \var{flag} maybe a string of more than one
-character.
-\end{methoddesc}
-
-When an \class{MMDFMessage} instance is created based upon a
-\class{MaildirMessage} instance, a "From~" line is generated based upon the
-\class{MaildirMessage} instance's delivery date, and the following conversions
-take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MaildirMessage} state}
-\lineii{R flag}{S flag}
-\lineii{O flag}{"cur" subdirectory}
-\lineii{D flag}{T flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{R flag}
-\end{tableii}
-
-When an \class{MMDFMessage} instance is created based upon an \class{MHMessage}
-instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{MHMessage} state}
-\lineii{R flag and O flag}{no "unseen" sequence}
-\lineii{O flag}{"unseen" sequence}
-\lineii{F flag}{"flagged" sequence}
-\lineii{A flag}{"replied" sequence}
-\end{tableii}
-
-When an \class{MMDFMessage} instance is created based upon a
-\class{BabylMessage} instance, the following conversions take place:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{BabylMessage} state}
-\lineii{R flag and O flag}{no "unseen" label}
-\lineii{O flag}{"unseen" label}
-\lineii{D flag}{"deleted" label}
-\lineii{A flag}{"answered" label}
-\end{tableii}
-
-When an \class{MMDFMessage} instance is created based upon an
-\class{mboxMessage} instance, the "From~" line is copied and all flags directly
-correspond:
-
-\begin{tableii}{l|l}{textrm}
- {Resulting state}{\class{mboxMessage} state}
-\lineii{R flag}{R flag}
-\lineii{O flag}{O flag}
-\lineii{D flag}{D flag}
-\lineii{F flag}{F flag}
-\lineii{A flag}{A flag}
-\end{tableii}
-
-\subsection{Exceptions}
-
-The following exception classes are defined in the \module{mailbox} module:
-
-\begin{classdesc}{Error}{}
-The based class for all other module-specific exceptions.
-\end{classdesc}
-
-\begin{classdesc}{NoSuchMailboxError}{}
-Raised when a mailbox is expected but is not found, such as when instantiating
-a \class{Mailbox} subclass with a path that does not exist (and with the
-\var{create} parameter set to \code{False}), or when opening a folder that does
-not exist.
-\end{classdesc}
-
-\begin{classdesc}{NotEmptyErrorError}{}
-Raised when a mailbox is not empty but is expected to be, such as when deleting
-a folder that contains messages.
-\end{classdesc}
-
-\begin{classdesc}{ExternalClashError}{}
-Raised when some mailbox-related condition beyond the control of the program
-causes it to be unable to proceed, such as when failing to acquire a lock that
-another program already holds a lock, or when a uniquely-generated file name
-already exists.
-\end{classdesc}
-
-\begin{classdesc}{FormatError}{}
-Raised when the data in a file cannot be parsed, such as when an \class{MH}
-instance attempts to read a corrupted \file{.mh_sequences} file.
-\end{classdesc}
-
-\subsection{Deprecated classes and methods}
-\label{mailbox-deprecated}
-
-Older versions of the \module{mailbox} module do not support modification of
-mailboxes, such as adding or removing message, and do not provide classes to
-represent format-specific message properties. For backward compatibility, the
-older mailbox classes are still available, but the newer classes should be used
-in preference to them.
-
-Older mailbox objects support only iteration and provide a single public
-method:
-
-\begin{methoddesc}[oldmailbox]{next}{}
-Return the next message in the mailbox, created with the optional \var{factory}
-argument passed into the mailbox object's constructor. By default this is an
-\class{rfc822.Message} object (see the \refmodule{rfc822} module). Depending
-on the mailbox implementation the \var{fp} attribute of this object may be a
-true file object or a class instance simulating a file object, taking care of
-things like message boundaries if multiple mail messages are contained in a
-single file, etc. If no more messages are available, this method returns
-\code{None}.
-\end{methoddesc}
-
-Most of the older mailbox classes have names that differ from the current
-mailbox class names, except for \class{Maildir}. For this reason, the new
-\class{Maildir} class defines a \method{next()} method and its constructor
-differs slightly from those of the other new mailbox classes.
-
-The older mailbox classes whose names are not the same as their newer
-counterparts are as follows:
-
-\begin{classdesc}{UnixMailbox}{fp\optional{, factory}}
-Access to a classic \UNIX-style mailbox, where all messages are
-contained in a single file and separated by \samp{From }
-(a.k.a.\ \samp{From_}) lines. The file object \var{fp} points to the
-mailbox file. The optional \var{factory} parameter is a callable that
-should create new message objects. \var{factory} is called with one
-argument, \var{fp} by the \method{next()} method of the mailbox
-object. The default is the \class{rfc822.Message} class (see the
-\refmodule{rfc822} module -- and the note below).
-
-\begin{notice}
- For reasons of this module's internal implementation, you will
- probably want to open the \var{fp} object in binary mode. This is
- especially important on Windows.
-\end{notice}
-
-For maximum portability, messages in a \UNIX-style mailbox are
-separated by any line that begins exactly with the string \code{'From
-'} (note the trailing space) if preceded by exactly two newlines.
-Because of the wide-range of variations in practice, nothing else on
-the \samp{From_} line should be considered. However, the current
-implementation doesn't check for the leading two newlines. This is
-usually fine for most applications.
-
-The \class{UnixMailbox} class implements a more strict version of
-\samp{From_} line checking, using a regular expression that usually correctly
-matched \samp{From_} delimiters. It considers delimiter line to be separated
-by \samp{From \var{name} \var{time}} lines. For maximum portability,
-use the \class{PortableUnixMailbox} class instead. This class is
-identical to \class{UnixMailbox} except that individual messages are
-separated by only \samp{From } lines.
-
-For more information, see
-\citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
-Netscape Mail on \UNIX: Why the Content-Length Format is Bad}.
-\end{classdesc}
-
-\begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}}
-A less-strict version of \class{UnixMailbox}, which considers only the
-\samp{From } at the beginning of the line separating messages. The
-``\var{name} \var{time}'' portion of the From line is ignored, to
-protect against some variations that are observed in practice. This
-works since lines in the message which begin with \code{'From '} are
-quoted by mail handling software at delivery-time.
-\end{classdesc}
-
-\begin{classdesc}{MmdfMailbox}{fp\optional{, factory}}
-Access an MMDF-style mailbox, where all messages are contained
-in a single file and separated by lines consisting of 4 control-A
-characters. The file object \var{fp} points to the mailbox file.
-Optional \var{factory} is as with the \class{UnixMailbox} class.
-\end{classdesc}
-
-\begin{classdesc}{MHMailbox}{dirname\optional{, factory}}
-Access an MH mailbox, a directory with each message in a separate
-file with a numeric name.
-The name of the mailbox directory is passed in \var{dirname}.
-\var{factory} is as with the \class{UnixMailbox} class.
-\end{classdesc}
-
-\begin{classdesc}{BabylMailbox}{fp\optional{, factory}}
-Access a Babyl mailbox, which is similar to an MMDF mailbox. In
-Babyl format, each message has two sets of headers, the
-\emph{original} headers and the \emph{visible} headers. The original
-headers appear before a line containing only \code{'*** EOOH ***'}
-(End-Of-Original-Headers) and the visible headers appear after the
-\code{EOOH} line. Babyl-compliant mail readers will show you only the
-visible headers, and \class{BabylMailbox} objects will return messages
-containing only the visible headers. You'll have to do your own
-parsing of the mailbox file to get at the original headers. Mail
-messages start with the EOOH line and end with a line containing only
-\code{'\e{}037\e{}014'}. \var{factory} is as with the
-\class{UnixMailbox} class.
-\end{classdesc}
-
-If you wish to use the older mailbox classes with the \module{email} module
-rather than the deprecated \module{rfc822} module, you can do so as follows:
-
-\begin{verbatim}
-import email
-import email.Errors
-import mailbox
-
-def msgfactory(fp):
- try:
- return email.message_from_file(fp)
- except email.Errors.MessageParseError:
- # Don't return None since that will
- # stop the mailbox iterator
- return ''
-
-mbox = mailbox.UnixMailbox(fp, msgfactory)
-\end{verbatim}
-
-Alternatively, if you know your mailbox contains only well-formed MIME
-messages, you can simplify this to:
-
-\begin{verbatim}
-import email
-import mailbox
-
-mbox = mailbox.UnixMailbox(fp, email.message_from_file)
-\end{verbatim}
-
-\subsection{Examples}
-\label{mailbox-examples}
-
-A simple example of printing the subjects of all messages in a mailbox that
-seem interesting:
-
-\begin{verbatim}
-import mailbox
-for message in mailbox.mbox('~/mbox'):
- subject = message['subject'] # Could possibly be None.
- if subject and 'python' in subject.lower():
- print subject
-\end{verbatim}
-
-To copy all mail from a Babyl mailbox to an MH mailbox, converting all
-of the format-specific information that can be converted:
-
-\begin{verbatim}
-import mailbox
-destination = mailbox.MH('~/Mail')
-destination.lock()
-for message in mailbox.Babyl('~/RMAIL'):
- destination.add(MHMessage(message))
-destination.flush()
-destination.unlock()
-\end{verbatim}
-
-This example sorts mail from several mailing lists into different
-mailboxes, being careful to avoid mail corruption due to concurrent
-modification by other programs, mail loss due to interruption of the
-program, or premature termination due to malformed messages in the
-mailbox:
-
-\begin{verbatim}
-import mailbox
-import email.Errors
-
-list_names = ('python-list', 'python-dev', 'python-bugs')
-
-boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
-inbox = mailbox.Maildir('~/Maildir', factory=None)
-
-for key in inbox.iterkeys():
- try:
- message = inbox[key]
- except email.Errors.MessageParseError:
- continue # The message is malformed. Just leave it.
-
- for name in list_names:
- list_id = message['list-id']
- if list_id and name in list_id:
- # Get mailbox to use
- box = boxes[name]
-
- # Write copy to disk before removing original.
- # If there's a crash, you might duplicate a message, but
- # that's better than losing a message completely.
- box.lock()
- box.add(message)
- box.flush()
- box.unlock()
-
- # Remove original message
- inbox.lock()
- inbox.discard(key)
- inbox.flush()
- inbox.unlock()
- break # Found destination, so stop looking.
-
-for box in boxes.itervalues():
- box.close()
-\end{verbatim}
diff --git a/Doc/lib/libmailcap.tex b/Doc/lib/libmailcap.tex
deleted file mode 100644
index b221bb3..0000000
--- a/Doc/lib/libmailcap.tex
+++ /dev/null
@@ -1,82 +0,0 @@
-\section{\module{mailcap} ---
- Mailcap file handling.}
-\declaremodule{standard}{mailcap}
-
-\modulesynopsis{Mailcap file handling.}
-
-
-Mailcap files are used to configure how MIME-aware applications such
-as mail readers and Web browsers react to files with different MIME
-types. (The name ``mailcap'' is derived from the phrase ``mail
-capability''.) For example, a mailcap file might contain a line like
-\samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email
-message or Web document with the MIME type \mimetype{video/mpeg},
-\samp{\%s} will be replaced by a filename (usually one belonging to a
-temporary file) and the \program{xmpeg} program can be automatically
-started to view the file.
-
-The mailcap format is documented in \rfc{1524}, ``A User Agent
-Configuration Mechanism For Multimedia Mail Format Information,'' but
-is not an Internet standard. However, mailcap files are supported on
-most \UNIX{} systems.
-
-\begin{funcdesc}{findmatch}{caps, MIMEtype%
- \optional{, key\optional{,
- filename\optional{, plist}}}}
-Return a 2-tuple; the first element is a string containing the command
-line to be executed
-(which can be passed to \function{os.system()}), and the second element is
-the mailcap entry for a given MIME type. If no matching MIME
-type can be found, \code{(None, None)} is returned.
-
-\var{key} is the name of the field desired, which represents the type
-of activity to be performed; the default value is 'view', since in the
-most common case you simply want to view the body of the MIME-typed
-data. Other possible values might be 'compose' and 'edit', if you
-wanted to create a new body of the given MIME type or alter the
-existing body data. See \rfc{1524} for a complete list of these
-fields.
-
-\var{filename} is the filename to be substituted for \samp{\%s} in the
-command line; the default value is
-\code{'/dev/null'} which is almost certainly not what you want, so
-usually you'll override it by specifying a filename.
-
-\var{plist} can be a list containing named parameters; the default
-value is simply an empty list. Each entry in the list must be a
-string containing the parameter name, an equals sign (\character{=}),
-and the parameter's value. Mailcap entries can contain
-named parameters like \code{\%\{foo\}}, which will be replaced by the
-value of the parameter named 'foo'. For example, if the command line
-\samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}}
-was in a mailcap file, and \var{plist} was set to \code{['id=1',
-'number=2', 'total=3']}, the resulting command line would be
-\code{'showpartial 1 2 3'}.
-
-In a mailcap file, the ``test'' field can optionally be specified to
-test some external condition (such as the machine architecture, or the
-window system in use) to determine whether or not the mailcap line
-applies. \function{findmatch()} will automatically check such
-conditions and skip the entry if the check fails.
-\end{funcdesc}
-
-\begin{funcdesc}{getcaps}{}
-Returns a dictionary mapping MIME types to a list of mailcap file
-entries. This dictionary must be passed to the \function{findmatch()}
-function. An entry is stored as a list of dictionaries, but it
-shouldn't be necessary to know the details of this representation.
-
-The information is derived from all of the mailcap files found on the
-system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
-will override settings in the system mailcap files
-\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
-\file{/usr/local/etc/mailcap}.
-\end{funcdesc}
-
-An example usage:
-\begin{verbatim}
->>> import mailcap
->>> d=mailcap.getcaps()
->>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
-('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
-\end{verbatim}
diff --git a/Doc/lib/libmain.tex b/Doc/lib/libmain.tex
deleted file mode 100644
index 00c7426..0000000
--- a/Doc/lib/libmain.tex
+++ /dev/null
@@ -1,16 +0,0 @@
-\section{\module{__main__} ---
- Top-level script environment}
-
-\declaremodule[main]{builtin}{__main__}
-\modulesynopsis{The environment where the top-level script is run.}
-
-This module represents the (otherwise anonymous) scope in which the
-interpreter's main program executes --- commands read either from
-standard input, from a script file, or from an interactive prompt. It
-is this environment in which the idiomatic ``conditional script''
-stanza causes a script to run:
-
-\begin{verbatim}
-if __name__ == "__main__":
- main()
-\end{verbatim}
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
deleted file mode 100644
index 63ff392..0000000
--- a/Doc/lib/libmarshal.tex
+++ /dev/null
@@ -1,117 +0,0 @@
-\section{\module{marshal} ---
- Internal Python object serialization}
-
-\declaremodule{builtin}{marshal}
-\modulesynopsis{Convert Python objects to streams of bytes and back
- (with different constraints).}
-
-
-This module contains functions that can read and write Python
-values in a binary format. The format is specific to Python, but
-independent of machine architecture issues (e.g., you can write a
-Python value to a file on a PC, transport the file to a Sun, and read
-it back there). Details of the format are undocumented on purpose;
-it may change between Python versions (although it rarely
-does).\footnote{The name of this module stems from a bit of
- terminology used by the designers of Modula-3 (amongst others), who
- use the term ``marshalling'' for shipping of data around in a
- self-contained form. Strictly speaking, ``to marshal'' means to
- convert some data from internal to external form (in an RPC buffer for
- instance) and ``unmarshalling'' for the reverse process.}
-
-This is not a general ``persistence'' module. For general persistence
-and transfer of Python objects through RPC calls, see the modules
-\refmodule{pickle} and \refmodule{shelve}. The \module{marshal} module exists
-mainly to support reading and writing the ``pseudo-compiled'' code for
-Python modules of \file{.pyc} files. Therefore, the Python
-maintainers reserve the right to modify the marshal format in backward
-incompatible ways should the need arise. If you're serializing and
-de-serializing Python objects, use the \module{pickle} module instead.
-\refstmodindex{pickle}
-\refstmodindex{shelve}
-\obindex{code}
-
-\begin{notice}[warning]
-The \module{marshal} module is not intended to be secure against
-erroneous or maliciously constructed data. Never unmarshal data
-received from an untrusted or unauthenticated source.
-\end{notice}
-
-Not all Python object types are supported; in general, only objects
-whose value is independent from a particular invocation of Python can
-be written and read by this module. The following types are supported:
-\code{None}, integers, long integers, floating point numbers,
-strings, Unicode objects, tuples, lists, dictionaries, and code
-objects, where it should be understood that tuples, lists and
-dictionaries are only supported as long as the values contained
-therein are themselves supported; and recursive lists and dictionaries
-should not be written (they will cause infinite loops).
-
-\strong{Caveat:} On machines where C's \code{long int} type has more than
-32 bits (such as the DEC Alpha), it is possible to create plain Python
-integers that are longer than 32 bits.
-If such an integer is marshaled and read back in on a machine where
-C's \code{long int} type has only 32 bits, a Python long integer object
-is returned instead. While of a different type, the numeric value is
-the same. (This behavior is new in Python 2.2. In earlier versions,
-all but the least-significant 32 bits of the value were lost, and a
-warning message was printed.)
-
-There are functions that read/write files as well as functions
-operating on strings.
-
-The module defines these functions:
-
-\begin{funcdesc}{dump}{value, file\optional{, version}}
- Write the value on the open file. The value must be a supported
- type. The file must be an open file object such as
- \code{sys.stdout} or returned by \function{open()} or
- \function{posix.popen()}. It must be opened in binary mode
- (\code{'wb'} or \code{'w+b'}).
-
- If the value has (or contains an object that has) an unsupported type,
- a \exception{ValueError} exception is raised --- but garbage data
- will also be written to the file. The object will not be properly
- read back by \function{load()}.
-
- \versionadded[The \var{version} argument indicates the data
- format that \code{dump} should use (see below)]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{load}{file}
- Read one value from the open file and return it. If no valid value
- is read, raise \exception{EOFError}, \exception{ValueError} or
- \exception{TypeError}. The file must be an open file object opened
- in binary mode (\code{'rb'} or \code{'r+b'}).
-
- \warning{If an object containing an unsupported type was
- marshalled with \function{dump()}, \function{load()} will substitute
- \code{None} for the unmarshallable type.}
-\end{funcdesc}
-
-\begin{funcdesc}{dumps}{value\optional{, version}}
- Return the string that would be written to a file by
- \code{dump(\var{value}, \var{file})}. The value must be a supported
- type. Raise a \exception{ValueError} exception if value has (or
- contains an object that has) an unsupported type.
-
- \versionadded[The \var{version} argument indicates the data
- format that \code{dumps} should use (see below)]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{loads}{string}
- Convert the string to a value. If no valid value is found, raise
- \exception{EOFError}, \exception{ValueError} or
- \exception{TypeError}. Extra characters in the string are ignored.
-\end{funcdesc}
-
-In addition, the following constants are defined:
-
-\begin{datadesc}{version}
- Indicates the format that the module uses. Version 0 is the
- historical format, version 1 (added in Python 2.4) shares interned
- strings and version 2 (added in Python 2.5) uses a binary format for
- floating point numbers. The current version is 2.
-
- \versionadded{2.4}
-\end{datadesc}
diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex
deleted file mode 100644
index e52f8f9..0000000
--- a/Doc/lib/libmath.tex
+++ /dev/null
@@ -1,209 +0,0 @@
-\section{\module{math} ---
- Mathematical functions}
-
-\declaremodule{builtin}{math}
-\modulesynopsis{Mathematical functions (\function{sin()} etc.).}
-
-This module is always available. It provides access to the
-mathematical functions defined by the C standard.
-
-These functions cannot be used with complex numbers; use the functions
-of the same name from the \refmodule{cmath} module if you require
-support for complex numbers. The distinction between functions which
-support complex numbers and those which don't is made since most users
-do not want to learn quite as much mathematics as required to
-understand complex numbers. Receiving an exception instead of a
-complex result allows earlier detection of the unexpected complex
-number used as a parameter, so that the programmer can determine how
-and why it was generated in the first place.
-
-The following functions are provided by this module. Except
-when explicitly noted otherwise, all return values are floats.
-
-Number-theoretic and representation functions:
-
-\begin{funcdesc}{ceil}{x}
-Return the ceiling of \var{x} as a float, the smallest integer value
-greater than or equal to \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{fabs}{x}
-Return the absolute value of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{floor}{x}
-Return the floor of \var{x} as a float, the largest integer value
-less than or equal to \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{fmod}{x, y}
-Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
-Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
-the same result. The intent of the C standard is that
-\code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite
-precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer
-\var{n} such that the result has the same sign as \var{x} and
-magnitude less than \code{abs(\var{y})}. Python's
-\code{\var{x} \%\ \var{y}} returns a result with the sign of
-\var{y} instead, and may not be exactly computable for float arguments.
-For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the
-result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which
-cannot be represented exactly as a float, and rounds to the surprising
-\code{1e100}. For this reason, function \function{fmod()} is generally
-preferred when working with floats, while Python's
-\code{\var{x} \%\ \var{y}} is preferred when working with integers.
-\end{funcdesc}
-
-\begin{funcdesc}{frexp}{x}
-Return the mantissa and exponent of \var{x} as the pair
-\code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an
-integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly.
-If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
-\code{0.5 <= abs(\var{m}) < 1}. This is used to "pick apart" the
-internal representation of a float in a portable way.
-\end{funcdesc}
-
-\begin{funcdesc}{ldexp}{x, i}
-Return \code{\var{x} * (2**\var{i})}. This is essentially the inverse of
-function \function{frexp()}.
-\end{funcdesc}
-
-\begin{funcdesc}{modf}{x}
-Return the fractional and integer parts of \var{x}. Both results
-carry the sign of \var{x}, and both are floats.
-\end{funcdesc}
-
-Note that \function{frexp()} and \function{modf()} have a different
-call/return pattern than their C equivalents: they take a single
-argument and return a pair of values, rather than returning their
-second return value through an `output parameter' (there is no such
-thing in Python).
-
-For the \function{ceil()}, \function{floor()}, and \function{modf()}
-functions, note that \emph{all} floating-point numbers of sufficiently
-large magnitude are exact integers. Python floats typically carry no more
-than 53 bits of precision (the same as the platform C double type), in
-which case any float \var{x} with \code{abs(\var{x}) >= 2**52}
-necessarily has no fractional bits.
-
-
-Power and logarithmic functions:
-
-\begin{funcdesc}{exp}{x}
-Return \code{e**\var{x}}.
-\end{funcdesc}
-
-\begin{funcdesc}{log}{x\optional{, base}}
-Return the logarithm of \var{x} to the given \var{base}.
-If the \var{base} is not specified, return the natural logarithm of \var{x}
-(that is, the logarithm to base \emph{e}).
-\versionchanged[\var{base} argument added]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{log10}{x}
-Return the base-10 logarithm of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{pow}{x, y}
-Return \code{\var{x}**\var{y}}.
-\end{funcdesc}
-
-\begin{funcdesc}{sqrt}{x}
-Return the square root of \var{x}.
-\end{funcdesc}
-
-Trigonometric functions:
-
-\begin{funcdesc}{acos}{x}
-Return the arc cosine of \var{x}, in radians.
-\end{funcdesc}
-
-\begin{funcdesc}{asin}{x}
-Return the arc sine of \var{x}, in radians.
-\end{funcdesc}
-
-\begin{funcdesc}{atan}{x}
-Return the arc tangent of \var{x}, in radians.
-\end{funcdesc}
-
-\begin{funcdesc}{atan2}{y, x}
-Return \code{atan(\var{y} / \var{x})}, in radians.
-The result is between \code{-pi} and \code{pi}.
-The vector in the plane from the origin to point \code{(\var{x}, \var{y})}
-makes this angle with the positive X axis.
-The point of \function{atan2()} is that the signs of both inputs are
-known to it, so it can compute the correct quadrant for the angle.
-For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4},
-but \code{atan2(-1, -1)} is \code{-3*pi/4}.
-\end{funcdesc}
-
-\begin{funcdesc}{cos}{x}
-Return the cosine of \var{x} radians.
-\end{funcdesc}
-
-\begin{funcdesc}{hypot}{x, y}
-Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
-This is the length of the vector from the origin to point
-\code{(\var{x}, \var{y})}.
-\end{funcdesc}
-
-\begin{funcdesc}{sin}{x}
-Return the sine of \var{x} radians.
-\end{funcdesc}
-
-\begin{funcdesc}{tan}{x}
-Return the tangent of \var{x} radians.
-\end{funcdesc}
-
-Angular conversion:
-
-\begin{funcdesc}{degrees}{x}
-Converts angle \var{x} from radians to degrees.
-\end{funcdesc}
-
-\begin{funcdesc}{radians}{x}
-Converts angle \var{x} from degrees to radians.
-\end{funcdesc}
-
-Hyperbolic functions:
-
-\begin{funcdesc}{cosh}{x}
-Return the hyperbolic cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{sinh}{x}
-Return the hyperbolic sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{tanh}{x}
-Return the hyperbolic tangent of \var{x}.
-\end{funcdesc}
-
-The module also defines two mathematical constants:
-
-\begin{datadesc}{pi}
-The mathematical constant \emph{pi}.
-\end{datadesc}
-
-\begin{datadesc}{e}
-The mathematical constant \emph{e}.
-\end{datadesc}
-
-\begin{notice}
- The \module{math} module consists mostly of thin wrappers around
- the platform C math library functions. Behavior in exceptional cases is
- loosely specified by the C standards, and Python inherits much of its
- math-function error-reporting behavior from the platform C
- implementation. As a result,
- the specific exceptions raised in error cases (and even whether some
- arguments are considered to be exceptional at all) are not defined in any
- useful cross-platform or cross-release way. For example, whether
- \code{math.log(0)} returns \code{-Inf} or raises \exception{ValueError} or
- \exception{OverflowError} isn't defined, and in
- cases where \code{math.log(0)} raises \exception{OverflowError},
- \code{math.log(0L)} may raise \exception{ValueError} instead.
-\end{notice}
-
-\begin{seealso}
- \seemodule{cmath}{Complex number versions of many of these functions.}
-\end{seealso}
diff --git a/Doc/lib/libmhlib.tex b/Doc/lib/libmhlib.tex
deleted file mode 100644
index 3e70663..0000000
--- a/Doc/lib/libmhlib.tex
+++ /dev/null
@@ -1,168 +0,0 @@
-\section{\module{mhlib} ---
- Access to MH mailboxes}
-
-% LaTeX'ized from the comments in the module by Skip Montanaro
-% <skip@mojam.com>.
-
-\declaremodule{standard}{mhlib}
-\modulesynopsis{Manipulate MH mailboxes from Python.}
-
-
-The \module{mhlib} module provides a Python interface to MH folders and
-their contents.
-
-The module contains three basic classes, \class{MH}, which represents a
-particular collection of folders, \class{Folder}, which represents a single
-folder, and \class{Message}, which represents a single message.
-
-
-\begin{classdesc}{MH}{\optional{path\optional{, profile}}}
-\class{MH} represents a collection of MH folders.
-\end{classdesc}
-
-\begin{classdesc}{Folder}{mh, name}
-The \class{Folder} class represents a single folder and its messages.
-\end{classdesc}
-
-\begin{classdesc}{Message}{folder, number\optional{, name}}
-\class{Message} objects represent individual messages in a folder. The
-Message class is derived from \class{mimetools.Message}.
-\end{classdesc}
-
-
-\subsection{MH Objects \label{mh-objects}}
-
-\class{MH} instances have the following methods:
-
-
-\begin{methoddesc}[MH]{error}{format\optional{, ...}}
-Print an error message -- can be overridden.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{getprofile}{key}
-Return a profile entry (\code{None} if not set).
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{getpath}{}
-Return the mailbox pathname.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{getcontext}{}
-Return the current folder name.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{setcontext}{name}
-Set the current folder name.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listfolders}{}
-Return a list of top-level folders.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listallfolders}{}
-Return a list of all folders.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listsubfolders}{name}
-Return a list of direct subfolders of the given folder.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{listallsubfolders}{name}
-Return a list of all subfolders of the given folder.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{makefolder}{name}
-Create a new folder.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{deletefolder}{name}
-Delete a folder -- must have no subfolders.
-\end{methoddesc}
-
-\begin{methoddesc}[MH]{openfolder}{name}
-Return a new open folder object.
-\end{methoddesc}
-
-
-
-\subsection{Folder Objects \label{mh-folder-objects}}
-
-\class{Folder} instances represent open folders and have the following
-methods:
-
-
-\begin{methoddesc}[Folder]{error}{format\optional{, ...}}
-Print an error message -- can be overridden.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getfullname}{}
-Return the folder's full pathname.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getsequencesfilename}{}
-Return the full pathname of the folder's sequences file.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getmessagefilename}{n}
-Return the full pathname of message \var{n} of the folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{listmessages}{}
-Return a list of messages in the folder (as numbers).
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getcurrent}{}
-Return the current message number.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{setcurrent}{n}
-Set the current message number to \var{n}.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{parsesequence}{seq}
-Parse msgs syntax into list of messages.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getlast}{}
-Get last message, or \code{0} if no messages are in the folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{setlast}{n}
-Set last message (internal use only).
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{getsequences}{}
-Return dictionary of sequences in folder. The sequence names are used
-as keys, and the values are the lists of message numbers in the
-sequences.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{putsequences}{dict}
-Return dictionary of sequences in folder {name: list}.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{removemessages}{list}
-Remove messages in list from folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{refilemessages}{list, tofolder}
-Move messages in list to other folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton}
-Move one message to a given destination in another folder.
-\end{methoddesc}
-
-\begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton}
-Copy one message to a given destination in another folder.
-\end{methoddesc}
-
-
-\subsection{Message Objects \label{mh-message-objects}}
-
-The \class{Message} class adds one method to those of
-\class{mimetools.Message}:
-
-\begin{methoddesc}[Message]{openmessage}{n}
-Return a new open message object (costs a file descriptor).
-\end{methoddesc}
diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex
deleted file mode 100644
index 3e4bd4b..0000000
--- a/Doc/lib/libmimetools.tex
+++ /dev/null
@@ -1,120 +0,0 @@
-\section{\module{mimetools} ---
- Tools for parsing MIME messages}
-
-\declaremodule{standard}{mimetools}
-\modulesynopsis{Tools for parsing MIME-style message bodies.}
-
-\deprecated{2.3}{The \refmodule{email} package should be used in
- preference to the \module{mimetools} module. This
- module is present only to maintain backward
- compatibility.}
-
-This module defines a subclass of the
-\refmodule{rfc822}\refstmodindex{rfc822} module's
-\class{Message} class and a number of utility functions that are
-useful for the manipulation for MIME multipart or encoded message.
-
-It defines the following items:
-
-\begin{classdesc}{Message}{fp\optional{, seekable}}
-Return a new instance of the \class{Message} class. This is a
-subclass of the \class{rfc822.Message} class, with some additional
-methods (see below). The \var{seekable} argument has the same meaning
-as for \class{rfc822.Message}.
-\end{classdesc}
-
-\begin{funcdesc}{choose_boundary}{}
-Return a unique string that has a high likelihood of being usable as a
-part boundary. The string has the form
-\code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
-\end{funcdesc}
-
-\begin{funcdesc}{decode}{input, output, encoding}
-Read data encoded using the allowed MIME \var{encoding} from open file
-object \var{input} and write the decoded data to open file object
-\var{output}. Valid values for \var{encoding} include
-\code{'base64'}, \code{'quoted-printable'}, \code{'uuencode'},
-\code{'x-uuencode'}, \code{'uue'}, \code{'x-uue'}, \code{'7bit'}, and
-\code{'8bit'}. Decoding messages encoded in \code{'7bit'} or \code{'8bit'}
-has no effect. The input is simply copied to the output.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{input, output, encoding}
-Read data from open file object \var{input} and write it encoded using
-the allowed MIME \var{encoding} to open file object \var{output}.
-Valid values for \var{encoding} are the same as for \method{decode()}.
-\end{funcdesc}
-
-\begin{funcdesc}{copyliteral}{input, output}
-Read lines from open file \var{input} until \EOF{} and write them to
-open file \var{output}.
-\end{funcdesc}
-
-\begin{funcdesc}{copybinary}{input, output}
-Read blocks until \EOF{} from open file \var{input} and write them to
-open file \var{output}. The block size is currently fixed at 8192.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{email}{Comprehensive email handling package; supersedes
- the \module{mimetools} module.}
- \seemodule{rfc822}{Provides the base class for
- \class{mimetools.Message}.}
- \seemodule{multifile}{Support for reading files which contain
- distinct parts, such as MIME data.}
- \seeurl{http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html}{
- The MIME Frequently Asked Questions document. For an
- overview of MIME, see the answer to question 1.1 in Part 1
- of this document.}
-\end{seealso}
-
-
-\subsection{Additional Methods of Message Objects
- \label{mimetools-message-objects}}
-
-The \class{Message} class defines the following methods in
-addition to the \class{rfc822.Message} methods:
-
-\begin{methoddesc}[Message]{getplist}{}
-Return the parameter list of the \mailheader{Content-Type} header.
-This is a list of strings. For parameters of the form
-\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
-\var{value} is not. For example, if the message contains the header
-\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
-\method{getplist()} will return the Python list \code{['spam=1',
-'spam=2', 'Spam']}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getparam}{name}
-Return the \var{value} of the first parameter (as returned by
-\method{getplist()}) of the form \samp{\var{name}=\var{value}} for the
-given \var{name}. If \var{value} is surrounded by quotes of the form
-`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getencoding}{}
-Return the encoding specified in the
-\mailheader{Content-Transfer-Encoding} message header. If no such
-header exists, return \code{'7bit'}. The encoding is converted to
-lower case.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{gettype}{}
-Return the message type (of the form \samp{\var{type}/\var{subtype}})
-as specified in the \mailheader{Content-Type} header. If no such
-header exists, return \code{'text/plain'}. The type is converted to
-lower case.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getmaintype}{}
-Return the main type as specified in the \mailheader{Content-Type}
-header. If no such header exists, return \code{'text'}. The main
-type is converted to lower case.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getsubtype}{}
-Return the subtype as specified in the \mailheader{Content-Type}
-header. If no such header exists, return \code{'plain'}. The subtype
-is converted to lower case.
-\end{methoddesc}
diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex
deleted file mode 100644
index af99f08..0000000
--- a/Doc/lib/libmimetypes.tex
+++ /dev/null
@@ -1,226 +0,0 @@
-\section{\module{mimetypes} ---
- Map filenames to MIME types}
-
-\declaremodule{standard}{mimetypes}
-\modulesynopsis{Mapping of filename extensions to MIME types.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-\indexii{MIME}{content type}
-
-The \module{mimetypes} module converts between a filename or URL and
-the MIME type associated with the filename extension. Conversions are
-provided from filename to MIME type and from MIME type to filename
-extension; encodings are not supported for the latter conversion.
-
-The module provides one class and a number of convenience functions.
-The functions are the normal interface to this module, but some
-applications may be interested in the class as well.
-
-The functions described below provide the primary interface for this
-module. If the module has not been initialized, they will call
-\function{init()} if they rely on the information \function{init()}
-sets up.
-
-
-\begin{funcdesc}{guess_type}{filename\optional{, strict}}
-Guess the type of a file based on its filename or URL, given by
-\var{filename}. The return value is a tuple \code{(\var{type},
-\var{encoding})} where \var{type} is \code{None} if the type can't be
-guessed (missing or unknown suffix) or a string of the form
-\code{'\var{type}/\var{subtype}'}, usable for a MIME
-\mailheader{content-type} header\indexii{MIME}{headers}.
-
-\var{encoding} is \code{None} for no encoding or the name of the
-program used to encode (e.g. \program{compress} or \program{gzip}).
-The encoding is suitable for use as a \mailheader{Content-Encoding}
-header, \emph{not} as a \mailheader{Content-Transfer-Encoding} header.
-The mappings are table driven. Encoding suffixes are case sensitive;
-type suffixes are first tried case sensitively, then case
-insensitively.
-
-Optional \var{strict} is a flag specifying whether the list of known
-MIME types is limited to only the official types \ulink{registered
-with IANA}{http://www.isi.edu/in-notes/iana/assignments/media-types}
-are recognized. When \var{strict} is true (the default), only the
-IANA types are supported; when \var{strict} is false, some additional
-non-standard but commonly used MIME types are also recognized.
-\end{funcdesc}
-
-\begin{funcdesc}{guess_all_extensions}{type\optional{, strict}}
-Guess the extensions for a file based on its MIME type, given by
-\var{type}.
-The return value is a list of strings giving all possible filename extensions,
-including the leading dot (\character{.}). The extensions are not guaranteed
-to have been associated with any particular data stream, but would be mapped
-to the MIME type \var{type} by \function{guess_type()}.
-
-Optional \var{strict} has the same meaning as with the
-\function{guess_type()} function.
-\end{funcdesc}
-
-
-\begin{funcdesc}{guess_extension}{type\optional{, strict}}
-Guess the extension for a file based on its MIME type, given by
-\var{type}.
-The return value is a string giving a filename extension, including the
-leading dot (\character{.}). The extension is not guaranteed to have been
-associated with any particular data stream, but would be mapped to the
-MIME type \var{type} by \function{guess_type()}. If no extension can
-be guessed for \var{type}, \code{None} is returned.
-
-Optional \var{strict} has the same meaning as with the
-\function{guess_type()} function.
-\end{funcdesc}
-
-
-Some additional functions and data items are available for controlling
-the behavior of the module.
-
-
-\begin{funcdesc}{init}{\optional{files}}
-Initialize the internal data structures. If given, \var{files} must
-be a sequence of file names which should be used to augment the
-default type map. If omitted, the file names to use are taken from
-\constant{knownfiles}. Each file named in \var{files} or
-\constant{knownfiles} takes precedence over those named before it.
-Calling \function{init()} repeatedly is allowed.
-\end{funcdesc}
-
-\begin{funcdesc}{read_mime_types}{filename}
-Load the type map given in the file \var{filename}, if it exists. The
-type map is returned as a dictionary mapping filename extensions,
-including the leading dot (\character{.}), to strings of the form
-\code{'\var{type}/\var{subtype}'}. If the file \var{filename} does
-not exist or cannot be read, \code{None} is returned.
-\end{funcdesc}
-
-
-\begin{funcdesc}{add_type}{type, ext\optional{, strict}}
-Add a mapping from the mimetype \var{type} to the extension \var{ext}.
-When the extension is already known, the new type will replace the old
-one. When the type is already known the extension will be added
-to the list of known extensions.
-
-When \var{strict} is the mapping will added to the official
-MIME types, otherwise to the non-standard ones.
-\end{funcdesc}
-
-
-\begin{datadesc}{inited}
-Flag indicating whether or not the global data structures have been
-initialized. This is set to true by \function{init()}.
-\end{datadesc}
-
-\begin{datadesc}{knownfiles}
-List of type map file names commonly installed. These files are
-typically named \file{mime.types} and are installed in different
-locations by different packages.\index{file!mime.types}
-\end{datadesc}
-
-\begin{datadesc}{suffix_map}
-Dictionary mapping suffixes to suffixes. This is used to allow
-recognition of encoded files for which the encoding and the type are
-indicated by the same extension. For example, the \file{.tgz}
-extension is mapped to \file{.tar.gz} to allow the encoding and type
-to be recognized separately.
-\end{datadesc}
-
-\begin{datadesc}{encodings_map}
-Dictionary mapping filename extensions to encoding types.
-\end{datadesc}
-
-\begin{datadesc}{types_map}
-Dictionary mapping filename extensions to MIME types.
-\end{datadesc}
-
-\begin{datadesc}{common_types}
-Dictionary mapping filename extensions to non-standard, but commonly
-found MIME types.
-\end{datadesc}
-
-
-The \class{MimeTypes} class may be useful for applications which may
-want more than one MIME-type database:
-
-\begin{classdesc}{MimeTypes}{\optional{filenames}}
- This class represents a MIME-types database. By default, it
- provides access to the same database as the rest of this module.
- The initial database is a copy of that provided by the module, and
- may be extended by loading additional \file{mime.types}-style files
- into the database using the \method{read()} or \method{readfp()}
- methods. The mapping dictionaries may also be cleared before
- loading additional data if the default data is not desired.
-
- The optional \var{filenames} parameter can be used to cause
- additional files to be loaded ``on top'' of the default database.
-
- \versionadded{2.2}
-\end{classdesc}
-
-An example usage of the module:
-
-\begin{verbatim}
->>> import mimetypes
->>> mimetypes.init()
->>> mimetypes.knownfiles
-['/etc/mime.types', '/etc/httpd/mime.types', ... ]
->>> mimetypes.suffix_map['.tgz']
-'.tar.gz'
->>> mimetypes.encodings_map['.gz']
-'gzip'
->>> mimetypes.types_map['.tgz']
-'application/x-tar-gz'
-\end{verbatim}
-
-\subsection{MimeTypes Objects \label{mimetypes-objects}}
-
-\class{MimeTypes} instances provide an interface which is very like
-that of the \refmodule{mimetypes} module.
-
-\begin{memberdesc}[MimeTypes]{suffix_map}
- Dictionary mapping suffixes to suffixes. This is used to allow
- recognition of encoded files for which the encoding and the type are
- indicated by the same extension. For example, the \file{.tgz}
- extension is mapped to \file{.tar.gz} to allow the encoding and type
- to be recognized separately. This is initially a copy of the global
- \code{suffix_map} defined in the module.
-\end{memberdesc}
-
-\begin{memberdesc}[MimeTypes]{encodings_map}
- Dictionary mapping filename extensions to encoding types. This is
- initially a copy of the global \code{encodings_map} defined in the
- module.
-\end{memberdesc}
-
-\begin{memberdesc}[MimeTypes]{types_map}
- Dictionary mapping filename extensions to MIME types. This is
- initially a copy of the global \code{types_map} defined in the
- module.
-\end{memberdesc}
-
-\begin{memberdesc}[MimeTypes]{common_types}
- Dictionary mapping filename extensions to non-standard, but commonly
- found MIME types. This is initially a copy of the global
- \code{common_types} defined in the module.
-\end{memberdesc}
-
-\begin{methoddesc}[MimeTypes]{guess_extension}{type\optional{, strict}}
- Similar to the \function{guess_extension()} function, using the
- tables stored as part of the object.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeTypes]{guess_type}{url\optional{, strict}}
- Similar to the \function{guess_type()} function, using the tables
- stored as part of the object.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeTypes]{read}{path}
- Load MIME information from a file named \var{path}. This uses
- \method{readfp()} to parse the file.
-\end{methoddesc}
-
-\begin{methoddesc}[MimeTypes]{readfp}{file}
- Load MIME type information from an open file. The file must have
- the format of the standard \file{mime.types} files.
-\end{methoddesc}
diff --git a/Doc/lib/libmisc.tex b/Doc/lib/libmisc.tex
deleted file mode 100644
index 6f79eda..0000000
--- a/Doc/lib/libmisc.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-\chapter{Miscellaneous Services}
-\label{misc}
-
-The modules described in this chapter provide miscellaneous services
-that are available in all Python versions. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libmm.tex b/Doc/lib/libmm.tex
deleted file mode 100644
index 22c14b4..0000000
--- a/Doc/lib/libmm.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Multimedia Services}
-\label{mmedia}
-
-The modules described in this chapter implement various algorithms or
-interfaces that are mainly useful for multimedia applications. They
-are available at the discretion of the installation. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex
deleted file mode 100644
index 345aeea..0000000
--- a/Doc/lib/libmmap.tex
+++ /dev/null
@@ -1,171 +0,0 @@
-\section{\module{mmap} ---
-Memory-mapped file support}
-
-\declaremodule{builtin}{mmap}
-\modulesynopsis{Interface to memory-mapped files for \UNIX\ and Windows.}
-
-Memory-mapped file objects behave like both strings and like
-file objects. Unlike normal string objects, however, these are
-mutable. You can use mmap objects in most places where strings
-are expected; for example, you can use the \module{re} module to
-search through a memory-mapped file. Since they're mutable, you can
-change a single character by doing \code{obj[\var{index}] = 'a'}, or
-change a substring by assigning to a slice:
-\code{obj[\var{i1}:\var{i2}] = '...'}. You can also read and write
-data starting at the current file position, and \method{seek()}
-through the file to different positions.
-
-A memory-mapped file is created by the \function{mmap()} function,
-which is different on \UNIX{} and on Windows. In either case you must
-provide a file descriptor for a file opened for update.
-If you wish to map an existing Python file object, use its
-\method{fileno()} method to obtain the correct value for the
-\var{fileno} parameter. Otherwise, you can open the file using the
-\function{os.open()} function, which returns a file descriptor
-directly (the file still needs to be closed when done).
-
-For both the \UNIX{} and Windows versions of the function,
-\var{access} may be specified as an optional keyword parameter.
-\var{access} accepts one of three values: \constant{ACCESS_READ},
-\constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify
-readonly, write-through or copy-on-write memory respectively.
-\var{access} can be used on both \UNIX{} and Windows. If
-\var{access} is not specified, Windows mmap returns a write-through
-mapping. The initial memory values for all three access types are
-taken from the specified file. Assignment to an
-\constant{ACCESS_READ} memory map raises a \exception{TypeError}
-exception. Assignment to an \constant{ACCESS_WRITE} memory map
-affects both memory and the underlying file. Assignment to an
-\constant{ACCESS_COPY} memory map affects memory but does not update
-the underlying file. \versionchanged[To map anonymous memory,
--1 should be passed as the fileno along with the length]{2.5}
-
-\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
- \strong{(Windows version)} Maps \var{length} bytes from the file
- specified by the file handle \var{fileno}, and returns a mmap
- object. If \var{length} is larger than the current size of the file,
- the file is extended to contain \var{length} bytes. If \var{length}
- is \code{0}, the maximum length of the map is the current size
- of the file, except that if the file is empty Windows raises an
- exception (you cannot create an empty mapping on Windows).
-
- \var{tagname}, if specified and not \code{None}, is a string giving
- a tag name for the mapping. Windows allows you to have many
- different mappings against the same file. If you specify the name
- of an existing tag, that tag is opened, otherwise a new tag of this
- name is created. If this parameter is omitted or \code{None}, the
- mapping is created without a name. Avoiding the use of the tag
- parameter will assist in keeping your code portable between \UNIX{}
- and Windows.
-\end{funcdesc}
-
-\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
- prot\optional{, access}}}}
- \strong{(\UNIX{} version)} Maps \var{length} bytes from the file
- specified by the file descriptor \var{fileno}, and returns a mmap
- object. If \var{length} is \code{0}, the maximum length of the map
- will be the current size of the file when \function{mmap()} is
- called.
-
- \var{flags} specifies the nature of the mapping.
- \constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
- changes to the contents of the mmap object will be private to this
- process, and \constant{MAP_SHARED} creates a mapping that's shared
- with all other processes mapping the same areas of the file. The
- default value is \constant{MAP_SHARED}.
-
- \var{prot}, if specified, gives the desired memory protection; the
- two most useful values are \constant{PROT_READ} and
- \constant{PROT_WRITE}, to specify that the pages may be read or
- written. \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
-
- \var{access} may be specified in lieu of \var{flags} and \var{prot}
- as an optional keyword parameter. It is an error to specify both
- \var{flags}, \var{prot} and \var{access}. See the description of
- \var{access} above for information on how to use this parameter.
-\end{funcdescni}
-
-
-Memory-mapped file objects support the following methods:
-
-
-\begin{methoddesc}[mmap]{close}{}
- Close the file. Subsequent calls to other methods of the object
- will result in an exception being raised.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{find}{string\optional{, start}}
- Returns the lowest index in the object where the substring
- \var{string} is found. Returns \code{-1} on failure. \var{start}
- is the index at which the search begins, and defaults to zero.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{flush}{\optional{offset, size}}
- Flushes changes made to the in-memory copy of a file back to disk.
- Without use of this call there is no guarantee that changes are
- written back before the object is destroyed. If \var{offset} and
- \var{size} are specified, only changes to the given range of bytes
- will be flushed to disk; otherwise, the whole extent of the mapping
- is flushed.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{move}{\var{dest}, \var{src}, \var{count}}
- Copy the \var{count} bytes starting at offset \var{src} to the
- destination index \var{dest}. If the mmap was created with
- \constant{ACCESS_READ}, then calls to move will throw a
- \exception{TypeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{read}{\var{num}}
- Return a string containing up to \var{num} bytes starting from the
- current file position; the file position is updated to point after the
- bytes that were returned.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{read_byte}{}
- Returns a string of length 1 containing the character at the current
- file position, and advances the file position by 1.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{readline}{}
- Returns a single line, starting at the current file position and up to
- the next newline.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{resize}{\var{newsize}}
- Resizes the map and the underlying file, if any.
- If the mmap was created with \constant{ACCESS_READ} or
- \constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{seek}{pos\optional{, whence}}
- Set the file's current position. \var{whence} argument is optional
- and defaults to \code{os.SEEK_SET} or \code{0} (absolute file
- positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek
- relative to the current position) and \code{os.SEEK_END} or \code{2}
- (seek relative to the file's end).
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{size}{}
- Return the length of the file, which can be larger than the size of
- the memory-mapped area.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{tell}{}
- Returns the current position of the file pointer.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{write}{\var{string}}
- Write the bytes in \var{string} into memory at the current position
- of the file pointer; the file position is updated to point after the
- bytes that were written. If the mmap was created with
- \constant{ACCESS_READ}, then writing to it will throw a
- \exception{TypeError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[mmap]{write_byte}{\var{byte}}
- Write the single-character string \var{byte} into memory at the
- current position of the file pointer; the file position is advanced
- by \code{1}. If the mmap was created with \constant{ACCESS_READ},
- then writing to it will throw a \exception{TypeError} exception.
-\end{methoddesc}
diff --git a/Doc/lib/libmodulefinder.tex b/Doc/lib/libmodulefinder.tex
deleted file mode 100644
index 5fb9e8e..0000000
--- a/Doc/lib/libmodulefinder.tex
+++ /dev/null
@@ -1,51 +0,0 @@
-\section{\module{modulefinder} ---
- Find modules used by a script}
-\sectionauthor{A.M. Kuchling}{amk@amk.ca}
-
-\declaremodule{standard}{modulefinder}
-\modulesynopsis{Find modules used by a script.}
-
-\versionadded{2.3}
-
-This module provides a \class{ModuleFinder} class that can be used to
-determine the set of modules imported by a script.
-\code{modulefinder.py} can also be run as a script, giving the
-filename of a Python script as its argument, after which a report of
-the imported modules will be printed.
-
-\begin{funcdesc}{AddPackagePath}{pkg_name, path}
-Record that the package named \var{pkg_name} can be found in the specified \var{path}.
-\end{funcdesc}
-
-\begin{funcdesc}{ReplacePackage}{oldname, newname}
-Allows specifying that the module named \var{oldname} is in fact
-the package named \var{newname}. The most common usage would be
-to handle how the \module{_xmlplus} package replaces the \module{xml}
-package.
-\end{funcdesc}
-
-\begin{classdesc}{ModuleFinder}{\optional{path=None, debug=0, excludes=[], replace_paths=[]}}
-
-This class provides \method{run_script()} and \method{report()}
-methods to determine the set of modules imported by a script.
-\var{path} can be a list of directories to search for modules; if not
-specified, \code{sys.path} is used.
-\var{debug} sets the debugging level; higher values make the class print
-debugging messages about what it's doing.
-\var{excludes} is a list of module names to exclude from the analysis.
-\var{replace_paths} is a list of \code{(\var{oldpath}, \var{newpath})}
-tuples that will be replaced in module paths.
-\end{classdesc}
-
-\begin{methoddesc}[ModuleFinder]{report}{}
-Print a report to standard output that lists the modules imported by the script
-and their
-paths, as well as modules that are missing or seem to be missing.
-\end{methoddesc}
-
-\begin{methoddesc}[ModuleFinder]{run_script}{pathname}
-Analyze the contents of the \var{pathname} file, which must contain
-Python code.
-\end{methoddesc}
-
-
diff --git a/Doc/lib/libmsilib.tex b/Doc/lib/libmsilib.tex
deleted file mode 100644
index 075103a..0000000
--- a/Doc/lib/libmsilib.tex
+++ /dev/null
@@ -1,485 +0,0 @@
-\section{\module{msilib} ---
- Read and write Microsoft Installer files}
-
-\declaremodule{standard}{msilib}
- \platform{Windows}
-\modulesynopsis{Creation of Microsoft Installer files, and CAB files.}
-\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\index{msi}
-
-\versionadded{2.5}
-
-The \module{msilib} supports the creation of Microsoft Installer
-(\code{.msi}) files. Because these files often contain an embedded
-``cabinet'' file (\code{.cab}), it also exposes an API to create
-CAB files. Support for reading \code{.cab} files is currently not
-implemented; read support for the \code{.msi} database is possible.
-
-This package aims to provide complete access to all tables in an
-\code{.msi} file, therefore, it is a fairly low-level API. Two
-primary applications of this package are the \module{distutils}
-command \code{bdist_msi}, and the creation of Python installer
-package itself (although that currently uses a different version
-of \code{msilib}).
-
-The package contents can be roughly split into four parts:
-low-level CAB routines, low-level MSI routines, higher-level
-MSI routines, and standard table structures.
-
-\begin{funcdesc}{FCICreate}{cabname, files}
- Create a new CAB file named \var{cabname}. \var{files} must
- be a list of tuples, each containing the name of the file on
- disk, and the name of the file inside the CAB file.
-
- The files are added to the CAB file in the order they appear
- in the list. All files are added into a single CAB file,
- using the MSZIP compression algorithm.
-
- Callbacks to Python for the various steps of MSI creation
- are currently not exposed.
-\end{funcdesc}
-
-\begin{funcdesc}{UUIDCreate}{}
- Return the string representation of a new unique identifier.
- This wraps the Windows API functions \cfunction{UuidCreate} and
- \cfunction{UuidToString}.
-\end{funcdesc}
-
-\begin{funcdesc}{OpenDatabase}{path, persist}
- Return a new database object by calling MsiOpenDatabase.
- \var{path} is the file name of the
- MSI file; \var{persist} can be one of the constants
- \code{MSIDBOPEN_CREATEDIRECT}, \code{MSIDBOPEN_CREATE},
- \code{MSIDBOPEN_DIRECT}, \code{MSIDBOPEN_READONLY}, or
- \code{MSIDBOPEN_TRANSACT}, and may include the flag
- \code{MSIDBOPEN_PATCHFILE}. See the Microsoft documentation for
- the meaning of these flags; depending on the flags,
- an existing database is opened, or a new one created.
-\end{funcdesc}
-
-\begin{funcdesc}{CreateRecord}{count}
- Return a new record object by calling \cfunction{MSICreateRecord}.
- \var{count} is the number of fields of the record.
-\end{funcdesc}
-
-\begin{funcdesc}{init_database}{name, schema, ProductName, ProductCode, ProductVersion, Manufacturer}
- Create and return a new database \var{name}, initialize it
- with \var{schema}, and set the properties \var{ProductName},
- \var{ProductCode}, \var{ProductVersion}, and \var{Manufacturer}.
-
- \var{schema} must be a module object containing \code{tables} and
- \code{_Validation_records} attributes; typically,
- \module{msilib.schema} should be used.
-
- The database will contain just the schema and the validation
- records when this function returns.
-\end{funcdesc}
-
-\begin{funcdesc}{add_data}{database, records}
- Add all \var{records} to \var{database}. \var{records} should
- be a list of tuples, each one containing all fields of a record
- according to the schema of the table. For optional fields,
- \code{None} can be passed.
-
- Field values can be int or long numbers, strings, or instances
- of the Binary class.
-\end{funcdesc}
-
-\begin{classdesc}{Binary}{filename}
- Represents entries in the Binary table; inserting such
- an object using \function{add_data} reads the file named
- \var{filename} into the table.
-\end{classdesc}
-
-\begin{funcdesc}{add_tables}{database, module}
- Add all table content from \var{module} to \var{database}.
- \var{module} must contain an attribute \var{tables}
- listing all tables for which content should be added,
- and one attribute per table that has the actual content.
-
- This is typically used to install the sequence tables.
-\end{funcdesc}
-
-\begin{funcdesc}{add_stream}{database, name, path}
- Add the file \var{path} into the \code{_Stream} table
- of \var{database}, with the stream name \var{name}.
-\end{funcdesc}
-
-\begin{funcdesc}{gen_uuid}{}
- Return a new UUID, in the format that MSI typically
- requires (i.e. in curly braces, and with all hexdigits
- in upper-case).
-\end{funcdesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devnotes/winprog/fcicreate.asp]{FCICreateFile}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidcreate.asp]{UuidCreate}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp]{UuidToString}{}
-\end{seealso}
-
-\subsection{Database Objects\label{database-objects}}
-
-\begin{methoddesc}[Database]{OpenView}{sql}
- Return a view object, by calling \cfunction{MSIDatabaseOpenView}.
- \var{sql} is the SQL statement to execute.
-\end{methoddesc}
-
-\begin{methoddesc}[Database]{Commit}{}
- Commit the changes pending in the current transaction,
- by calling \cfunction{MSIDatabaseCommit}.
-\end{methoddesc}
-
-\begin{methoddesc}[Database]{GetSummaryInformation}{count}
- Return a new summary information object, by calling
- \cfunction{MsiGetSummaryInformation}. \var{count} is the maximum number of
- updated values.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiopenview.asp]{MSIOpenView}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp]{MSIDatabaseCommit}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp]{MSIGetSummaryInformation}{}
-\end{seealso}
-
-\subsection{View Objects\label{view-objects}}
-
-\begin{methoddesc}[View]{Execute}{\optional{params=None}}
- Execute the SQL query of the view, through \cfunction{MSIViewExecute}.
- \var{params} is an optional record describing actual values
- of the parameter tokens in the query.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{GetColumnInfo}{kind}
- Return a record describing the columns of the view, through
- calling \cfunction{MsiViewGetColumnInfo}. \var{kind} can be either
- \code{MSICOLINFO_NAMES} or \code{MSICOLINFO_TYPES}.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{Fetch}{}
- Return a result record of the query, through calling
- \cfunction{MsiViewFetch}.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{Modify}{kind, data}
- Modify the view, by calling \cfunction{MsiViewModify}. \var{kind}
- can be one of \code{MSIMODIFY_SEEK}, \code{MSIMODIFY_REFRESH},
- \code{MSIMODIFY_INSERT}, \code{MSIMODIFY_UPDATE}, \code{MSIMODIFY_ASSIGN},
- \code{MSIMODIFY_REPLACE}, \code{MSIMODIFY_MERGE}, \code{MSIMODIFY_DELETE},
- \code{MSIMODIFY_INSERT_TEMPORARY}, \code{MSIMODIFY_VALIDATE},
- \code{MSIMODIFY_VALIDATE_NEW}, \code{MSIMODIFY_VALIDATE_FIELD}, or
- \code{MSIMODIFY_VALIDATE_DELETE}.
-
- \var{data} must be a record describing the new data.
-\end{methoddesc}
-
-\begin{methoddesc}[View]{Close}{}
- Close the view, through \cfunction{MsiViewClose}.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp]{MsiViewExecute}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp]{MSIViewGetColumnInfo}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewfetch.asp]{MsiViewFetch}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewmodify.asp]{MsiViewModify}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp]{MsiViewClose}{}
-\end{seealso}
-
-\subsection{Summary Information Objects\label{summary-objects}}
-
-\begin{methoddesc}[SummaryInformation]{GetProperty}{field}
- Return a property of the summary, through \cfunction{MsiSummaryInfoGetProperty}.
- \var{field} is the name of the property, and can be one of the
- constants
- \code{PID_CODEPAGE}, \code{PID_TITLE}, \code{PID_SUBJECT},
- \code{PID_AUTHOR}, \code{PID_KEYWORDS}, \code{PID_COMMENTS},
- \code{PID_TEMPLATE}, \code{PID_LASTAUTHOR}, \code{PID_REVNUMBER},
- \code{PID_LASTPRINTED}, \code{PID_CREATE_DTM}, \code{PID_LASTSAVE_DTM},
- \code{PID_PAGECOUNT}, \code{PID_WORDCOUNT}, \code{PID_CHARCOUNT},
- \code{PID_APPNAME}, or \code{PID_SECURITY}.
-\end{methoddesc}
-
-\begin{methoddesc}[SummaryInformation]{GetPropertyCount}{}
- Return the number of summary properties, through
- \cfunction{MsiSummaryInfoGetPropertyCount}.
-\end{methoddesc}
-
-\begin{methoddesc}[SummaryInformation]{SetProperty}{field, value}
- Set a property through \cfunction{MsiSummaryInfoSetProperty}. \var{field}
- can have the same values as in \method{GetProperty}, \var{value}
- is the new value of the property. Possible value types are integer
- and string.
-\end{methoddesc}
-
-\begin{methoddesc}[SummaryInformation]{Persist}{}
- Write the modified properties to the summary information stream,
- using \cfunction{MsiSummaryInfoPersist}.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp]{MsiSummaryInfoGetProperty}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp]{MsiSummaryInfoGetPropertyCount}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp]{MsiSummaryInfoSetProperty}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp]{MsiSummaryInfoPersist}{}
-\end{seealso}
-
-\subsection{Record Objects\label{record-objects}}
-
-\begin{methoddesc}[Record]{GetFieldCount}{}
- Return the number of fields of the record, through \cfunction{MsiRecordGetFieldCount}.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{SetString}{field, value}
- Set \var{field} to \var{value} through \cfunction{MsiRecordSetString}.
- \var{field} must be an integer; \var{value} a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{SetStream}{field, value}
- Set \var{field} to the contents of the file named \var{value},
- through \cfunction{MsiRecordSetStream}.
- \var{field} must be an integer; \var{value} a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{SetInteger}{field, value}
- Set \var{field} to \var{value} through \cfunction{MsiRecordSetInteger}.
- Both \var{field} and \var{value} must be an integer.
-\end{methoddesc}
-
-\begin{methoddesc}[Record]{ClearData}{}
- Set all fields of the record to 0, through \cfunction{MsiRecordClearData}.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp]{MsiRecordGetFieldCount}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp]{MsiRecordSetString}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstream.asp]{MsiRecordSetStream}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetinteger.asp]{MsiRecordSetInteger}{}
- \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordclear.asp]{MsiRecordClear}{}
-\end{seealso}
-
-\subsection{Errors\label{msi-errors}}
-
-All wrappers around MSI functions raise \exception{MsiError};
-the string inside the exception will contain more detail.
-
-\subsection{CAB Objects\label{cab}}
-
-\begin{classdesc}{CAB}{name}
- The class \class{CAB} represents a CAB file. During MSI construction,
- files will be added simultaneously to the \code{Files} table, and
- to a CAB file. Then, when all files have been added, the CAB file
- can be written, then added to the MSI file.
-
- \var{name} is the name of the CAB file in the MSI file.
-\end{classdesc}
-
-\begin{methoddesc}[CAB]{append}{full, file, logical}
- Add the file with the pathname \var{full} to the CAB file,
- under the name \var{logical}. If there is already a file
- named \var{logical}, a new file name is created.
-
- Return the index of the file in the CAB file, and the
- new name of the file inside the CAB file.
-\end{methoddesc}
-
-\begin{methoddesc}[CAB]{commit}{database}
- Generate a CAB file, add it as a stream to the MSI file,
- put it into the \code{Media} table, and remove the generated
- file from the disk.
-\end{methoddesc}
-
-\subsection{Directory Objects\label{msi-directory}}
-
-\begin{classdesc}{Directory}{database, cab, basedir, physical,
- logical, default, component, \optional{componentflags}}
- Create a new directory in the Directory table. There is a current
- component at each point in time for the directory, which is either
- explicitly created through \method{start_component}, or implicitly when files
- are added for the first time. Files are added into the current
- component, and into the cab file. To create a directory, a base
- directory object needs to be specified (can be \code{None}), the path to
- the physical directory, and a logical directory name. \var{default}
- specifies the DefaultDir slot in the directory table. \var{componentflags}
- specifies the default flags that new components get.
-\end{classdesc}
-
-\begin{methoddesc}[Directory]{start_component}{\optional{component\optional{,
- feature\optional{, flags\optional{, keyfile\optional{, uuid}}}}}}
- Add an entry to the Component table, and make this component the
- current component for this directory. If no component name is given, the
- directory name is used. If no \var{feature} is given, the current feature
- is used. If no \var{flags} are given, the directory's default flags are
- used. If no \var{keyfile} is given, the KeyPath is left null in the
- Component table.
-\end{methoddesc}
-
-\begin{methoddesc}[Directory]{add_file}{file\optional{, src\optional{,
- version\optional{, language}}}}
- Add a file to the current component of the directory, starting a new
- one if there is no current component. By default, the file name
- in the source and the file table will be identical. If the \var{src} file
- is specified, it is interpreted relative to the current
- directory. Optionally, a \var{version} and a \var{language} can be specified for
- the entry in the File table.
-\end{methoddesc}
-
-\begin{methoddesc}[Directory]{glob}{pattern\optional{, exclude}}
- Add a list of files to the current component as specified in the glob
- pattern. Individual files can be excluded in the \var{exclude} list.
-\end{methoddesc}
-
-\begin{methoddesc}[Directory]{remove_pyc}{}
- Remove \code{.pyc}/\code{.pyo} files on uninstall.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp]{Directory Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp]{File Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp]{Component Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp]{FeatureComponents Table}{}
-\end{seealso}
-
-
-\subsection{Features\label{features}}
-
-\begin{classdesc}{Feature}{database, id, title, desc, display\optional{,
- level=1\optional{, parent\optional{, directory\optional{,
- attributes=0}}}}}
-
- Add a new record to the \code{Feature} table, using the values
- \var{id}, \var{parent.id}, \var{title}, \var{desc}, \var{display},
- \var{level}, \var{directory}, and \var{attributes}. The resulting
- feature object can be passed to the \method{start_component} method
- of \class{Directory}.
-\end{classdesc}
-
-\begin{methoddesc}[Feature]{set_current}{}
- Make this feature the current feature of \module{msilib}.
- New components are automatically added to the default feature,
- unless a feature is explicitly specified.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp]{Feature Table}{}
-\end{seealso}
-
-\subsection{GUI classes\label{msi-gui}}
-
-\module{msilib} provides several classes that wrap the GUI tables in
-an MSI database. However, no standard user interface is provided; use
-\module{bdist_msi} to create MSI files with a user-interface for
-installing Python packages.
-
-\begin{classdesc}{Control}{dlg, name}
- Base class of the dialog controls. \var{dlg} is the dialog object
- the control belongs to, and \var{name} is the control's name.
-\end{classdesc}
-
-\begin{methoddesc}[Control]{event}{event, argument\optional{,
- condition = ``1''\optional{, ordering}}}
-
- Make an entry into the \code{ControlEvent} table for this control.
-\end{methoddesc}
-
-\begin{methoddesc}[Control]{mapping}{event, attribute}
- Make an entry into the \code{EventMapping} table for this control.
-\end{methoddesc}
-
-\begin{methoddesc}[Control]{condition}{action, condition}
- Make an entry into the \code{ControlCondition} table for this control.
-\end{methoddesc}
-
-
-\begin{classdesc}{RadioButtonGroup}{dlg, name, property}
- Create a radio button control named \var{name}. \var{property}
- is the installer property that gets set when a radio button
- is selected.
-\end{classdesc}
-
-\begin{methoddesc}[RadioButtonGroup]{add}{name, x, y, width, height, text
- \optional{, value}}
- Add a radio button named \var{name} to the group, at the
- coordinates \var{x}, \var{y}, \var{width}, \var{height}, and
- with the label \var{text}. If \var{value} is omitted, it
- defaults to \var{name}.
-\end{methoddesc}
-
-\begin{classdesc}{Dialog}{db, name, x, y, w, h, attr, title, first,
- default, cancel}
- Return a new \class{Dialog} object. An entry in the \code{Dialog} table
- is made, with the specified coordinates, dialog attributes, title,
- name of the first, default, and cancel controls.
-\end{classdesc}
-
-\begin{methoddesc}[Dialog]{control}{name, type, x, y, width, height,
- attributes, property, text, control_next, help}
- Return a new \class{Control} object. An entry in the \code{Control} table
- is made with the specified parameters.
-
- This is a generic method; for specific types, specialized methods
- are provided.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Dialog]{text}{name, x, y, width, height, attributes, text}
- Add and return a \code{Text} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{bitmap}{name, x, y, width, height, text}
- Add and return a \code{Bitmap} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{line}{name, x, y, width, height}
- Add and return a \code{Line} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{pushbutton}{name, x, y, width, height, attributes,
- text, next_control}
- Add and return a \code{PushButton} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{radiogroup}{name, x, y, width, height,
- attributes, property, text, next_control}
- Add and return a \code{RadioButtonGroup} control.
-\end{methoddesc}
-
-\begin{methoddesc}[Dialog]{checkbox}{name, x, y, width, height,
- attributes, property, text, next_control}
- Add and return a \code{CheckBox} control.
-\end{methoddesc}
-
-\begin{seealso}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp]{Dialog Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp]{Control Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp]{Control Types}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp]{ControlCondition Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp]{ControlEvent Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp]{EventMapping Table}{}
- \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp]{RadioButton Table}{}
-\end{seealso}
-
-\subsection{Precomputed tables\label{msi-tables}}
-
-\module{msilib} provides a few subpackages that contain
-only schema and table definitions. Currently, these definitions
-are based on MSI version 2.0.
-
-\begin{datadesc}{schema}
- This is the standard MSI schema for MSI 2.0, with the
- \var{tables} variable providing a list of table definitions,
- and \var{_Validation_records} providing the data for
- MSI validation.
-\end{datadesc}
-
-\begin{datadesc}{sequence}
- This module contains table contents for the standard sequence
- tables: \var{AdminExecuteSequence}, \var{AdminUISequence},
- \var{AdvtExecuteSequence}, \var{InstallExecuteSequence}, and
- \var{InstallUISequence}.
-\end{datadesc}
-
-\begin{datadesc}{text}
- This module contains definitions for the UIText and ActionText
- tables, for the standard installer actions.
-\end{datadesc}
diff --git a/Doc/lib/libmsvcrt.tex b/Doc/lib/libmsvcrt.tex
deleted file mode 100644
index 3e4ce5a..0000000
--- a/Doc/lib/libmsvcrt.tex
+++ /dev/null
@@ -1,109 +0,0 @@
-\section{\module{msvcrt} --
- Useful routines from the MS V\Cpp\ runtime}
-
-\declaremodule{builtin}{msvcrt}
- \platform{Windows}
-\modulesynopsis{Miscellaneous useful routines from the MS V\Cpp\ runtime.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-These functions provide access to some useful capabilities on Windows
-platforms. Some higher-level modules use these functions to build the
-Windows implementations of their services. For example, the
-\refmodule{getpass} module uses this in the implementation of the
-\function{getpass()} function.
-
-Further documentation on these functions can be found in the Platform
-API documentation.
-
-
-\subsection{File Operations \label{msvcrt-files}}
-
-\begin{funcdesc}{locking}{fd, mode, nbytes}
- Lock part of a file based on file descriptor \var{fd} from the C
- runtime. Raises \exception{IOError} on failure. The locked region
- of the file extends from the current file position for \var{nbytes}
- bytes, and may continue beyond the end of the file. \var{mode} must
- be one of the \constant{LK_\var{*}} constants listed below.
- Multiple regions in a file may be locked at the same time, but may
- not overlap. Adjacent regions are not merged; they must be unlocked
- individually.
-\end{funcdesc}
-
-\begin{datadesc}{LK_LOCK}
-\dataline{LK_RLCK}
- Locks the specified bytes. If the bytes cannot be locked, the
- program immediately tries again after 1 second. If, after 10
- attempts, the bytes cannot be locked, \exception{IOError} is
- raised.
-\end{datadesc}
-
-\begin{datadesc}{LK_NBLCK}
-\dataline{LK_NBRLCK}
- Locks the specified bytes. If the bytes cannot be locked,
- \exception{IOError} is raised.
-\end{datadesc}
-
-\begin{datadesc}{LK_UNLCK}
- Unlocks the specified bytes, which must have been previously locked.
-\end{datadesc}
-
-\begin{funcdesc}{setmode}{fd, flags}
- Set the line-end translation mode for the file descriptor \var{fd}.
- To set it to text mode, \var{flags} should be \constant{os.O_TEXT};
- for binary, it should be \constant{os.O_BINARY}.
-\end{funcdesc}
-
-\begin{funcdesc}{open_osfhandle}{handle, flags}
- Create a C runtime file descriptor from the file handle
- \var{handle}. The \var{flags} parameter should be a bit-wise OR of
- \constant{os.O_APPEND}, \constant{os.O_RDONLY}, and
- \constant{os.O_TEXT}. The returned file descriptor may be used as a
- parameter to \function{os.fdopen()} to create a file object.
-\end{funcdesc}
-
-\begin{funcdesc}{get_osfhandle}{fd}
- Return the file handle for the file descriptor \var{fd}. Raises
- \exception{IOError} if \var{fd} is not recognized.
-\end{funcdesc}
-
-
-\subsection{Console I/O \label{msvcrt-console}}
-
-\begin{funcdesc}{kbhit}{}
- Return true if a keypress is waiting to be read.
-\end{funcdesc}
-
-\begin{funcdesc}{getch}{}
- Read a keypress and return the resulting character. Nothing is
- echoed to the console. This call will block if a keypress is not
- already available, but will not wait for \kbd{Enter} to be pressed.
- If the pressed key was a special function key, this will return
- \code{'\e000'} or \code{'\e xe0'}; the next call will return the
- keycode. The \kbd{Control-C} keypress cannot be read with this
- function.
-\end{funcdesc}
-
-\begin{funcdesc}{getche}{}
- Similar to \function{getch()}, but the keypress will be echoed if it
- represents a printable character.
-\end{funcdesc}
-
-\begin{funcdesc}{putch}{char}
- Print the character \var{char} to the console without buffering.
-\end{funcdesc}
-
-\begin{funcdesc}{ungetch}{char}
- Cause the character \var{char} to be ``pushed back'' into the
- console buffer; it will be the next character read by
- \function{getch()} or \function{getche()}.
-\end{funcdesc}
-
-
-\subsection{Other Functions \label{msvcrt-other}}
-
-\begin{funcdesc}{heapmin}{}
- Force the \cfunction{malloc()} heap to clean itself up and return
- unused blocks to the operating system. This only works on Windows
- NT. On failure, this raises \exception{IOError}.
-\end{funcdesc}
diff --git a/Doc/lib/libmultifile.tex b/Doc/lib/libmultifile.tex
deleted file mode 100644
index f3f0af7..0000000
--- a/Doc/lib/libmultifile.tex
+++ /dev/null
@@ -1,175 +0,0 @@
-\section{\module{multifile} ---
- Support for files containing distinct parts}
-
-\declaremodule{standard}{multifile}
-\modulesynopsis{Support for reading files which contain distinct
- parts, such as some MIME data.}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-\deprecated{2.5}{The \refmodule{email} package should be used in
- preference to the \module{multifile} module.
- This module is present only to maintain backward
- compatibility.}
-
-The \class{MultiFile} object enables you to treat sections of a text
-file as file-like input objects, with \code{''} being returned by
-\method{readline()} when a given delimiter pattern is encountered. The
-defaults of this class are designed to make it useful for parsing
-MIME multipart messages, but by subclassing it and overriding methods
-it can be easily adapted for more general use.
-
-\begin{classdesc}{MultiFile}{fp\optional{, seekable}}
-Create a multi-file. You must instantiate this class with an input
-object argument for the \class{MultiFile} instance to get lines from,
-such as a file object returned by \function{open()}.
-
-\class{MultiFile} only ever looks at the input object's
-\method{readline()}, \method{seek()} and \method{tell()} methods, and
-the latter two are only needed if you want random access to the
-individual MIME parts. To use \class{MultiFile} on a non-seekable
-stream object, set the optional \var{seekable} argument to false; this
-will prevent using the input object's \method{seek()} and
-\method{tell()} methods.
-\end{classdesc}
-
-It will be useful to know that in \class{MultiFile}'s view of the world, text
-is composed of three kinds of lines: data, section-dividers, and
-end-markers. MultiFile is designed to support parsing of
-messages that may have multiple nested message parts, each with its
-own pattern for section-divider and end-marker lines.
-
-\begin{seealso}
- \seemodule{email}{Comprehensive email handling package; supersedes
- the \module{multifile} module.}
-\end{seealso}
-
-
-\subsection{MultiFile Objects \label{MultiFile-objects}}
-
-A \class{MultiFile} instance has the following methods:
-
-\begin{methoddesc}[MultiFile]{readline}{str}
-Read a line. If the line is data (not a section-divider or end-marker
-or real EOF) return it. If the line matches the most-recently-stacked
-boundary, return \code{''} and set \code{self.last} to 1 or 0 according as
-the match is or is not an end-marker. If the line matches any other
-stacked boundary, raise an error. On encountering end-of-file on the
-underlying stream object, the method raises \exception{Error} unless
-all boundaries have been popped.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{readlines}{str}
-Return all lines remaining in this part as a list of strings.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{read}{}
-Read all lines, up to the next section. Return them as a single
-(multiline) string. Note that this doesn't take a size argument!
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{seek}{pos\optional{, whence}}
-Seek. Seek indices are relative to the start of the current section.
-The \var{pos} and \var{whence} arguments are interpreted as for a file
-seek.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{tell}{}
-Return the file position relative to the start of the current section.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{next}{}
-Skip lines to the next section (that is, read lines until a
-section-divider or end-marker has been consumed). Return true if
-there is such a section, false if an end-marker is seen. Re-enable
-the most-recently-pushed boundary.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{is_data}{str}
-Return true if \var{str} is data and false if it might be a section
-boundary. As written, it tests for a prefix other than \code{'-}\code{-'} at
-start of line (which all MIME boundaries have) but it is declared so
-it can be overridden in derived classes.
-
-Note that this test is used intended as a fast guard for the real
-boundary tests; if it always returns false it will merely slow
-processing, not cause it to fail.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{push}{str}
-Push a boundary string. When a decorated version of this boundary
-is found as an input line, it will be interpreted as a section-divider
-or end-marker (depending on the decoration, see \rfc{2045}). All subsequent
-reads will return the empty string to indicate end-of-file, until a
-call to \method{pop()} removes the boundary a or \method{next()} call
-reenables it.
-
-It is possible to push more than one boundary. Encountering the
-most-recently-pushed boundary will return EOF; encountering any other
-boundary will raise an error.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{pop}{}
-Pop a section boundary. This boundary will no longer be interpreted
-as EOF.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{section_divider}{str}
-Turn a boundary into a section-divider line. By default, this
-method prepends \code{'-}\code{-'} (which MIME section boundaries have) but
-it is declared so it can be overridden in derived classes. This
-method need not append LF or CR-LF, as comparison with the result
-ignores trailing whitespace.
-\end{methoddesc}
-
-\begin{methoddesc}[MultiFile]{end_marker}{str}
-Turn a boundary string into an end-marker line. By default, this
-method prepends \code{'-}\code{-'} and appends \code{'-}\code{-'} (like a
-MIME-multipart end-of-message marker) but it is declared so it can be
-overridden in derived classes. This method need not append LF or
-CR-LF, as comparison with the result ignores trailing whitespace.
-\end{methoddesc}
-
-Finally, \class{MultiFile} instances have two public instance variables:
-
-\begin{memberdesc}[MultiFile]{level}
-Nesting depth of the current part.
-\end{memberdesc}
-
-\begin{memberdesc}[MultiFile]{last}
-True if the last end-of-file was for an end-of-message marker.
-\end{memberdesc}
-
-
-\subsection{\class{MultiFile} Example \label{multifile-example}}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\begin{verbatim}
-import mimetools
-import multifile
-import StringIO
-
-def extract_mime_part_matching(stream, mimetype):
- """Return the first element in a multipart MIME message on stream
- matching mimetype."""
-
- msg = mimetools.Message(stream)
- msgtype = msg.gettype()
- params = msg.getplist()
-
- data = StringIO.StringIO()
- if msgtype[:10] == "multipart/":
-
- file = multifile.MultiFile(stream)
- file.push(msg.getparam("boundary"))
- while file.next():
- submsg = mimetools.Message(file)
- try:
- data = StringIO.StringIO()
- mimetools.decode(file, data, submsg.getencoding())
- except ValueError:
- continue
- if submsg.gettype() == mimetype:
- break
- file.pop()
- return data.getvalue()
-\end{verbatim}
diff --git a/Doc/lib/libmutex.tex b/Doc/lib/libmutex.tex
deleted file mode 100644
index 8c35c96..0000000
--- a/Doc/lib/libmutex.tex
+++ /dev/null
@@ -1,57 +0,0 @@
-\section{\module{mutex} ---
- Mutual exclusion support}
-
-\declaremodule{standard}{mutex}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Lock and queue for mutual exclusion.}
-
-The \module{mutex} module defines a class that allows mutual-exclusion
-via acquiring and releasing locks. It does not require (or imply)
-threading or multi-tasking, though it could be useful for
-those purposes.
-
-The \module{mutex} module defines the following class:
-
-\begin{classdesc}{mutex}{}
-Create a new (unlocked) mutex.
-
-A mutex has two pieces of state --- a ``locked'' bit and a queue.
-When the mutex is not locked, the queue is empty.
-Otherwise, the queue contains zero or more
-\code{(\var{function}, \var{argument})} pairs
-representing functions (or methods) waiting to acquire the lock.
-When the mutex is unlocked while the queue is not empty,
-the first queue entry is removed and its
-\code{\var{function}(\var{argument})} pair called,
-implying it now has the lock.
-
-Of course, no multi-threading is implied -- hence the funny interface
-for \method{lock()}, where a function is called once the lock is
-acquired.
-\end{classdesc}
-
-
-\subsection{Mutex Objects \label{mutex-objects}}
-
-\class{mutex} objects have following methods:
-
-\begin{methoddesc}[mutex]{test}{}
-Check whether the mutex is locked.
-\end{methoddesc}
-
-\begin{methoddesc}[mutex]{testandset}{}
-``Atomic'' test-and-set, grab the lock if it is not set,
-and return \code{True}, otherwise, return \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[mutex]{lock}{function, argument}
-Execute \code{\var{function}(\var{argument})}, unless the mutex is locked.
-In the case it is locked, place the function and argument on the queue.
-See \method{unlock} for explanation of when
-\code{\var{function}(\var{argument})} is executed in that case.
-\end{methoddesc}
-
-\begin{methoddesc}[mutex]{unlock}{}
-Unlock the mutex if queue is empty, otherwise execute the first element
-in the queue.
-\end{methoddesc}
diff --git a/Doc/lib/libnetrc.tex b/Doc/lib/libnetrc.tex
deleted file mode 100644
index f867b34..0000000
--- a/Doc/lib/libnetrc.tex
+++ /dev/null
@@ -1,68 +0,0 @@
-\section{\module{netrc} ---
- netrc file processing}
-
-\declaremodule{standard}{netrc}
-% Note the \protect needed for \file... ;-(
-\modulesynopsis{Loading of \protect\file{.netrc} files.}
-\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-
-\versionadded{1.5.2}
-
-The \class{netrc} class parses and encapsulates the netrc file format
-used by the \UNIX{} \program{ftp} program and other FTP clients.
-
-\begin{classdesc}{netrc}{\optional{file}}
-A \class{netrc} instance or subclass instance encapsulates data from
-a netrc file. The initialization argument, if present, specifies the
-file to parse. If no argument is given, the file \file{.netrc} in the
-user's home directory will be read. Parse errors will raise
-\exception{NetrcParseError} with diagnostic information including the
-file name, line number, and terminating token.
-\end{classdesc}
-
-\begin{excdesc}{NetrcParseError}
-Exception raised by the \class{netrc} class when syntactical errors
-are encountered in source text. Instances of this exception provide
-three interesting attributes: \member{msg} is a textual explanation
-of the error, \member{filename} is the name of the source file, and
-\member{lineno} gives the line number on which the error was found.
-\end{excdesc}
-
-
-\subsection{netrc Objects \label{netrc-objects}}
-
-A \class{netrc} instance has the following methods:
-
-\begin{methoddesc}[netrc]{authenticators}{host}
-Return a 3-tuple \code{(\var{login}, \var{account}, \var{password})}
-of authenticators for \var{host}. If the netrc file did not
-contain an entry for the given host, return the tuple associated with
-the `default' entry. If neither matching host nor default entry is
-available, return \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[netrc]{__repr__}{}
-Dump the class data as a string in the format of a netrc file.
-(This discards comments and may reorder the entries.)
-\end{methoddesc}
-
-Instances of \class{netrc} have public instance variables:
-
-\begin{memberdesc}[netrc]{hosts}
-Dictionary mapping host names to \code{(\var{login}, \var{account},
-\var{password})} tuples. The `default' entry, if any, is represented
-as a pseudo-host by that name.
-\end{memberdesc}
-
-\begin{memberdesc}[netrc]{macros}
-Dictionary mapping macro names to string lists.
-\end{memberdesc}
-
-\note{Passwords are limited to a subset of the ASCII character set.
-Versions of this module prior to 2.3 were extremely limited. Starting with
-2.3, all ASCII punctuation is allowed in passwords. However, note that
-whitespace and non-printable characters are not allowed in passwords. This
-is a limitation of the way the .netrc file is parsed and may be removed in
-the future.}
diff --git a/Doc/lib/libnew.tex b/Doc/lib/libnew.tex
deleted file mode 100644
index 18162dc..0000000
--- a/Doc/lib/libnew.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\section{\module{new} ---
- Creation of runtime internal objects}
-
-\declaremodule{builtin}{new}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Interface to the creation of runtime implementation objects.}
-
-
-The \module{new} module allows an interface to the interpreter object
-creation functions. This is for use primarily in marshal-type functions,
-when a new object needs to be created ``magically'' and not by using the
-regular creation functions. This module provides a low-level interface
-to the interpreter, so care must be exercised when using this module.
-It is possible to supply non-sensical arguments which crash the
-interpreter when the object is used.
-
-The \module{new} module defines the following functions:
-
-\begin{funcdesc}{instancemethod}{function, instance, class}
-This function will return a method object, bound to \var{instance}, or
-unbound if \var{instance} is \code{None}. \var{function} must be
-callable.
-\end{funcdesc}
-
-\begin{funcdesc}{function}{code, globals\optional{, name\optional{,
- argdefs\optional{, closure}}}}
-Returns a (Python) function with the given code and globals. If
-\var{name} is given, it must be a string or \code{None}. If it is a
-string, the function will have the given name, otherwise the function
-name will be taken from \code{\var{code}.co_name}. If
-\var{argdefs} is given, it must be a tuple and will be used to
-determine the default values of parameters. If \var{closure} is given,
-it must be \code{None} or a tuple of cell objects containing objects
-to bind to the names in \code{\var{code}.co_freevars}.
-\end{funcdesc}
-
-\begin{funcdesc}{code}{argcount, nlocals, stacksize, flags, codestring,
- constants, names, varnames, filename, name, firstlineno,
- lnotab}
-This function is an interface to the \cfunction{PyCode_New()} C
-function.
-%XXX This is still undocumented!!!!!!!!!!!
-\end{funcdesc}
-
-\begin{funcdesc}{module}{name[, doc]}
-This function returns a new module object with name \var{name}.
-\var{name} must be a string.
-The optional \var{doc} argument can have any type.
-\end{funcdesc}
-
-\begin{funcdesc}{classobj}{name, baseclasses, dict}
-This function returns a new class object, with name \var{name}, derived
-from \var{baseclasses} (which should be a tuple of classes) and with
-namespace \var{dict}.
-\end{funcdesc}
diff --git a/Doc/lib/libni.tex b/Doc/lib/libni.tex
deleted file mode 100644
index fa2b3ee..0000000
--- a/Doc/lib/libni.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{ni} ---
- None}
-\declaremodule{standard}{ni}
-
-\modulesynopsis{None}
-
-
-\strong{Warning: This module is obsolete.} As of Python 1.5a4,
-package support (with different semantics for \code{__init__} and no
-support for \code{__domain__} or \code{__}) is built in the
-interpreter. The ni module is retained only for backward
-compatibility. As of Python 1.5b2, it has been renamed to \code{ni1};
-if you really need it, you can use \code{import ni1}, but the
-recommended approach is to rely on the built-in package support,
-converting existing packages if needed. Note that mixing \code{ni}
-and the built-in package support doesn't work: once you import
-\code{ni}, all packages use it.
-
-The \code{ni} module defines a new importing scheme, which supports
-packages containing several Python modules. To enable package
-support, execute \code{import ni} before importing any packages. Importing
-this module automatically installs the relevant import hooks. There
-are no publicly-usable functions or variables in the \code{ni} module.
-
-To create a package named \code{spam} containing sub-modules \code{ham}, \code{bacon} and
-\code{eggs}, create a directory \file{spam} somewhere on Python's module search
-path, as given in \code{sys.path}. Then, create files called \file{ham.py}, \file{bacon.py} and
-\file{eggs.py} inside \file{spam}.
-
-To import module \code{ham} from package \code{spam} and use function
-\code{hamneggs()} from that module, you can use any of the following
-possibilities:
-
-\begin{verbatim}
-import spam.ham # *not* "import spam" !!!
-spam.ham.hamneggs()
-\end{verbatim}
-%
-\begin{verbatim}
-from spam import ham
-ham.hamneggs()
-\end{verbatim}
-%
-\begin{verbatim}
-from spam.ham import hamneggs
-hamneggs()
-\end{verbatim}
-%
-\code{import spam} creates an
-empty package named \code{spam} if one does not already exist, but it does
-\emph{not} automatically import \code{spam}'s submodules.
-The only submodule that is guaranteed to be imported is
-\code{spam.__init__}, if it exists; it would be in a file named
-\file{__init__.py} in the \file{spam} directory. Note that
-\code{spam.__init__} is a submodule of package spam. It can refer to
-spam's namespace as \code{__} (two underscores):
-
-\begin{verbatim}
-__.spam_inited = 1 # Set a package-level variable
-\end{verbatim}
-%
-Additional initialization code (setting up variables, importing other
-submodules) can be performed in \file{spam/__init__.py}.
diff --git a/Doc/lib/libnis.tex b/Doc/lib/libnis.tex
deleted file mode 100644
index fe4acb5..0000000
--- a/Doc/lib/libnis.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{nis} ---
- Interface to Sun's NIS (Yellow Pages)}
-
-\declaremodule{extension}{nis}
- \platform{Unix}
-\moduleauthor{Fred Gansevles}{Fred.Gansevles@cs.utwente.nl}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Interface to Sun's NIS (Yellow Pages) library.}
-
-The \module{nis} module gives a thin wrapper around the NIS library, useful
-for central administration of several hosts.
-
-Because NIS exists only on \UNIX{} systems, this module is
-only available for \UNIX.
-
-The \module{nis} module defines the following functions:
-
-\begin{funcdesc}{match}{key, mapname[, domain=default_domain]}
-Return the match for \var{key} in map \var{mapname}, or raise an
-error (\exception{nis.error}) if there is none.
-Both should be strings, \var{key} is 8-bit clean.
-Return value is an arbitrary array of bytes (may contain \code{NULL}
-and other joys).
-
-Note that \var{mapname} is first checked if it is an alias to another
-name.
-
-\versionchanged[The \var{domain} argument allows to override
-the NIS domain used for the lookup. If unspecified, lookup is in the
-default NIS domain]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{cat}{mapname[, domain=default_domain]}
-Return a dictionary mapping \var{key} to \var{value} such that
-\code{match(\var{key}, \var{mapname})==\var{value}}.
-Note that both keys and values of the dictionary are arbitrary
-arrays of bytes.
-
-Note that \var{mapname} is first checked if it is an alias to another
-name.
-
-\versionchanged[The \var{domain} argument allows to override
-the NIS domain used for the lookup. If unspecified, lookup is in the
-default NIS domain]{2.5}
-\end{funcdesc}
-
- \begin{funcdesc}{maps}{[domain=default_domain]}
-Return a list of all valid maps.
-
-\versionchanged[The \var{domain} argument allows to override
-the NIS domain used for the lookup. If unspecified, lookup is in the
-default NIS domain]{2.5}
-\end{funcdesc}
-
- \begin{funcdesc}{get_default_domain}{}
-Return the system default NIS domain. \versionadded{2.5}
-\end{funcdesc}
-
-The \module{nis} module defines the following exception:
-
-\begin{excdesc}{error}
-An error raised when a NIS function returns an error code.
-\end{excdesc}
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
deleted file mode 100644
index 22236f4..0000000
--- a/Doc/lib/libnntplib.tex
+++ /dev/null
@@ -1,355 +0,0 @@
-\section{\module{nntplib} ---
- NNTP protocol client}
-
-\declaremodule{standard}{nntplib}
-\modulesynopsis{NNTP protocol client (requires sockets).}
-
-\indexii{NNTP}{protocol}
-\index{Network News Transfer Protocol}
-
-This module defines the class \class{NNTP} which implements the client
-side of the NNTP protocol. It can be used to implement a news reader
-or poster, or automated news processors. For more information on NNTP
-(Network News Transfer Protocol), see Internet \rfc{977}.
-
-Here are two small examples of how it can be used. To list some
-statistics about a newsgroup and print the subjects of the last 10
-articles:
-
-\begin{verbatim}
->>> s = NNTP('news.cwi.nl')
->>> resp, count, first, last, name = s.group('comp.lang.python')
->>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
-Group comp.lang.python has 59 articles, range 3742 to 3803
->>> resp, subs = s.xhdr('subject', first + '-' + last)
->>> for id, sub in subs[-10:]: print id, sub
-...
-3792 Re: Removing elements from a list while iterating...
-3793 Re: Who likes Info files?
-3794 Emacs and doc strings
-3795 a few questions about the Mac implementation
-3796 Re: executable python scripts
-3797 Re: executable python scripts
-3798 Re: a few questions about the Mac implementation
-3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
-3802 Re: executable python scripts
-3803 Re: \POSIX{} wait and SIGCHLD
->>> s.quit()
-'205 news.cwi.nl closing connection. Goodbye.'
-\end{verbatim}
-
-To post an article from a file (this assumes that the article has
-valid headers):
-
-\begin{verbatim}
->>> s = NNTP('news.cwi.nl')
->>> f = open('/tmp/article')
->>> s.post(f)
-'240 Article posted successfully.'
->>> s.quit()
-'205 news.cwi.nl closing connection. Goodbye.'
-\end{verbatim}
-
-The module itself defines the following items:
-
-\begin{classdesc}{NNTP}{host\optional{, port
- \optional{, user\optional{, password
- \optional{, readermode}
- \optional{, usenetrc}}}}}
-Return a new instance of the \class{NNTP} class, representing a
-connection to the NNTP server running on host \var{host}, listening at
-port \var{port}. The default \var{port} is 119. If the optional
-\var{user} and \var{password} are provided,
-or if suitable credentials are present in \file{~/.netrc} and the
-optional flag \var{usenetrc} is true (the default),
-the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to
-identify and authenticate the user to the server. If the optional
-flag \var{readermode} is true, then a \samp{mode reader} command is
-sent before authentication is performed. Reader mode is sometimes
-necessary if you are connecting to an NNTP server on the local machine
-and intend to call reader-specific commands, such as \samp{group}. If
-you get unexpected \exception{NNTPPermanentError}s, you might need to set
-\var{readermode}. \var{readermode} defaults to \code{None}.
-\var{usenetrc} defaults to \code{True}.
-
-\versionchanged[\var{usenetrc} argument added]{2.4}
-\end{classdesc}
-
-\begin{excdesc}{NNTPError}
-Derived from the standard exception \exception{Exception}, this is the
-base class for all exceptions raised by the \module{nntplib} module.
-\end{excdesc}
-
-\begin{excdesc}{NNTPReplyError}
-Exception raised when an unexpected reply is received from the
-server. For backwards compatibility, the exception \code{error_reply}
-is equivalent to this class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPTemporaryError}
-Exception raised when an error code in the range 400--499 is
-received. For backwards compatibility, the exception
-\code{error_temp} is equivalent to this class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPPermanentError}
-Exception raised when an error code in the range 500--599 is
-received. For backwards compatibility, the exception
-\code{error_perm} is equivalent to this class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPProtocolError}
-Exception raised when a reply is received from the server that does
-not begin with a digit in the range 1--5. For backwards
-compatibility, the exception \code{error_proto} is equivalent to this
-class.
-\end{excdesc}
-
-\begin{excdesc}{NNTPDataError}
-Exception raised when there is some error in the response data. For
-backwards compatibility, the exception \code{error_data} is
-equivalent to this class.
-\end{excdesc}
-
-
-\subsection{NNTP Objects \label{nntp-objects}}
-
-NNTP instances have the following methods. The \var{response} that is
-returned as the first item in the return tuple of almost all methods
-is the server's response: a string beginning with a three-digit code.
-If the server's response indicates an error, the method raises one of
-the above exceptions.
-
-
-\begin{methoddesc}[NNTP]{getwelcome}{}
-Return the welcome message sent by the server in reply to the initial
-connection. (This message sometimes contains disclaimers or help
-information that may be relevant to the user.)
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{set_debuglevel}{level}
-Set the instance's debugging level. This controls the amount of
-debugging output printed. The default, \code{0}, produces no debugging
-output. A value of \code{1} produces a moderate amount of debugging
-output, generally a single line per request or response. A value of
-\code{2} or higher produces the maximum amount of debugging output,
-logging each line sent and received on the connection (including
-message text).
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{newgroups}{date, time, \optional{file}}
-Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
-string of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating the
-date, and \var{time} should be a string of the form
-\code{'\var{hh}\var{mm}\var{ss}'} indicating the time. Return a pair
-\code{(\var{response}, \var{groups})} where \var{groups} is a list of
-group names that are new since the given date and time.
-If the \var{file} parameter is supplied, then the output of the
-\samp{NEWGROUPS} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{newnews}{group, date, time, \optional{file}}
-Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
-\code{'*'}, and \var{date} and \var{time} have the same meaning as for
-\method{newgroups()}. Return a pair \code{(\var{response},
-\var{articles})} where \var{articles} is a list of message ids.
-If the \var{file} parameter is supplied, then the output of the
-\samp{NEWNEWS} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{list}{\optional{file}}
-Send a \samp{LIST} command. Return a pair \code{(\var{response},
-\var{list})} where \var{list} is a list of tuples. Each tuple has the
-form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
-\var{group} is a group name, \var{last} and \var{first} are the last
-and first article numbers (as strings), and \var{flag} is
-\code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if
-the newsgroup is moderated. (Note the ordering: \var{last},
-\var{first}.)
-If the \var{file} parameter is supplied, then the output of the
-\samp{LIST} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{descriptions}{grouppattern}
-Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmat
-string as specified in RFC2980 (it's essentially the same as DOS or UNIX
-shell wildcard strings). Return a pair \code{(\var{response},
-\var{list})}, where \var{list} is a list of tuples containing
-\code{(\var{name}, \var{title})}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{description}{group}
-Get a description for a single group \var{group}. If more than one group
-matches (if 'group' is a real wildmat string), return the first match.
-If no group matches, return an empty string.
-
-This elides the response code from the server. If the response code is
-needed, use \method{descriptions()}.
-
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{group}{name}
-Send a \samp{GROUP} command, where \var{name} is the group name.
-Return a tuple \code{(\var{response}, \var{count}, \var{first},
-\var{last}, \var{name})} where \var{count} is the (estimated) number
-of articles in the group, \var{first} is the first article number in
-the group, \var{last} is the last article number in the group, and
-\var{name} is the group name. The numbers are returned as strings.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{help}{\optional{file}}
-Send a \samp{HELP} command. Return a pair \code{(\var{response},
-\var{list})} where \var{list} is a list of help strings.
-If the \var{file} parameter is supplied, then the output of the
-\samp{HELP} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{stat}{id}
-Send a \samp{STAT} command, where \var{id} is the message id (enclosed
-in \character{<} and \character{>}) or an article number (as a string).
-Return a triple \code{(\var{response}, \var{number}, \var{id})} where
-\var{number} is the article number (as a string) and \var{id} is the
-message id (enclosed in \character{<} and \character{>}).
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{next}{}
-Send a \samp{NEXT} command. Return as for \method{stat()}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{last}{}
-Send a \samp{LAST} command. Return as for \method{stat()}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{head}{id}
-Send a \samp{HEAD} command, where \var{id} has the same meaning as for
-\method{stat()}. Return a tuple
-\code{(\var{response}, \var{number}, \var{id}, \var{list})}
-where the first three are the same as for \method{stat()},
-and \var{list} is a list of the article's headers (an uninterpreted
-list of lines, without trailing newlines).
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{body}{id,\optional{file}}
-Send a \samp{BODY} command, where \var{id} has the same meaning as for
-\method{stat()}. If the \var{file} parameter is supplied, then
-the body is stored in a file. If \var{file} is a string, then
-the method will open a file object with that name, write to it then close it.
-If \var{file} is a file object, then it will start calling
-\method{write()} on it to store the lines of the body.
-Return as for \method{head()}. If \var{file} is supplied, then
-the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{article}{id}
-Send an \samp{ARTICLE} command, where \var{id} has the same meaning as
-for \method{stat()}. Return as for \method{head()}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{slave}{}
-Send a \samp{SLAVE} command. Return the server's \var{response}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xhdr}{header, string, \optional{file}}
-Send an \samp{XHDR} command. This command is not defined in the RFC
-but is a common extension. The \var{header} argument is a header
-keyword, e.g. \code{'subject'}. The \var{string} argument should have
-the form \code{'\var{first}-\var{last}'} where \var{first} and
-\var{last} are the first and last article numbers to search. Return a
-pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
-pairs \code{(\var{id}, \var{text})}, where \var{id} is an article number
-(as a string) and \var{text} is the text of the requested header for
-that article.
-If the \var{file} parameter is supplied, then the output of the
-\samp{XHDR} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{post}{file}
-Post an article using the \samp{POST} command. The \var{file}
-argument is an open file object which is read until EOF using its
-\method{readline()} method. It should be a well-formed news article,
-including the required headers. The \method{post()} method
-automatically escapes lines beginning with \samp{.}.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{ihave}{id, file}
-Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in
-\character{<} and \character{>}).
-If the response is not an error, treat
-\var{file} exactly as for the \method{post()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{date}{}
-Return a triple \code{(\var{response}, \var{date}, \var{time})},
-containing the current date and time in a form suitable for the
-\method{newnews()} and \method{newgroups()} methods.
-This is an optional NNTP extension, and may not be supported by all
-servers.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xgtitle}{name, \optional{file}}
-Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
-\var{list})}, where \var{list} is a list of tuples containing
-\code{(\var{name}, \var{title})}.
-% XXX huh? Should that be name, description?
-If the \var{file} parameter is supplied, then the output of the
-\samp{XGTITLE} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-This is an optional NNTP extension, and may not be supported by all
-servers.
-
-RFC2980 says ``It is suggested that this extension be deprecated''. Use
-\method{descriptions()} or \method{description()} instead.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xover}{start, end, \optional{file}}
-Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
-of tuples, one for each article in the range delimited by the \var{start}
-and \var{end} article numbers. Each tuple is of the form
-\code{(\var{article number}, \var{subject}, \var{poster}, \var{date},
-\var{id}, \var{references}, \var{size}, \var{lines})}.
-If the \var{file} parameter is supplied, then the output of the
-\samp{XOVER} command is stored in a file. If \var{file} is a string,
-then the method will open a file object with that name, write to it
-then close it. If \var{file} is a file object, then it will start
-calling \method{write()} on it to store the lines of the command output.
-If \var{file} is supplied, then the returned \var{list} is an empty list.
-This is an optional NNTP extension, and may not be supported by all
-servers.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{xpath}{id}
-Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
-directory path to the article with message ID \var{id}. This is an
-optional NNTP extension, and may not be supported by all servers.
-\end{methoddesc}
-
-\begin{methoddesc}[NNTP]{quit}{}
-Send a \samp{QUIT} command and close the connection. Once this method
-has been called, no other methods of the NNTP object should be called.
-\end{methoddesc}
diff --git a/Doc/lib/libobjs.tex b/Doc/lib/libobjs.tex
deleted file mode 100644
index 3c7d798..0000000
--- a/Doc/lib/libobjs.tex
+++ /dev/null
@@ -1,24 +0,0 @@
-\chapter{Built-in Objects \label{builtin}}
-
-Names for built-in exceptions and functions and a number of constants are
-found in a separate
-symbol table. This table is searched last when the interpreter looks
-up the meaning of a name, so local and global
-user-defined names can override built-in names. Built-in types are
-described together here for easy reference.\footnote{
- Most descriptions sorely lack explanations of the exceptions
- that may be raised --- this will be fixed in a future version of
- this manual.}
-\indexii{built-in}{types}
-\indexii{built-in}{exceptions}
-\indexii{built-in}{functions}
-\indexii{built-in}{constants}
-\index{symbol table}
-
-The tables in this chapter document the priorities of operators by
-listing them in order of ascending priority (within a table) and
-grouping operators that have the same priority in the same box.
-Binary operators of the same priority group from left to right.
-(Unary operators group from right to left, but there you have no real
-choice.) See chapter 5 of the \citetitle[../ref/ref.html]{Python
-Reference Manual} for the complete picture on operator priorities.
diff --git a/Doc/lib/liboperator.tex b/Doc/lib/liboperator.tex
deleted file mode 100644
index 867c2ab..0000000
--- a/Doc/lib/liboperator.tex
+++ /dev/null
@@ -1,530 +0,0 @@
-\section{\module{operator} ---
- Standard operators as functions.}
-\declaremodule{builtin}{operator}
-\sectionauthor{Skip Montanaro}{skip@automatrix.com}
-
-\modulesynopsis{All Python's standard operators as built-in functions.}
-
-
-The \module{operator} module exports a set of functions implemented in C
-corresponding to the intrinsic operators of Python. For example,
-\code{operator.add(x, y)} is equivalent to the expression \code{x+y}. The
-function names are those used for special class methods; variants without
-leading and trailing \samp{__} are also provided for convenience.
-
-The functions fall into categories that perform object comparisons,
-logical operations, mathematical operations, sequence operations, and
-abstract type tests.
-
-The object comparison functions are useful for all objects, and are
-named after the rich comparison operators they support:
-
-\begin{funcdesc}{lt}{a, b}
-\funcline{le}{a, b}
-\funcline{eq}{a, b}
-\funcline{ne}{a, b}
-\funcline{ge}{a, b}
-\funcline{gt}{a, b}
-\funcline{__lt__}{a, b}
-\funcline{__le__}{a, b}
-\funcline{__eq__}{a, b}
-\funcline{__ne__}{a, b}
-\funcline{__ge__}{a, b}
-\funcline{__gt__}{a, b}
-Perform ``rich comparisons'' between \var{a} and \var{b}. Specifically,
-\code{lt(\var{a}, \var{b})} is equivalent to \code{\var{a} < \var{b}},
-\code{le(\var{a}, \var{b})} is equivalent to \code{\var{a} <= \var{b}},
-\code{eq(\var{a}, \var{b})} is equivalent to \code{\var{a} == \var{b}},
-\code{ne(\var{a}, \var{b})} is equivalent to \code{\var{a} != \var{b}},
-\code{gt(\var{a}, \var{b})} is equivalent to \code{\var{a} > \var{b}}
-and
-\code{ge(\var{a}, \var{b})} is equivalent to \code{\var{a} >= \var{b}}.
-Note that unlike the built-in \function{cmp()}, these functions can
-return any value, which may or may not be interpretable as a Boolean
-value. See the \citetitle[../ref/ref.html]{Python Reference Manual}
-for more information about rich comparisons.
-\versionadded{2.2}
-\end{funcdesc}
-
-
-The logical operations are also generally applicable to all objects,
-and support truth tests, identity tests, and boolean operations:
-
-\begin{funcdesc}{not_}{o}
-\funcline{__not__}{o}
-Return the outcome of \keyword{not} \var{o}. (Note that there is no
-\method{__not__()} method for object instances; only the interpreter
-core defines this operation. The result is affected by the
-\method{__bool__()} and \method{__len__()} methods.)
-\end{funcdesc}
-
-\begin{funcdesc}{truth}{o}
-Return \constant{True} if \var{o} is true, and \constant{False}
-otherwise. This is equivalent to using the \class{bool}
-constructor.
-\end{funcdesc}
-
-\begin{funcdesc}{is_}{a, b}
-Return \code{\var{a} is \var{b}}. Tests object identity.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{is_not}{a, b}
-Return \code{\var{a} is not \var{b}}. Tests object identity.
-\versionadded{2.3}
-\end{funcdesc}
-
-
-The mathematical and bitwise operations are the most numerous:
-
-\begin{funcdesc}{abs}{o}
-\funcline{__abs__}{o}
-Return the absolute value of \var{o}.
-\end{funcdesc}
-
-\begin{funcdesc}{add}{a, b}
-\funcline{__add__}{a, b}
-Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
-\end{funcdesc}
-
-\begin{funcdesc}{and_}{a, b}
-\funcline{__and__}{a, b}
-Return the bitwise and of \var{a} and \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{div}{a, b}
-\funcline{__div__}{a, b}
-Return \var{a} \code{/} \var{b} when \code{__future__.division} is not
-in effect. This is also known as ``classic'' division.
-\end{funcdesc}
-
-\begin{funcdesc}{floordiv}{a, b}
-\funcline{__floordiv__}{a, b}
-Return \var{a} \code{//} \var{b}.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{inv}{o}
-\funcline{invert}{o}
-\funcline{__inv__}{o}
-\funcline{__invert__}{o}
-Return the bitwise inverse of the number \var{o}. This is equivalent
-to \code{\textasciitilde}\var{o}. The names \function{invert()} and
-\function{__invert__()} were added in Python 2.0.
-\end{funcdesc}
-
-\begin{funcdesc}{lshift}{a, b}
-\funcline{__lshift__}{a, b}
-Return \var{a} shifted left by \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{mod}{a, b}
-\funcline{__mod__}{a, b}
-Return \var{a} \code{\%} \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{mul}{a, b}
-\funcline{__mul__}{a, b}
-Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers.
-\end{funcdesc}
-
-\begin{funcdesc}{neg}{o}
-\funcline{__neg__}{o}
-Return \var{o} negated.
-\end{funcdesc}
-
-\begin{funcdesc}{or_}{a, b}
-\funcline{__or__}{a, b}
-Return the bitwise or of \var{a} and \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{pos}{o}
-\funcline{__pos__}{o}
-Return \var{o} positive.
-\end{funcdesc}
-
-\begin{funcdesc}{pow}{a, b}
-\funcline{__pow__}{a, b}
-Return \var{a} \code{**} \var{b}, for \var{a} and \var{b} numbers.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{rshift}{a, b}
-\funcline{__rshift__}{a, b}
-Return \var{a} shifted right by \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{sub}{a, b}
-\funcline{__sub__}{a, b}
-Return \var{a} \code{-} \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{truediv}{a, b}
-\funcline{__truediv__}{a, b}
-Return \var{a} \code{/} \var{b} when \code{__future__.division} is in
-effect. This is also known as ``true'' division.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{xor}{a, b}
-\funcline{__xor__}{a, b}
-Return the bitwise exclusive or of \var{a} and \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{index}{a}
-\funcline{__index__}{a}
-Return \var{a} converted to an integer. Equivalent to \var{a}\code{.__index__()}.
-\versionadded{2.5}
-\end{funcdesc}
-
-Operations which work with sequences include:
-
-\begin{funcdesc}{concat}{a, b}
-\funcline{__concat__}{a, b}
-Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences.
-\end{funcdesc}
-
-\begin{funcdesc}{contains}{a, b}
-\funcline{__contains__}{a, b}
-Return the outcome of the test \var{b} \code{in} \var{a}.
-Note the reversed operands. The name \function{__contains__()} was
-added in Python 2.0.
-\end{funcdesc}
-
-\begin{funcdesc}{countOf}{a, b}
-Return the number of occurrences of \var{b} in \var{a}.
-\end{funcdesc}
-
-\begin{funcdesc}{delitem}{a, b}
-\funcline{__delitem__}{a, b}
-Remove the value of \var{a} at index \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{delslice}{a, b, c}
-\funcline{__delslice__}{a, b, c}
-Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
-\end{funcdesc}
-
-\begin{funcdesc}{getitem}{a, b}
-\funcline{__getitem__}{a, b}
-Return the value of \var{a} at index \var{b}.
-\end{funcdesc}
-
-\begin{funcdesc}{getslice}{a, b, c}
-\funcline{__getslice__}{a, b, c}
-Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
-\end{funcdesc}
-
-\begin{funcdesc}{indexOf}{a, b}
-Return the index of the first of occurrence of \var{b} in \var{a}.
-\end{funcdesc}
-
-\begin{funcdesc}{repeat}{a, b}
-\funcline{__repeat__}{a, b}
-Return \var{a} \code{*} \var{b} where \var{a} is a sequence and
-\var{b} is an integer.
-\end{funcdesc}
-
-\begin{funcdesc}{sequenceIncludes}{\unspecified}
-\deprecated{2.0}{Use \function{contains()} instead.}
-Alias for \function{contains()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setitem}{a, b, c}
-\funcline{__setitem__}{a, b, c}
-Set the value of \var{a} at index \var{b} to \var{c}.
-\end{funcdesc}
-
-\begin{funcdesc}{setslice}{a, b, c, v}
-\funcline{__setslice__}{a, b, c, v}
-Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the
-sequence \var{v}.
-\end{funcdesc}
-
-
-Many operations have an ``in-place'' version. The following functions
-provide a more primitive access to in-place operators than the usual
-syntax does; for example, the statement \code{x += y} is equivalent to
-\code{x = operator.iadd(x, y)}. Another way to put it is to say that
-\code{z = operator.iadd(x, y)} is equivalent to the compound statement
-\code{z = x; z += y}.
-
-\begin{funcdesc}{iadd}{a, b}
-\funcline{__iadd__}{a, b}
-\code{a = iadd(a, b)} is equivalent to \code{a += b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{iand}{a, b}
-\funcline{__iand__}{a, b}
-\code{a = iand(a, b)} is equivalent to \code{a \&= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{iconcat}{a, b}
-\funcline{__iconcat__}{a, b}
-\code{a = iconcat(a, b)} is equivalent to \code{a += b} for \var{a}
-and \var{b} sequences.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{idiv}{a, b}
-\funcline{__idiv__}{a, b}
-\code{a = idiv(a, b)} is equivalent to \code{a /= b} when
-\code{__future__.division} is not in effect.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ifloordiv}{a, b}
-\funcline{__ifloordiv__}{a, b}
-\code{a = ifloordiv(a, b)} is equivalent to \code{a //= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ilshift}{a, b}
-\funcline{__ilshift__}{a, b}
-\code{a = ilshift(a, b)} is equivalent to \code{a <}\code{<= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{imod}{a, b}
-\funcline{__imod__}{a, b}
-\code{a = imod(a, b)} is equivalent to \code{a \%= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{imul}{a, b}
-\funcline{__imul__}{a, b}
-\code{a = imul(a, b)} is equivalent to \code{a *= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ior}{a, b}
-\funcline{__ior__}{a, b}
-\code{a = ior(a, b)} is equivalent to \code{a |= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ipow}{a, b}
-\funcline{__ipow__}{a, b}
-\code{a = ipow(a, b)} is equivalent to \code{a **= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{irepeat}{a, b}
-\funcline{__irepeat__}{a, b}
-\code{a = irepeat(a, b)} is equivalent to \code{a *= b} where
-\var{a} is a sequence and \var{b} is an integer.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{irshift}{a, b}
-\funcline{__irshift__}{a, b}
-\code{a = irshift(a, b)} is equivalent to \code{a >>= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{isub}{a, b}
-\funcline{__isub__}{a, b}
-\code{a = isub(a, b)} is equivalent to \code{a -= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{itruediv}{a, b}
-\funcline{__itruediv__}{a, b}
-\code{a = itruediv(a, b)} is equivalent to \code{a /= b} when
-\code{__future__.division} is in effect.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{ixor}{a, b}
-\funcline{__ixor__}{a, b}
-\code{a = ixor(a, b)} is equivalent to \code{a \textasciicircum= b}.
-\versionadded{2.5}
-\end{funcdesc}
-
-
-The \module{operator} module also defines a few predicates to test the
-type of objects. \note{Be careful not to misinterpret the
-results of these functions; only \function{isCallable()} has any
-measure of reliability with instance objects. For example:}
-
-\begin{verbatim}
->>> class C:
-... pass
-...
->>> import operator
->>> o = C()
->>> operator.isMappingType(o)
-True
-\end{verbatim}
-
-\begin{funcdesc}{isCallable}{o}
-\deprecated{2.0}{Use the \function{callable()} built-in function instead.}
-Returns true if the object \var{o} can be called like a function,
-otherwise it returns false. True is returned for functions, bound and
-unbound methods, class objects, and instance objects which support the
-\method{__call__()} method.
-\end{funcdesc}
-
-\begin{funcdesc}{isMappingType}{o}
-Returns true if the object \var{o} supports the mapping interface.
-This is true for dictionaries and all instance objects defining
-\method{__getitem__}.
-\warning{There is no reliable way to test if an instance
-supports the complete mapping protocol since the interface itself is
-ill-defined. This makes this test less useful than it otherwise might
-be.}
-\end{funcdesc}
-
-\begin{funcdesc}{isNumberType}{o}
-Returns true if the object \var{o} represents a number. This is true
-for all numeric types implemented in C.
-\warning{There is no reliable way to test if an instance
-supports the complete numeric interface since the interface itself is
-ill-defined. This makes this test less useful than it otherwise might
-be.}
-\end{funcdesc}
-
-\begin{funcdesc}{isSequenceType}{o}
-Returns true if the object \var{o} supports the sequence protocol.
-This returns true for all objects which define sequence methods in C,
-and for all instance objects defining \method{__getitem__}.
-\warning{There is no reliable
-way to test if an instance supports the complete sequence interface
-since the interface itself is ill-defined. This makes this test less
-useful than it otherwise might be.}
-\end{funcdesc}
-
-
-Example: Build a dictionary that maps the ordinals from \code{0} to
-\code{255} to their character equivalents.
-
-\begin{verbatim}
->>> import operator
->>> d = {}
->>> keys = range(256)
->>> vals = map(chr, keys)
->>> map(operator.setitem, [d]*len(keys), keys, vals)
-\end{verbatim}
-
-
-The \module{operator} module also defines tools for generalized attribute
-and item lookups. These are useful for making fast field extractors
-as arguments for \function{map()}, \function{sorted()},
-\method{itertools.groupby()}, or other functions that expect a
-function argument.
-
-\begin{funcdesc}{attrgetter}{attr\optional{, args...}}
-Return a callable object that fetches \var{attr} from its operand.
-If more than one attribute is requested, returns a tuple of attributes.
-After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns
-\samp{b.name}. After, \samp{f=attrgetter('name', 'date')}, the call
-\samp{f(b)} returns \samp{(b.name, b.date)}.
-\versionadded{2.4}
-\versionchanged[Added support for multiple attributes]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{itemgetter}{item\optional{, args...}}
-Return a callable object that fetches \var{item} from its operand.
-If more than one item is requested, returns a tuple of items.
-After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns
-\samp{b[2]}.
-After, \samp{f=itemgetter(2,5,3)}, the call \samp{f(b)} returns
-\samp{(b[2], b[5], b[3])}.
-\versionadded{2.4}
-\versionchanged[Added support for multiple item extraction]{2.5}
-\end{funcdesc}
-
-Examples:
-
-\begin{verbatim}
->>> from operator import itemgetter
->>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
->>> getcount = itemgetter(1)
->>> map(getcount, inventory)
-[3, 2, 5, 1]
->>> sorted(inventory, key=getcount)
-[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
-\end{verbatim}
-
-
-\subsection{Mapping Operators to Functions \label{operator-map}}
-
-This table shows how abstract operations correspond to operator
-symbols in the Python syntax and the functions in the
-\refmodule{operator} module.
-
-
-\begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function}
- \lineiii{Addition}{\code{\var{a} + \var{b}}}
- {\code{add(\var{a}, \var{b})}}
- \lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}}
- {\code{concat(\var{seq1}, \var{seq2})}}
- \lineiii{Containment Test}{\code{\var{o} in \var{seq}}}
- {\code{contains(\var{seq}, \var{o})}}
- \lineiii{Division}{\code{\var{a} / \var{b}}}
- {\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}}
- \lineiii{Division}{\code{\var{a} / \var{b}}}
- {\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}}
- \lineiii{Division}{\code{\var{a} // \var{b}}}
- {\code{floordiv(\var{a}, \var{b})}}
- \lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}}
- {\code{and_(\var{a}, \var{b})}}
- \lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}}
- {\code{xor(\var{a}, \var{b})}}
- \lineiii{Bitwise Inversion}{\code{\~{} \var{a}}}
- {\code{invert(\var{a})}}
- \lineiii{Bitwise Or}{\code{\var{a} | \var{b}}}
- {\code{or_(\var{a}, \var{b})}}
- \lineiii{Exponentiation}{\code{\var{a} ** \var{b}}}
- {\code{pow(\var{a}, \var{b})}}
- \lineiii{Identity}{\code{\var{a} is \var{b}}}
- {\code{is_(\var{a}, \var{b})}}
- \lineiii{Identity}{\code{\var{a} is not \var{b}}}
- {\code{is_not(\var{a}, \var{b})}}
- \lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}}
- {\code{setitem(\var{o}, \var{k}, \var{v})}}
- \lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}}
- {\code{delitem(\var{o}, \var{k})}}
- \lineiii{Indexing}{\code{\var{o}[\var{k}]}}
- {\code{getitem(\var{o}, \var{k})}}
- \lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}}
- {\code{lshift(\var{a}, \var{b})}}
- \lineiii{Modulo}{\code{\var{a} \%\ \var{b}}}
- {\code{mod(\var{a}, \var{b})}}
- \lineiii{Multiplication}{\code{\var{a} * \var{b}}}
- {\code{mul(\var{a}, \var{b})}}
- \lineiii{Negation (Arithmetic)}{\code{- \var{a}}}
- {\code{neg(\var{a})}}
- \lineiii{Negation (Logical)}{\code{not \var{a}}}
- {\code{not_(\var{a})}}
- \lineiii{Right Shift}{\code{\var{a} >> \var{b}}}
- {\code{rshift(\var{a}, \var{b})}}
- \lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}}
- {\code{repeat(\var{seq}, \var{i})}}
- \lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}}
- {\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}}
- \lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}}
- {\code{delslice(\var{seq}, \var{i}, \var{j})}}
- \lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}}
- {\code{getslice(\var{seq}, \var{i}, \var{j})}}
- \lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}}
- {\code{mod(\var{s}, \var{o})}}
- \lineiii{Subtraction}{\code{\var{a} - \var{b}}}
- {\code{sub(\var{a}, \var{b})}}
- \lineiii{Truth Test}{\code{\var{o}}}
- {\code{truth(\var{o})}}
- \lineiii{Ordering}{\code{\var{a} < \var{b}}}
- {\code{lt(\var{a}, \var{b})}}
- \lineiii{Ordering}{\code{\var{a} <= \var{b}}}
- {\code{le(\var{a}, \var{b})}}
- \lineiii{Equality}{\code{\var{a} == \var{b}}}
- {\code{eq(\var{a}, \var{b})}}
- \lineiii{Difference}{\code{\var{a} != \var{b}}}
- {\code{ne(\var{a}, \var{b})}}
- \lineiii{Ordering}{\code{\var{a} >= \var{b}}}
- {\code{ge(\var{a}, \var{b})}}
- \lineiii{Ordering}{\code{\var{a} > \var{b}}}
- {\code{gt(\var{a}, \var{b})}}
-\end{tableiii}
diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex
deleted file mode 100644
index eb4919b..0000000
--- a/Doc/lib/liboptparse.tex
+++ /dev/null
@@ -1,1888 +0,0 @@
-% THIS FILE IS AUTO-GENERATED! DO NOT EDIT!
-% (Your changes will be lost the next time it is generated.)
-\section{\module{optparse} --- More powerful command line option parser}
-\declaremodule{standard}{optparse}
-\moduleauthor{Greg Ward}{gward@python.net}
-\modulesynopsis{More convenient, flexible, and powerful command-line parsing library.}
-\versionadded{2.3}
-\sectionauthor{Greg Ward}{gward@python.net}
-% An intro blurb used only when generating LaTeX docs for the Python
-% manual (based on README.txt).
-
-\code{optparse} is a more convenient, flexible, and powerful library for
-parsing command-line options than \code{getopt}. \code{optparse} uses a more
-declarative style of command-line parsing: you create an instance of
-\class{OptionParser}, populate it with options, and parse the command line.
-\code{optparse} allows users to specify options in the conventional GNU/POSIX
-syntax, and additionally generates usage and help messages for you.
-
-Here's an example of using \code{optparse} in a simple script:
-\begin{verbatim}
-from optparse import OptionParser
-[...]
-parser = OptionParser()
-parser.add_option("-f", "--file", dest="filename",
- help="write report to FILE", metavar="FILE")
-parser.add_option("-q", "--quiet",
- action="store_false", dest="verbose", default=True,
- help="don't print status messages to stdout")
-
-(options, args) = parser.parse_args()
-\end{verbatim}
-
-With these few lines of code, users of your script can now do the
-``usual thing'' on the command-line, for example:
-\begin{verbatim}
-<yourscript> --file=outfile -q
-\end{verbatim}
-
-As it parses the command line, \code{optparse} sets attributes of the
-\code{options} object returned by \method{parse{\_}args()} based on user-supplied
-command-line values. When \method{parse{\_}args()} returns from parsing this
-command line, \code{options.filename} will be \code{"outfile"} and
-\code{options.verbose} will be \code{False}. \code{optparse} supports both long
-and short options, allows short options to be merged together, and
-allows options to be associated with their arguments in a variety of
-ways. Thus, the following command lines are all equivalent to the above
-example:
-\begin{verbatim}
-<yourscript> -f outfile --quiet
-<yourscript> --quiet --file outfile
-<yourscript> -q -foutfile
-<yourscript> -qfoutfile
-\end{verbatim}
-
-Additionally, users can run one of
-\begin{verbatim}
-<yourscript> -h
-<yourscript> --help
-\end{verbatim}
-
-and \code{optparse} will print out a brief summary of your script's
-options:
-\begin{verbatim}
-usage: <yourscript> [options]
-
-options:
- -h, --help show this help message and exit
- -f FILE, --file=FILE write report to FILE
- -q, --quiet don't print status messages to stdout
-\end{verbatim}
-
-where the value of \emph{yourscript} is determined at runtime (normally
-from \code{sys.argv{[}0]}).
-% $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
-
-
-\subsection{Background\label{optparse-background}}
-
-\module{optparse} was explicitly designed to encourage the creation of programs with
-straightforward, conventional command-line interfaces. To that end, it
-supports only the most common command-line syntax and semantics
-conventionally used under \UNIX{}. If you are unfamiliar with these
-conventions, read this section to acquaint yourself with them.
-
-
-\subsubsection{Terminology\label{optparse-terminology}}
-\begin{description}
-\item[argument]
-a string entered on the command-line, and passed by the shell to
-\code{execl()} or \code{execv()}. In Python, arguments are elements of
-\code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being
-executed). \UNIX{} shells also use the term ``word''.
-
-It is occasionally desirable to substitute an argument list other
-than \code{sys.argv{[}1:]}, so you should read ``argument'' as ``an element of
-\code{sys.argv{[}1:]}, or of some other list provided as a substitute for
-\code{sys.argv{[}1:]}''.
-\item[option ]
-an argument used to supply extra information to guide or customize the
-execution of a program. There are many different syntaxes for
-options; the traditional \UNIX{} syntax is a hyphen (``-'') followed by a
-single letter, e.g. \code{"-x"} or \code{"-F"}. Also, traditional \UNIX{}
-syntax allows multiple options to be merged into a single argument,
-e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project
-introduced \code{"-{}-"} followed by a series of hyphen-separated words,
-e.g. \code{"-{}-file"} or \code{"-{}-dry-run"}. These are the only two option
-syntaxes provided by \module{optparse}.
-
-Some other option syntaxes that the world has seen include:
-\begin{itemize}
-\item {}
-a hyphen followed by a few letters, e.g. \code{"-pf"} (this is
-\emph{not} the same as multiple options merged into a single argument)
-
-\item {}
-a hyphen followed by a whole word, e.g. \code{"-file"} (this is
-technically equivalent to the previous syntax, but they aren't
-usually seen in the same program)
-
-\item {}
-a plus sign followed by a single letter, or a few letters,
-or a word, e.g. \code{"+f"}, \code{"+rgb"}
-
-\item {}
-a slash followed by a letter, or a few letters, or a word, e.g.
-\code{"/f"}, \code{"/file"}
-
-\end{itemize}
-
-These option syntaxes are not supported by \module{optparse}, and they never will
-be. This is deliberate: the first three are non-standard on any
-environment, and the last only makes sense if you're exclusively
-targeting VMS, MS-DOS, and/or Windows.
-\item[option argument]
-an argument that follows an option, is closely associated with that
-option, and is consumed from the argument list when that option is.
-With \module{optparse}, option arguments may either be in a separate argument
-from their option:
-\begin{verbatim}
--f foo
---file foo
-\end{verbatim}
-
-or included in the same argument:
-\begin{verbatim}
--ffoo
---file=foo
-\end{verbatim}
-
-Typically, a given option either takes an argument or it doesn't.
-Lots of people want an ``optional option arguments'' feature, meaning
-that some options will take an argument if they see it, and won't if
-they don't. This is somewhat controversial, because it makes parsing
-ambiguous: if \code{"-a"} takes an optional argument and \code{"-b"} is
-another option entirely, how do we interpret \code{"-ab"}? Because of
-this ambiguity, \module{optparse} does not support this feature.
-\item[positional argument]
-something leftover in the argument list after options have been
-parsed, i.e. after options and their arguments have been parsed and
-removed from the argument list.
-\item[required option]
-an option that must be supplied on the command-line; note that the
-phrase ``required option'' is self-contradictory in English. \module{optparse}
-doesn't prevent you from implementing required options, but doesn't
-give you much help at it either. See \code{examples/required{\_}1.py} and
-\code{examples/required{\_}2.py} in the \module{optparse} source distribution for two
-ways to implement required options with \module{optparse}.
-\end{description}
-
-For example, consider this hypothetical command-line:
-\begin{verbatim}
-prog -v --report /tmp/report.txt foo bar
-\end{verbatim}
-
-\code{"-v"} and \code{"-{}-report"} are both options. Assuming that
-\longprogramopt{report} takes one argument, \code{"/tmp/report.txt"} is an option
-argument. \code{"foo"} and \code{"bar"} are positional arguments.
-
-
-\subsubsection{What are options for?\label{optparse-what-options-for}}
-
-Options are used to provide extra information to tune or customize the
-execution of a program. In case it wasn't clear, options are usually
-\emph{optional}. A program should be able to run just fine with no options
-whatsoever. (Pick a random program from the \UNIX{} or GNU toolsets. Can
-it run without any options at all and still make sense? The main
-exceptions are \code{find}, \code{tar}, and \code{dd}{---}all of which are mutant
-oddballs that have been rightly criticized for their non-standard syntax
-and confusing interfaces.)
-
-Lots of people want their programs to have ``required options''. Think
-about it. If it's required, then it's \emph{not optional}! If there is a
-piece of information that your program absolutely requires in order to
-run successfully, that's what positional arguments are for.
-
-As an example of good command-line interface design, consider the humble
-\code{cp} utility, for copying files. It doesn't make much sense to try to
-copy files without supplying a destination and at least one source.
-Hence, \code{cp} fails if you run it with no arguments. However, it has a
-flexible, useful syntax that does not require any options at all:
-\begin{verbatim}
-cp SOURCE DEST
-cp SOURCE ... DEST-DIR
-\end{verbatim}
-
-You can get pretty far with just that. Most \code{cp} implementations
-provide a bunch of options to tweak exactly how the files are copied:
-you can preserve mode and modification time, avoid following symlinks,
-ask before clobbering existing files, etc. But none of this distracts
-from the core mission of \code{cp}, which is to copy either one file to
-another, or several files to another directory.
-
-
-\subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}}
-
-Positional arguments are for those pieces of information that your
-program absolutely, positively requires to run.
-
-A good user interface should have as few absolute requirements as
-possible. If your program requires 17 distinct pieces of information in
-order to run successfully, it doesn't much matter \emph{how} you get that
-information from the user{---}most people will give up and walk away
-before they successfully run the program. This applies whether the user
-interface is a command-line, a configuration file, or a GUI: if you make
-that many demands on your users, most of them will simply give up.
-
-In short, try to minimize the amount of information that users are
-absolutely required to supply{---}use sensible defaults whenever
-possible. Of course, you also want to make your programs reasonably
-flexible. That's what options are for. Again, it doesn't matter if
-they are entries in a config file, widgets in the ``Preferences'' dialog
-of a GUI, or command-line options{---}the more options you implement, the
-more flexible your program is, and the more complicated its
-implementation becomes. Too much flexibility has drawbacks as well, of
-course; too many options can overwhelm users and make your code much
-harder to maintain.
-% $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
-
-
-\subsection{Tutorial\label{optparse-tutorial}}
-
-While \module{optparse} is quite flexible and powerful, it's also straightforward to
-use in most cases. This section covers the code patterns that are
-common to any \module{optparse}-based program.
-
-First, you need to import the OptionParser class; then, early in the
-main program, create an OptionParser instance:
-\begin{verbatim}
-from optparse import OptionParser
-[...]
-parser = OptionParser()
-\end{verbatim}
-
-Then you can start defining options. The basic syntax is:
-\begin{verbatim}
-parser.add_option(opt_str, ...,
- attr=value, ...)
-\end{verbatim}
-
-Each option has one or more option strings, such as \code{"-f"} or
-\code{"-{}-file"}, and several option attributes that tell \module{optparse} what to
-expect and what to do when it encounters that option on the command
-line.
-
-Typically, each option will have one short option string and one long
-option string, e.g.:
-\begin{verbatim}
-parser.add_option("-f", "--file", ...)
-\end{verbatim}
-
-You're free to define as many short option strings and as many long
-option strings as you like (including zero), as long as there is at
-least one option string overall.
-
-The option strings passed to \method{add{\_}option()} are effectively labels for
-the option defined by that call. For brevity, we will frequently refer
-to \emph{encountering an option} on the command line; in reality, \module{optparse}
-encounters \emph{option strings} and looks up options from them.
-
-Once all of your options are defined, instruct \module{optparse} to parse your
-program's command line:
-\begin{verbatim}
-(options, args) = parser.parse_args()
-\end{verbatim}
-
-(If you like, you can pass a custom argument list to \method{parse{\_}args()},
-but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.)
-
-\method{parse{\_}args()} returns two values:
-\begin{itemize}
-\item {}
-\code{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then
-\code{options.file} will be the filename supplied by the user, or
-\code{None} if the user did not supply that option
-
-\item {}
-\code{args}, the list of positional arguments leftover after parsing
-options
-
-\end{itemize}
-
-This tutorial section only covers the four most important option
-attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}.
-Of these, \member{action} is the most fundamental.
-
-
-\subsubsection{Understanding option actions\label{optparse-understanding-option-actions}}
-
-Actions tell \module{optparse} what to do when it encounters an option on the
-command line. There is a fixed set of actions hard-coded into \module{optparse};
-adding new actions is an advanced topic covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
-Most actions tell \module{optparse} to store a value in some variable{---}for
-example, take a string from the command line and store it in an
-attribute of \code{options}.
-
-If you don't specify an option action, \module{optparse} defaults to \code{store}.
-
-
-\subsubsection{The store action\label{optparse-store-action}}
-
-The most common option action is \code{store}, which tells \module{optparse} to take
-the next argument (or the remainder of the current argument), ensure
-that it is of the correct type, and store it to your chosen destination.
-
-For example:
-\begin{verbatim}
-parser.add_option("-f", "--file",
- action="store", type="string", dest="filename")
-\end{verbatim}
-
-Now let's make up a fake command line and ask \module{optparse} to parse it:
-\begin{verbatim}
-args = ["-f", "foo.txt"]
-(options, args) = parser.parse_args(args)
-\end{verbatim}
-
-When \module{optparse} sees the option string \code{"-f"}, it consumes the next
-argument, \code{"foo.txt"}, and stores it in \code{options.filename}. So,
-after this call to \method{parse{\_}args()}, \code{options.filename} is
-\code{"foo.txt"}.
-
-Some other option types supported by \module{optparse} are \code{int} and \code{float}.
-Here's an option that expects an integer argument:
-\begin{verbatim}
-parser.add_option("-n", type="int", dest="num")
-\end{verbatim}
-
-Note that this option has no long option string, which is perfectly
-acceptable. Also, there's no explicit action, since the default is
-\code{store}.
-
-Let's parse another fake command-line. This time, we'll jam the option
-argument right up against the option: since \code{"-n42"} (one argument) is
-equivalent to \code{"-n 42"} (two arguments), the code
-\begin{verbatim}
-(options, args) = parser.parse_args(["-n42"])
-print options.num
-\end{verbatim}
-
-will print \code{"42"}.
-
-If you don't specify a type, \module{optparse} assumes \code{string}. Combined with the
-fact that the default action is \code{store}, that means our first example
-can be a lot shorter:
-\begin{verbatim}
-parser.add_option("-f", "--file", dest="filename")
-\end{verbatim}
-
-If you don't supply a destination, \module{optparse} figures out a sensible default
-from the option strings: if the first long option string is
-\code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}. If there
-are no long option strings, \module{optparse} looks at the first short option
-string: the default destination for \code{"-f"} is \code{f}.
-
-\module{optparse} also includes built-in \code{long} and \code{complex} types. Adding
-types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
-
-
-\subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}}
-
-Flag options{---}set a variable to true or false when a particular option
-is seen{---}are quite common. \module{optparse} supports them with two separate
-actions, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a
-\code{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose")
-parser.add_option("-q", action="store_false", dest="verbose")
-\end{verbatim}
-
-Here we have two different options with the same destination, which is
-perfectly OK. (It just means you have to be a bit careful when setting
-default values{---}see below.)
-
-When \module{optparse} encounters \code{"-v"} on the command line, it sets
-\code{options.verbose} to \code{True}; when it encounters \code{"-q"},
-\code{options.verbose} is set to \code{False}.
-
-
-\subsubsection{Other actions\label{optparse-other-actions}}
-
-Some other actions supported by \module{optparse} are:
-\begin{description}
-\item[\code{store{\_}const}]
-store a constant value
-\item[\code{append}]
-append this option's argument to a list
-\item[\code{count}]
-increment a counter by one
-\item[\code{callback}]
-call a specified function
-\end{description}
-
-These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks.
-
-
-\subsubsection{Default values\label{optparse-default-values}}
-
-All of the above examples involve setting some variable (the
-``destination'') when certain command-line options are seen. What happens
-if those options are never seen? Since we didn't supply any defaults,
-they are all set to \code{None}. This is usually fine, but sometimes you
-want more control. \module{optparse} lets you supply a default value for each
-destination, which is assigned before the command line is parsed.
-
-First, consider the verbose/quiet example. If we want \module{optparse} to set
-\code{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose", default=True)
-parser.add_option("-q", action="store_false", dest="verbose")
-\end{verbatim}
-
-Since default values apply to the \emph{destination} rather than to any
-particular option, and these two options happen to have the same
-destination, this is exactly equivalent:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose")
-parser.add_option("-q", action="store_false", dest="verbose", default=True)
-\end{verbatim}
-
-Consider this:
-\begin{verbatim}
-parser.add_option("-v", action="store_true", dest="verbose", default=False)
-parser.add_option("-q", action="store_false", dest="verbose", default=True)
-\end{verbatim}
-
-Again, the default value for \code{verbose} will be \code{True}: the last
-default value supplied for any particular destination is the one that
-counts.
-
-A clearer way to specify default values is the \method{set{\_}defaults()}
-method of OptionParser, which you can call at any time before calling
-\method{parse{\_}args()}:
-\begin{verbatim}
-parser.set_defaults(verbose=True)
-parser.add_option(...)
-(options, args) = parser.parse_args()
-\end{verbatim}
-
-As before, the last value specified for a given option destination is
-the one that counts. For clarity, try to use one method or the other of
-setting default values, not both.
-
-
-\subsubsection{Generating help\label{optparse-generating-help}}
-
-\module{optparse}'s ability to generate help and usage text automatically is useful
-for creating user-friendly command-line interfaces. All you have to do
-is supply a \member{help} value for each option, and optionally a short usage
-message for your whole program. Here's an OptionParser populated with
-user-friendly (documented) options:
-\begin{verbatim}
-usage = "usage: %prog [options] arg1 arg2"
-parser = OptionParser(usage=usage)
-parser.add_option("-v", "--verbose",
- action="store_true", dest="verbose", default=True,
- help="make lots of noise [default]")
-parser.add_option("-q", "--quiet",
- action="store_false", dest="verbose",
- help="be vewwy quiet (I'm hunting wabbits)")
-parser.add_option("-f", "--filename",
- metavar="FILE", help="write output to FILE"),
-parser.add_option("-m", "--mode",
- default="intermediate",
- help="interaction mode: novice, intermediate, "
- "or expert [default: %default]")
-\end{verbatim}
-
-If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line,
-or if you just call \method{parser.print{\_}help()}, it prints the following to
-standard output:
-\begin{verbatim}
-usage: <yourscript> [options] arg1 arg2
-
-options:
- -h, --help show this help message and exit
- -v, --verbose make lots of noise [default]
- -q, --quiet be vewwy quiet (I'm hunting wabbits)
- -f FILE, --filename=FILE
- write output to FILE
- -m MODE, --mode=MODE interaction mode: novice, intermediate, or
- expert [default: intermediate]
-\end{verbatim}
-
-(If the help output is triggered by a help option, \module{optparse} exits after
-printing the help text.)
-
-There's a lot going on here to help \module{optparse} generate the best possible
-help message:
-\begin{itemize}
-\item {}
-the script defines its own usage message:
-\begin{verbatim}
-usage = "usage: %prog [options] arg1 arg2"
-\end{verbatim}
-
-\module{optparse} expands \code{"{\%}prog"} in the usage string to the name of the current
-program, i.e. \code{os.path.basename(sys.argv{[}0])}. The expanded string
-is then printed before the detailed option help.
-
-If you don't supply a usage string, \module{optparse} uses a bland but sensible
-default: \code{"usage: {\%}prog {[}options]"}, which is fine if your script
-doesn't take any positional arguments.
-
-\item {}
-every option defines a help string, and doesn't worry about line-
-wrapping{---}\module{optparse} takes care of wrapping lines and making the
-help output look good.
-
-\item {}
-options that take a value indicate this fact in their
-automatically-generated help message, e.g. for the ``mode'' option:
-\begin{verbatim}
--m MODE, --mode=MODE
-\end{verbatim}
-
-Here, ``MODE'' is called the meta-variable: it stands for the argument
-that the user is expected to supply to \programopt{-m}/\longprogramopt{mode}. By default,
-\module{optparse} converts the destination variable name to uppercase and uses
-that for the meta-variable. Sometimes, that's not what you want{---}for example, the \longprogramopt{filename} option explicitly sets
-\code{metavar="FILE"}, resulting in this automatically-generated option
-description:
-\begin{verbatim}
--f FILE, --filename=FILE
-\end{verbatim}
-
-This is important for more than just saving space, though: the
-manually written help text uses the meta-variable ``FILE'' to clue the
-user in that there's a connection between the semi-formal syntax ``-f
-FILE'' and the informal semantic description ``write output to FILE''.
-This is a simple but effective way to make your help text a lot
-clearer and more useful for end users.
-
-\item {}
-options that have a default value can include \code{{\%}default} in
-the help string{---}\module{optparse} will replace it with \function{str()} of the
-option's default value. If an option has no default value (or the
-default value is \code{None}), \code{{\%}default} expands to \code{none}.
-
-\end{itemize}
-
-
-\subsubsection{Printing a version string\label{optparse-printing-version-string}}
-
-Similar to the brief usage string, \module{optparse} can also print a version string
-for your program. You have to supply the string as the \code{version}
-argument to OptionParser:
-\begin{verbatim}
-parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
-\end{verbatim}
-
-\code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart
-from that, \code{version} can contain anything you like. When you supply
-it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser.
-If it encounters this option on the command line, it expands your
-\code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and
-exits.
-
-For example, if your script is called \code{/usr/bin/foo}:
-\begin{verbatim}
-$ /usr/bin/foo --version
-foo 1.0
-\end{verbatim}
-
-
-\subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}}
-
-There are two broad classes of errors that \module{optparse} has to worry about:
-programmer errors and user errors. Programmer errors are usually
-erroneous calls to \code{parser.add{\_}option()}, e.g. invalid option strings,
-unknown option attributes, missing option attributes, etc. These are
-dealt with in the usual way: raise an exception (either
-\code{optparse.OptionError} or \code{TypeError}) and let the program crash.
-
-Handling user errors is much more important, since they are guaranteed
-to happen no matter how stable your code is. \module{optparse} can automatically
-detect some user errors, such as bad option arguments (passing \code{"-n
-4x"} where \programopt{-n} takes an integer argument), missing arguments
-(\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument
-of any type). Also, you can call \code{parser.error()} to signal an
-application-defined error condition:
-\begin{verbatim}
-(options, args) = parser.parse_args()
-[...]
-if options.a and options.b:
- parser.error("options -a and -b are mutually exclusive")
-\end{verbatim}
-
-In either case, \module{optparse} handles the error the same way: it prints the
-program's usage message and an error message to standard error and
-exits with error status 2.
-
-Consider the first example above, where the user passes \code{"4x"} to an
-option that takes an integer:
-\begin{verbatim}
-$ /usr/bin/foo -n 4x
-usage: foo [options]
-
-foo: error: option -n: invalid integer value: '4x'
-\end{verbatim}
-
-Or, where the user fails to pass a value at all:
-\begin{verbatim}
-$ /usr/bin/foo -n
-usage: foo [options]
-
-foo: error: -n option requires an argument
-\end{verbatim}
-
-\module{optparse}-generated error messages take care always to mention the option
-involved in the error; be sure to do the same when calling
-\code{parser.error()} from your application code.
-
-If \module{optparse}'s default error-handling behaviour does not suite your needs,
-you'll need to subclass OptionParser and override \code{exit()} and/or
-\method{error()}.
-
-
-\subsubsection{Putting it all together\label{optparse-putting-it-all-together}}
-
-Here's what \module{optparse}-based scripts usually look like:
-\begin{verbatim}
-from optparse import OptionParser
-[...]
-def main():
- usage = "usage: %prog [options] arg"
- parser = OptionParser(usage)
- parser.add_option("-f", "--file", dest="filename",
- help="read data from FILENAME")
- parser.add_option("-v", "--verbose",
- action="store_true", dest="verbose")
- parser.add_option("-q", "--quiet",
- action="store_false", dest="verbose")
- [...]
- (options, args) = parser.parse_args()
- if len(args) != 1:
- parser.error("incorrect number of arguments")
- if options.verbose:
- print "reading %s..." % options.filename
- [...]
-
-if __name__ == "__main__":
- main()
-\end{verbatim}
-% $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $
-
-
-\subsection{Reference Guide\label{optparse-reference-guide}}
-
-
-\subsubsection{Creating the parser\label{optparse-creating-parser}}
-
-The first step in using \module{optparse} is to create an OptionParser instance:
-\begin{verbatim}
-parser = OptionParser(...)
-\end{verbatim}
-
-The OptionParser constructor has no required arguments, but a number of
-optional keyword arguments. You should always pass them as keyword
-arguments, i.e. do not rely on the order in which the arguments are
-declared.
-\begin{quote}
-\begin{description}
-\item[\code{usage} (default: \code{"{\%}prog {[}options]"})]
-The usage summary to print when your program is run incorrectly or
-with a help option. When \module{optparse} prints the usage string, it expands
-\code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if
-you passed that keyword argument). To suppress a usage message,
-pass the special value \code{optparse.SUPPRESS{\_}USAGE}.
-\item[\code{option{\_}list} (default: \code{{[}]})]
-A list of Option objects to populate the parser with. The options
-in \code{option{\_}list} are added after any options in
-\code{standard{\_}option{\_}list} (a class attribute that may be set by
-OptionParser subclasses), but before any version or help options.
-Deprecated; use \method{add{\_}option()} after creating the parser instead.
-\item[\code{option{\_}class} (default: optparse.Option)]
-Class to use when adding options to the parser in \method{add{\_}option()}.
-\item[\code{version} (default: \code{None})]
-A version string to print when the user supplies a version option.
-If you supply a true value for \code{version}, \module{optparse} automatically adds
-a version option with the single option string \code{"-{}-version"}. The
-substring \code{"{\%}prog"} is expanded the same as for \code{usage}.
-\item[\code{conflict{\_}handler} (default: \code{"error"})]
-Specifies what to do when options with conflicting option strings
-are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options.
-\item[\code{description} (default: \code{None})]
-A paragraph of text giving a brief overview of your program. \module{optparse}
-reformats this paragraph to fit the current terminal width and
-prints it when the user requests help (after \code{usage}, but before
-the list of options).
-\item[\code{formatter} (default: a new IndentedHelpFormatter)]
-An instance of optparse.HelpFormatter that will be used for
-printing help text. \module{optparse} provides two concrete classes for this
-purpose: IndentedHelpFormatter and TitledHelpFormatter.
-\item[\code{add{\_}help{\_}option} (default: \code{True})]
-If true, \module{optparse} will add a help option (with option strings \code{"-h"}
-and \code{"-{}-help"}) to the parser.
-\item[\code{prog}]
-The string to use when expanding \code{"{\%}prog"} in \code{usage} and
-\code{version} instead of \code{os.path.basename(sys.argv{[}0])}.
-\end{description}
-\end{quote}
-
-
-\subsubsection{Populating the parser\label{optparse-populating-parser}}
-
-There are several ways to populate the parser with options. The
-preferred way is by using \code{OptionParser.add{\_}option()}, as shown in
-section~\ref{optparse-tutorial}, the tutorial. \method{add{\_}option()} can be called in one of two
-ways:
-\begin{itemize}
-\item {}
-pass it an Option instance (as returned by \function{make{\_}option()})
-
-\item {}
-pass it any combination of positional and keyword arguments that are
-acceptable to \function{make{\_}option()} (i.e., to the Option constructor),
-and it will create the Option instance for you
-
-\end{itemize}
-
-The other alternative is to pass a list of pre-constructed Option
-instances to the OptionParser constructor, as in:
-\begin{verbatim}
-option_list = [
- make_option("-f", "--filename",
- action="store", type="string", dest="filename"),
- make_option("-q", "--quiet",
- action="store_false", dest="verbose"),
- ]
-parser = OptionParser(option_list=option_list)
-\end{verbatim}
-
-(\function{make{\_}option()} is a factory function for creating Option instances;
-currently it is an alias for the Option constructor. A future version
-of \module{optparse} may split Option into several classes, and \function{make{\_}option()}
-will pick the right class to instantiate. Do not instantiate Option
-directly.)
-
-
-\subsubsection{Defining options\label{optparse-defining-options}}
-
-Each Option instance represents a set of synonymous command-line option
-strings, e.g. \programopt{-f} and \longprogramopt{file}. You can
-specify any number of short or long option strings, but you must specify
-at least one overall option string.
-
-The canonical way to create an Option instance is with the
-\method{add{\_}option()} method of \class{OptionParser}:
-\begin{verbatim}
-parser.add_option(opt_str[, ...], attr=value, ...)
-\end{verbatim}
-
-To define an option with only a short option string:
-\begin{verbatim}
-parser.add_option("-f", attr=value, ...)
-\end{verbatim}
-
-And to define an option with only a long option string:
-\begin{verbatim}
-parser.add_option("--foo", attr=value, ...)
-\end{verbatim}
-
-The keyword arguments define attributes of the new Option object. The
-most important option attribute is \member{action}, and it largely determines
-which other attributes are relevant or required. If you pass irrelevant
-option attributes, or fail to pass required ones, \module{optparse} raises an
-OptionError exception explaining your mistake.
-
-An options's \emph{action} determines what \module{optparse} does when it encounters this
-option on the command-line. The standard option actions hard-coded into
-\module{optparse} are:
-\begin{description}
-\item[\code{store}]
-store this option's argument (default)
-\item[\code{store{\_}const}]
-store a constant value
-\item[\code{store{\_}true}]
-store a true value
-\item[\code{store{\_}false}]
-store a false value
-\item[\code{append}]
-append this option's argument to a list
-\item[\code{append{\_}const}]
-append a constant value to a list
-\item[\code{count}]
-increment a counter by one
-\item[\code{callback}]
-call a specified function
-\item[\member{help}]
-print a usage message including all options and the
-documentation for them
-\end{description}
-
-(If you don't supply an action, the default is \code{store}. For this
-action, you may also supply \member{type} and \member{dest} option attributes; see
-below.)
-
-As you can see, most actions involve storing or updating a value
-somewhere. \module{optparse} always creates a special object for this,
-conventionally called \code{options} (it happens to be an instance of
-\code{optparse.Values}). Option arguments (and various other values) are
-stored as attributes of this object, according to the \member{dest}
-(destination) option attribute.
-
-For example, when you call
-\begin{verbatim}
-parser.parse_args()
-\end{verbatim}
-
-one of the first things \module{optparse} does is create the \code{options} object:
-\begin{verbatim}
-options = Values()
-\end{verbatim}
-
-If one of the options in this parser is defined with
-\begin{verbatim}
-parser.add_option("-f", "--file", action="store", type="string", dest="filename")
-\end{verbatim}
-
-and the command-line being parsed includes any of the following:
-\begin{verbatim}
--ffoo
--f foo
---file=foo
---file foo
-\end{verbatim}
-
-then \module{optparse}, on seeing this option, will do the equivalent of
-\begin{verbatim}
-options.filename = "foo"
-\end{verbatim}
-
-The \member{type} and \member{dest} option attributes are almost as important as
-\member{action}, but \member{action} is the only one that makes sense for \emph{all}
-options.
-
-
-\subsubsection{Standard option actions\label{optparse-standard-option-actions}}
-
-The various option actions all have slightly different requirements and
-effects. Most actions have several relevant option attributes which you
-may specify to guide \module{optparse}'s behaviour; a few have required attributes,
-which you must specify for any option using that action.
-\begin{itemize}
-\item {}
-\code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
-
-The option must be followed by an argument, which is
-converted to a value according to \member{type} and stored in
-\member{dest}. If \code{nargs} {\textgreater} 1, multiple arguments will be consumed
-from the command line; all will be converted according to
-\member{type} and stored to \member{dest} as a tuple. See the ``Option
-types'' section below.
-
-If \code{choices} is supplied (a list or tuple of strings), the type
-defaults to \code{choice}.
-
-If \member{type} is not supplied, it defaults to \code{string}.
-
-If \member{dest} is not supplied, \module{optparse} derives a destination from the
-first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}).
-If there are no long option strings, \module{optparse} derives a destination from
-the first short option string (e.g., \code{"-f"} implies \code{f}).
-
-Example:
-\begin{verbatim}
-parser.add_option("-f")
-parser.add_option("-p", type="float", nargs=3, dest="point")
-\end{verbatim}
-
-As it parses the command line
-\begin{verbatim}
--f foo.txt -p 1 -3.5 4 -fbar.txt
-\end{verbatim}
-
-\module{optparse} will set
-\begin{verbatim}
-options.f = "foo.txt"
-options.point = (1.0, -3.5, 4.0)
-options.f = "bar.txt"
-\end{verbatim}
-
-\item {}
-\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}]
-
-The value \code{const} is stored in \member{dest}.
-
-Example:
-\begin{verbatim}
-parser.add_option("-q", "--quiet",
- action="store_const", const=0, dest="verbose")
-parser.add_option("-v", "--verbose",
- action="store_const", const=1, dest="verbose")
-parser.add_option("--noisy",
- action="store_const", const=2, dest="verbose")
-\end{verbatim}
-
-If \code{"-{}-noisy"} is seen, \module{optparse} will set
-\begin{verbatim}
-options.verbose = 2
-\end{verbatim}
-
-\item {}
-\code{store{\_}true} {[}relevant: \member{dest}]
-
-A special case of \code{store{\_}const} that stores a true value
-to \member{dest}.
-
-\item {}
-\code{store{\_}false} {[}relevant: \member{dest}]
-
-Like \code{store{\_}true}, but stores a false value.
-
-Example:
-\begin{verbatim}
-parser.add_option("--clobber", action="store_true", dest="clobber")
-parser.add_option("--no-clobber", action="store_false", dest="clobber")
-\end{verbatim}
-
-\item {}
-\code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}]
-
-The option must be followed by an argument, which is appended to the
-list in \member{dest}. If no default value for \member{dest} is supplied, an
-empty list is automatically created when \module{optparse} first encounters this
-option on the command-line. If \code{nargs} {\textgreater} 1, multiple arguments are
-consumed, and a tuple of length \code{nargs} is appended to \member{dest}.
-
-The defaults for \member{type} and \member{dest} are the same as for the
-\code{store} action.
-
-Example:
-\begin{verbatim}
-parser.add_option("-t", "--tracks", action="append", type="int")
-\end{verbatim}
-
-If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of:
-\begin{verbatim}
-options.tracks = []
-options.tracks.append(int("3"))
-\end{verbatim}
-
-If, a little later on, \code{"-{}-tracks=4"} is seen, it does:
-\begin{verbatim}
-options.tracks.append(int("4"))
-\end{verbatim}
-
-\item {}
-\code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}]
-
-Like \code{store{\_}const}, but the value \code{const} is appended to \member{dest};
-as with \code{append}, \member{dest} defaults to \code{None}, and an an empty list is
-automatically created the first time the option is encountered.
-
-\item {}
-\code{count} {[}relevant: \member{dest}]
-
-Increment the integer stored at \member{dest}. If no default value is
-supplied, \member{dest} is set to zero before being incremented the first
-time.
-
-Example:
-\begin{verbatim}
-parser.add_option("-v", action="count", dest="verbosity")
-\end{verbatim}
-
-The first time \code{"-v"} is seen on the command line, \module{optparse} does the
-equivalent of:
-\begin{verbatim}
-options.verbosity = 0
-options.verbosity += 1
-\end{verbatim}
-
-Every subsequent occurrence of \code{"-v"} results in
-\begin{verbatim}
-options.verbosity += 1
-\end{verbatim}
-
-\item {}
-\code{callback} {[}required: \code{callback};
-relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}]
-
-Call the function specified by \code{callback}, which is called as
-\begin{verbatim}
-func(option, opt_str, value, parser, *args, **kwargs)
-\end{verbatim}
-
-See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail.
-
-\item {}
-\member{help}
-
-Prints a complete help message for all the options in the
-current option parser. The help message is constructed from
-the \code{usage} string passed to OptionParser's constructor and
-the \member{help} string passed to every option.
-
-If no \member{help} string is supplied for an option, it will still be
-listed in the help message. To omit an option entirely, use
-the special value \code{optparse.SUPPRESS{\_}HELP}.
-
-\module{optparse} automatically adds a \member{help} option to all OptionParsers, so
-you do not normally need to create one.
-
-Example:
-\begin{verbatim}
-from optparse import OptionParser, SUPPRESS_HELP
-
-parser = OptionParser()
-parser.add_option("-h", "--help", action="help"),
-parser.add_option("-v", action="store_true", dest="verbose",
- help="Be moderately verbose")
-parser.add_option("--file", dest="filename",
- help="Input file to read data from"),
-parser.add_option("--secret", help=SUPPRESS_HELP)
-\end{verbatim}
-
-If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it
-will print something like the following help message to stdout
-(assuming \code{sys.argv{[}0]} is \code{"foo.py"}):
-\begin{verbatim}
-usage: foo.py [options]
-
-options:
- -h, --help Show this help message and exit
- -v Be moderately verbose
- --file=FILENAME Input file to read data from
-\end{verbatim}
-
-After printing the help message, \module{optparse} terminates your process
-with \code{sys.exit(0)}.
-
-\item {}
-\code{version}
-
-Prints the version number supplied to the OptionParser to stdout and
-exits. The version number is actually formatted and printed by the
-\code{print{\_}version()} method of OptionParser. Generally only relevant
-if the \code{version} argument is supplied to the OptionParser
-constructor. As with \member{help} options, you will rarely create
-\code{version} options, since \module{optparse} automatically adds them when needed.
-
-\end{itemize}
-
-
-\subsubsection{Option attributes\label{optparse-option-attributes}}
-
-The following option attributes may be passed as keyword arguments
-to \code{parser.add{\_}option()}. If you pass an option attribute
-that is not relevant to a particular option, or fail to pass a required
-option attribute, \module{optparse} raises OptionError.
-\begin{itemize}
-\item {}
-\member{action} (default: \code{"store"})
-
-Determines \module{optparse}'s behaviour when this option is seen on the command
-line; the available options are documented above.
-
-\item {}
-\member{type} (default: \code{"string"})
-
-The argument type expected by this option (e.g., \code{"string"} or
-\code{"int"}); the available option types are documented below.
-
-\item {}
-\member{dest} (default: derived from option strings)
-
-If the option's action implies writing or modifying a value somewhere,
-this tells \module{optparse} where to write it: \member{dest} names an attribute of the
-\code{options} object that \module{optparse} builds as it parses the command line.
-
-\item {}
-\code{default} (deprecated)
-
-The value to use for this option's destination if the option is not
-seen on the command line. Deprecated; use \code{parser.set{\_}defaults()}
-instead.
-
-\item {}
-\code{nargs} (default: 1)
-
-How many arguments of type \member{type} should be consumed when this
-option is seen. If {\textgreater} 1, \module{optparse} will store a tuple of values to
-\member{dest}.
-
-\item {}
-\code{const}
-
-For actions that store a constant value, the constant value to store.
-
-\item {}
-\code{choices}
-
-For options of type \code{"choice"}, the list of strings the user
-may choose from.
-
-\item {}
-\code{callback}
-
-For options with action \code{"callback"}, the callable to call when this
-option is seen. See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments
-passed to \code{callable}.
-
-\item {}
-\code{callback{\_}args}, \code{callback{\_}kwargs}
-
-Additional positional and keyword arguments to pass to \code{callback}
-after the four standard callback arguments.
-
-\item {}
-\member{help}
-
-Help text to print for this option when listing all available options
-after the user supplies a \member{help} option (such as \code{"-{}-help"}).
-If no help text is supplied, the option will be listed without help
-text. To hide this option, use the special value \code{SUPPRESS{\_}HELP}.
-
-\item {}
-\code{metavar} (default: derived from option strings)
-
-Stand-in for the option argument(s) to use when printing help text.
-See section~\ref{optparse-tutorial}, the tutorial for an example.
-
-\end{itemize}
-
-
-\subsubsection{Standard option types\label{optparse-standard-option-types}}
-
-\module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long},
-\code{choice}, \code{float} and \code{complex}. If you need to add new option
-types, see section~\ref{optparse-extending-optparse}, Extending \module{optparse}.
-
-Arguments to string options are not checked or converted in any way: the
-text on the command line is stored in the destination (or passed to the
-callback) as-is.
-
-Integer arguments (type \code{int} or \code{long}) are parsed as follows:
-\begin{quote}
-\begin{itemize}
-\item {}
-if the number starts with \code{0x}, it is parsed as a hexadecimal number
-
-\item {}
-if the number starts with \code{0}, it is parsed as an octal number
-
-\item {}
-if the number starts with \code{0b}, is is parsed as a binary number
-
-\item {}
-otherwise, the number is parsed as a decimal number
-
-\end{itemize}
-\end{quote}
-
-The conversion is done by calling either \code{int()} or \code{long()} with
-the appropriate base (2, 8, 10, or 16). If this fails, so will \module{optparse},
-although with a more useful error message.
-
-\code{float} and \code{complex} option arguments are converted directly with
-\code{float()} and \code{complex()}, with similar error-handling.
-
-\code{choice} options are a subtype of \code{string} options. The \code{choices}
-option attribute (a sequence of strings) defines the set of allowed
-option arguments. \code{optparse.check{\_}choice()} compares
-user-supplied option arguments against this master list and raises
-OptionValueError if an invalid string is given.
-
-
-\subsubsection{Parsing arguments\label{optparse-parsing-arguments}}
-
-The whole point of creating and populating an OptionParser is to call
-its \method{parse{\_}args()} method:
-\begin{verbatim}
-(options, args) = parser.parse_args(args=None, values=None)
-\end{verbatim}
-
-where the input parameters are
-\begin{description}
-\item[\code{args}]
-the list of arguments to process (default: \code{sys.argv{[}1:]})
-\item[\code{values}]
-object to store option arguments in (default: a new instance of
-optparse.Values)
-\end{description}
-
-and the return values are
-\begin{description}
-\item[\code{options}]
-the same object that was passed in as \code{options}, or the
-optparse.Values instance created by \module{optparse}
-\item[\code{args}]
-the leftover positional arguments after all options have been
-processed
-\end{description}
-
-The most common usage is to supply neither keyword argument. If you
-supply \code{options}, it will be modified with repeated \code{setattr()}
-calls (roughly one for every option argument stored to an option
-destination) and returned by \method{parse{\_}args()}.
-
-If \method{parse{\_}args()} encounters any errors in the argument list, it calls
-the OptionParser's \method{error()} method with an appropriate end-user error
-message. This ultimately terminates your process with an exit status of
-2 (the traditional \UNIX{} exit status for command-line errors).
-
-
-\subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}}
-
-Sometimes, it's useful to poke around your option parser and see what's
-there. OptionParser provides a couple of methods to help you out:
-\begin{description}
-\item[\code{has{\_}option(opt{\_}str)}]
-Return true if the OptionParser has an option with
-option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}).
-\item[\code{get{\_}option(opt{\_}str)}]
-Returns the Option instance with the option string \code{opt{\_}str}, or
-\code{None} if no options have that option string.
-\item[\code{remove{\_}option(opt{\_}str)}]
-If the OptionParser has an option corresponding to \code{opt{\_}str},
-that option is removed. If that option provided any other
-option strings, all of those option strings become invalid.
-If \code{opt{\_}str} does not occur in any option belonging to this
-OptionParser, raises ValueError.
-\end{description}
-
-
-\subsubsection{Conflicts between options\label{optparse-conflicts-between-options}}
-
-If you're not careful, it's easy to define options with conflicting
-option strings:
-\begin{verbatim}
-parser.add_option("-n", "--dry-run", ...)
-[...]
-parser.add_option("-n", "--noisy", ...)
-\end{verbatim}
-
-(This is particularly true if you've defined your own OptionParser
-subclass with some standard options.)
-
-Every time you add an option, \module{optparse} checks for conflicts with existing
-options. If it finds any, it invokes the current conflict-handling
-mechanism. You can set the conflict-handling mechanism either in the
-constructor:
-\begin{verbatim}
-parser = OptionParser(..., conflict_handler=handler)
-\end{verbatim}
-
-or with a separate call:
-\begin{verbatim}
-parser.set_conflict_handler(handler)
-\end{verbatim}
-
-The available conflict handlers are:
-\begin{quote}
-\begin{description}
-\item[\code{error} (default)]
-assume option conflicts are a programming error and raise
-OptionConflictError
-\item[\code{resolve}]
-resolve option conflicts intelligently (see below)
-\end{description}
-\end{quote}
-
-As an example, let's define an OptionParser that resolves conflicts
-intelligently and add conflicting options to it:
-\begin{verbatim}
-parser = OptionParser(conflict_handler="resolve")
-parser.add_option("-n", "--dry-run", ..., help="do no harm")
-parser.add_option("-n", "--noisy", ..., help="be noisy")
-\end{verbatim}
-
-At this point, \module{optparse} detects that a previously-added option is already
-using the \code{"-n"} option string. Since \code{conflict{\_}handler} is
-\code{"resolve"}, it resolves the situation by removing \code{"-n"} from the
-earlier option's list of option strings. Now \code{"-{}-dry-run"} is the
-only way for the user to activate that option. If the user asks for
-help, the help message will reflect that:
-\begin{verbatim}
-options:
- --dry-run do no harm
- [...]
- -n, --noisy be noisy
-\end{verbatim}
-
-It's possible to whittle away the option strings for a previously-added
-option until there are none left, and the user has no way of invoking
-that option from the command-line. In that case, \module{optparse} removes that
-option completely, so it doesn't show up in help text or anywhere else.
-Carrying on with our existing OptionParser:
-\begin{verbatim}
-parser.add_option("--dry-run", ..., help="new dry-run option")
-\end{verbatim}
-
-At this point, the original \programopt{-n/-{}-dry-run} option is no longer
-accessible, so \module{optparse} removes it, leaving this help text:
-\begin{verbatim}
-options:
- [...]
- -n, --noisy be noisy
- --dry-run new dry-run option
-\end{verbatim}
-
-
-\subsubsection{Cleanup\label{optparse-cleanup}}
-
-OptionParser instances have several cyclic references. This should not
-be a problem for Python's garbage collector, but you may wish to break
-the cyclic references explicitly by calling \code{destroy()} on your
-OptionParser once you are done with it. This is particularly useful in
-long-running applications where large object graphs are reachable from
-your OptionParser.
-
-
-\subsubsection{Other methods\label{optparse-other-methods}}
-
-OptionParser supports several other public methods:
-\begin{itemize}
-\item {}
-\code{set{\_}usage(usage)}
-
-Set the usage string according to the rules described above for the
-\code{usage} constructor keyword argument. Passing \code{None} sets the
-default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage
-message.
-
-\item {}
-\code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()}
-
-Enable/disable positional arguments interspersed with options, similar
-to GNU getopt (enabled by default). For example, if \code{"-a"} and
-\code{"-b"} are both simple options that take no arguments, \module{optparse}
-normally accepts this syntax:
-\begin{verbatim}
-prog -a arg1 -b arg2
-\end{verbatim}
-
-and treats it as equivalent to
-\begin{verbatim}
-prog -a -b arg1 arg2
-\end{verbatim}
-
-To disable this feature, call \code{disable{\_}interspersed{\_}args()}. This
-restores traditional \UNIX{} syntax, where option parsing stops with the
-first non-option argument.
-
-\item {}
-\code{set{\_}defaults(dest=value, ...)}
-
-Set default values for several option destinations at once. Using
-\method{set{\_}defaults()} is the preferred way to set default values for
-options, since multiple options can share the same destination. For
-example, if several ``mode'' options all set the same destination, any
-one of them can set the default, and the last one wins:
-\begin{verbatim}
-parser.add_option("--advanced", action="store_const",
- dest="mode", const="advanced",
- default="novice") # overridden below
-parser.add_option("--novice", action="store_const",
- dest="mode", const="novice",
- default="advanced") # overrides above setting
-\end{verbatim}
-
-To avoid this confusion, use \method{set{\_}defaults()}:
-\begin{verbatim}
-parser.set_defaults(mode="advanced")
-parser.add_option("--advanced", action="store_const",
- dest="mode", const="advanced")
-parser.add_option("--novice", action="store_const",
- dest="mode", const="novice")
-\end{verbatim}
-
-\end{itemize}
-% $Id: reference.txt 519 2006-06-11 14:39:11Z gward $
-
-
-\subsection{Option Callbacks\label{optparse-option-callbacks}}
-
-When \module{optparse}'s built-in actions and types aren't quite enough for your
-needs, you have two choices: extend \module{optparse} or define a callback option.
-Extending \module{optparse} is more general, but overkill for a lot of simple
-cases. Quite often a simple callback is all you need.
-
-There are two steps to defining a callback option:
-\begin{itemize}
-\item {}
-define the option itself using the \code{callback} action
-
-\item {}
-write the callback; this is a function (or method) that
-takes at least four arguments, as described below
-
-\end{itemize}
-
-
-\subsubsection{Defining a callback option\label{optparse-defining-callback-option}}
-
-As always, the easiest way to define a callback option is by using the
-\code{parser.add{\_}option()} method. Apart from \member{action}, the only option
-attribute you must specify is \code{callback}, the function to call:
-\begin{verbatim}
-parser.add_option("-c", action="callback", callback=my_callback)
-\end{verbatim}
-
-\code{callback} is a function (or other callable object), so you must have
-already defined \code{my{\_}callback()} when you create this callback option.
-In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any
-arguments, which usually means that the option takes no arguments{---}the
-mere presence of \programopt{-c} on the command-line is all it needs to know. In
-some circumstances, though, you might want your callback to consume an
-arbitrary number of command-line arguments. This is where writing
-callbacks gets tricky; it's covered later in this section.
-
-\module{optparse} always passes four particular arguments to your callback, and it
-will only pass additional arguments if you specify them via
-\code{callback{\_}args} and \code{callback{\_}kwargs}. Thus, the minimal callback
-function signature is:
-\begin{verbatim}
-def my_callback(option, opt, value, parser):
-\end{verbatim}
-
-The four arguments to a callback are described below.
-
-There are several other option attributes that you can supply when you
-define a callback option:
-\begin{description}
-\item[\member{type}]
-has its usual meaning: as with the \code{store} or \code{append} actions,
-it instructs \module{optparse} to consume one argument and convert it to
-\member{type}. Rather than storing the converted value(s) anywhere,
-though, \module{optparse} passes it to your callback function.
-\item[\code{nargs}]
-also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will
-consume \code{nargs} arguments, each of which must be convertible to
-\member{type}. It then passes a tuple of converted values to your
-callback.
-\item[\code{callback{\_}args}]
-a tuple of extra positional arguments to pass to the callback
-\item[\code{callback{\_}kwargs}]
-a dictionary of extra keyword arguments to pass to the callback
-\end{description}
-
-
-\subsubsection{How callbacks are called\label{optparse-how-callbacks-called}}
-
-All callbacks are called as follows:
-\begin{verbatim}
-func(option, opt_str, value, parser, *args, **kwargs)
-\end{verbatim}
-
-where
-\begin{description}
-\item[\code{option}]
-is the Option instance that's calling the callback
-\item[\code{opt{\_}str}]
-is the option string seen on the command-line that's triggering the
-callback. (If an abbreviated long option was used, \code{opt{\_}str} will
-be the full, canonical option string{---}e.g. if the user puts
-\code{"-{}-foo"} on the command-line as an abbreviation for
-\code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.)
-\item[\code{value}]
-is the argument to this option seen on the command-line. \module{optparse} will
-only expect an argument if \member{type} is set; the type of \code{value}
-will be the type implied by the option's type. If \member{type} for this
-option is \code{None} (no argument expected), then \code{value} will be
-\code{None}. If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of
-the appropriate type.
-\item[\code{parser}]
-is the OptionParser instance driving the whole thing, mainly
-useful because you can access some other interesting data through
-its instance attributes:
-\begin{description}
-\item[\code{parser.largs}]
-the current list of leftover arguments, ie. arguments that have
-been consumed but are neither options nor option arguments.
-Feel free to modify \code{parser.largs}, e.g. by adding more
-arguments to it. (This list will become \code{args}, the second
-return value of \method{parse{\_}args()}.)
-\item[\code{parser.rargs}]
-the current list of remaining arguments, ie. with \code{opt{\_}str} and
-\code{value} (if applicable) removed, and only the arguments
-following them still there. Feel free to modify
-\code{parser.rargs}, e.g. by consuming more arguments.
-\item[\code{parser.values}]
-the object where option values are by default stored (an
-instance of optparse.OptionValues). This lets callbacks use the
-same mechanism as the rest of \module{optparse} for storing option values;
-you don't need to mess around with globals or closures. You can
-also access or modify the value(s) of any options already
-encountered on the command-line.
-\end{description}
-\item[\code{args}]
-is a tuple of arbitrary positional arguments supplied via the
-\code{callback{\_}args} option attribute.
-\item[\code{kwargs}]
-is a dictionary of arbitrary keyword arguments supplied via
-\code{callback{\_}kwargs}.
-\end{description}
-
-
-\subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}}
-
-The callback function should raise OptionValueError if there are any
-problems with the option or its argument(s). \module{optparse} catches this and
-terminates the program, printing the error message you supply to
-stderr. Your message should be clear, concise, accurate, and mention
-the option at fault. Otherwise, the user will have a hard time
-figuring out what he did wrong.
-
-
-\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}}
-
-Here's an example of a callback option that takes no arguments, and
-simply records that the option was seen:
-\begin{verbatim}
-def record_foo_seen(option, opt_str, value, parser):
- parser.saw_foo = True
-
-parser.add_option("--foo", action="callback", callback=record_foo_seen)
-\end{verbatim}
-
-Of course, you could do that with the \code{store{\_}true} action.
-
-
-\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}}
-
-Here's a slightly more interesting example: record the fact that
-\code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the
-command-line.
-\begin{verbatim}
-def check_order(option, opt_str, value, parser):
- if parser.values.b:
- raise OptionValueError("can't use -a after -b")
- parser.values.a = 1
-[...]
-parser.add_option("-a", action="callback", callback=check_order)
-parser.add_option("-b", action="store_true", dest="b")
-\end{verbatim}
-
-
-\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}}
-
-If you want to re-use this callback for several similar options (set a
-flag, but blow up if \code{"-b"} has already been seen), it needs a bit of
-work: the error message and the flag that it sets must be
-generalized.
-\begin{verbatim}
-def check_order(option, opt_str, value, parser):
- if parser.values.b:
- raise OptionValueError("can't use %s after -b" % opt_str)
- setattr(parser.values, option.dest, 1)
-[...]
-parser.add_option("-a", action="callback", callback=check_order, dest='a')
-parser.add_option("-b", action="store_true", dest="b")
-parser.add_option("-c", action="callback", callback=check_order, dest='c')
-\end{verbatim}
-
-
-\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}}
-
-Of course, you could put any condition in there{---}you're not limited
-to checking the values of already-defined options. For example, if
-you have options that should not be called when the moon is full, all
-you have to do is this:
-\begin{verbatim}
-def check_moon(option, opt_str, value, parser):
- if is_moon_full():
- raise OptionValueError("%s option invalid when moon is full"
- % opt_str)
- setattr(parser.values, option.dest, 1)
-[...]
-parser.add_option("--foo",
- action="callback", callback=check_moon, dest="foo")
-\end{verbatim}
-
-(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the
-reader.)
-
-
-\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}}
-
-Things get slightly more interesting when you define callback options
-that take a fixed number of arguments. Specifying that a callback
-option takes arguments is similar to defining a \code{store} or \code{append}
-option: if you define \member{type}, then the option takes one argument that
-must be convertible to that type; if you further define \code{nargs}, then
-the option takes \code{nargs} arguments.
-
-Here's an example that just emulates the standard \code{store} action:
-\begin{verbatim}
-def store_value(option, opt_str, value, parser):
- setattr(parser.values, option.dest, value)
-[...]
-parser.add_option("--foo",
- action="callback", callback=store_value,
- type="int", nargs=3, dest="foo")
-\end{verbatim}
-
-Note that \module{optparse} takes care of consuming 3 arguments and converting them
-to integers for you; all you have to do is store them. (Or whatever;
-obviously you don't need a callback for this example.)
-
-
-\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}}
-
-Things get hairy when you want an option to take a variable number of
-arguments. For this case, you must write a callback, as \module{optparse} doesn't
-provide any built-in capabilities for it. And you have to deal with
-certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse}
-normally handles for you. In particular, callbacks should implement
-the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments:
-\begin{itemize}
-\item {}
-either \code{"-{}-"} or \code{"-"} can be option arguments
-
-\item {}
-bare \code{"-{}-"} (if not the argument to some option): halt command-line
-processing and discard the \code{"-{}-"}
-
-\item {}
-bare \code{"-"} (if not the argument to some option): halt command-line
-processing but keep the \code{"-"} (append it to \code{parser.largs})
-
-\end{itemize}
-
-If you want an option that takes a variable number of arguments, there
-are several subtle, tricky issues to worry about. The exact
-implementation you choose will be based on which trade-offs you're
-willing to make for your application (which is why \module{optparse} doesn't support
-this sort of thing directly).
-
-Nevertheless, here's a stab at a callback for an option with variable
-arguments:
-\begin{verbatim}
-def vararg_callback(option, opt_str, value, parser):
- assert value is None
- done = 0
- value = []
- rargs = parser.rargs
- while rargs:
- arg = rargs[0]
-
- # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
- # etc. Note that this also stops on "-3" or "-3.0", so if
- # your option takes numeric values, you will need to handle
- # this.
- if ((arg[:2] == "--" and len(arg) > 2) or
- (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
- break
- else:
- value.append(arg)
- del rargs[0]
-
- setattr(parser.values, option.dest, value)
-
-[...]
-parser.add_option("-c", "--callback",
- action="callback", callback=varargs)
-\end{verbatim}
-
-The main weakness with this particular implementation is that negative
-numbers in the arguments following \code{"-c"} will be interpreted as
-further options (probably causing an error), rather than as arguments to
-\code{"-c"}. Fixing this is left as an exercise for the reader.
-% $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
-
-
-\subsection{Extending \module{optparse}\label{optparse-extending-optparse}}
-
-Since the two major controlling factors in how \module{optparse} interprets
-command-line options are the action and type of each option, the most
-likely direction of extension is to add new actions and new types.
-
-
-\subsubsection{Adding new types\label{optparse-adding-new-types}}
-
-To add new types, you need to define your own subclass of \module{optparse}'s Option
-class. This class has a couple of attributes that define \module{optparse}'s types:
-\member{TYPES} and \member{TYPE{\_}CHECKER}.
-
-\member{TYPES} is a tuple of type names; in your subclass, simply define a new
-tuple \member{TYPES} that builds on the standard one.
-
-\member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking
-functions. A type-checking function has the following signature:
-\begin{verbatim}
-def check_mytype(option, opt, value)
-\end{verbatim}
-
-where \code{option} is an \class{Option} instance, \code{opt} is an option string
-(e.g., \code{"-f"}), and \code{value} is the string from the command line that
-must be checked and converted to your desired type. \code{check{\_}mytype()}
-should return an object of the hypothetical type \code{mytype}. The value
-returned by a type-checking function will wind up in the OptionValues
-instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a
-callback as the \code{value} parameter.
-
-Your type-checking function should raise OptionValueError if it
-encounters any problems. OptionValueError takes a single string
-argument, which is passed as-is to OptionParser's \method{error()} method,
-which in turn prepends the program name and the string \code{"error:"} and
-prints everything to stderr before terminating the process.
-
-Here's a silly example that demonstrates adding a \code{complex} option
-type to parse Python-style complex numbers on the command line. (This
-is even sillier than it used to be, because \module{optparse} 1.3 added built-in
-support for complex numbers, but never mind.)
-
-First, the necessary imports:
-\begin{verbatim}
-from copy import copy
-from optparse import Option, OptionValueError
-\end{verbatim}
-
-You need to define your type-checker first, since it's referred to later
-(in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass):
-\begin{verbatim}
-def check_complex(option, opt, value):
- try:
- return complex(value)
- except ValueError:
- raise OptionValueError(
- "option %s: invalid complex value: %r" % (opt, value))
-\end{verbatim}
-
-Finally, the Option subclass:
-\begin{verbatim}
-class MyOption (Option):
- TYPES = Option.TYPES + ("complex",)
- TYPE_CHECKER = copy(Option.TYPE_CHECKER)
- TYPE_CHECKER["complex"] = check_complex
-\end{verbatim}
-
-(If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end
-up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class.
-This being Python, nothing stops you from doing that except good manners
-and common sense.)
-
-That's it! Now you can write a script that uses the new option type
-just like any other \module{optparse}-based script, except you have to instruct your
-OptionParser to use MyOption instead of Option:
-\begin{verbatim}
-parser = OptionParser(option_class=MyOption)
-parser.add_option("-c", type="complex")
-\end{verbatim}
-
-Alternately, you can build your own option list and pass it to
-OptionParser; if you don't use \method{add{\_}option()} in the above way, you
-don't need to tell OptionParser which option class to use:
-\begin{verbatim}
-option_list = [MyOption("-c", action="store", type="complex", dest="c")]
-parser = OptionParser(option_list=option_list)
-\end{verbatim}
-
-
-\subsubsection{Adding new actions\label{optparse-adding-new-actions}}
-
-Adding new actions is a bit trickier, because you have to understand
-that \module{optparse} has a couple of classifications for actions:
-\begin{description}
-\item[``store'' actions]
-actions that result in \module{optparse} storing a value to an attribute of the
-current OptionValues instance; these options require a \member{dest}
-attribute to be supplied to the Option constructor
-\item[``typed'' actions]
-actions that take a value from the command line and expect it to be
-of a certain type; or rather, a string that can be converted to a
-certain type. These options require a \member{type} attribute to the
-Option constructor.
-\end{description}
-
-These are overlapping sets: some default ``store'' actions are \code{store},
-\code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed''
-actions are \code{store}, \code{append}, and \code{callback}.
-
-When you add an action, you need to categorize it by listing it in at
-least one of the following class attributes of Option (all are lists of
-strings):
-\begin{description}
-\item[\member{ACTIONS}]
-all actions must be listed in ACTIONS
-\item[\member{STORE{\_}ACTIONS}]
-``store'' actions are additionally listed here
-\item[\member{TYPED{\_}ACTIONS}]
-``typed'' actions are additionally listed here
-\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}]
-actions that always take a type (i.e. whose options always take a
-value) are additionally listed here. The only effect of this is
-that \module{optparse} assigns the default type, \code{string}, to options with no
-explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}.
-\end{description}
-
-In order to actually implement your new action, you must override
-Option's \method{take{\_}action()} method and add a case that recognizes your
-action.
-
-For example, let's add an \code{extend} action. This is similar to the
-standard \code{append} action, but instead of taking a single value from
-the command-line and appending it to an existing list, \code{extend} will
-take multiple values in a single comma-delimited string, and extend an
-existing list with them. That is, if \code{"-{}-names"} is an \code{extend}
-option of type \code{string}, the command line
-\begin{verbatim}
---names=foo,bar --names blah --names ding,dong
-\end{verbatim}
-
-would result in a list
-\begin{verbatim}
-["foo", "bar", "blah", "ding", "dong"]
-\end{verbatim}
-
-Again we define a subclass of Option:
-\begin{verbatim}
-class MyOption (Option):
-
- ACTIONS = Option.ACTIONS + ("extend",)
- STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
- TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
- ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
-
- def take_action(self, action, dest, opt, value, values, parser):
- if action == "extend":
- lvalue = value.split(",")
- values.ensure_value(dest, []).extend(lvalue)
- else:
- Option.take_action(
- self, action, dest, opt, value, values, parser)
-\end{verbatim}
-
-Features of note:
-\begin{itemize}
-\item {}
-\code{extend} both expects a value on the command-line and stores that
-value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and
-\member{TYPED{\_}ACTIONS}
-
-\item {}
-to ensure that \module{optparse} assigns the default type of \code{string} to
-\code{extend} actions, we put the \code{extend} action in
-\code{ALWAYS{\_}TYPED{\_}ACTIONS} as well
-
-\item {}
-\method{MyOption.take{\_}action()} implements just this one new action, and
-passes control back to \method{Option.take{\_}action()} for the standard
-\module{optparse} actions
-
-\item {}
-\code{values} is an instance of the optparse{\_}parser.Values class,
-which provides the very useful \method{ensure{\_}value()} method.
-\method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve;
-it is called as
-\begin{verbatim}
-values.ensure_value(attr, value)
-\end{verbatim}
-
-If the \code{attr} attribute of \code{values} doesn't exist or is None, then
-ensure{\_}value() first sets it to \code{value}, and then returns 'value.
-This is very handy for actions like \code{extend}, \code{append}, and
-\code{count}, all of which accumulate data in a variable and expect that
-variable to be of a certain type (a list for the first two, an integer
-for the latter). Using \method{ensure{\_}value()} means that scripts using
-your action don't have to worry about setting a default value for the
-option destinations in question; they can just leave the default as
-None and \method{ensure{\_}value()} will take care of getting it right when
-it's needed.
-
-\end{itemize}
-% $Id: extending.txt 517 2006-06-10 16:18:11Z gward $
-
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
deleted file mode 100644
index 826e9fa..0000000
--- a/Doc/lib/libos.tex
+++ /dev/null
@@ -1,1980 +0,0 @@
-\section{\module{os} ---
- Miscellaneous operating system interfaces}
-
-\declaremodule{standard}{os}
-\modulesynopsis{Miscellaneous operating system interfaces.}
-
-
-This module provides a more portable way of using operating system
-dependent functionality than importing a operating system dependent
-built-in module like \refmodule{posix} or \module{nt}.
-
-This module searches for an operating system dependent built-in module like
-\module{mac} or \refmodule{posix} and exports the same functions and data
-as found there. The design of all Python's built-in operating system dependent
-modules is such that as long as the same functionality is available,
-it uses the same interface; for example, the function
-\code{os.stat(\var{path})} returns stat information about \var{path} in
-the same format (which happens to have originated with the
-\POSIX{} interface).
-
-Extensions peculiar to a particular operating system are also
-available through the \module{os} module, but using them is of course a
-threat to portability!
-
-Note that after the first time \module{os} is imported, there is
-\emph{no} performance penalty in using functions from \module{os}
-instead of directly from the operating system dependent built-in module,
-so there should be \emph{no} reason not to use \module{os}!
-
-
-% Frank Stajano <fstajano@uk.research.att.com> complained that it
-% wasn't clear that the entries described in the subsections were all
-% available at the module level (most uses of subsections are
-% different); I think this is only a problem for the HTML version,
-% where the relationship may not be as clear.
-%
-\ifhtml
-The \module{os} module contains many functions and data values.
-The items below and in the following sub-sections are all available
-directly from the \module{os} module.
-\fi
-
-
-\begin{excdesc}{error}
-This exception is raised when a function returns a system-related
-error (not for illegal argument types or other incidental errors).
-This is also known as the built-in exception \exception{OSError}. The
-accompanying value is a pair containing the numeric error code from
-\cdata{errno} and the corresponding string, as would be printed by the
-C function \cfunction{perror()}. See the module
-\refmodule{errno}\refbimodindex{errno}, which contains names for the
-error codes defined by the underlying operating system.
-
-When exceptions are classes, this exception carries two attributes,
-\member{errno} and \member{strerror}. The first holds the value of
-the C \cdata{errno} variable, and the latter holds the corresponding
-error message from \cfunction{strerror()}. For exceptions that
-involve a file system path (such as \function{chdir()} or
-\function{unlink()}), the exception instance will contain a third
-attribute, \member{filename}, which is the file name passed to the
-function.
-\end{excdesc}
-
-\begin{datadesc}{name}
-The name of the operating system dependent module imported. The
-following names have currently been registered: \code{'posix'},
-\code{'nt'}, \code{'mac'}, \code{'os2'}, \code{'ce'},
-\code{'java'}, \code{'riscos'}.
-\end{datadesc}
-
-\begin{datadesc}{path}
-The corresponding operating system dependent standard module for pathname
-operations, such as \module{posixpath} or \module{macpath}. Thus,
-given the proper imports, \code{os.path.split(\var{file})} is
-equivalent to but more portable than
-\code{posixpath.split(\var{file})}. Note that this is also an
-importable module: it may be imported directly as
-\refmodule{os.path}.
-\end{datadesc}
-
-
-
-\subsection{Process Parameters \label{os-procinfo}}
-
-These functions and data items provide information and operate on the
-current process and user.
-
-\begin{datadesc}{environ}
-A mapping object representing the string environment. For example,
-\code{environ['HOME']} is the pathname of your home directory (on some
-platforms), and is equivalent to \code{getenv("HOME")} in C.
-
-This mapping is captured the first time the \module{os} module is
-imported, typically during Python startup as part of processing
-\file{site.py}. Changes to the environment made after this time are
-not reflected in \code{os.environ}, except for changes made by modifying
-\code{os.environ} directly.
-
-If the platform supports the \function{putenv()} function, this
-mapping may be used to modify the environment as well as query the
-environment. \function{putenv()} will be called automatically when
-the mapping is modified.
-\note{Calling \function{putenv()} directly does not change
-\code{os.environ}, so it's better to modify \code{os.environ}.}
-\note{On some platforms, including FreeBSD and Mac OS X, setting
-\code{environ} may cause memory leaks. Refer to the system documentation
-for \cfunction{putenv()}.}
-
-If \function{putenv()} is not provided, a modified copy of this mapping
-may be passed to the appropriate process-creation functions to cause
-child processes to use a modified environment.
-
-If the platform supports the \function{unsetenv()} function, you can
-delete items in this mapping to unset environment variables.
-\function{unsetenv()} will be called automatically when an item is
-deleted from \code{os.environ}.
-
-\end{datadesc}
-
-\begin{funcdescni}{chdir}{path}
-\funclineni{fchdir}{fd}
-\funclineni{getcwd}{}
-These functions are described in ``Files and Directories'' (section
-\ref{os-file-dir}).
-\end{funcdescni}
-
-\begin{funcdesc}{ctermid}{}
-Return the filename corresponding to the controlling terminal of the
-process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getegid}{}
-Return the effective group id of the current process. This
-corresponds to the `set id' bit on the file being executed in the
-current process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{geteuid}{}
-\index{user!effective id}
-Return the current process' effective user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getgid}{}
-\index{process!group}
-Return the real group id of the current process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getgroups}{}
-Return list of supplemental group ids associated with the current
-process.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getlogin}{}
-Return the name of the user logged in on the controlling terminal of
-the process. For most purposes, it is more useful to use the
-environment variable \envvar{LOGNAME} to find out who the user is,
-or \code{pwd.getpwuid(os.getuid())[0]} to get the login name
-of the currently effective user ID.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getpgid}{pid}
-Return the process group id of the process with process id \var{pid}.
-If \var{pid} is 0, the process group id of the current process is
-returned. Availability: \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getpgrp}{}
-\index{process!group}
-Return the id of the current process group.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getpid}{}
-\index{process!id}
-Return the current process id.
-Availability: \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{getppid}{}
-\index{process!id of parent}
-Return the parent's process id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getuid}{}
-\index{user!id}
-Return the current process' user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getenv}{varname\optional{, value}}
-Return the value of the environment variable \var{varname} if it
-exists, or \var{value} if it doesn't. \var{value} defaults to
-\code{None}.
-Availability: most flavors of \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{putenv}{varname, value}
-\index{environment variables!setting}
-Set the environment variable named \var{varname} to the string
-\var{value}. Such changes to the environment affect subprocesses
-started with \function{os.system()}, \function{popen()} or
-\function{fork()} and \function{execv()}.
-Availability: most flavors of \UNIX, Windows.
-
-\note{On some platforms, including FreeBSD and Mac OS X,
-setting \code{environ} may cause memory leaks.
-Refer to the system documentation for putenv.}
-
-When \function{putenv()} is
-supported, assignments to items in \code{os.environ} are automatically
-translated into corresponding calls to \function{putenv()}; however,
-calls to \function{putenv()} don't update \code{os.environ}, so it is
-actually preferable to assign to items of \code{os.environ}.
-\end{funcdesc}
-
-\begin{funcdesc}{setegid}{egid}
-Set the current process's effective group id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{seteuid}{euid}
-Set the current process's effective user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setgid}{gid}
-Set the current process' group id.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setgroups}{groups}
-Set the list of supplemental group ids associated with the current
-process to \var{groups}. \var{groups} must be a sequence, and each
-element must be an integer identifying a group. This operation is
-typical available only to the superuser.
-Availability: \UNIX.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{setpgrp}{}
-Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
-0)} depending on which version is implemented (if any). See the
-\UNIX{} manual for the semantics.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setpgid}{pid, pgrp} Calls the system call
-\cfunction{setpgid()} to set the process group id of the process with
-id \var{pid} to the process group with id \var{pgrp}. See the \UNIX{}
-manual for the semantics.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setreuid}{ruid, euid}
-Set the current process's real and effective user ids.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setregid}{rgid, egid}
-Set the current process's real and effective group ids.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getsid}{pid}
-Calls the system call \cfunction{getsid()}. See the \UNIX{} manual
-for the semantics.
-Availability: \UNIX. \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{setsid}{}
-Calls the system call \cfunction{setsid()}. See the \UNIX{} manual
-for the semantics.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{setuid}{uid}
-\index{user!id, setting}
-Set the current process' user id.
-Availability: \UNIX.
-\end{funcdesc}
-
-% placed in this section since it relates to errno.... a little weak
-\begin{funcdesc}{strerror}{code}
-Return the error message corresponding to the error code in
-\var{code}.
-Availability: \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{umask}{mask}
-Set the current numeric umask and returns the previous umask.
-Availability: \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{uname}{}
-Return a 5-tuple containing information identifying the current
-operating system. The tuple contains 5 strings:
-\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
-\var{machine})}. Some systems truncate the nodename to 8
-characters or to the leading component; a better way to get the
-hostname is \function{socket.gethostname()}
-\withsubitem{(in module socket)}{\ttindex{gethostname()}}
-or even
-\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}
-\code{socket.gethostbyaddr(socket.gethostname())}.
-Availability: recent flavors of \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{unsetenv}{varname}
-\index{environment variables!deleting}
-Unset (delete) the environment variable named \var{varname}. Such
-changes to the environment affect subprocesses started with
-\function{os.system()}, \function{popen()} or \function{fork()} and
-\function{execv()}. Availability: most flavors of \UNIX, Windows.
-
-When \function{unsetenv()} is
-supported, deletion of items in \code{os.environ} is automatically
-translated into a corresponding call to \function{unsetenv()}; however,
-calls to \function{unsetenv()} don't update \code{os.environ}, so it is
-actually preferable to delete items of \code{os.environ}.
-\end{funcdesc}
-
-\subsection{File Object Creation \label{os-newstreams}}
-
-These functions create new file objects.
-
-
-\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
-Return an open file object connected to the file descriptor \var{fd}.
-\index{I/O control!buffering}
-The \var{mode} and \var{bufsize} arguments have the same meaning as
-the corresponding arguments to the built-in \function{open()}
-function.
-Availability: Macintosh, \UNIX, Windows.
-
-\versionchanged[When specified, the \var{mode} argument must now start
- with one of the letters \character{r}, \character{w}, or \character{a},
- otherwise a \exception{ValueError} is raised]{2.3}
-\versionchanged[On \UNIX, when the \var{mode} argument starts with
- \character{a}, the \var{O_APPEND} flag is set on the file descriptor
- (which the \cfunction{fdopen()} implementation already does on most
- platforms)]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
-Open a pipe to or from \var{command}. The return value is an open
-file object connected to the pipe, which can be read or written
-depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
-The \var{bufsize} argument has the same meaning as the corresponding
-argument to the built-in \function{open()} function. The exit status of
-the command (encoded in the format specified for \function{wait()}) is
-available as the return value of the \method{close()} method of the file
-object, except that when the exit status is zero (termination without
-errors), \code{None} is returned.
-Availability: Macintosh, \UNIX, Windows.
-
-\deprecated{2.6}{This function is obsolete. Use the
- \module{subprocess} module.}
-
-\versionchanged[This function worked unreliably under Windows in
- earlier versions of Python. This was due to the use of the
- \cfunction{_popen()} function from the libraries provided with
- Windows. Newer versions of Python do not use the broken
- implementation from the Windows libraries]{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{tmpfile}{}
-Return a new file object opened in update mode (\samp{w+b}). The file
-has no directory entries associated with it and will be automatically
-deleted once there are no file descriptors for the file.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-
-\subsection{File Descriptor Operations \label{os-fd-ops}}
-
-These functions operate on I/O streams referenced using file
-descriptors.
-
-File descriptors are small integers corresponding to a file that has
-been opened by the current process. For example, standard input is
-usually file descriptor 0, standard output is 1, and standard error is
-2. Further files opened by a process will then be assigned 3, 4, 5,
-and so forth. The name ``file descriptor'' is slightly deceptive; on
-{\UNIX} platforms, sockets and pipes are also referenced by file descriptors.
-
-
-\begin{funcdesc}{close}{fd}
-Close file descriptor \var{fd}.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-This function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}. To close a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, use its \method{close()} method.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{dup}{fd}
-Return a duplicate of file descriptor \var{fd}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{dup2}{fd, fd2}
-Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
-first if necessary.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{fdatasync}{fd}
-Force write of file with filedescriptor \var{fd} to disk.
-Does not force update of metadata.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{fpathconf}{fd, name}
-Return system configuration information relevant to an open file.
-\var{name} specifies the configuration value to retrieve; it may be a
-string which is the name of a defined system value; these names are
-specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and
-others). Some platforms define additional names as well. The names
-known to the host operating system are given in the
-\code{pathconf_names} dictionary. For configuration variables not
-included in that mapping, passing an integer for \var{name} is also
-accepted.
-Availability: Macintosh, \UNIX.
-
-If \var{name} is a string and is not known, \exception{ValueError} is
-raised. If a specific value for \var{name} is not supported by the
-host system, even if it is included in \code{pathconf_names}, an
-\exception{OSError} is raised with \constant{errno.EINVAL} for the
-error number.
-\end{funcdesc}
-
-\begin{funcdesc}{fstat}{fd}
-Return status for file descriptor \var{fd}, like \function{stat()}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{fstatvfs}{fd}
-Return information about the filesystem containing the file associated
-with file descriptor \var{fd}, like \function{statvfs()}.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{fsync}{fd}
-Force write of file with filedescriptor \var{fd} to disk. On \UNIX,
-this calls the native \cfunction{fsync()} function; on Windows, the
-MS \cfunction{_commit()} function.
-
-If you're starting with a Python file object \var{f}, first do
-\code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())},
-to ensure that all internal buffers associated with \var{f} are written
-to disk.
-Availability: Macintosh, \UNIX, and Windows starting in 2.2.3.
-\end{funcdesc}
-
-\begin{funcdesc}{ftruncate}{fd, length}
-Truncate the file corresponding to file descriptor \var{fd},
-so that it is at most \var{length} bytes in size.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{isatty}{fd}
-Return \code{True} if the file descriptor \var{fd} is open and
-connected to a tty(-like) device, else \code{False}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{lseek}{fd, pos, how}
-Set the current position of file descriptor \var{fd} to position
-\var{pos}, modified by \var{how}: \code{0} to set the position
-relative to the beginning of the file; \code{1} to set it relative to
-the current position; \code{2} to set it relative to the end of the
-file.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{open}{file, flags\optional{, mode}}
-Open the file \var{file} and set various flags according to
-\var{flags} and possibly its mode according to \var{mode}.
-The default \var{mode} is \code{0777} (octal), and the current umask
-value is first masked out. Return the file descriptor for the newly
-opened file.
-Availability: Macintosh, \UNIX, Windows.
-
-For a description of the flag and mode values, see the C run-time
-documentation; flag constants (like \constant{O_RDONLY} and
-\constant{O_WRONLY}) are defined in this module too (see below).
-
-\begin{notice}
-This function is intended for low-level I/O. For normal usage,
-use the built-in function \function{open()}, which returns a ``file
-object'' with \method{read()} and \method{write()} methods (and many
-more). To wrap a file descriptor in a ``file object'', use
-\function{fdopen()}.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{openpty}{}
-Open a new pseudo-terminal pair. Return a pair of file descriptors
-\code{(\var{master}, \var{slave})} for the pty and the tty,
-respectively. For a (slightly) more portable approach, use the
-\refmodule{pty}\refstmodindex{pty} module.
-Availability: Macintosh, Some flavors of \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{pipe}{}
-Create a pipe. Return a pair of file descriptors \code{(\var{r},
-\var{w})} usable for reading and writing, respectively.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{read}{fd, n}
-Read at most \var{n} bytes from file descriptor \var{fd}.
-Return a string containing the bytes read. If the end of the file
-referred to by \var{fd} has been reached, an empty string is
-returned.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-This function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}. To read a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, or \code{sys.stdin}, use its
-\method{read()} or \method{readline()} methods.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{tcgetpgrp}{fd}
-Return the process group associated with the terminal given by
-\var{fd} (an open file descriptor as returned by \function{open()}).
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{tcsetpgrp}{fd, pg}
-Set the process group associated with the terminal given by
-\var{fd} (an open file descriptor as returned by \function{open()})
-to \var{pg}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{ttyname}{fd}
-Return a string which specifies the terminal device associated with
-file-descriptor \var{fd}. If \var{fd} is not associated with a terminal
-device, an exception is raised.
-Availability:Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{write}{fd, str}
-Write the string \var{str} to file descriptor \var{fd}.
-Return the number of bytes actually written.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-This function is intended for low-level I/O and must be applied
-to a file descriptor as returned by \function{open()} or
-\function{pipe()}. To write a ``file object'' returned by the
-built-in function \function{open()} or by \function{popen()} or
-\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
-its \method{write()} method.
-\end{notice}
-\end{funcdesc}
-
-
-The following data items are available for use in constructing the
-\var{flags} parameter to the \function{open()} function. Some items will
-not be available on all platforms. For descriptions of their availability
-and use, consult \manpage{open}{2}.
-
-\begin{datadesc}{O_RDONLY}
-\dataline{O_WRONLY}
-\dataline{O_RDWR}
-\dataline{O_APPEND}
-\dataline{O_CREAT}
-\dataline{O_EXCL}
-\dataline{O_TRUNC}
-Options for the \var{flag} argument to the \function{open()} function.
-These can be bit-wise OR'd together.
-Availability: Macintosh, \UNIX, Windows.
-\end{datadesc}
-
-\begin{datadesc}{O_DSYNC}
-\dataline{O_RSYNC}
-\dataline{O_SYNC}
-\dataline{O_NDELAY}
-\dataline{O_NONBLOCK}
-\dataline{O_NOCTTY}
-\dataline{O_SHLOCK}
-\dataline{O_EXLOCK}
-More options for the \var{flag} argument to the \function{open()} function.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{datadesc}{O_BINARY}
-Option for the \var{flag} argument to the \function{open()} function.
-This can be bit-wise OR'd together with those listed above.
-Availability: Windows.
-% XXX need to check on the availability of this one.
-\end{datadesc}
-
-\begin{datadesc}{O_NOINHERIT}
-\dataline{O_SHORT_LIVED}
-\dataline{O_TEMPORARY}
-\dataline{O_RANDOM}
-\dataline{O_SEQUENTIAL}
-\dataline{O_TEXT}
-Options for the \var{flag} argument to the \function{open()} function.
-These can be bit-wise OR'd together.
-Availability: Windows.
-\end{datadesc}
-
-\begin{datadesc}{SEEK_SET}
-\dataline{SEEK_CUR}
-\dataline{SEEK_END}
-Parameters to the \function{lseek()} function.
-Their values are 0, 1, and 2, respectively.
-Availability: Windows, Macintosh, \UNIX.
-\versionadded{2.5}
-\end{datadesc}
-
-\subsection{Files and Directories \label{os-file-dir}}
-
-\begin{funcdesc}{access}{path, mode}
-Use the real uid/gid to test for access to \var{path}. Note that most
-operations will use the effective uid/gid, therefore this routine can
-be used in a suid/sgid environment to test if the invoking user has the
-specified access to \var{path}. \var{mode} should be \constant{F_OK}
-to test the existence of \var{path}, or it can be the inclusive OR of
-one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to
-test permissions. Return \constant{True} if access is allowed,
-\constant{False} if not.
-See the \UNIX{} man page \manpage{access}{2} for more information.
-Availability: Macintosh, \UNIX, Windows.
-
-\note{Using \function{access()} to check if a user is authorized to e.g.
-open a file before actually doing so using \function{open()} creates a
-security hole, because the user might exploit the short time interval
-between checking and opening the file to manipulate it.}
-
-\note{I/O operations may fail even when \function{access()}
-indicates that they would succeed, particularly for operations
-on network filesystems which may have permissions semantics
-beyond the usual \POSIX{} permission-bit model.}
-\end{funcdesc}
-
-\begin{datadesc}{F_OK}
- Value to pass as the \var{mode} parameter of \function{access()} to
- test the existence of \var{path}.
-\end{datadesc}
-
-\begin{datadesc}{R_OK}
- Value to include in the \var{mode} parameter of \function{access()}
- to test the readability of \var{path}.
-\end{datadesc}
-
-\begin{datadesc}{W_OK}
- Value to include in the \var{mode} parameter of \function{access()}
- to test the writability of \var{path}.
-\end{datadesc}
-
-\begin{datadesc}{X_OK}
- Value to include in the \var{mode} parameter of \function{access()}
- to determine if \var{path} can be executed.
-\end{datadesc}
-
-\begin{funcdesc}{chdir}{path}
-\index{directory!changing}
-Change the current working directory to \var{path}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{fchdir}{fd}
-Change the current working directory to the directory represented by
-the file descriptor \var{fd}. The descriptor must refer to an opened
-directory, not an open file.
-Availability: \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getcwd}{}
-Return a string representing the current working directory.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{getcwdu}{}
-Return a Unicode object representing the current working directory.
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{chflags}{path, flags}
-Set the flags of \var{path} to the numeric \var{flags}.
-\var{flags} may take a combination (bitwise OR) of the following values
-(as defined in the \module{stat} module):
-\begin{itemize}
- \item \code{UF_NODUMP}
- \item \code{UF_IMMUTABLE}
- \item \code{UF_APPEND}
- \item \code{UF_OPAQUE}
- \item \code{UF_NOUNLINK}
- \item \code{SF_ARCHIVED}
- \item \code{SF_IMMUTABLE}
- \item \code{SF_APPEND}
- \item \code{SF_NOUNLINK}
- \item \code{SF_SNAPSHOT}
-\end{itemize}
-Availability: Macintosh, \UNIX.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{chroot}{path}
-Change the root directory of the current process to \var{path}.
-Availability: Macintosh, \UNIX.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{chmod}{path, mode}
-Change the mode of \var{path} to the numeric \var{mode}.
-\var{mode} may take one of the following values
-(as defined in the \module{stat} module) or bitwise or-ed
-combinations of them:
-\begin{itemize}
- \item \code{S_ISUID}
- \item \code{S_ISGID}
- \item \code{S_ENFMT}
- \item \code{S_ISVTX}
- \item \code{S_IREAD}
- \item \code{S_IWRITE}
- \item \code{S_IEXEC}
- \item \code{S_IRWXU}
- \item \code{S_IRUSR}
- \item \code{S_IWUSR}
- \item \code{S_IXUSR}
- \item \code{S_IRWXG}
- \item \code{S_IRGRP}
- \item \code{S_IWGRP}
- \item \code{S_IXGRP}
- \item \code{S_IRWXO}
- \item \code{S_IROTH}
- \item \code{S_IWOTH}
- \item \code{S_IXOTH}
-\end{itemize}
-Availability: Macintosh, \UNIX, Windows.
-
-\note{Although Windows supports \function{chmod()}, you can only
-set the file's read-only flag with it (via the \code{S_IWRITE}
-and \code{S_IREAD} constants or a corresponding integer value).
-All other bits are ignored.}
-\end{funcdesc}
-
-\begin{funcdesc}{chown}{path, uid, gid}
-Change the owner and group id of \var{path} to the numeric \var{uid}
-and \var{gid}. To leave one of the ids unchanged, set it to -1.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{lchflags}{path, flags}
-Set the flags of \var{path} to the numeric \var{flags}, like
-\function{chflags()}, but do not follow symbolic links.
-Availability: \UNIX.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{lchown}{path, uid, gid}
-Change the owner and group id of \var{path} to the numeric \var{uid}
-and gid. This function will not follow symbolic links.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{link}{src, dst}
-Create a hard link pointing to \var{src} named \var{dst}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{listdir}{path}
-Return a list containing the names of the entries in the directory.
-The list is in arbitrary order. It does not include the special
-entries \code{'.'} and \code{'..'} even if they are present in the
-directory.
-Availability: Macintosh, \UNIX, Windows.
-
-\versionchanged[On Windows NT/2k/XP and \UNIX, if \var{path} is a Unicode
-object, the result will be a list of Unicode objects]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{lstat}{path}
-Like \function{stat()}, but do not follow symbolic links.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{mkfifo}{path\optional{, mode}}
-Create a FIFO (a named pipe) named \var{path} with numeric mode
-\var{mode}. The default \var{mode} is \code{0666} (octal). The current
-umask value is first masked out from the mode.
-Availability: Macintosh, \UNIX.
-
-FIFOs are pipes that can be accessed like regular files. FIFOs exist
-until they are deleted (for example with \function{os.unlink()}).
-Generally, FIFOs are used as rendezvous between ``client'' and
-``server'' type processes: the server opens the FIFO for reading, and
-the client opens it for writing. Note that \function{mkfifo()}
-doesn't open the FIFO --- it just creates the rendezvous point.
-\end{funcdesc}
-
-\begin{funcdesc}{mknod}{filename\optional{, mode=0600, device}}
-Create a filesystem node (file, device special file or named pipe)
-named \var{filename}. \var{mode} specifies both the permissions to use and
-the type of node to be created, being combined (bitwise OR) with one
-of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are
-available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device}
-defines the newly created device special file (probably using
-\function{os.makedev()}), otherwise it is ignored.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{major}{device}
-Extracts the device major number from a raw device number (usually
-the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{minor}{device}
-Extracts the device minor number from a raw device number (usually
-the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{makedev}{major, minor}
-Composes a raw device number from the major and minor device numbers.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{mkdir}{path\optional{, mode}}
-Create a directory named \var{path} with numeric mode \var{mode}.
-The default \var{mode} is \code{0777} (octal). On some systems,
-\var{mode} is ignored. Where it is used, the current umask value is
-first masked out.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{makedirs}{path\optional{, mode}}
-Recursive directory creation function.\index{directory!creating}
-\index{UNC paths!and \function{os.makedirs()}}
-Like \function{mkdir()},
-but makes all intermediate-level directories needed to contain the
-leaf directory. Throws an \exception{error} exception if the leaf
-directory already exists or cannot be created. The default \var{mode}
-is \code{0777} (octal). On some systems, \var{mode} is ignored.
-Where it is used, the current umask value is first masked out.
-\note{\function{makedirs()} will become confused if the path elements
-to create include \var{os.pardir}.}
-\versionadded{1.5.2}
-\versionchanged[This function now handles UNC paths correctly]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{pathconf}{path, name}
-Return system configuration information relevant to a named file.
-\var{name} specifies the configuration value to retrieve; it may be a
-string which is the name of a defined system value; these names are
-specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and
-others). Some platforms define additional names as well. The names
-known to the host operating system are given in the
-\code{pathconf_names} dictionary. For configuration variables not
-included in that mapping, passing an integer for \var{name} is also
-accepted.
-Availability: Macintosh, \UNIX.
-
-If \var{name} is a string and is not known, \exception{ValueError} is
-raised. If a specific value for \var{name} is not supported by the
-host system, even if it is included in \code{pathconf_names}, an
-\exception{OSError} is raised with \constant{errno.EINVAL} for the
-error number.
-\end{funcdesc}
-
-\begin{datadesc}{pathconf_names}
-Dictionary mapping names accepted by \function{pathconf()} and
-\function{fpathconf()} to the integer values defined for those names
-by the host operating system. This can be used to determine the set
-of names known to the system.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{funcdesc}{readlink}{path}
-Return a string representing the path to which the symbolic link
-points. The result may be either an absolute or relative pathname; if
-it is relative, it may be converted to an absolute pathname using
-\code{os.path.join(os.path.dirname(\var{path}), \var{result})}.
-\versionchanged [If the \var{path} is a Unicode object the result will also
-be a Unicode object]{2.6}
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{remove}{path}
-Remove the file \var{path}. If \var{path} is a directory,
-\exception{OSError} is raised; see \function{rmdir()} below to remove
-a directory. This is identical to the \function{unlink()} function
-documented below. On Windows, attempting to remove a file that is in
-use causes an exception to be raised; on \UNIX, the directory entry is
-removed but the storage allocated to the file is not made available
-until the original file is no longer in use.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{removedirs}{path}
-\index{directory!deleting}
-Removes directories recursively. Works like
-\function{rmdir()} except that, if the leaf directory is
-successfully removed, \function{removedirs()}
-tries to successively remove every parent directory mentioned in
-\var{path} until an error is raised (which is ignored, because
-it generally means that a parent directory is not empty).
-For example, \samp{os.removedirs('foo/bar/baz')} will first remove
-the directory \samp{'foo/bar/baz'}, and then remove \samp{'foo/bar'}
-and \samp{'foo'} if they are empty.
-Raises \exception{OSError} if the leaf directory could not be
-successfully removed.
-\versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{rename}{src, dst}
-Rename the file or directory \var{src} to \var{dst}. If \var{dst} is
-a directory, \exception{OSError} will be raised. On \UNIX, if
-\var{dst} exists and is a file, it will be removed silently if the
-user has permission. The operation may fail on some \UNIX{} flavors
-if \var{src} and \var{dst} are on different filesystems. If
-successful, the renaming will be an atomic operation (this is a
-\POSIX{} requirement). On Windows, if \var{dst} already exists,
-\exception{OSError} will be raised even if it is a file; there may be
-no way to implement an atomic rename when \var{dst} names an existing
-file.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{renames}{old, new}
-Recursive directory or file renaming function.
-Works like \function{rename()}, except creation of any intermediate
-directories needed to make the new pathname good is attempted first.
-After the rename, directories corresponding to rightmost path segments
-of the old name will be pruned away using \function{removedirs()}.
-\versionadded{1.5.2}
-
-\begin{notice}
-This function can fail with the new directory structure made if
-you lack permissions needed to remove the leaf directory or file.
-\end{notice}
-\end{funcdesc}
-
-\begin{funcdesc}{rmdir}{path}
-Remove the directory \var{path}.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{stat}{path}
-Perform a \cfunction{stat()} system call on the given path. The
-return value is an object whose attributes correspond to the members of
-the \ctype{stat} structure, namely:
-\member{st_mode} (protection bits),
-\member{st_ino} (inode number),
-\member{st_dev} (device),
-\member{st_nlink} (number of hard links),
-\member{st_uid} (user ID of owner),
-\member{st_gid} (group ID of owner),
-\member{st_size} (size of file, in bytes),
-\member{st_atime} (time of most recent access),
-\member{st_mtime} (time of most recent content modification),
-\member{st_ctime}
-(platform dependent; time of most recent metadata change on \UNIX, or
-the time of creation on Windows):
-
-\begin{verbatim}
->>> import os
->>> statinfo = os.stat('somefile.txt')
->>> statinfo
-(33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
->>> statinfo.st_size
-926L
->>>
-\end{verbatim}
-
-\versionchanged [If \function{stat_float_times} returns true, the time
-values are floats, measuring seconds. Fractions of a second may be
-reported if the system supports that. On Mac OS, the times are always
-floats. See \function{stat_float_times} for further discussion]{2.3}
-
-On some \UNIX{} systems (such as Linux), the following attributes may
-also be available:
-\member{st_blocks} (number of blocks allocated for file),
-\member{st_blksize} (filesystem blocksize),
-\member{st_rdev} (type of device if an inode device).
-\member{st_flags} (user defined flags for file).
-
-On other \UNIX{} systems (such as FreeBSD), the following attributes
-may be available (but may be only filled out if root tries to
-use them):
-\member{st_gen} (file generation number),
-\member{st_birthtime} (time of file creation).
-
-On Mac OS systems, the following attributes may also be available:
-\member{st_rsize},
-\member{st_creator},
-\member{st_type}.
-
-On RISCOS systems, the following attributes are also available:
-\member{st_ftype} (file type),
-\member{st_attrs} (attributes),
-\member{st_obtype} (object type).
-
-For backward compatibility, the return value of \function{stat()} is
-also accessible as a tuple of at least 10 integers giving the most
-important (and portable) members of the \ctype{stat} structure, in the
-order
-\member{st_mode},
-\member{st_ino},
-\member{st_dev},
-\member{st_nlink},
-\member{st_uid},
-\member{st_gid},
-\member{st_size},
-\member{st_atime},
-\member{st_mtime},
-\member{st_ctime}.
-More items may be added at the end by some implementations.
-The standard module \refmodule{stat}\refstmodindex{stat} defines
-functions and constants that are useful for extracting information
-from a \ctype{stat} structure.
-(On Windows, some items are filled with dummy values.)
-
-\note{The exact meaning and resolution of the \member{st_atime},
- \member{st_mtime}, and \member{st_ctime} members depends on the
- operating system and the file system. For example, on Windows systems
- using the FAT or FAT32 file systems, \member{st_mtime} has 2-second
- resolution, and \member{st_atime} has only 1-day resolution. See
- your operating system documentation for details.}
-
-Availability: Macintosh, \UNIX, Windows.
-
-\versionchanged
-[Added access to values as attributes of the returned object]{2.2}
-\versionchanged[Added st_gen, st_birthtime]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{stat_float_times}{\optional{newvalue}}
-Determine whether \class{stat_result} represents time stamps as float
-objects. If \var{newvalue} is \code{True}, future calls to \function{stat()}
-return floats, if it is \code{False}, future calls return ints.
-If \var{newvalue} is omitted, return the current setting.
-
-For compatibility with older Python versions, accessing
-\class{stat_result} as a tuple always returns integers.
-
-\versionchanged[Python now returns float values by default. Applications
-which do not work correctly with floating point time stamps can use
-this function to restore the old behaviour]{2.5}
-
-The resolution of the timestamps (that is the smallest possible fraction)
-depends on the system. Some systems only support second resolution;
-on these systems, the fraction will always be zero.
-
-It is recommended that this setting is only changed at program startup
-time in the \var{__main__} module; libraries should never change this
-setting. If an application uses a library that works incorrectly if
-floating point time stamps are processed, this application should turn
-the feature off until the library has been corrected.
-
-\end{funcdesc}
-
-\begin{funcdesc}{statvfs}{path}
-Perform a \cfunction{statvfs()} system call on the given path. The
-return value is an object whose attributes describe the filesystem on
-the given path, and correspond to the members of the
-\ctype{statvfs} structure, namely:
-\member{f_bsize},
-\member{f_frsize},
-\member{f_blocks},
-\member{f_bfree},
-\member{f_bavail},
-\member{f_files},
-\member{f_ffree},
-\member{f_favail},
-\member{f_flag},
-\member{f_namemax}.
-Availability: \UNIX.
-
-For backward compatibility, the return value is also accessible as a
-tuple whose values correspond to the attributes, in the order given above.
-The standard module \refmodule{statvfs}\refstmodindex{statvfs}
-defines constants that are useful for extracting information
-from a \ctype{statvfs} structure when accessing it as a sequence; this
-remains useful when writing code that needs to work with versions of
-Python that don't support accessing the fields as attributes.
-
-\versionchanged
-[Added access to values as attributes of the returned object]{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{symlink}{src, dst}
-Create a symbolic link pointing to \var{src} named \var{dst}.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}}
-Return a unique path name that is reasonable for creating a temporary
-file. This will be an absolute path that names a potential directory
-entry in the directory \var{dir} or a common location for temporary
-files if \var{dir} is omitted or \code{None}. If given and not
-\code{None}, \var{prefix} is used to provide a short prefix to the
-filename. Applications are responsible for properly creating and
-managing files created using paths returned by \function{tempnam()};
-no automatic cleanup is provided.
-On \UNIX, the environment variable \envvar{TMPDIR} overrides
-\var{dir}, while on Windows the \envvar{TMP} is used. The specific
-behavior of this function depends on the C library implementation;
-some aspects are underspecified in system documentation.
-\warning{Use of \function{tempnam()} is vulnerable to symlink attacks;
-consider using \function{tmpfile()} (section \ref{os-newstreams})
-instead.} Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{tmpnam}{}
-Return a unique path name that is reasonable for creating a temporary
-file. This will be an absolute path that names a potential directory
-entry in a common location for temporary files. Applications are
-responsible for properly creating and managing files created using
-paths returned by \function{tmpnam()}; no automatic cleanup is
-provided.
-\warning{Use of \function{tmpnam()} is vulnerable to symlink attacks;
-consider using \function{tmpfile()} (section \ref{os-newstreams})
-instead.} Availability: \UNIX, Windows. This function probably
-shouldn't be used on Windows, though: Microsoft's implementation of
-\function{tmpnam()} always creates a name in the root directory of the
-current drive, and that's generally a poor location for a temp file
-(depending on privileges, you may not even be able to open a file
-using this name).
-\end{funcdesc}
-
-\begin{datadesc}{TMP_MAX}
-The maximum number of unique names that \function{tmpnam()} will
-generate before reusing names.
-\end{datadesc}
-
-\begin{funcdesc}{unlink}{path}
-Remove the file \var{path}. This is the same function as
-\function{remove()}; the \function{unlink()} name is its traditional
-\UNIX{} name.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{utime}{path, times}
-Set the access and modified times of the file specified by \var{path}.
-If \var{times} is \code{None}, then the file's access and modified
-times are set to the current time. Otherwise, \var{times} must be a
-2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})}
-which is used to set the access and modified times, respectively.
-Whether a directory can be given for \var{path} depends on whether the
-operating system implements directories as files (for example, Windows
-does not). Note that the exact times you set here may not be returned
-by a subsequent \function{stat()} call, depending on the resolution
-with which your operating system records access and modification times;
-see \function{stat()}.
-\versionchanged[Added support for \code{None} for \var{times}]{2.0}
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{walk}{top\optional{, topdown\code{=True}
- \optional{, onerror\code{=None}\optional{,
- followlinks\code{=False}}}}}
-\index{directory!walking}
-\index{directory!traversal}
-\function{walk()} generates the file names in a directory tree, by
-walking the tree either top down or bottom up.
-For each directory in the tree rooted at directory \var{top} (including
-\var{top} itself), it yields a 3-tuple
-\code{(\var{dirpath}, \var{dirnames}, \var{filenames})}.
-
-\var{dirpath} is a string, the path to the directory. \var{dirnames} is
-a list of the names of the subdirectories in \var{dirpath}
-(excluding \code{'.'} and \code{'..'}). \var{filenames} is a list of
-the names of the non-directory files in \var{dirpath}. Note that the
-names in the lists contain no path components. To get a full
-path (which begins with \var{top}) to a file or directory in
-\var{dirpath}, do \code{os.path.join(\var{dirpath}, \var{name})}.
-
-If optional argument \var{topdown} is true or not specified, the triple
-for a directory is generated before the triples for any of its
-subdirectories (directories are generated top down). If \var{topdown} is
-false, the triple for a directory is generated after the triples for all
-of its subdirectories (directories are generated bottom up).
-
-When \var{topdown} is true, the caller can modify the \var{dirnames} list
-in-place (perhaps using \keyword{del} or slice assignment), and
-\function{walk()} will only recurse into the subdirectories whose names
-remain in \var{dirnames}; this can be used to prune the search,
-impose a specific order of visiting, or even to inform \function{walk()}
-about directories the caller creates or renames before it resumes
-\function{walk()} again. Modifying \var{dirnames} when \var{topdown} is
-false is ineffective, because in bottom-up mode the directories in
-\var{dirnames} are generated before \var{dirpath} itself is generated.
-
-By default errors from the \code{os.listdir()} call are ignored. If
-optional argument \var{onerror} is specified, it should be a function;
-it will be called with one argument, an \exception{OSError} instance. It can
-report the error to continue with the walk, or raise the exception
-to abort the walk. Note that the filename is available as the
-\code{filename} attribute of the exception object.
-
-By default, \function{walk()} will not walk down into symbolic links that
-resolve to directories. Set \var{followlinks} to True to visit directories
-pointed to by symlinks, on systems that support them.
-
-\versionadded[The \var{followlinks} parameter]{2.6}
-
-\begin{notice}
-Be aware that setting \var{followlinks} to true can lead to infinite recursion
-if a link points to a parent directory of itself. \function{walk()} does not
-keep track of the directories it visited already.
-\end{notice}
-
-\begin{notice}
-If you pass a relative pathname, don't change the current working
-directory between resumptions of \function{walk()}. \function{walk()}
-never changes the current directory, and assumes that its caller
-doesn't either.
-\end{notice}
-
-This example displays the number of bytes taken by non-directory files
-in each directory under the starting directory, except that it doesn't
-look under any CVS subdirectory:
-
-\begin{verbatim}
-import os
-from os.path import join, getsize
-for root, dirs, files in os.walk('python/Lib/email'):
- print root, "consumes",
- print sum(getsize(join(root, name)) for name in files),
- print "bytes in", len(files), "non-directory files"
- if 'CVS' in dirs:
- dirs.remove('CVS') # don't visit CVS directories
-\end{verbatim}
-
-In the next example, walking the tree bottom up is essential:
-\function{rmdir()} doesn't allow deleting a directory before the
-directory is empty:
-
-\begin{verbatim}
-# Delete everything reachable from the directory named in 'top',
-# assuming there are no symbolic links.
-# CAUTION: This is dangerous! For example, if top == '/', it
-# could delete all your disk files.
-import os
-for root, dirs, files in os.walk(top, topdown=False):
- for name in files:
- os.remove(os.path.join(root, name))
- for name in dirs:
- os.rmdir(os.path.join(root, name))
-\end{verbatim}
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\subsection{Process Management \label{os-process}}
-
-These functions may be used to create and manage processes.
-
-The various \function{exec*()} functions take a list of arguments for
-the new program loaded into the process. In each case, the first of
-these arguments is passed to the new program as its own name rather
-than as an argument a user may have typed on a command line. For the
-C programmer, this is the \code{argv[0]} passed to a program's
-\cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo',
-'bar'])} will only print \samp{bar} on standard output; \samp{foo}
-will seem to be ignored.
-
-
-\begin{funcdesc}{abort}{}
-Generate a \constant{SIGABRT} signal to the current process. On
-\UNIX, the default behavior is to produce a core dump; on Windows, the
-process immediately returns an exit code of \code{3}. Be aware that
-programs which use \function{signal.signal()} to register a handler
-for \constant{SIGABRT} will behave differently.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{execl}{path, arg0, arg1, \moreargs}
-\funcline{execle}{path, arg0, arg1, \moreargs, env}
-\funcline{execlp}{file, arg0, arg1, \moreargs}
-\funcline{execlpe}{file, arg0, arg1, \moreargs, env}
-\funcline{execv}{path, args}
-\funcline{execve}{path, args, env}
-\funcline{execvp}{file, args}
-\funcline{execvpe}{file, args, env}
-These functions all execute a new program, replacing the current
-process; they do not return. On \UNIX, the new executable is loaded
-into the current process, and will have the same process ID as the
-caller. Errors will be reported as \exception{OSError} exceptions.
-
-The \character{l} and \character{v} variants of the
-\function{exec*()} functions differ in how command-line arguments are
-passed. The \character{l} variants are perhaps the easiest to work
-with if the number of parameters is fixed when the code is written;
-the individual parameters simply become additional parameters to the
-\function{execl*()} functions. The \character{v} variants are good
-when the number of parameters is variable, with the arguments being
-passed in a list or tuple as the \var{args} parameter. In either
-case, the arguments to the child process should start with the name of
-the command being run, but this is not enforced.
-
-The variants which include a \character{p} near the end
-(\function{execlp()}, \function{execlpe()}, \function{execvp()},
-and \function{execvpe()}) will use the \envvar{PATH} environment
-variable to locate the program \var{file}. When the environment is
-being replaced (using one of the \function{exec*e()} variants,
-discussed in the next paragraph), the
-new environment is used as the source of the \envvar{PATH} variable.
-The other variants, \function{execl()}, \function{execle()},
-\function{execv()}, and \function{execve()}, will not use the
-\envvar{PATH} variable to locate the executable; \var{path} must
-contain an appropriate absolute or relative path.
-
-For \function{execle()}, \function{execlpe()}, \function{execve()},
-and \function{execvpe()} (note that these all end in \character{e}),
-the \var{env} parameter must be a mapping which is used to define the
-environment variables for the new process; the \function{execl()},
-\function{execlp()}, \function{execv()}, and \function{execvp()}
-all cause the new process to inherit the environment of the current
-process.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{_exit}{n}
-Exit to the system with status \var{n}, without calling cleanup
-handlers, flushing stdio buffers, etc.
-Availability: Macintosh, \UNIX, Windows.
-
-\begin{notice}
-The standard way to exit is \code{sys.exit(\var{n})}.
-\function{_exit()} should normally only be used in the child process
-after a \function{fork()}.
-\end{notice}
-\end{funcdesc}
-
-The following exit codes are a defined, and can be used with
-\function{_exit()}, although they are not required. These are
-typically used for system programs written in Python, such as a
-mail server's external command delivery program.
-\note{Some of these may not be available on all \UNIX{} platforms,
-since there is some variation. These constants are defined where they
-are defined by the underlying platform.}
-
-\begin{datadesc}{EX_OK}
-Exit code that means no error occurred.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_USAGE}
-Exit code that means the command was used incorrectly, such as when
-the wrong number of arguments are given.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_DATAERR}
-Exit code that means the input data was incorrect.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOINPUT}
-Exit code that means an input file did not exist or was not readable.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOUSER}
-Exit code that means a specified user did not exist.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOHOST}
-Exit code that means a specified host did not exist.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_UNAVAILABLE}
-Exit code that means that a required service is unavailable.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_SOFTWARE}
-Exit code that means an internal software error was detected.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_OSERR}
-Exit code that means an operating system error was detected, such as
-the inability to fork or create a pipe.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_OSFILE}
-Exit code that means some system file did not exist, could not be
-opened, or had some other kind of error.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_CANTCREAT}
-Exit code that means a user specified output file could not be created.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_IOERR}
-Exit code that means that an error occurred while doing I/O on some file.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_TEMPFAIL}
-Exit code that means a temporary failure occurred. This indicates
-something that may not really be an error, such as a network
-connection that couldn't be made during a retryable operation.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_PROTOCOL}
-Exit code that means that a protocol exchange was illegal, invalid, or
-not understood.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOPERM}
-Exit code that means that there were insufficient permissions to
-perform the operation (but not intended for file system problems).
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_CONFIG}
-Exit code that means that some kind of configuration error occurred.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{EX_NOTFOUND}
-Exit code that means something like ``an entry was not found''.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{funcdesc}{fork}{}
-Fork a child process. Return \code{0} in the child, the child's
-process id in the parent.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{forkpty}{}
-Fork a child process, using a new pseudo-terminal as the child's
-controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})},
-where \var{pid} is \code{0} in the child, the new child's process id
-in the parent, and \var{fd} is the file descriptor of the master end
-of the pseudo-terminal. For a more portable approach, use the
-\refmodule{pty} module.
-Availability: Macintosh, Some flavors of \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{kill}{pid, sig}
-\index{process!killing}
-\index{process!signalling}
-Send signal \var{sig} to the process \var{pid}. Constants for the
-specific signals available on the host platform are defined in the
-\refmodule{signal} module.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{killpg}{pgid, sig}
-\index{process!killing}
-\index{process!signalling}
-Send the signal \var{sig} to the process group \var{pgid}.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{nice}{increment}
-Add \var{increment} to the process's ``niceness''. Return the new
-niceness.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{plock}{op}
-Lock program segments into memory. The value of \var{op}
-(defined in \code{<sys/lock.h>}) determines which segments are locked.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdescni}{popen}{\unspecified}
-Run child processes, returning opened pipes for communications. These
-functions are described in section \ref{os-newstreams}.
-\end{funcdescni}
-
-\begin{funcdesc}{spawnl}{mode, path, \moreargs}
-\funcline{spawnle}{mode, path, \moreargs, env}
-\funcline{spawnlp}{mode, file, \moreargs}
-\funcline{spawnlpe}{mode, file, \moreargs, env}
-\funcline{spawnv}{mode, path, args}
-\funcline{spawnve}{mode, path, args, env}
-\funcline{spawnvp}{mode, file, args}
-\funcline{spawnvpe}{mode, file, args, env}
-Execute the program \var{path} in a new process.
-
-(Note that the \module{subprocess} module provides more powerful
-facilities for spawning new processes and retrieving their results;
-using that module is preferable to using these functions.)
-
-If \var{mode} is
-\constant{P_NOWAIT}, this function returns the process ID of the new
-process; if \var{mode} is \constant{P_WAIT}, returns the process's
-exit code if it exits normally, or \code{-\var{signal}}, where
-\var{signal} is the signal that killed the process. On Windows, the
-process ID will actually be the process handle, so can be used with
-the \function{waitpid()} function.
-
-The \character{l} and \character{v} variants of the
-\function{spawn*()} functions differ in how command-line arguments are
-passed. The \character{l} variants are perhaps the easiest to work
-with if the number of parameters is fixed when the code is written;
-the individual parameters simply become additional parameters to the
-\function{spawnl*()} functions. The \character{v} variants are good
-when the number of parameters is variable, with the arguments being
-passed in a list or tuple as the \var{args} parameter. In either
-case, the arguments to the child process must start with the name of
-the command being run.
-
-The variants which include a second \character{p} near the end
-(\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()},
-and \function{spawnvpe()}) will use the \envvar{PATH} environment
-variable to locate the program \var{file}. When the environment is
-being replaced (using one of the \function{spawn*e()} variants,
-discussed in the next paragraph), the new environment is used as the
-source of the \envvar{PATH} variable. The other variants,
-\function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and
-\function{spawnve()}, will not use the \envvar{PATH} variable to
-locate the executable; \var{path} must contain an appropriate absolute
-or relative path.
-
-For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()},
-and \function{spawnvpe()} (note that these all end in \character{e}),
-the \var{env} parameter must be a mapping which is used to define the
-environment variables for the new process; the \function{spawnl()},
-\function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()}
-all cause the new process to inherit the environment of the current
-process.
-
-As an example, the following calls to \function{spawnlp()} and
-\function{spawnvpe()} are equivalent:
-
-\begin{verbatim}
-import os
-os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
-
-L = ['cp', 'index.html', '/dev/null']
-os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
-\end{verbatim}
-
-Availability: \UNIX, Windows. \function{spawnlp()},
-\function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()}
-are not available on Windows.
-\versionadded{1.6}
-\end{funcdesc}
-
-\begin{datadesc}{P_NOWAIT}
-\dataline{P_NOWAITO}
-Possible values for the \var{mode} parameter to the \function{spawn*()}
-family of functions. If either of these values is given, the
-\function{spawn*()} functions will return as soon as the new process
-has been created, with the process ID as the return value.
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{1.6}
-\end{datadesc}
-
-\begin{datadesc}{P_WAIT}
-Possible value for the \var{mode} parameter to the \function{spawn*()}
-family of functions. If this is given as \var{mode}, the
-\function{spawn*()} functions will not return until the new process
-has run to completion and will return the exit code of the process the
-run is successful, or \code{-\var{signal}} if a signal kills the
-process.
-Availability: Macintosh, \UNIX, Windows.
-\versionadded{1.6}
-\end{datadesc}
-
-\begin{datadesc}{P_DETACH}
-\dataline{P_OVERLAY}
-Possible values for the \var{mode} parameter to the
-\function{spawn*()} family of functions. These are less portable than
-those listed above.
-\constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new
-process is detached from the console of the calling process.
-If \constant{P_OVERLAY} is used, the current process will be replaced;
-the \function{spawn*()} function will not return.
-Availability: Windows.
-\versionadded{1.6}
-\end{datadesc}
-
-\begin{funcdesc}{startfile}{path\optional{, operation}}
-Start a file with its associated application.
-
-When \var{operation} is not specified or \code{'open'}, this acts like
-double-clicking the file in Windows Explorer, or giving the file name
-as an argument to the \program{start} command from the interactive
-command shell: the file is opened with whatever application (if any)
-its extension is associated.
-
-When another \var{operation} is given, it must be a ``command verb''
-that specifies what should be done with the file.
-Common verbs documented by Microsoft are \code{'print'} and
-\code{'edit'} (to be used on files) as well as \code{'explore'} and
-\code{'find'} (to be used on directories).
-
-\function{startfile()} returns as soon as the associated application
-is launched. There is no option to wait for the application to close,
-and no way to retrieve the application's exit status. The \var{path}
-parameter is relative to the current directory. If you want to use an
-absolute path, make sure the first character is not a slash
-(\character{/}); the underlying Win32 \cfunction{ShellExecute()}
-function doesn't work if it is. Use the \function{os.path.normpath()}
-function to ensure that the path is properly encoded for Win32.
-Availability: Windows.
-\versionadded{2.0}
-\versionadded[The \var{operation} parameter]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{system}{command}
-Execute the command (a string) in a subshell. This is implemented by
-calling the Standard C function \cfunction{system()}, and has the
-same limitations. Changes to \code{posix.environ}, \code{sys.stdin},
-etc.\ are not reflected in the environment of the executed command.
-
-On \UNIX, the return value is the exit status of the process encoded in the
-format specified for \function{wait()}. Note that \POSIX{} does not
-specify the meaning of the return value of the C \cfunction{system()}
-function, so the return value of the Python function is system-dependent.
-
-On Windows, the return value is that returned by the system shell after
-running \var{command}, given by the Windows environment variable
-\envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME)
-this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000
-and XP) this is the exit status of the command run; on systems using
-a non-native shell, consult your shell documentation.
-
-Availability: Macintosh, \UNIX, Windows.
-
-The \module{subprocess} module provides more powerful facilities for
-spawning new processes and retrieving their results; using that module
-is preferable to using this function.
-\end{funcdesc}
-
-\begin{funcdesc}{times}{}
-Return a 5-tuple of floating point numbers indicating accumulated
-(processor or other)
-times, in seconds. The items are: user time, system time, children's
-user time, children's system time, and elapsed real time since a fixed
-point in the past, in that order. See the \UNIX{} manual page
-\manpage{times}{2} or the corresponding Windows Platform API
-documentation.
-Availability: Macintosh, \UNIX, Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{wait}{}
-Wait for completion of a child process, and return a tuple containing
-its pid and exit status indication: a 16-bit number, whose low byte is
-the signal number that killed the process, and whose high byte is the
-exit status (if the signal number is zero); the high bit of the low
-byte is set if a core file was produced.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{waitpid}{pid, options}
-The details of this function differ on \UNIX{} and Windows.
-
-On \UNIX:
-Wait for completion of a child process given by process id \var{pid},
-and return a tuple containing its process id and exit status
-indication (encoded as for \function{wait()}). The semantics of the
-call are affected by the value of the integer \var{options}, which
-should be \code{0} for normal operation.
-
-If \var{pid} is greater than \code{0}, \function{waitpid()} requests
-status information for that specific process. If \var{pid} is
-\code{0}, the request is for the status of any child in the process
-group of the current process. If \var{pid} is \code{-1}, the request
-pertains to any child of the current process. If \var{pid} is less
-than \code{-1}, status is requested for any process in the process
-group \code{-\var{pid}} (the absolute value of \var{pid}).
-
-On Windows:
-Wait for completion of a process given by process handle \var{pid},
-and return a tuple containing \var{pid},
-and its exit status shifted left by 8 bits (shifting makes cross-platform
-use of the function easier).
-A \var{pid} less than or equal to \code{0} has no special meaning on
-Windows, and raises an exception.
-The value of integer \var{options} has no effect.
-\var{pid} can refer to any process whose id is known, not necessarily a
-child process.
-The \function{spawn()} functions called with \constant{P_NOWAIT}
-return suitable process handles.
-\end{funcdesc}
-
-\begin{funcdesc}{wait3}{\optional{options}}
-Similar to \function{waitpid()}, except no process id argument is given and
-a 3-element tuple containing the child's process id, exit status indication,
-and resource usage information is returned. Refer to
-\module{resource}.\function{getrusage()}
-for details on resource usage information. The option argument is the same
-as that provided to \function{waitpid()} and \function{wait4()}.
-Availability: \UNIX.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{wait4}{pid, options}
-Similar to \function{waitpid()}, except a 3-element tuple, containing the
-child's process id, exit status indication, and resource usage information
-is returned. Refer to \module{resource}.\function{getrusage()} for details
-on resource usage information. The arguments to \function{wait4()} are
-the same as those provided to \function{waitpid()}.
-Availability: \UNIX.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{datadesc}{WNOHANG}
-The option for \function{waitpid()} to return immediately if no child
-process status is available immediately. The function returns
-\code{(0, 0)} in this case.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{datadesc}{WCONTINUED}
-This option causes child processes to be reported if they have been
-continued from a job control stop since their status was last
-reported.
-Availability: Some \UNIX{} systems.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{WUNTRACED}
-This option causes child processes to be reported if they have been
-stopped but their current state has not been reported since they were
-stopped.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{datadesc}
-
-The following functions take a process status code as returned by
-\function{system()}, \function{wait()}, or \function{waitpid()} as a
-parameter. They may be used to determine the disposition of a
-process.
-
-\begin{funcdesc}{WCOREDUMP}{status}
-Returns \code{True} if a core dump was generated for the process,
-otherwise it returns \code{False}.
-Availability: Macintosh, \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{WIFCONTINUED}{status}
-Returns \code{True} if the process has been continued from a job
-control stop, otherwise it returns \code{False}.
-Availability: \UNIX.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{WIFSTOPPED}{status}
-Returns \code{True} if the process has been stopped, otherwise it
-returns \code{False}.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WIFSIGNALED}{status}
-Returns \code{True} if the process exited due to a signal, otherwise
-it returns \code{False}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WIFEXITED}{status}
-Returns \code{True} if the process exited using the \manpage{exit}{2}
-system call, otherwise it returns \code{False}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WEXITSTATUS}{status}
-If \code{WIFEXITED(\var{status})} is true, return the integer
-parameter to the \manpage{exit}{2} system call. Otherwise, the return
-value is meaningless.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WSTOPSIG}{status}
-Return the signal which caused the process to stop.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{WTERMSIG}{status}
-Return the signal which caused the process to exit.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-
-\subsection{Miscellaneous System Information \label{os-path}}
-
-
-\begin{funcdesc}{confstr}{name}
-Return string-valued system configuration values.
-\var{name} specifies the configuration value to retrieve; it may be a
-string which is the name of a defined system value; these names are
-specified in a number of standards (\POSIX, \UNIX{} 95, \UNIX{} 98, and
-others). Some platforms define additional names as well. The names
-known to the host operating system are given as the keys of the
-\code{confstr_names} dictionary. For configuration variables not
-included in that mapping, passing an integer for \var{name} is also
-accepted.
-Availability: Macintosh, \UNIX.
-
-If the configuration value specified by \var{name} isn't defined,
-\code{None} is returned.
-
-If \var{name} is a string and is not known, \exception{ValueError} is
-raised. If a specific value for \var{name} is not supported by the
-host system, even if it is included in \code{confstr_names}, an
-\exception{OSError} is raised with \constant{errno.EINVAL} for the
-error number.
-\end{funcdesc}
-
-\begin{datadesc}{confstr_names}
-Dictionary mapping names accepted by \function{confstr()} to the
-integer values defined for those names by the host operating system.
-This can be used to determine the set of names known to the system.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-\begin{funcdesc}{getloadavg}{}
-Return the number of processes in the system run queue averaged over
-the last 1, 5, and 15 minutes or raises \exception{OSError} if the load
-average was unobtainable.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{sysconf}{name}
-Return integer-valued system configuration values.
-If the configuration value specified by \var{name} isn't defined,
-\code{-1} is returned. The comments regarding the \var{name}
-parameter for \function{confstr()} apply here as well; the dictionary
-that provides information on the known names is given by
-\code{sysconf_names}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{datadesc}{sysconf_names}
-Dictionary mapping names accepted by \function{sysconf()} to the
-integer values defined for those names by the host operating system.
-This can be used to determine the set of names known to the system.
-Availability: Macintosh, \UNIX.
-\end{datadesc}
-
-
-The follow data values are used to support path manipulation
-operations. These are defined for all platforms.
-
-Higher-level operations on pathnames are defined in the
-\refmodule{os.path} module.
-
-
-\begin{datadesc}{curdir}
-The constant string used by the operating system to refer to the current
-directory.
-For example: \code{'.'} for \POSIX{} or \code{':'} for Mac OS 9.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{pardir}
-The constant string used by the operating system to refer to the parent
-directory.
-For example: \code{'..'} for \POSIX{} or \code{'::'} for Mac OS 9.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{sep}
-The character used by the operating system to separate pathname components,
-for example, \character{/} for \POSIX{} or \character{:} for
-Mac OS 9. Note that knowing this is not sufficient to be able to
-parse or concatenate pathnames --- use \function{os.path.split()} and
-\function{os.path.join()} --- but it is occasionally useful.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{altsep}
-An alternative character used by the operating system to separate pathname
-components, or \code{None} if only one separator character exists. This is
-set to \character{/} on Windows systems where \code{sep} is a
-backslash.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{extsep}
-The character which separates the base filename from the extension;
-for example, the \character{.} in \file{os.py}.
-Also available via \module{os.path}.
-\versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{pathsep}
-The character conventionally used by the operating system to separate
-search path components (as in \envvar{PATH}), such as \character{:} for
-\POSIX{} or \character{;} for Windows.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{defpath}
-The default search path used by \function{exec*p*()} and
-\function{spawn*p*()} if the environment doesn't have a \code{'PATH'}
-key.
-Also available via \module{os.path}.
-\end{datadesc}
-
-\begin{datadesc}{linesep}
-The string used to separate (or, rather, terminate) lines on the
-current platform. This may be a single character, such as
-\code{'\e n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple
-characters, for example, \code{'\e r\e n'} for Windows.
-Do not use \var{os.linesep} as a line terminator when writing files
-opened in text mode (the default); use a single \code{'\e n'} instead,
-on all platforms.
-\end{datadesc}
-
-\begin{datadesc}{devnull}
-The file path of the null device.
-For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for
-Mac OS 9.
-Also available via \module{os.path}.
-\versionadded{2.4}
-\end{datadesc}
-
-
-\subsection{Miscellaneous Functions \label{os-miscfunc}}
-
-\begin{funcdesc}{urandom}{n}
-Return a string of \var{n} random bytes suitable for cryptographic use.
-
-This function returns random bytes from an OS-specific
-randomness source. The returned data should be unpredictable enough for
-cryptographic applications, though its exact quality depends on the OS
-implementation. On a UNIX-like system this will query /dev/urandom, and
-on Windows it will use CryptGenRandom. If a randomness source is not
-found, \exception{NotImplementedError} will be raised.
-\versionadded{2.4}
-\end{funcdesc}
-
-
-
-
diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
deleted file mode 100644
index 4c19aaf..0000000
--- a/Doc/lib/libossaudiodev.tex
+++ /dev/null
@@ -1,401 +0,0 @@
-\section{\module{ossaudiodev} ---
- Access to OSS-compatible audio devices}
-
-\declaremodule{builtin}{ossaudiodev}
-\platform{Linux, FreeBSD}
-\modulesynopsis{Access to OSS-compatible audio devices.}
-
-\versionadded{2.3}
-
-This module allows you to access the OSS (Open Sound System) audio
-interface. OSS is available for a wide range of open-source and
-commercial Unices, and is the standard audio interface for Linux and
-recent versions of FreeBSD.
-
-% Things will get more complicated for future Linux versions, since
-% ALSA is in the standard kernel as of 2.5.x. Presumably if you
-% use ALSA, you'll have to make sure its OSS compatibility layer
-% is active to use ossaudiodev, but you're gonna need it for the vast
-% majority of Linux audio apps anyways.
-%
-% Sounds like things are also complicated for other BSDs. In response
-% to my python-dev query, Thomas Wouters said:
-%
-% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
-% > OSS installation manual tells you to remove references to OSS/Free from the
-% > kernel :)
-%
-% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
-% from its <soundcard.h>:
-% > * WARNING! WARNING!
-% > * This is an OSS (Linux) audio emulator.
-% > * Use the Native NetBSD API for developing new code, and this
-% > * only for compiling Linux programs.
-%
-% There's also an ossaudio manpage on OpenBSD that explains things
-% further. Presumably NetBSD and OpenBSD have a different standard
-% audio interface. That's the great thing about standards, there are so
-% many to choose from ... ;-)
-%
-% This probably all warrants a footnote or two, but I don't understand
-% things well enough right now to write it! --GPW
-
-\begin{seealso}
-\seetitle[http://www.opensound.com/pguide/oss.pdf]
- {Open Sound System Programmer's Guide} {the official
- documentation for the OSS C API}
-\seetext{The module defines a large number of constants supplied by
- the OSS device driver; see \code{<sys/soundcard.h>} on either
- Linux or FreeBSD for a listing .}
-\end{seealso}
-
-\module{ossaudiodev} defines the following variables and functions:
-
-\begin{excdesc}{OSSAudioError}
-This exception is raised on certain errors. The argument is a string
-describing what went wrong.
-
-(If \module{ossaudiodev} receives an error from a system call such as
-\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it
-raises \exception{IOError}. Errors detected directly by
-\module{ossaudiodev} result in \exception{OSSAudioError}.)
-
-(For backwards compatibility, the exception class is also available as
-\code{ossaudiodev.error}.)
-\end{excdesc}
-
-\begin{funcdesc}{open}{\optional{device, }mode}
-Open an audio device and return an OSS audio device object. This
-object supports many file-like methods, such as \method{read()},
-\method{write()}, and \method{fileno()} (although there are subtle
-differences between conventional \UNIX{} read/write semantics and those of
-OSS audio devices). It also supports a number of audio-specific
-methods; see below for the complete list of methods.
-
-\var{device} is the audio device filename to use. If it is not
-specified, this module first looks in the environment variable
-\envvar{AUDIODEV} for a device to use. If not found, it falls back to
-\file{/dev/dsp}.
-
-\var{mode} is one of \code{'r'} for read-only (record) access,
-\code{'w'} for write-only (playback) access and \code{'rw'} for both.
-Since many sound cards only allow one process to have the recorder or
-player open at a time, it is a good idea to open the device only for the
-activity needed. Further, some sound cards are half-duplex: they can be
-opened for reading or writing, but not both at once.
-
-Note the unusual calling syntax: the \emph{first} argument is optional,
-and the second is required. This is a historical artifact for
-compatibility with the older \module{linuxaudiodev} module which
-\module{ossaudiodev} supersedes. % XXX it might also be motivated
-% by my unfounded-but-still-possibly-true belief that the default
-% audio device varies unpredictably across operating systems. -GW
-\end{funcdesc}
-
-\begin{funcdesc}{openmixer}{\optional{device}}
-Open a mixer device and return an OSS mixer device object.
-\var{device} is the mixer device filename to use. If it is
-not specified, this module first looks in the environment variable
-\envvar{MIXERDEV} for a device to use. If not found, it falls back to
-\file{/dev/mixer}.
-
-\end{funcdesc}
-
-\subsection{Audio Device Objects \label{ossaudio-device-objects}}
-
-Before you can write to or read from an audio device, you must call
-three methods in the correct order:
-\begin{enumerate}
-\item \method{setfmt()} to set the output format
-\item \method{channels()} to set the number of channels
-\item \method{speed()} to set the sample rate
-\end{enumerate}
-Alternately, you can use the \method{setparameters()} method to set all
-three audio parameters at once. This is more convenient, but may not be
-as flexible in all cases.
-
-The audio device objects returned by \function{open()} define the
-following methods and (read-only) attributes:
-
-\begin{methoddesc}[audio device]{close}{}
-Explicitly close the audio device. When you are done writing to or
-reading from an audio device, you should explicitly close it. A closed
-device cannot be used again.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{fileno}{}
-Return the file descriptor associated with the device.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{read}{size}
-Read \var{size} bytes from the audio input and return them as a Python
-string. Unlike most \UNIX{} device drivers, OSS audio devices in
-blocking mode (the default) will block \function{read()} until the
-entire requested amount of data is available.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{write}{data}
-Write the Python string \var{data} to the audio device and return the
-number of bytes written. If the audio device is in blocking mode (the
-default), the entire string is always written (again, this is different
-from usual \UNIX{} device semantics). If the device is in non-blocking
-mode, some data may not be written---see \method{writeall()}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{writeall}{data}
-Write the entire Python string \var{data} to the audio device: waits
-until the audio device is able to accept data, writes as much data as it
-will accept, and repeats until \var{data} has been completely written.
-If the device is in blocking mode (the default), this has the same
-effect as \method{write()}; \method{writeall()} is only useful in
-non-blocking mode. Has no return value, since the amount of data
-written is always equal to the amount of data supplied.
-\end{methoddesc}
-
-The following methods each map to exactly one
-\function{ioctl()} system call. The correspondence is obvious: for
-example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT}
-ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful
-when consulting the OSS documentation). If the underlying
-\function{ioctl()} fails, they all raise \exception{IOError}.
-
-\begin{methoddesc}[audio device]{nonblock}{}
-Put the device into non-blocking mode. Once in non-blocking mode, there
-is no way to return it to blocking mode.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{getfmts}{}
-Return a bitmask of the audio output formats supported by the
-soundcard. Some of the formats supported by OSS are:
-
-\begin{tableii}{l|l}{constant}{Format}{Description}
-\lineii{AFMT_MU_LAW}
- {a logarithmic encoding (used by Sun \code{.au} files and
- \filenq{/dev/audio})}
-\lineii{AFMT_A_LAW}
- {a logarithmic encoding}
-\lineii{AFMT_IMA_ADPCM}
- {a 4:1 compressed format defined by the Interactive Multimedia
- Association}
-\lineii{AFMT_U8}
- {Unsigned, 8-bit audio}
-\lineii{AFMT_S16_LE}
- {Signed, 16-bit audio, little-endian byte order (as used by
- Intel processors)}
-\lineii{AFMT_S16_BE}
- {Signed, 16-bit audio, big-endian byte order (as used by 68k,
- PowerPC, Sparc)}
-\lineii{AFMT_S8}
- {Signed, 8 bit audio}
-\lineii{AFMT_U16_LE}
- {Unsigned, 16-bit little-endian audio}
-\lineii{AFMT_U16_BE}
- {Unsigned, 16-bit big-endian audio}
-\end{tableii}
-Consult the OSS documentation for a full list of audio formats, and note
-that most devices support only a subset of these formats. Some older
-devices only support \constant{AFMT_U8}; the most common format used
-today is \constant{AFMT_S16_LE}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{setfmt}{format}
-Try to set the current audio format to \var{format}---see
-\method{getfmts()} for a list. Returns the audio format that the device
-was set to, which may not be the requested format. May also be used to
-return the current audio format---do this by passing an ``audio format''
-of
-\constant{AFMT_QUERY}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{channels}{nchannels}
-Set the number of output channels to \var{nchannels}. A value of 1
-indicates monophonic sound, 2 stereophonic. Some devices may have more
-than 2 channels, and some high-end devices may not support mono.
-Returns the number of channels the device was set to.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{speed}{samplerate}
-Try to set the audio sampling rate to \var{samplerate} samples per
-second. Returns the rate actually set. Most sound devices don't
-support arbitrary sampling rates. Common rates are:
-\begin{tableii}{l|l}{textrm}{Rate}{Description}
-\lineii{8000}{default rate for \filenq{/dev/audio}}
-\lineii{11025}{speech recording}
-\lineii{22050}{}
-\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)}
-\lineii{96000}{DVD quality audio (at 24 bits/sample)}
-\end{tableii}
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{sync}{}
-Wait until the sound device has played every byte in its buffer. (This
-happens implicitly when the device is closed.) The OSS documentation
-recommends closing and re-opening the device rather than using
-\method{sync()}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{reset}{}
-Immediately stop playing or recording and return the device to a
-state where it can accept commands. The OSS documentation recommends
-closing and re-opening the device after calling \method{reset()}.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{post}{}
-Tell the driver that there is likely to be a pause in the output, making
-it possible for the device to handle the pause more intelligently. You
-might use this after playing a spot sound effect, before waiting for
-user input, or before doing disk I/O.
-\end{methoddesc}
-
-The following convenience methods combine several ioctls, or one ioctl
-and some simple calculations.
-
-\begin{methoddesc}[audio device]{setparameters}
- {format, nchannels, samplerate \optional{, strict=False}}
-
-Set the key audio sampling parameters---sample format, number of
-channels, and sampling rate---in one method call. \var{format},
-\var{nchannels}, and \var{samplerate} should be as specified in the
-\method{setfmt()}, \method{channels()}, and \method{speed()}
-methods. If \var{strict} is true, \method{setparameters()} checks to
-see if each parameter was actually set to the requested value, and
-raises \exception{OSSAudioError} if not. Returns a tuple (\var{format},
-\var{nchannels}, \var{samplerate}) indicating the parameter values that
-were actually set by the device driver (i.e., the same as the return
-values of \method{setfmt()}, \method{channels()}, and \method{speed()}).
-
-For example,
-\begin{verbatim}
- (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
-\end{verbatim}
-is equivalent to
-\begin{verbatim}
- fmt = dsp.setfmt(fmt)
- channels = dsp.channels(channels)
- rate = dsp.rate(channels)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{bufsize}{}
-Returns the size of the hardware buffer, in samples.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{obufcount}{}
-Returns the number of samples that are in the hardware buffer yet to be
-played.
-\end{methoddesc}
-
-\begin{methoddesc}[audio device]{obuffree}{}
-Returns the number of samples that could be queued into the hardware
-buffer to be played without blocking.
-\end{methoddesc}
-
-Audio device objects also support several read-only attributes:
-
-\begin{memberdesc}[audio device]{closed}{}
-Boolean indicating whether the device has been closed.
-\end{memberdesc}
-
-\begin{memberdesc}[audio device]{name}{}
-String containing the name of the device file.
-\end{memberdesc}
-
-\begin{memberdesc}[audio device]{mode}{}
-The I/O mode for the file, either \code{"r"}, \code{"rw"}, or \code{"w"}.
-\end{memberdesc}
-
-
-\subsection{Mixer Device Objects \label{mixer-device-objects}}
-
-The mixer object provides two file-like methods:
-
-\begin{methoddesc}[mixer device]{close}{}
-This method closes the open mixer device file. Any further attempts to
-use the mixer after this file is closed will raise an \exception{IOError}.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{fileno}{}
-Returns the file handle number of the open mixer device file.
-\end{methoddesc}
-
-The remaining methods are specific to audio mixing:
-
-\begin{methoddesc}[mixer device]{controls}{}
-This method returns a bitmask specifying the available mixer controls
-(``Control'' being a specific mixable ``channel'', such as
-\constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This
-bitmask indicates a subset of all available mixer controls---the
-\constant{SOUND_MIXER_*} constants defined at module level. To determine if,
-for example, the current mixer object supports a PCM mixer, use the
-following Python code:
-
-\begin{verbatim}
-mixer=ossaudiodev.openmixer()
-if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
- # PCM is supported
- ... code ...
-\end{verbatim}
-
-For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and
-\constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the
-mixer should be flexible when it comes to choosing mixer controls. On
-the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
-exist.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{stereocontrols}{}
-Returns a bitmask indicating stereo mixer controls. If a bit is set,
-the corresponding control is stereo; if it is unset, the control is
-either monophonic or not supported by the mixer (use in combination with
-\method{controls()} to determine which).
-
-See the code example for the \method{controls()} function for an example
-of getting data from a bitmask.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{reccontrols}{}
-Returns a bitmask specifying the mixer controls that may be used to
-record. See the code example for \method{controls()} for an example of
-reading from a bitmask.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{get}{control}
-Returns the volume of a given mixer control. The returned volume is a
-2-tuple \code{(left_volume,right_volume)}. Volumes are specified as
-numbers from 0 (silent) to 100 (full volume). If the control is
-monophonic, a 2-tuple is still returned, but both volumes are
-the same.
-
-Raises \exception{OSSAudioError} if an invalid control was is specified,
-or \exception{IOError} if an unsupported control is specified.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{set}{control, (left, right)}
-Sets the volume for a given mixer control to \code{(left,right)}.
-\code{left} and \code{right} must be ints and between 0 (silent) and 100
-(full volume). On success, the new volume is returned as a 2-tuple.
-Note that this may not be exactly the same as the volume specified,
-because of the limited resolution of some soundcard's mixers.
-
-Raises \exception{OSSAudioError} if an invalid mixer control was
-specified, or if the specified volumes were out-of-range.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{get_recsrc}{}
-This method returns a bitmask indicating which control(s) are
-currently being used as a recording source.
-\end{methoddesc}
-
-\begin{methoddesc}[mixer device]{set_recsrc}{bitmask}
-Call this function to specify a recording source. Returns a bitmask
-indicating the new recording source (or sources) if successful; raises
-\exception{IOError} if an invalid source was specified. To set the current
-recording source to the microphone input:
-
-\begin{verbatim}
-mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
-\end{verbatim}
-\end{methoddesc}
-
-
-
diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex
deleted file mode 100644
index a993624..0000000
--- a/Doc/lib/libparser.tex
+++ /dev/null
@@ -1,712 +0,0 @@
-\section{\module{parser} ---
- Access Python parse trees}
-
-% Copyright 1995 Virginia Polytechnic Institute and State University
-% and Fred L. Drake, Jr. This copyright notice must be distributed on
-% all copies, but this document otherwise may be distributed as part
-% of the Python distribution. No fee may be charged for this document
-% in any representation, either on paper or electronically. This
-% restriction does not affect other elements in a distributed package
-% in any way.
-
-\declaremodule{builtin}{parser}
-\modulesynopsis{Access parse trees for Python source code.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-\index{parsing!Python source code}
-
-The \module{parser} module provides an interface to Python's internal
-parser and byte-code compiler. The primary purpose for this interface
-is to allow Python code to edit the parse tree of a Python expression
-and create executable code from this. This is better than trying
-to parse and modify an arbitrary Python code fragment as a string
-because parsing is performed in a manner identical to the code
-forming the application. It is also faster.
-
-There are a few things to note about this module which are important
-to making use of the data structures created. This is not a tutorial
-on editing the parse trees for Python code, but some examples of using
-the \module{parser} module are presented.
-
-Most importantly, a good understanding of the Python grammar processed
-by the internal parser is required. For full information on the
-language syntax, refer to the \citetitle[../ref/ref.html]{Python
-Language Reference}. The parser itself is created from a grammar
-specification defined in the file \file{Grammar/Grammar} in the
-standard Python distribution. The parse trees stored in the AST
-objects created by this module are the actual output from the internal
-parser when created by the \function{expr()} or \function{suite()}
-functions, described below. The AST objects created by
-\function{sequence2ast()} faithfully simulate those structures. Be
-aware that the values of the sequences which are considered
-``correct'' will vary from one version of Python to another as the
-formal grammar for the language is revised. However, transporting
-code from one Python version to another as source text will always
-allow correct parse trees to be created in the target version, with
-the only restriction being that migrating to an older version of the
-interpreter will not support more recent language constructs. The
-parse trees are not typically compatible from one version to another,
-whereas source code has always been forward-compatible.
-
-Each element of the sequences returned by \function{ast2list()} or
-\function{ast2tuple()} has a simple form. Sequences representing
-non-terminal elements in the grammar always have a length greater than
-one. The first element is an integer which identifies a production in
-the grammar. These integers are given symbolic names in the C header
-file \file{Include/graminit.h} and the Python module
-\refmodule{symbol}. Each additional element of the sequence represents
-a component of the production as recognized in the input string: these
-are always sequences which have the same form as the parent. An
-important aspect of this structure which should be noted is that
-keywords used to identify the parent node type, such as the keyword
-\keyword{if} in an \constant{if_stmt}, are included in the node tree without
-any special treatment. For example, the \keyword{if} keyword is
-represented by the tuple \code{(1, 'if')}, where \code{1} is the
-numeric value associated with all \constant{NAME} tokens, including
-variable and function names defined by the user. In an alternate form
-returned when line number information is requested, the same token
-might be represented as \code{(1, 'if', 12)}, where the \code{12}
-represents the line number at which the terminal symbol was found.
-
-Terminal elements are represented in much the same way, but without
-any child elements and the addition of the source text which was
-identified. The example of the \keyword{if} keyword above is
-representative. The various types of terminal symbols are defined in
-the C header file \file{Include/token.h} and the Python module
-\refmodule{token}.
-
-The AST objects are not required to support the functionality of this
-module, but are provided for three purposes: to allow an application
-to amortize the cost of processing complex parse trees, to provide a
-parse tree representation which conserves memory space when compared
-to the Python list or tuple representation, and to ease the creation
-of additional modules in C which manipulate parse trees. A simple
-``wrapper'' class may be created in Python to hide the use of AST
-objects.
-
-The \module{parser} module defines functions for a few distinct
-purposes. The most important purposes are to create AST objects and
-to convert AST objects to other representations such as parse trees
-and compiled code objects, but there are also functions which serve to
-query the type of parse tree represented by an AST object.
-
-
-\begin{seealso}
- \seemodule{symbol}{Useful constants representing internal nodes of
- the parse tree.}
- \seemodule{token}{Useful constants representing leaf nodes of the
- parse tree and functions for testing node values.}
-\end{seealso}
-
-
-\subsection{Creating AST Objects \label{Creating ASTs}}
-
-AST objects may be created from source code or from a parse tree.
-When creating an AST object from source, different functions are used
-to create the \code{'eval'} and \code{'exec'} forms.
-
-\begin{funcdesc}{expr}{source}
-The \function{expr()} function parses the parameter \var{source}
-as if it were an input to \samp{compile(\var{source}, 'file.py',
-'eval')}. If the parse succeeds, an AST object is created to hold the
-internal parse tree representation, otherwise an appropriate exception
-is thrown.
-\end{funcdesc}
-
-\begin{funcdesc}{suite}{source}
-The \function{suite()} function parses the parameter \var{source}
-as if it were an input to \samp{compile(\var{source}, 'file.py',
-'exec')}. If the parse succeeds, an AST object is created to hold the
-internal parse tree representation, otherwise an appropriate exception
-is thrown.
-\end{funcdesc}
-
-\begin{funcdesc}{sequence2ast}{sequence}
-This function accepts a parse tree represented as a sequence and
-builds an internal representation if possible. If it can validate
-that the tree conforms to the Python grammar and all nodes are valid
-node types in the host version of Python, an AST object is created
-from the internal representation and returned to the called. If there
-is a problem creating the internal representation, or if the tree
-cannot be validated, a \exception{ParserError} exception is thrown. An AST
-object created this way should not be assumed to compile correctly;
-normal exceptions thrown by compilation may still be initiated when
-the AST object is passed to \function{compileast()}. This may indicate
-problems not related to syntax (such as a \exception{MemoryError}
-exception), but may also be due to constructs such as the result of
-parsing \code{del f(0)}, which escapes the Python parser but is
-checked by the bytecode compiler.
-
-Sequences representing terminal tokens may be represented as either
-two-element lists of the form \code{(1, 'name')} or as three-element
-lists of the form \code{(1, 'name', 56)}. If the third element is
-present, it is assumed to be a valid line number. The line number
-may be specified for any subset of the terminal symbols in the input
-tree.
-\end{funcdesc}
-
-\begin{funcdesc}{tuple2ast}{sequence}
-This is the same function as \function{sequence2ast()}. This entry point
-is maintained for backward compatibility.
-\end{funcdesc}
-
-
-\subsection{Converting AST Objects \label{Converting ASTs}}
-
-AST objects, regardless of the input used to create them, may be
-converted to parse trees represented as list- or tuple- trees, or may
-be compiled into executable code objects. Parse trees may be
-extracted with or without line numbering information.
-
-\begin{funcdesc}{ast2list}{ast\optional{, line_info}}
-This function accepts an AST object from the caller in
-\var{ast} and returns a Python list representing the
-equivalent parse tree. The resulting list representation can be used
-for inspection or the creation of a new parse tree in list form. This
-function does not fail so long as memory is available to build the
-list representation. If the parse tree will only be used for
-inspection, \function{ast2tuple()} should be used instead to reduce memory
-consumption and fragmentation. When the list representation is
-required, this function is significantly faster than retrieving a
-tuple representation and converting that to nested lists.
-
-If \var{line_info} is true, line number information will be
-included for all terminal tokens as a third element of the list
-representing the token. Note that the line number provided specifies
-the line on which the token \emph{ends}. This information is
-omitted if the flag is false or omitted.
-\end{funcdesc}
-
-\begin{funcdesc}{ast2tuple}{ast\optional{, line_info}}
-This function accepts an AST object from the caller in
-\var{ast} and returns a Python tuple representing the
-equivalent parse tree. Other than returning a tuple instead of a
-list, this function is identical to \function{ast2list()}.
-
-If \var{line_info} is true, line number information will be
-included for all terminal tokens as a third element of the list
-representing the token. This information is omitted if the flag is
-false or omitted.
-\end{funcdesc}
-
-\begin{funcdesc}{compileast}{ast\optional{, filename\code{ = '<ast>'}}}
-The Python byte compiler can be invoked on an AST object to produce
-code objects which can be used as part of a call to the built-in
-\function{exec()}\bifuncindex{exec} or \function{eval()}
-\bifuncindex{eval} functions.
-This function provides the interface to the compiler, passing the
-internal parse tree from \var{ast} to the parser, using the
-source file name specified by the \var{filename} parameter.
-The default value supplied for \var{filename} indicates that
-the source was an AST object.
-
-Compiling an AST object may result in exceptions related to
-compilation; an example would be a \exception{SyntaxError} caused by the
-parse tree for \code{del f(0)}: this statement is considered legal
-within the formal grammar for Python but is not a legal language
-construct. The \exception{SyntaxError} raised for this condition is
-actually generated by the Python byte-compiler normally, which is why
-it can be raised at this point by the \module{parser} module. Most
-causes of compilation failure can be diagnosed programmatically by
-inspection of the parse tree.
-\end{funcdesc}
-
-
-\subsection{Queries on AST Objects \label{Querying ASTs}}
-
-Two functions are provided which allow an application to determine if
-an AST was created as an expression or a suite. Neither of these
-functions can be used to determine if an AST was created from source
-code via \function{expr()} or \function{suite()} or from a parse tree
-via \function{sequence2ast()}.
-
-\begin{funcdesc}{isexpr}{ast}
-When \var{ast} represents an \code{'eval'} form, this function
-returns true, otherwise it returns false. This is useful, since code
-objects normally cannot be queried for this information using existing
-built-in functions. Note that the code objects created by
-\function{compileast()} cannot be queried like this either, and are
-identical to those created by the built-in
-\function{compile()}\bifuncindex{compile} function.
-\end{funcdesc}
-
-
-\begin{funcdesc}{issuite}{ast}
-This function mirrors \function{isexpr()} in that it reports whether an
-AST object represents an \code{'exec'} form, commonly known as a
-``suite.'' It is not safe to assume that this function is equivalent
-to \samp{not isexpr(\var{ast})}, as additional syntactic fragments may
-be supported in the future.
-\end{funcdesc}
-
-
-\subsection{Exceptions and Error Handling \label{AST Errors}}
-
-The parser module defines a single exception, but may also pass other
-built-in exceptions from other portions of the Python runtime
-environment. See each function for information about the exceptions
-it can raise.
-
-\begin{excdesc}{ParserError}
-Exception raised when a failure occurs within the parser module. This
-is generally produced for validation failures rather than the built in
-\exception{SyntaxError} thrown during normal parsing.
-The exception argument is either a string describing the reason of the
-failure or a tuple containing a sequence causing the failure from a parse
-tree passed to \function{sequence2ast()} and an explanatory string. Calls to
-\function{sequence2ast()} need to be able to handle either type of exception,
-while calls to other functions in the module will only need to be
-aware of the simple string values.
-\end{excdesc}
-
-Note that the functions \function{compileast()}, \function{expr()}, and
-\function{suite()} may throw exceptions which are normally thrown by the
-parsing and compilation process. These include the built in
-exceptions \exception{MemoryError}, \exception{OverflowError},
-\exception{SyntaxError}, and \exception{SystemError}. In these cases, these
-exceptions carry all the meaning normally associated with them. Refer
-to the descriptions of each function for detailed information.
-
-
-\subsection{AST Objects \label{AST Objects}}
-
-Ordered and equality comparisons are supported between AST objects.
-Pickling of AST objects (using the \refmodule{pickle} module) is also
-supported.
-
-\begin{datadesc}{ASTType}
-The type of the objects returned by \function{expr()},
-\function{suite()} and \function{sequence2ast()}.
-\end{datadesc}
-
-
-AST objects have the following methods:
-
-
-\begin{methoddesc}[AST]{compile}{\optional{filename}}
-Same as \code{compileast(\var{ast}, \var{filename})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{isexpr}{}
-Same as \code{isexpr(\var{ast})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{issuite}{}
-Same as \code{issuite(\var{ast})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{tolist}{\optional{line_info}}
-Same as \code{ast2list(\var{ast}, \var{line_info})}.
-\end{methoddesc}
-
-\begin{methoddesc}[AST]{totuple}{\optional{line_info}}
-Same as \code{ast2tuple(\var{ast}, \var{line_info})}.
-\end{methoddesc}
-
-
-\subsection{Examples \label{AST Examples}}
-
-The parser modules allows operations to be performed on the parse tree
-of Python source code before the bytecode is generated, and provides
-for inspection of the parse tree for information gathering purposes.
-Two examples are presented. The simple example demonstrates emulation
-of the \function{compile()}\bifuncindex{compile} built-in function and
-the complex example shows the use of a parse tree for information
-discovery.
-
-\subsubsection{Emulation of \function{compile()}}
-
-While many useful operations may take place between parsing and
-bytecode generation, the simplest operation is to do nothing. For
-this purpose, using the \module{parser} module to produce an
-intermediate data structure is equivalent to the code
-
-\begin{verbatim}
->>> code = compile('a + 5', 'file.py', 'eval')
->>> a = 5
->>> eval(code)
-10
-\end{verbatim}
-
-The equivalent operation using the \module{parser} module is somewhat
-longer, and allows the intermediate internal parse tree to be retained
-as an AST object:
-
-\begin{verbatim}
->>> import parser
->>> ast = parser.expr('a + 5')
->>> code = ast.compile('file.py')
->>> a = 5
->>> eval(code)
-10
-\end{verbatim}
-
-An application which needs both AST and code objects can package this
-code into readily available functions:
-
-\begin{verbatim}
-import parser
-
-def load_suite(source_string):
- ast = parser.suite(source_string)
- return ast, ast.compile()
-
-def load_expression(source_string):
- ast = parser.expr(source_string)
- return ast, ast.compile()
-\end{verbatim}
-
-\subsubsection{Information Discovery}
-
-Some applications benefit from direct access to the parse tree. The
-remainder of this section demonstrates how the parse tree provides
-access to module documentation defined in
-docstrings\index{string!documentation}\index{docstrings} without
-requiring that the code being examined be loaded into a running
-interpreter via \keyword{import}. This can be very useful for
-performing analyses of untrusted code.
-
-Generally, the example will demonstrate how the parse tree may be
-traversed to distill interesting information. Two functions and a set
-of classes are developed which provide programmatic access to high
-level function and class definitions provided by a module. The
-classes extract information from the parse tree and provide access to
-the information at a useful semantic level, one function provides a
-simple low-level pattern matching capability, and the other function
-defines a high-level interface to the classes by handling file
-operations on behalf of the caller. All source files mentioned here
-which are not part of the Python installation are located in the
-\file{Demo/parser/} directory of the distribution.
-
-The dynamic nature of Python allows the programmer a great deal of
-flexibility, but most modules need only a limited measure of this when
-defining classes, functions, and methods. In this example, the only
-definitions that will be considered are those which are defined in the
-top level of their context, e.g., a function defined by a \keyword{def}
-statement at column zero of a module, but not a function defined
-within a branch of an \keyword{if} ... \keyword{else} construct, though
-there are some good reasons for doing so in some situations. Nesting
-of definitions will be handled by the code developed in the example.
-
-To construct the upper-level extraction methods, we need to know what
-the parse tree structure looks like and how much of it we actually
-need to be concerned about. Python uses a moderately deep parse tree
-so there are a large number of intermediate nodes. It is important to
-read and understand the formal grammar used by Python. This is
-specified in the file \file{Grammar/Grammar} in the distribution.
-Consider the simplest case of interest when searching for docstrings:
-a module consisting of a docstring and nothing else. (See file
-\file{docstring.py}.)
-
-\begin{verbatim}
-"""Some documentation.
-"""
-\end{verbatim}
-
-Using the interpreter to take a look at the parse tree, we find a
-bewildering mass of numbers and parentheses, with the documentation
-buried deep in nested tuples.
-
-\begin{verbatim}
->>> import parser
->>> import pprint
->>> ast = parser.suite(open('docstring.py').read())
->>> tup = ast.totuple()
->>> pprint.pprint(tup)
-(257,
- (264,
- (265,
- (266,
- (267,
- (307,
- (287,
- (288,
- (289,
- (290,
- (292,
- (293,
- (294,
- (295,
- (296,
- (297,
- (298,
- (299,
- (300, (3, '"""Some documentation.\n"""'))))))))))))))))),
- (4, ''))),
- (4, ''),
- (0, ''))
-\end{verbatim}
-
-The numbers at the first element of each node in the tree are the node
-types; they map directly to terminal and non-terminal symbols in the
-grammar. Unfortunately, they are represented as integers in the
-internal representation, and the Python structures generated do not
-change that. However, the \refmodule{symbol} and \refmodule{token} modules
-provide symbolic names for the node types and dictionaries which map
-from the integers to the symbolic names for the node types.
-
-In the output presented above, the outermost tuple contains four
-elements: the integer \code{257} and three additional tuples. Node
-type \code{257} has the symbolic name \constant{file_input}. Each of
-these inner tuples contains an integer as the first element; these
-integers, \code{264}, \code{4}, and \code{0}, represent the node types
-\constant{stmt}, \constant{NEWLINE}, and \constant{ENDMARKER},
-respectively.
-Note that these values may change depending on the version of Python
-you are using; consult \file{symbol.py} and \file{token.py} for
-details of the mapping. It should be fairly clear that the outermost
-node is related primarily to the input source rather than the contents
-of the file, and may be disregarded for the moment. The \constant{stmt}
-node is much more interesting. In particular, all docstrings are
-found in subtrees which are formed exactly as this node is formed,
-with the only difference being the string itself. The association
-between the docstring in a similar tree and the defined entity (class,
-function, or module) which it describes is given by the position of
-the docstring subtree within the tree defining the described
-structure.
-
-By replacing the actual docstring with something to signify a variable
-component of the tree, we allow a simple pattern matching approach to
-check any given subtree for equivalence to the general pattern for
-docstrings. Since the example demonstrates information extraction, we
-can safely require that the tree be in tuple form rather than list
-form, allowing a simple variable representation to be
-\code{['variable_name']}. A simple recursive function can implement
-the pattern matching, returning a Boolean and a dictionary of variable
-name to value mappings. (See file \file{example.py}.)
-
-\begin{verbatim}
-from types import ListType, TupleType
-
-def match(pattern, data, vars=None):
- if vars is None:
- vars = {}
- if type(pattern) is ListType:
- vars[pattern[0]] = data
- return 1, vars
- if type(pattern) is not TupleType:
- return (pattern == data), vars
- if len(data) != len(pattern):
- return 0, vars
- for pattern, data in map(None, pattern, data):
- same, vars = match(pattern, data, vars)
- if not same:
- break
- return same, vars
-\end{verbatim}
-
-Using this simple representation for syntactic variables and the symbolic
-node types, the pattern for the candidate docstring subtrees becomes
-fairly readable. (See file \file{example.py}.)
-
-\begin{verbatim}
-import symbol
-import token
-
-DOCSTRING_STMT_PATTERN = (
- symbol.stmt,
- (symbol.simple_stmt,
- (symbol.small_stmt,
- (symbol.expr_stmt,
- (symbol.testlist,
- (symbol.test,
- (symbol.and_test,
- (symbol.not_test,
- (symbol.comparison,
- (symbol.expr,
- (symbol.xor_expr,
- (symbol.and_expr,
- (symbol.shift_expr,
- (symbol.arith_expr,
- (symbol.term,
- (symbol.factor,
- (symbol.power,
- (symbol.atom,
- (token.STRING, ['docstring'])
- )))))))))))))))),
- (token.NEWLINE, '')
- ))
-\end{verbatim}
-
-Using the \function{match()} function with this pattern, extracting the
-module docstring from the parse tree created previously is easy:
-
-\begin{verbatim}
->>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
->>> found
-1
->>> vars
-{'docstring': '"""Some documentation.\n"""'}
-\end{verbatim}
-
-Once specific data can be extracted from a location where it is
-expected, the question of where information can be expected
-needs to be answered. When dealing with docstrings, the answer is
-fairly simple: the docstring is the first \constant{stmt} node in a code
-block (\constant{file_input} or \constant{suite} node types). A module
-consists of a single \constant{file_input} node, and class and function
-definitions each contain exactly one \constant{suite} node. Classes and
-functions are readily identified as subtrees of code block nodes which
-start with \code{(stmt, (compound_stmt, (classdef, ...} or
-\code{(stmt, (compound_stmt, (funcdef, ...}. Note that these subtrees
-cannot be matched by \function{match()} since it does not support multiple
-sibling nodes to match without regard to number. A more elaborate
-matching function could be used to overcome this limitation, but this
-is sufficient for the example.
-
-Given the ability to determine whether a statement might be a
-docstring and extract the actual string from the statement, some work
-needs to be performed to walk the parse tree for an entire module and
-extract information about the names defined in each context of the
-module and associate any docstrings with the names. The code to
-perform this work is not complicated, but bears some explanation.
-
-The public interface to the classes is straightforward and should
-probably be somewhat more flexible. Each ``major'' block of the
-module is described by an object providing several methods for inquiry
-and a constructor which accepts at least the subtree of the complete
-parse tree which it represents. The \class{ModuleInfo} constructor
-accepts an optional \var{name} parameter since it cannot
-otherwise determine the name of the module.
-
-The public classes include \class{ClassInfo}, \class{FunctionInfo},
-and \class{ModuleInfo}. All objects provide the
-methods \method{get_name()}, \method{get_docstring()},
-\method{get_class_names()}, and \method{get_class_info()}. The
-\class{ClassInfo} objects support \method{get_method_names()} and
-\method{get_method_info()} while the other classes provide
-\method{get_function_names()} and \method{get_function_info()}.
-
-Within each of the forms of code block that the public classes
-represent, most of the required information is in the same form and is
-accessed in the same way, with classes having the distinction that
-functions defined at the top level are referred to as ``methods.''
-Since the difference in nomenclature reflects a real semantic
-distinction from functions defined outside of a class, the
-implementation needs to maintain the distinction.
-Hence, most of the functionality of the public classes can be
-implemented in a common base class, \class{SuiteInfoBase}, with the
-accessors for function and method information provided elsewhere.
-Note that there is only one class which represents function and method
-information; this parallels the use of the \keyword{def} statement to
-define both types of elements.
-
-Most of the accessor functions are declared in \class{SuiteInfoBase}
-and do not need to be overridden by subclasses. More importantly, the
-extraction of most information from a parse tree is handled through a
-method called by the \class{SuiteInfoBase} constructor. The example
-code for most of the classes is clear when read alongside the formal
-grammar, but the method which recursively creates new information
-objects requires further examination. Here is the relevant part of
-the \class{SuiteInfoBase} definition from \file{example.py}:
-
-\begin{verbatim}
-class SuiteInfoBase:
- _docstring = ''
- _name = ''
-
- def __init__(self, tree = None):
- self._class_info = {}
- self._function_info = {}
- if tree:
- self._extract_info(tree)
-
- def _extract_info(self, tree):
- # extract docstring
- if len(tree) == 2:
- found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
- else:
- found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
- if found:
- self._docstring = eval(vars['docstring'])
- # discover inner definitions
- for node in tree[1:]:
- found, vars = match(COMPOUND_STMT_PATTERN, node)
- if found:
- cstmt = vars['compound']
- if cstmt[0] == symbol.funcdef:
- name = cstmt[2][1]
- self._function_info[name] = FunctionInfo(cstmt)
- elif cstmt[0] == symbol.classdef:
- name = cstmt[2][1]
- self._class_info[name] = ClassInfo(cstmt)
-\end{verbatim}
-
-After initializing some internal state, the constructor calls the
-\method{_extract_info()} method. This method performs the bulk of the
-information extraction which takes place in the entire example. The
-extraction has two distinct phases: the location of the docstring for
-the parse tree passed in, and the discovery of additional definitions
-within the code block represented by the parse tree.
-
-The initial \keyword{if} test determines whether the nested suite is of
-the ``short form'' or the ``long form.'' The short form is used when
-the code block is on the same line as the definition of the code
-block, as in
-
-\begin{verbatim}
-def square(x): "Square an argument."; return x ** 2
-\end{verbatim}
-
-while the long form uses an indented block and allows nested
-definitions:
-
-\begin{verbatim}
-def make_power(exp):
- "Make a function that raises an argument to the exponent `exp'."
- def raiser(x, y=exp):
- return x ** y
- return raiser
-\end{verbatim}
-
-When the short form is used, the code block may contain a docstring as
-the first, and possibly only, \constant{small_stmt} element. The
-extraction of such a docstring is slightly different and requires only
-a portion of the complete pattern used in the more common case. As
-implemented, the docstring will only be found if there is only
-one \constant{small_stmt} node in the \constant{simple_stmt} node.
-Since most functions and methods which use the short form do not
-provide a docstring, this may be considered sufficient. The
-extraction of the docstring proceeds using the \function{match()} function
-as described above, and the value of the docstring is stored as an
-attribute of the \class{SuiteInfoBase} object.
-
-After docstring extraction, a simple definition discovery
-algorithm operates on the \constant{stmt} nodes of the
-\constant{suite} node. The special case of the short form is not
-tested; since there are no \constant{stmt} nodes in the short form,
-the algorithm will silently skip the single \constant{simple_stmt}
-node and correctly not discover any nested definitions.
-
-Each statement in the code block is categorized as
-a class definition, function or method definition, or
-something else. For the definition statements, the name of the
-element defined is extracted and a representation object
-appropriate to the definition is created with the defining subtree
-passed as an argument to the constructor. The representation objects
-are stored in instance variables and may be retrieved by name using
-the appropriate accessor methods.
-
-The public classes provide any accessors required which are more
-specific than those provided by the \class{SuiteInfoBase} class, but
-the real extraction algorithm remains common to all forms of code
-blocks. A high-level function can be used to extract the complete set
-of information from a source file. (See file \file{example.py}.)
-
-\begin{verbatim}
-def get_docs(fileName):
- import os
- import parser
-
- source = open(fileName).read()
- basename = os.path.basename(os.path.splitext(fileName)[0])
- ast = parser.suite(source)
- return ModuleInfo(ast.totuple(), basename)
-\end{verbatim}
-
-This provides an easy-to-use interface to the documentation of a
-module. If information is required which is not extracted by the code
-of this example, the code may be extended at clearly defined points to
-provide additional capabilities.
diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex
deleted file mode 100644
index 45e778c..0000000
--- a/Doc/lib/libpdb.tex
+++ /dev/null
@@ -1,464 +0,0 @@
-\chapter{The Python Debugger \label{debugger}}
-
-\declaremodule{standard}{pdb}
-\modulesynopsis{The Python debugger for interactive interpreters.}
-
-
-The module \module{pdb} defines an interactive source code
-debugger\index{debugging} for Python programs. It supports setting
-(conditional) breakpoints and single stepping at the source line
-level, inspection of stack frames, source code listing, and evaluation
-of arbitrary Python code in the context of any stack frame. It also
-supports post-mortem debugging and can be called under program
-control.
-
-The debugger is extensible --- it is actually defined as the class
-\class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}.
-This is currently undocumented but easily understood by reading the
-source. The extension interface uses the modules
-\module{bdb}\refstmodindex{bdb} (undocumented) and
-\refmodule{cmd}\refstmodindex{cmd}.
-
-The debugger's prompt is \samp{(Pdb) }.
-Typical usage to run a program under control of the debugger is:
-
-\begin{verbatim}
->>> import pdb
->>> import mymodule
->>> pdb.run('mymodule.test()')
-> <string>(0)?()
-(Pdb) continue
-> <string>(1)?()
-(Pdb) continue
-NameError: 'spam'
-> <string>(1)?()
-(Pdb)
-\end{verbatim}
-
-\file{pdb.py} can also be invoked as
-a script to debug other scripts. For example:
-
-\begin{verbatim}
-python -m pdb myscript.py
-\end{verbatim}
-
-When invoked as a script, pdb will automatically enter post-mortem debugging
-if the program being debugged exits abnormally. After post-mortem debugging
-(or after normal exit of the program), pdb will restart the program.
-Automatic restarting preserves pdb's state (such as breakpoints) and in most
-cases is more useful than quitting the debugger upon program's exit.
-\versionadded[Restarting post-mortem behavior added]{2.4}
-
-Typical usage to inspect a crashed program is:
-
-\begin{verbatim}
->>> import pdb
->>> import mymodule
->>> mymodule.test()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "./mymodule.py", line 4, in test
- test2()
- File "./mymodule.py", line 3, in test2
- print spam
-NameError: spam
->>> pdb.pm()
-> ./mymodule.py(3)test2()
--> print spam
-(Pdb)
-\end{verbatim}
-
-The module defines the following functions; each enters the debugger
-in a slightly different way:
-
-\begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}}
-Execute the \var{statement} (given as a string) under debugger
-control. The debugger prompt appears before any code is executed; you
-can set breakpoints and type \samp{continue}, or you can step through
-the statement using \samp{step} or \samp{next} (all these commands are
-explained below). The optional \var{globals} and \var{locals}
-arguments specify the environment in which the code is executed; by
-default the dictionary of the module \refmodule[main]{__main__} is
-used. (See the explanation of the built-in \function{exec()} or
-\function{eval()} functions.)
-\end{funcdesc}
-
-\begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}}
-Evaluate the \var{expression} (given as a string) under debugger
-control. When \function{runeval()} returns, it returns the value of the
-expression. Otherwise this function is similar to
-\function{run()}.
-\end{funcdesc}
-
-\begin{funcdesc}{runcall}{function\optional{, argument, ...}}
-Call the \var{function} (a function or method object, not a string)
-with the given arguments. When \function{runcall()} returns, it returns
-whatever the function call returned. The debugger prompt appears as
-soon as the function is entered.
-\end{funcdesc}
-
-\begin{funcdesc}{set_trace}{}
-Enter the debugger at the calling stack frame. This is useful to
-hard-code a breakpoint at a given point in a program, even if the code
-is not otherwise being debugged (e.g. when an assertion fails).
-\end{funcdesc}
-
-\begin{funcdesc}{post_mortem}{traceback}
-Enter post-mortem debugging of the given \var{traceback} object.
-\end{funcdesc}
-
-\begin{funcdesc}{pm}{}
-Enter post-mortem debugging of the traceback found in
-\code{sys.last_traceback}.
-\end{funcdesc}
-
-
-\section{Debugger Commands \label{debugger-commands}}
-
-The debugger recognizes the following commands. Most commands can be
-abbreviated to one or two letters; e.g. \samp{h(elp)} means that
-either \samp{h} or \samp{help} can be used to enter the help
-command (but not \samp{he} or \samp{hel}, nor \samp{H} or
-\samp{Help} or \samp{HELP}). Arguments to commands must be
-separated by whitespace (spaces or tabs). Optional arguments are
-enclosed in square brackets (\samp{[]}) in the command syntax; the
-square brackets must not be typed. Alternatives in the command syntax
-are separated by a vertical bar (\samp{|}).
-
-Entering a blank line repeats the last command entered. Exception: if
-the last command was a \samp{list} command, the next 11 lines are
-listed.
-
-Commands that the debugger doesn't recognize are assumed to be Python
-statements and are executed in the context of the program being
-debugged. Python statements can also be prefixed with an exclamation
-point (\samp{!}). This is a powerful way to inspect the program
-being debugged; it is even possible to change a variable or call a
-function. When an
-exception occurs in such a statement, the exception name is printed
-but the debugger's state is not changed.
-
-Multiple commands may be entered on a single line, separated by
-\samp{;;}. (A single \samp{;} is not used as it is
-the separator for multiple commands in a line that is passed to
-the Python parser.)
-No intelligence is applied to separating the commands;
-the input is split at the first \samp{;;} pair, even if it is in
-the middle of a quoted string.
-
-The debugger supports aliases. Aliases can have parameters which
-allows one a certain level of adaptability to the context under
-examination.
-
-If a file \file{.pdbrc}
-\indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file}
-exists in the user's home directory or in the current directory, it is
-read in and executed as if it had been typed at the debugger prompt.
-This is particularly useful for aliases. If both files exist, the one
-in the home directory is read first and aliases defined there can be
-overridden by the local file.
-
-\begin{description}
-
-\item[h(elp) \optional{\var{command}}]
-
-Without argument, print the list of available commands. With a
-\var{command} as argument, print help about that command. \samp{help
-pdb} displays the full documentation file; if the environment variable
-\envvar{PAGER} is defined, the file is piped through that command
-instead. Since the \var{command} argument must be an identifier,
-\samp{help exec} must be entered to get help on the \samp{!} command.
-
-\item[w(here)]
-
-Print a stack trace, with the most recent frame at the bottom. An
-arrow indicates the current frame, which determines the context of
-most commands.
-
-\item[d(own)]
-
-Move the current frame one level down in the stack trace
-(to a newer frame).
-
-\item[u(p)]
-
-Move the current frame one level up in the stack trace
-(to an older frame).
-
-\item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}]
-
-With a \var{lineno} argument, set a break there in the current
-file. With a \var{function} argument, set a break at the first
-executable statement within that function.
-The line number may be prefixed with a filename and a colon,
-to specify a breakpoint in another file (probably one that
-hasn't been loaded yet). The file is searched on \code{sys.path}.
-Note that each breakpoint is assigned a number to which all the other
-breakpoint commands refer.
-
-If a second argument is present, it is an expression which must
-evaluate to true before the breakpoint is honored.
-
-Without argument, list all breaks, including for each breakpoint,
-the number of times that breakpoint has been hit, the current
-ignore count, and the associated condition if any.
-
-\item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}]
-
-Temporary breakpoint, which is removed automatically when it is
-first hit. The arguments are the same as break.
-
-\item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
-
-With a space separated list of breakpoint numbers, clear those
-breakpoints. Without argument, clear all breaks (but first
-ask confirmation).
-
-\item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
-
-Disables the breakpoints given as a space separated list of
-breakpoint numbers. Disabling a breakpoint means it cannot cause
-the program to stop execution, but unlike clearing a breakpoint, it
-remains in the list of breakpoints and can be (re-)enabled.
-
-\item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}]
-
-Enables the breakpoints specified.
-
-\item[ignore \var{bpnumber} \optional{\var{count}}]
-
-Sets the ignore count for the given breakpoint number. If
-count is omitted, the ignore count is set to 0. A breakpoint
-becomes active when the ignore count is zero. When non-zero,
-the count is decremented each time the breakpoint is reached
-and the breakpoint is not disabled and any associated condition
-evaluates to true.
-
-\item[condition \var{bpnumber} \optional{\var{condition}}]
-
-Condition is an expression which must evaluate to true before
-the breakpoint is honored. If condition is absent, any existing
-condition is removed; i.e., the breakpoint is made unconditional.
-
-\item[commands \optional{\var{bpnumber}}]
-
-Specify a list of commands for breakpoint number \var{bpnumber}. The
-commands themselves appear on the following lines. Type a line
-containing just 'end' to terminate the commands. An example:
-
-\begin{verbatim}
-(Pdb) commands 1
-(com) print some_variable
-(com) end
-(Pdb)
-\end{verbatim}
-
-To remove all commands from a breakpoint, type commands and
-follow it immediately with end; that is, give no commands.
-
-With no \var{bpnumber} argument, commands refers to the last
-breakpoint set.
-
-You can use breakpoint commands to start your program up again.
-Simply use the continue command, or step, or any other
-command that resumes execution.
-
-Specifying any command resuming execution (currently continue,
-step, next, return, jump, quit and their abbreviations) terminates
-the command list (as if that command was immediately followed by end).
-This is because any time you resume execution
-(even with a simple next or step), you may encounter·
-another breakpoint--which could have its own command list, leading to
-ambiguities about which list to execute.
-
- If you use the 'silent' command in the command list, the
-usual message about stopping at a breakpoint is not printed. This may
-be desirable for breakpoints that are to print a specific message and
-then continue. If none of the other commands print anything, you
-see no sign that the breakpoint was reached.
-
-\versionadded{2.5}
-
-\item[s(tep)]
-
-Execute the current line, stop at the first possible occasion
-(either in a function that is called or on the next line in the
-current function).
-
-\item[n(ext)]
-
-Continue execution until the next line in the current function
-is reached or it returns. (The difference between \samp{next} and
-\samp{step} is that \samp{step} stops inside a called function, while
-\samp{next} executes called functions at (nearly) full speed, only
-stopping at the next line in the current function.)
-
-\item[r(eturn)]
-
-Continue execution until the current function returns.
-
-\item[c(ont(inue))]
-
-Continue execution, only stop when a breakpoint is encountered.
-
-\item[j(ump) \var{lineno}]
-
-Set the next line that will be executed. Only available in the
-bottom-most frame. This lets you jump back and execute code
-again, or jump forward to skip code that you don't want to run.
-
-It should be noted that not all jumps are allowed --- for instance it
-is not possible to jump into the middle of a \keyword{for} loop or out
-of a \keyword{finally} clause.
-
-\item[l(ist) \optional{\var{first}\optional{, \var{last}}}]
-
-List source code for the current file. Without arguments, list 11
-lines around the current line or continue the previous listing. With
-one argument, list 11 lines around at that line. With two arguments,
-list the given range; if the second argument is less than the first,
-it is interpreted as a count.
-
-\item[a(rgs)]
-
-Print the argument list of the current function.
-
-\item[p \var{expression}]
-
-Evaluate the \var{expression} in the current context and print its
-value. \note{\samp{print} can also be used, but is not a debugger
-command --- this executes the Python \keyword{print} statement.}
-
-\item[pp \var{expression}]
-
-Like the \samp{p} command, except the value of the expression is
-pretty-printed using the \module{pprint} module.
-
-\item[alias \optional{\var{name} \optional{command}}]
-
-Creates an alias called \var{name} that executes \var{command}. The
-command must \emph{not} be enclosed in quotes. Replaceable parameters
-can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is
-replaced by all the parameters. If no command is given, the current
-alias for \var{name} is shown. If no arguments are given, all
-aliases are listed.
-
-Aliases may be nested and can contain anything that can be
-legally typed at the pdb prompt. Note that internal pdb commands
-\emph{can} be overridden by aliases. Such a command is
-then hidden until the alias is removed. Aliasing is recursively
-applied to the first word of the command line; all other words
-in the line are left alone.
-
-As an example, here are two useful aliases (especially when placed
-in the \file{.pdbrc} file):
-
-\begin{verbatim}
-#Print instance variables (usage "pi classInst")
-alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
-#Print instance variables in self
-alias ps pi self
-\end{verbatim}
-
-\item[unalias \var{name}]
-
-Deletes the specified alias.
-
-\item[\optional{!}\var{statement}]
-
-Execute the (one-line) \var{statement} in the context of
-the current stack frame.
-The exclamation point can be omitted unless the first word
-of the statement resembles a debugger command.
-To set a global variable, you can prefix the assignment
-command with a \samp{global} command on the same line, e.g.:
-
-\begin{verbatim}
-(Pdb) global list_options; list_options = ['-l']
-(Pdb)
-\end{verbatim}
-
-\item[run \optional{\var{args} ...}]
-Restart the debugged python program. If an argument is supplied, it is
-splitted with "shlex" and the result is used as the new sys.argv.
-History, breakpoints, actions and debugger options are preserved.
-"restart" is an alias for "run".
-
-\versionadded{2.6}
-
-\item[q(uit)]
-
-Quit from the debugger.
-The program being executed is aborted.
-
-\end{description}
-
-\section{How It Works \label{debugger-hooks}}
-
-Some changes were made to the interpreter:
-
-\begin{itemize}
-\item \code{sys.settrace(\var{func})} sets the global trace function
-\item there can also a local trace function (see later)
-\end{itemize}
-
-Trace functions have three arguments: \var{frame}, \var{event}, and
-\var{arg}. \var{frame} is the current stack frame. \var{event} is a
-string: \code{'call'}, \code{'line'}, \code{'return'}, \code{'exception'},
- \code{'c_call'}, \code{'c_return'}, or \code{'c_exception'}. \var{arg}
- depends on the event type.
-
-The global trace function is invoked (with \var{event} set to
-\code{'call'}) whenever a new local scope is entered; it should return
-a reference to the local trace function to be used that scope, or
-\code{None} if the scope shouldn't be traced.
-
-The local trace function should return a reference to itself (or to
-another function for further tracing in that scope), or \code{None} to
-turn off tracing in that scope.
-
-Instance methods are accepted (and very useful!) as trace functions.
-
-The events have the following meaning:
-
-\begin{description}
-
-\item[\code{'call'}]
-A function is called (or some other code block entered). The global
-trace function is called; \var{arg} is \code{None};
-the return value specifies the local trace function.
-
-\item[\code{'line'}]
-The interpreter is about to execute a new line of code (sometimes
-multiple line events on one line exist). The local trace function is
-called; \var{arg} is \code{None}; the return value specifies the new
-local trace function.
-
-\item[\code{'return'}]
-A function (or other code block) is about to return. The local trace
-function is called; \var{arg} is the value that will be returned. The
-trace function's return value is ignored.
-
-\item[\code{'exception'}]
-An exception has occurred. The local trace function is called;
-\var{arg} is a triple \code{(\var{exception}, \var{value},
-\var{traceback})}; the return value specifies the new local trace
-function.
-
-\item[\code{'c_call'}]
-A C function is about to be called. This may be an extension function
-or a builtin. \var{arg} is the C function object.
-
-\item[\code{'c_return'}]
-A C function has returned. \var{arg} is \code{None}.
-
-\item[\code{'c_exception'}]
-A C function has thrown an exception. \var{arg} is \code{None}.
-
-\end{description}
-
-Note that as an exception is propagated down the chain of callers, an
-\code{'exception'} event is generated at each level.
-
-For more information on code and frame objects, refer to the
-\citetitle[../ref/ref.html]{Python Reference Manual}.
diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
deleted file mode 100644
index 0c4cd98..0000000
--- a/Doc/lib/libpickle.tex
+++ /dev/null
@@ -1,888 +0,0 @@
-\section{\module{pickle} --- Python object serialization}
-
-\declaremodule{standard}{pickle}
-\modulesynopsis{Convert Python objects to streams of bytes and back.}
-% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>.
-% Rewritten by Barry Warsaw <barry@zope.com>
-
-\index{persistence}
-\indexii{persistent}{objects}
-\indexii{serializing}{objects}
-\indexii{marshalling}{objects}
-\indexii{flattening}{objects}
-\indexii{pickling}{objects}
-
-The \module{pickle} module implements a fundamental, but powerful
-algorithm for serializing and de-serializing a Python object
-structure. ``Pickling'' is the process whereby a Python object
-hierarchy is converted into a byte stream, and ``unpickling'' is the
-inverse operation, whereby a byte stream is converted back into an
-object hierarchy. Pickling (and unpickling) is alternatively known as
-``serialization'', ``marshalling,''\footnote{Don't confuse this with
-the \refmodule{marshal} module} or ``flattening'',
-however, to avoid confusion, the terms used here are ``pickling'' and
-``unpickling''.
-
-This documentation describes both the \module{pickle} module and the
-\refmodule{cPickle} module.
-
-\subsection{Relationship to other Python modules}
-
-The \module{pickle} module has an optimized cousin called the
-\module{cPickle} module. As its name implies, \module{cPickle} is
-written in C, so it can be up to 1000 times faster than
-\module{pickle}. However it does not support subclassing of the
-\function{Pickler()} and \function{Unpickler()} classes, because in
-\module{cPickle} these are functions, not classes. Most applications
-have no need for this functionality, and can benefit from the improved
-performance of \module{cPickle}. Other than that, the interfaces of
-the two modules are nearly identical; the common interface is
-described in this manual and differences are pointed out where
-necessary. In the following discussions, we use the term ``pickle''
-to collectively describe the \module{pickle} and
-\module{cPickle} modules.
-
-The data streams the two modules produce are guaranteed to be
-interchangeable.
-
-Python has a more primitive serialization module called
-\refmodule{marshal}, but in general
-\module{pickle} should always be the preferred way to serialize Python
-objects. \module{marshal} exists primarily to support Python's
-\file{.pyc} files.
-
-The \module{pickle} module differs from \refmodule{marshal} several
-significant ways:
-
-\begin{itemize}
-
-\item The \module{pickle} module keeps track of the objects it has
- already serialized, so that later references to the same object
- won't be serialized again. \module{marshal} doesn't do this.
-
- This has implications both for recursive objects and object
- sharing. Recursive objects are objects that contain references
- to themselves. These are not handled by marshal, and in fact,
- attempting to marshal recursive objects will crash your Python
- interpreter. Object sharing happens when there are multiple
- references to the same object in different places in the object
- hierarchy being serialized. \module{pickle} stores such objects
- only once, and ensures that all other references point to the
- master copy. Shared objects remain shared, which can be very
- important for mutable objects.
-
-\item \module{marshal} cannot be used to serialize user-defined
- classes and their instances. \module{pickle} can save and
- restore class instances transparently, however the class
- definition must be importable and live in the same module as
- when the object was stored.
-
-\item The \module{marshal} serialization format is not guaranteed to
- be portable across Python versions. Because its primary job in
- life is to support \file{.pyc} files, the Python implementers
- reserve the right to change the serialization format in
- non-backwards compatible ways should the need arise. The
- \module{pickle} serialization format is guaranteed to be
- backwards compatible across Python releases.
-
-\end{itemize}
-
-\begin{notice}[warning]
-The \module{pickle} module is not intended to be secure against
-erroneous or maliciously constructed data. Never unpickle data
-received from an untrusted or unauthenticated source.
-\end{notice}
-
-Note that serialization is a more primitive notion than persistence;
-although
-\module{pickle} reads and writes file objects, it does not handle the
-issue of naming persistent objects, nor the (even more complicated)
-issue of concurrent access to persistent objects. The \module{pickle}
-module can transform a complex object into a byte stream and it can
-transform the byte stream into an object with the same internal
-structure. Perhaps the most obvious thing to do with these byte
-streams is to write them onto a file, but it is also conceivable to
-send them across a network or store them in a database. The module
-\refmodule{shelve} provides a simple interface
-to pickle and unpickle objects on DBM-style database files.
-
-\subsection{Data stream format}
-
-The data format used by \module{pickle} is Python-specific. This has
-the advantage that there are no restrictions imposed by external
-standards such as XDR\index{XDR}\index{External Data Representation}
-(which can't represent pointer sharing); however it means that
-non-Python programs may not be able to reconstruct pickled Python
-objects.
-
-By default, the \module{pickle} data format uses a printable \ASCII{}
-representation. This is slightly more voluminous than a binary
-representation. The big advantage of using printable \ASCII{} (and of
-some other characteristics of \module{pickle}'s representation) is that
-for debugging or recovery purposes it is possible for a human to read
-the pickled file with a standard text editor.
-
-There are currently 3 different protocols which can be used for pickling.
-
-\begin{itemize}
-
-\item Protocol version 0 is the original ASCII protocol and is backwards
-compatible with earlier versions of Python.
-
-\item Protocol version 1 is the old binary format which is also compatible
-with earlier versions of Python.
-
-\item Protocol version 2 was introduced in Python 2.3. It provides
-much more efficient pickling of new-style classes.
-
-\end{itemize}
-
-Refer to PEP 307 for more information.
-
-If a \var{protocol} is not specified, protocol 0 is used.
-If \var{protocol} is specified as a negative value
-or \constant{HIGHEST_PROTOCOL},
-the highest protocol version available will be used.
-
-\versionchanged[Introduced the \var{protocol} parameter]{2.3}
-
-A binary format, which is slightly more efficient, can be chosen by
-specifying a \var{protocol} version >= 1.
-
-\subsection{Usage}
-
-To serialize an object hierarchy, you first create a pickler, then you
-call the pickler's \method{dump()} method. To de-serialize a data
-stream, you first create an unpickler, then you call the unpickler's
-\method{load()} method. The \module{pickle} module provides the
-following constant:
-
-\begin{datadesc}{HIGHEST_PROTOCOL}
-The highest protocol version available. This value can be passed
-as a \var{protocol} value.
-\versionadded{2.3}
-\end{datadesc}
-
-\note{Be sure to always open pickle files created with protocols >= 1 in
- binary mode. For the old ASCII-based pickle protocol 0 you can use
- either text mode or binary mode as long as you stay consistent.
-
- A pickle file written with protocol 0 in binary mode will contain
- lone linefeeds as line terminators and therefore will look ``funny''
- when viewed in Notepad or other editors which do not support this
- format.}
-
-The \module{pickle} module provides the
-following functions to make the pickling process more convenient:
-
-\begin{funcdesc}{dump}{obj, file\optional{, protocol}}
-Write a pickled representation of \var{obj} to the open file object
-\var{file}. This is equivalent to
-\code{Pickler(\var{file}, \var{protocol}).dump(\var{obj})}.
-
-If the \var{protocol} parameter is omitted, protocol 0 is used.
-If \var{protocol} is specified as a negative value
-or \constant{HIGHEST_PROTOCOL},
-the highest protocol version will be used.
-
-\versionchanged[Introduced the \var{protocol} parameter]{2.3}
-
-\var{file} must have a \method{write()} method that accepts a single
-string argument. It can thus be a file object opened for writing, a
-\refmodule{StringIO} object, or any other custom
-object that meets this interface.
-\end{funcdesc}
-
-\begin{funcdesc}{load}{file}
-Read a string from the open file object \var{file} and interpret it as
-a pickle data stream, reconstructing and returning the original object
-hierarchy. This is equivalent to \code{Unpickler(\var{file}).load()}.
-
-\var{file} must have two methods, a \method{read()} method that takes
-an integer argument, and a \method{readline()} method that requires no
-arguments. Both methods should return a string. Thus \var{file} can
-be a file object opened for reading, a
-\module{StringIO} object, or any other custom
-object that meets this interface.
-
-This function automatically determines whether the data stream was
-written in binary mode or not.
-\end{funcdesc}
-
-\begin{funcdesc}{dumps}{obj\optional{, protocol}}
-Return the pickled representation of the object as a string, instead
-of writing it to a file.
-
-If the \var{protocol} parameter is omitted, protocol 0 is used.
-If \var{protocol} is specified as a negative value
-or \constant{HIGHEST_PROTOCOL},
-the highest protocol version will be used.
-
-\versionchanged[The \var{protocol} parameter was added]{2.3}
-
-\end{funcdesc}
-
-\begin{funcdesc}{loads}{string}
-Read a pickled object hierarchy from a string. Characters in the
-string past the pickled object's representation are ignored.
-\end{funcdesc}
-
-The \module{pickle} module also defines three exceptions:
-
-\begin{excdesc}{PickleError}
-A common base class for the other exceptions defined below. This
-inherits from \exception{Exception}.
-\end{excdesc}
-
-\begin{excdesc}{PicklingError}
-This exception is raised when an unpicklable object is passed to
-the \method{dump()} method.
-\end{excdesc}
-
-\begin{excdesc}{UnpicklingError}
-This exception is raised when there is a problem unpickling an object.
-Note that other exceptions may also be raised during unpickling,
-including (but not necessarily limited to) \exception{AttributeError},
-\exception{EOFError}, \exception{ImportError}, and \exception{IndexError}.
-\end{excdesc}
-
-The \module{pickle} module also exports two callables\footnote{In the
-\module{pickle} module these callables are classes, which you could
-subclass to customize the behavior. However, in the \refmodule{cPickle}
-module these callables are factory functions and so cannot be
-subclassed. One common reason to subclass is to control what
-objects can actually be unpickled. See section~\ref{pickle-sub} for
-more details.}, \class{Pickler} and \class{Unpickler}:
-
-\begin{classdesc}{Pickler}{file\optional{, protocol}}
-This takes a file-like object to which it will write a pickle data
-stream.
-
-If the \var{protocol} parameter is omitted, protocol 0 is used.
-If \var{protocol} is specified as a negative value,
-the highest protocol version will be used.
-
-\versionchanged[Introduced the \var{protocol} parameter]{2.3}
-
-\var{file} must have a \method{write()} method that accepts a single
-string argument. It can thus be an open file object, a
-\module{StringIO} object, or any other custom
-object that meets this interface.
-\end{classdesc}
-
-\class{Pickler} objects define one (or two) public methods:
-
-\begin{methoddesc}[Pickler]{dump}{obj}
-Write a pickled representation of \var{obj} to the open file object
-given in the constructor. Either the binary or \ASCII{} format will
-be used, depending on the value of the \var{protocol} argument passed to the
-constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Pickler]{clear_memo}{}
-Clears the pickler's ``memo''. The memo is the data structure that
-remembers which objects the pickler has already seen, so that shared
-or recursive objects pickled by reference and not by value. This
-method is useful when re-using picklers.
-
-\begin{notice}
-Prior to Python 2.3, \method{clear_memo()} was only available on the
-picklers created by \refmodule{cPickle}. In the \module{pickle} module,
-picklers have an instance variable called \member{memo} which is a
-Python dictionary. So to clear the memo for a \module{pickle} module
-pickler, you could do the following:
-
-\begin{verbatim}
-mypickler.memo.clear()
-\end{verbatim}
-
-Code that does not need to support older versions of Python should
-simply use \method{clear_memo()}.
-\end{notice}
-\end{methoddesc}
-
-It is possible to make multiple calls to the \method{dump()} method of
-the same \class{Pickler} instance. These must then be matched to the
-same number of calls to the \method{load()} method of the
-corresponding \class{Unpickler} instance. If the same object is
-pickled by multiple \method{dump()} calls, the \method{load()} will
-all yield references to the same object.\footnote{\emph{Warning}: this
-is intended for pickling multiple objects without intervening
-modifications to the objects or their parts. If you modify an object
-and then pickle it again using the same \class{Pickler} instance, the
-object is not pickled again --- a reference to it is pickled and the
-\class{Unpickler} will return the old value, not the modified one.
-There are two problems here: (1) detecting changes, and (2)
-marshalling a minimal set of changes. Garbage Collection may also
-become a problem here.}
-
-\class{Unpickler} objects are defined as:
-
-\begin{classdesc}{Unpickler}{file}
-This takes a file-like object from which it will read a pickle data
-stream. This class automatically determines whether the data stream
-was written in binary mode or not, so it does not need a flag as in
-the \class{Pickler} factory.
-
-\var{file} must have two methods, a \method{read()} method that takes
-an integer argument, and a \method{readline()} method that requires no
-arguments. Both methods should return a string. Thus \var{file} can
-be a file object opened for reading, a
-\module{StringIO} object, or any other custom
-object that meets this interface.
-\end{classdesc}
-
-\class{Unpickler} objects have one (or two) public methods:
-
-\begin{methoddesc}[Unpickler]{load}{}
-Read a pickled object representation from the open file object given
-in the constructor, and return the reconstituted object hierarchy
-specified therein.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpickler]{noload}{}
-This is just like \method{load()} except that it doesn't actually
-create any objects. This is useful primarily for finding what's
-called ``persistent ids'' that may be referenced in a pickle data
-stream. See section~\ref{pickle-protocol} below for more details.
-
-\strong{Note:} the \method{noload()} method is currently only
-available on \class{Unpickler} objects created with the
-\module{cPickle} module. \module{pickle} module \class{Unpickler}s do
-not have the \method{noload()} method.
-\end{methoddesc}
-
-\subsection{What can be pickled and unpickled?}
-
-The following types can be pickled:
-
-\begin{itemize}
-
-\item \code{None}, \code{True}, and \code{False}
-
-\item integers, long integers, floating point numbers, complex numbers
-
-\item normal and Unicode strings
-
-\item tuples, lists, sets, and dictionaries containing only picklable objects
-
-\item functions defined at the top level of a module
-
-\item built-in functions defined at the top level of a module
-
-\item classes that are defined at the top level of a module
-
-\item instances of such classes whose \member{__dict__} or
-\method{__setstate__()} is picklable (see
-section~\ref{pickle-protocol} for details)
-
-\end{itemize}
-
-Attempts to pickle unpicklable objects will raise the
-\exception{PicklingError} exception; when this happens, an unspecified
-number of bytes may have already been written to the underlying file.
-Trying to pickle a highly recursive data structure may exceed the
-maximum recursion depth, a \exception{RuntimeError} will be raised
-in this case. You can carefully raise this limit with
-\function{sys.setrecursionlimit()}.
-
-Note that functions (built-in and user-defined) are pickled by ``fully
-qualified'' name reference, not by value. This means that only the
-function name is pickled, along with the name of module the function
-is defined in. Neither the function's code, nor any of its function
-attributes are pickled. Thus the defining module must be importable
-in the unpickling environment, and the module must contain the named
-object, otherwise an exception will be raised.\footnote{The exception
-raised will likely be an \exception{ImportError} or an
-\exception{AttributeError} but it could be something else.}
-
-Similarly, classes are pickled by named reference, so the same
-restrictions in the unpickling environment apply. Note that none of
-the class's code or data is pickled, so in the following example the
-class attribute \code{attr} is not restored in the unpickling
-environment:
-
-\begin{verbatim}
-class Foo:
- attr = 'a class attr'
-
-picklestring = pickle.dumps(Foo)
-\end{verbatim}
-
-These restrictions are why picklable functions and classes must be
-defined in the top level of a module.
-
-Similarly, when class instances are pickled, their class's code and
-data are not pickled along with them. Only the instance data are
-pickled. This is done on purpose, so you can fix bugs in a class or
-add methods to the class and still load objects that were created with
-an earlier version of the class. If you plan to have long-lived
-objects that will see many versions of a class, it may be worthwhile
-to put a version number in the objects so that suitable conversions
-can be made by the class's \method{__setstate__()} method.
-
-\subsection{The pickle protocol
-\label{pickle-protocol}}\setindexsubitem{(pickle protocol)}
-
-This section describes the ``pickling protocol'' that defines the
-interface between the pickler/unpickler and the objects that are being
-serialized. This protocol provides a standard way for you to define,
-customize, and control how your objects are serialized and
-de-serialized. The description in this section doesn't cover specific
-customizations that you can employ to make the unpickling environment
-slightly safer from untrusted pickle data streams; see section~\ref{pickle-sub}
-for more details.
-
-\subsubsection{Pickling and unpickling normal class
- instances\label{pickle-inst}}
-
-When a pickled class instance is unpickled, its \method{__init__()}
-method is normally \emph{not} invoked. If it is desirable that the
-\method{__init__()} method be called on unpickling, an old-style class
-can define a method \method{__getinitargs__()}, which should return a
-\emph{tuple} containing the arguments to be passed to the class
-constructor (\method{__init__()} for example). The
-\method{__getinitargs__()} method is called at
-pickle time; the tuple it returns is incorporated in the pickle for
-the instance.
-\withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}}
-\withsubitem{(instance constructor)}{\ttindex{__init__()}}
-
-\withsubitem{(copy protocol)}{\ttindex{__getnewargs__()}}
-
-New-style types can provide a \method{__getnewargs__()} method that is
-used for protocol 2. Implementing this method is needed if the type
-establishes some internal invariants when the instance is created, or
-if the memory allocation is affected by the values passed to the
-\method{__new__()} method for the type (as it is for tuples and
-strings). Instances of a new-style type \class{C} are created using
-
-\begin{alltt}
-obj = C.__new__(C, *\var{args})
-\end{alltt}
-
-where \var{args} is the result of calling \method{__getnewargs__()} on
-the original object; if there is no \method{__getnewargs__()}, an
-empty tuple is assumed.
-
-\withsubitem{(copy protocol)}{
- \ttindex{__getstate__()}\ttindex{__setstate__()}}
-\withsubitem{(instance attribute)}{
- \ttindex{__dict__}}
-
-Classes can further influence how their instances are pickled; if the
-class defines the method \method{__getstate__()}, it is called and the
-return state is pickled as the contents for the instance, instead of
-the contents of the instance's dictionary. If there is no
-\method{__getstate__()} method, the instance's \member{__dict__} is
-pickled.
-
-Upon unpickling, if the class also defines the method
-\method{__setstate__()}, it is called with the unpickled
-state.\footnote{These methods can also be used to implement copying
-class instances.} If there is no \method{__setstate__()} method, the
-pickled state must be a dictionary and its items are assigned to the
-new instance's dictionary. If a class defines both
-\method{__getstate__()} and \method{__setstate__()}, the state object
-needn't be a dictionary and these methods can do what they
-want.\footnote{This protocol is also used by the shallow and deep
-copying operations defined in the
-\refmodule{copy} module.}
-
-\begin{notice}[warning]
- For new-style classes, if \method{__getstate__()} returns a false
- value, the \method{__setstate__()} method will not be called.
-\end{notice}
-
-
-\subsubsection{Pickling and unpickling extension types}
-
-When the \class{Pickler} encounters an object of a type it knows
-nothing about --- such as an extension type --- it looks in two places
-for a hint of how to pickle it. One alternative is for the object to
-implement a \method{__reduce__()} method. If provided, at pickling
-time \method{__reduce__()} will be called with no arguments, and it
-must return either a string or a tuple.
-
-If a string is returned, it names a global variable whose contents are
-pickled as normal. The string returned by \method{__reduce__} should
-be the object's local name relative to its module; the pickle module
-searches the module namespace to determine the object's module.
-
-When a tuple is returned, it must be between two and five elements
-long. Optional elements can either be omitted, or \code{None} can be provided
-as their value. The semantics of each element are:
-
-\begin{itemize}
-
-\item A callable object that will be called to create the initial
-version of the object. The next element of the tuple will provide
-arguments for this callable, and later elements provide additional
-state information that will subsequently be used to fully reconstruct
-the pickled data.
-
-In the unpickling environment this object must be either a class, a
-callable registered as a ``safe constructor'' (see below), or it must
-have an attribute \member{__safe_for_unpickling__} with a true value.
-Otherwise, an \exception{UnpicklingError} will be raised in the
-unpickling environment. Note that as usual, the callable itself is
-pickled by name.
-
-\item A tuple of arguments for the callable object.
-\versionchanged[Formerly, this argument could also be \code{None}]{2.5}
-
-\item Optionally, the object's state, which will be passed to
- the object's \method{__setstate__()} method as described in
- section~\ref{pickle-inst}. If the object has no
- \method{__setstate__()} method, then, as above, the value must
- be a dictionary and it will be added to the object's
- \member{__dict__}.
-
-\item Optionally, an iterator (and not a sequence) yielding successive
-list items. These list items will be pickled, and appended to the
-object using either \code{obj.append(\var{item})} or
-\code{obj.extend(\var{list_of_items})}. This is primarily used for
-list subclasses, but may be used by other classes as long as they have
-\method{append()} and \method{extend()} methods with the appropriate
-signature. (Whether \method{append()} or \method{extend()} is used
-depends on which pickle protocol version is used as well as the number
-of items to append, so both must be supported.)
-
-\item Optionally, an iterator (not a sequence)
-yielding successive dictionary items, which should be tuples of the
-form \code{(\var{key}, \var{value})}. These items will be pickled
-and stored to the object using \code{obj[\var{key}] = \var{value}}.
-This is primarily used for dictionary subclasses, but may be used by
-other classes as long as they implement \method{__setitem__}.
-
-\end{itemize}
-
-It is sometimes useful to know the protocol version when implementing
-\method{__reduce__}. This can be done by implementing a method named
-\method{__reduce_ex__} instead of \method{__reduce__}.
-\method{__reduce_ex__}, when it exists, is called in preference over
-\method{__reduce__} (you may still provide \method{__reduce__} for
-backwards compatibility). The \method{__reduce_ex__} method will be
-called with a single integer argument, the protocol version.
-
-The \class{object} class implements both \method{__reduce__} and
-\method{__reduce_ex__}; however, if a subclass overrides
-\method{__reduce__} but not \method{__reduce_ex__}, the
-\method{__reduce_ex__} implementation detects this and calls
-\method{__reduce__}.
-
-An alternative to implementing a \method{__reduce__()} method on the
-object to be pickled, is to register the callable with the
-\refmodule[copyreg]{copy_reg} module. This module provides a way
-for programs to register ``reduction functions'' and constructors for
-user-defined types. Reduction functions have the same semantics and
-interface as the \method{__reduce__()} method described above, except
-that they are called with a single argument, the object to be pickled.
-
-The registered constructor is deemed a ``safe constructor'' for purposes
-of unpickling as described above.
-
-
-\subsubsection{Pickling and unpickling external objects}
-
-For the benefit of object persistence, the \module{pickle} module
-supports the notion of a reference to an object outside the pickled
-data stream. Such objects are referenced by a ``persistent id'',
-which is just an arbitrary string of printable \ASCII{} characters.
-The resolution of such names is not defined by the \module{pickle}
-module; it will delegate this resolution to user defined functions on
-the pickler and unpickler.\footnote{The actual mechanism for
-associating these user defined functions is slightly different for
-\module{pickle} and \module{cPickle}. The description given here
-works the same for both implementations. Users of the \module{pickle}
-module could also use subclassing to effect the same results,
-overriding the \method{persistent_id()} and \method{persistent_load()}
-methods in the derived classes.}
-
-To define external persistent id resolution, you need to set the
-\member{persistent_id} attribute of the pickler object and the
-\member{persistent_load} attribute of the unpickler object.
-
-To pickle objects that have an external persistent id, the pickler
-must have a custom \function{persistent_id()} method that takes an
-object as an argument and returns either \code{None} or the persistent
-id for that object. When \code{None} is returned, the pickler simply
-pickles the object as normal. When a persistent id string is
-returned, the pickler will pickle that string, along with a marker
-so that the unpickler will recognize the string as a persistent id.
-
-To unpickle external objects, the unpickler must have a custom
-\function{persistent_load()} function that takes a persistent id
-string and returns the referenced object.
-
-Here's a silly example that \emph{might} shed more light:
-
-\begin{verbatim}
-import pickle
-from cStringIO import StringIO
-
-src = StringIO()
-p = pickle.Pickler(src)
-
-def persistent_id(obj):
- if hasattr(obj, 'x'):
- return 'the value %d' % obj.x
- else:
- return None
-
-p.persistent_id = persistent_id
-
-class Integer:
- def __init__(self, x):
- self.x = x
- def __str__(self):
- return 'My name is integer %d' % self.x
-
-i = Integer(7)
-print i
-p.dump(i)
-
-datastream = src.getvalue()
-print repr(datastream)
-dst = StringIO(datastream)
-
-up = pickle.Unpickler(dst)
-
-class FancyInteger(Integer):
- def __str__(self):
- return 'I am the integer %d' % self.x
-
-def persistent_load(persid):
- if persid.startswith('the value '):
- value = int(persid.split()[2])
- return FancyInteger(value)
- else:
- raise pickle.UnpicklingError, 'Invalid persistent id'
-
-up.persistent_load = persistent_load
-
-j = up.load()
-print j
-\end{verbatim}
-
-In the \module{cPickle} module, the unpickler's
-\member{persistent_load} attribute can also be set to a Python
-list, in which case, when the unpickler reaches a persistent id, the
-persistent id string will simply be appended to this list. This
-functionality exists so that a pickle data stream can be ``sniffed''
-for object references without actually instantiating all the objects
-in a pickle.\footnote{We'll leave you with the image of Guido and Jim
-sitting around sniffing pickles in their living rooms.} Setting
-\member{persistent_load} to a list is usually used in conjunction with
-the \method{noload()} method on the Unpickler.
-
-% BAW: Both pickle and cPickle support something called
-% inst_persistent_id() which appears to give unknown types a second
-% shot at producing a persistent id. Since Jim Fulton can't remember
-% why it was added or what it's for, I'm leaving it undocumented.
-
-\subsection{Subclassing Unpicklers \label{pickle-sub}}
-
-By default, unpickling will import any class that it finds in the
-pickle data. You can control exactly what gets unpickled and what
-gets called by customizing your unpickler. Unfortunately, exactly how
-you do this is different depending on whether you're using
-\module{pickle} or \module{cPickle}.\footnote{A word of caution: the
-mechanisms described here use internal attributes and methods, which
-are subject to change in future versions of Python. We intend to
-someday provide a common interface for controlling this behavior,
-which will work in either \module{pickle} or \module{cPickle}.}
-
-In the \module{pickle} module, you need to derive a subclass from
-\class{Unpickler}, overriding the \method{load_global()}
-method. \method{load_global()} should read two lines from the pickle
-data stream where the first line will the name of the module
-containing the class and the second line will be the name of the
-instance's class. It then looks up the class, possibly importing the
-module and digging out the attribute, then it appends what it finds to
-the unpickler's stack. Later on, this class will be assigned to the
-\member{__class__} attribute of an empty class, as a way of magically
-creating an instance without calling its class's \method{__init__()}.
-Your job (should you choose to accept it), would be to have
-\method{load_global()} push onto the unpickler's stack, a known safe
-version of any class you deem safe to unpickle. It is up to you to
-produce such a class. Or you could raise an error if you want to
-disallow all unpickling of instances. If this sounds like a hack,
-you're right. Refer to the source code to make this work.
-
-Things are a little cleaner with \module{cPickle}, but not by much.
-To control what gets unpickled, you can set the unpickler's
-\member{find_global} attribute to a function or \code{None}. If it is
-\code{None} then any attempts to unpickle instances will raise an
-\exception{UnpicklingError}. If it is a function,
-then it should accept a module name and a class name, and return the
-corresponding class object. It is responsible for looking up the
-class and performing any necessary imports, and it may raise an
-error to prevent instances of the class from being unpickled.
-
-The moral of the story is that you should be really careful about the
-source of the strings your application unpickles.
-
-\subsection{Example \label{pickle-example}}
-
-For the simplest code, use the \function{dump()} and \function{load()}
-functions. Note that a self-referencing list is pickled and restored
-correctly.
-
-\begin{verbatim}
-import pickle
-
-data1 = {'a': [1, 2.0, 3, 4+6j],
- 'b': ('string', u'Unicode string'),
- 'c': None}
-
-selfref_list = [1, 2, 3]
-selfref_list.append(selfref_list)
-
-output = open('data.pkl', 'wb')
-
-# Pickle dictionary using protocol 0.
-pickle.dump(data1, output)
-
-# Pickle the list using the highest protocol available.
-pickle.dump(selfref_list, output, -1)
-
-output.close()
-\end{verbatim}
-
-The following example reads the resulting pickled data. When reading
-a pickle-containing file, you should open the file in binary mode
-because you can't be sure if the ASCII or binary format was used.
-
-\begin{verbatim}
-import pprint, pickle
-
-pkl_file = open('data.pkl', 'rb')
-
-data1 = pickle.load(pkl_file)
-pprint.pprint(data1)
-
-data2 = pickle.load(pkl_file)
-pprint.pprint(data2)
-
-pkl_file.close()
-\end{verbatim}
-
-Here's a larger example that shows how to modify pickling behavior for a
-class. The \class{TextReader} class opens a text file, and returns
-the line number and line contents each time its \method{readline()}
-method is called. If a \class{TextReader} instance is pickled, all
-attributes \emph{except} the file object member are saved. When the
-instance is unpickled, the file is reopened, and reading resumes from
-the last location. The \method{__setstate__()} and
-\method{__getstate__()} methods are used to implement this behavior.
-
-\begin{verbatim}
-class TextReader:
- """Print and number lines in a text file."""
- def __init__(self, file):
- self.file = file
- self.fh = open(file)
- self.lineno = 0
-
- def readline(self):
- self.lineno = self.lineno + 1
- line = self.fh.readline()
- if not line:
- return None
- if line.endswith("\n"):
- line = line[:-1]
- return "%d: %s" % (self.lineno, line)
-
- def __getstate__(self):
- odict = self.__dict__.copy() # copy the dict since we change it
- del odict['fh'] # remove filehandle entry
- return odict
-
- def __setstate__(self, dict):
- fh = open(dict['file']) # reopen file
- count = dict['lineno'] # read from file...
- while count: # until line count is restored
- fh.readline()
- count = count - 1
- self.__dict__.update(dict) # update attributes
- self.fh = fh # save the file object
-\end{verbatim}
-
-A sample usage might be something like this:
-
-\begin{verbatim}
->>> import TextReader
->>> obj = TextReader.TextReader("TextReader.py")
->>> obj.readline()
-'1: #!/usr/local/bin/python'
->>> # (more invocations of obj.readline() here)
-... obj.readline()
-'7: class TextReader:'
->>> import pickle
->>> pickle.dump(obj,open('save.p', 'wb'))
-\end{verbatim}
-
-If you want to see that \refmodule{pickle} works across Python
-processes, start another Python session, before continuing. What
-follows can happen from either the same process or a new process.
-
-\begin{verbatim}
->>> import pickle
->>> reader = pickle.load(open('save.p', 'rb'))
->>> reader.readline()
-'8: "Print and number lines in a text file."'
-\end{verbatim}
-
-
-\begin{seealso}
- \seemodule[copyreg]{copy_reg}{Pickle interface constructor
- registration for extension types.}
-
- \seemodule{shelve}{Indexed databases of objects; uses \module{pickle}.}
-
- \seemodule{copy}{Shallow and deep object copying.}
-
- \seemodule{marshal}{High-performance serialization of built-in types.}
-\end{seealso}
-
-
-\section{\module{cPickle} --- A faster \module{pickle}}
-
-\declaremodule{builtin}{cPickle}
-\modulesynopsis{Faster version of \refmodule{pickle}, but not subclassable.}
-\moduleauthor{Jim Fulton}{jim@zope.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The \module{cPickle} module supports serialization and
-de-serialization of Python objects, providing an interface and
-functionality nearly identical to the
-\refmodule{pickle}\refstmodindex{pickle} module. There are several
-differences, the most important being performance and subclassability.
-
-First, \module{cPickle} can be up to 1000 times faster than
-\module{pickle} because the former is implemented in C. Second, in
-the \module{cPickle} module the callables \function{Pickler()} and
-\function{Unpickler()} are functions, not classes. This means that
-you cannot use them to derive custom pickling and unpickling
-subclasses. Most applications have no need for this functionality and
-should benefit from the greatly improved performance of the
-\module{cPickle} module.
-
-The pickle data stream produced by \module{pickle} and
-\module{cPickle} are identical, so it is possible to use
-\module{pickle} and \module{cPickle} interchangeably with existing
-pickles.\footnote{Since the pickle data format is actually a tiny
-stack-oriented programming language, and some freedom is taken in the
-encodings of certain objects, it is possible that the two modules
-produce different data streams for the same input objects. However it
-is guaranteed that they will always be able to read each other's
-data streams.}
-
-There are additional minor differences in API between \module{cPickle}
-and \module{pickle}, however for most applications, they are
-interchangeable. More documentation is provided in the
-\module{pickle} module documentation, which
-includes a list of the documented differences.
-
-
diff --git a/Doc/lib/libpickletools.tex b/Doc/lib/libpickletools.tex
deleted file mode 100644
index 8f63626..0000000
--- a/Doc/lib/libpickletools.tex
+++ /dev/null
@@ -1,34 +0,0 @@
-\section{\module{pickletools} --- Tools for pickle developers.}
-
-\declaremodule{standard}{pickletools}
-\modulesynopsis{Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.}
-
-\versionadded{2.3}
-
-This module contains various constants relating to the intimate
-details of the \refmodule{pickle} module, some lengthy comments about
-the implementation, and a few useful functions for analyzing pickled
-data. The contents of this module are useful for Python core
-developers who are working on the \module{pickle} and \module{cPickle}
-implementations; ordinary users of the \module{pickle} module probably
-won't find the \module{pickletools} module relevant.
-
-\begin{funcdesc}{dis}{pickle\optional{, out=None, memo=None, indentlevel=4}}
-Outputs a symbolic disassembly of the pickle to the file-like object
-\var{out}, defaulting to \code{sys.stdout}. \var{pickle} can be a
-string or a file-like object. \var{memo} can be a Python dictionary
-that will be used as the pickle's memo; it can be used to perform
-disassemblies across multiple pickles created by the same pickler.
-Successive levels, indicated by \code{MARK} opcodes in the stream, are
-indented by \var{indentlevel} spaces.
-\end{funcdesc}
-
-\begin{funcdesc}{genops}{pickle}
-Provides an iterator over all of the opcodes in a pickle, returning a
-sequence of \code{(\var{opcode}, \var{arg}, \var{pos})} triples.
-\var{opcode} is an instance of an \class{OpcodeInfo} class; \var{arg}
-is the decoded value, as a Python object, of the opcode's argument;
-\var{pos} is the position at which this opcode is located.
-\var{pickle} can be a string or a file-like object.
-\end{funcdesc}
-
diff --git a/Doc/lib/libpipes.tex b/Doc/lib/libpipes.tex
deleted file mode 100644
index de25fb5..0000000
--- a/Doc/lib/libpipes.tex
+++ /dev/null
@@ -1,84 +0,0 @@
-\section{\module{pipes} ---
- Interface to shell pipelines}
-
-\declaremodule{standard}{pipes}
- \platform{Unix}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{A Python interface to \UNIX\ shell pipelines.}
-
-
-The \module{pipes} module defines a class to abstract the concept of
-a \emph{pipeline} --- a sequence of converters from one file to
-another.
-
-Because the module uses \program{/bin/sh} command lines, a \POSIX{} or
-compatible shell for \function{os.system()} and \function{os.popen()}
-is required.
-
-The \module{pipes} module defines the following class:
-
-\begin{classdesc}{Template}{}
-An abstraction of a pipeline.
-\end{classdesc}
-
-Example:
-
-\begin{verbatim}
->>> import pipes
->>> t=pipes.Template()
->>> t.append('tr a-z A-Z', '--')
->>> f=t.open('/tmp/1', 'w')
->>> f.write('hello world')
->>> f.close()
->>> open('/tmp/1').read()
-'HELLO WORLD'
-\end{verbatim}
-
-
-\subsection{Template Objects \label{template-objects}}
-
-Template objects following methods:
-
-\begin{methoddesc}[Template]{reset}{}
-Restore a pipeline template to its initial state.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{clone}{}
-Return a new, equivalent, pipeline template.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{debug}{flag}
-If \var{flag} is true, turn debugging on. Otherwise, turn debugging
-off. When debugging is on, commands to be executed are printed, and
-the shell is given \code{set -x} command to be more verbose.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{append}{cmd, kind}
-Append a new action at the end. The \var{cmd} variable must be a valid
-bourne shell command. The \var{kind} variable consists of two letters.
-
-The first letter can be either of \code{'-'} (which means the command
-reads its standard input), \code{'f'} (which means the commands reads
-a given file on the command line) or \code{'.'} (which means the commands
-reads no input, and hence must be first.)
-
-Similarly, the second letter can be either of \code{'-'} (which means
-the command writes to standard output), \code{'f'} (which means the
-command writes a file on the command line) or \code{'.'} (which means
-the command does not write anything, and hence must be last.)
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{prepend}{cmd, kind}
-Add a new action at the beginning. See \method{append()} for explanations
-of the arguments.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{open}{file, mode}
-Return a file-like object, open to \var{file}, but read from or
-written to by the pipeline. Note that only one of \code{'r'},
-\code{'w'} may be given.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{copy}{infile, outfile}
-Copy \var{infile} to \var{outfile} through the pipe.
-\end{methoddesc}
diff --git a/Doc/lib/libpkgutil.tex b/Doc/lib/libpkgutil.tex
deleted file mode 100644
index a286f00..0000000
--- a/Doc/lib/libpkgutil.tex
+++ /dev/null
@@ -1,45 +0,0 @@
-\section{\module{pkgutil} ---
- Package extension utility}
-
-\declaremodule{standard}{pkgutil}
-\modulesynopsis{Utilities to support extension of packages.}
-
-\versionadded{2.3}
-
-This module provides a single function:
-
-\begin{funcdesc}{extend_path}{path, name}
- Extend the search path for the modules which comprise a package.
- Intended use is to place the following code in a package's
- \file{__init__.py}:
-
-\begin{verbatim}
-from pkgutil import extend_path
-__path__ = extend_path(__path__, __name__)
-\end{verbatim}
-
- This will add to the package's \code{__path__} all subdirectories of
- directories on \code{sys.path} named after the package. This is
- useful if one wants to distribute different parts of a single
- logical package as multiple directories.
-
- It also looks for \file{*.pkg} files beginning where \code{*}
- matches the \var{name} argument. This feature is similar to
- \file{*.pth} files (see the \refmodule{site} module for more
- information), except that it doesn't special-case lines starting
- with \code{import}. A \file{*.pkg} file is trusted at face value:
- apart from checking for duplicates, all entries found in a
- \file{*.pkg} file are added to the path, regardless of whether they
- exist on the filesystem. (This is a feature.)
-
- If the input path is not a list (as is the case for frozen
- packages) it is returned unchanged. The input path is not
- modified; an extended copy is returned. Items are only appended
- to the copy at the end.
-
- It is assumed that \code{sys.path} is a sequence. Items of
- \code{sys.path} that are not (Unicode or 8-bit) strings referring to
- existing directories are ignored. Unicode items on \code{sys.path}
- that cause errors when used as filenames may cause this function to
- raise an exception (in line with \function{os.path.isdir()} behavior).
-\end{funcdesc}
diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex
deleted file mode 100644
index a2f1913..0000000
--- a/Doc/lib/libplatform.tex
+++ /dev/null
@@ -1,238 +0,0 @@
-\section{\module{platform} ---
- Access to underlying platform's identifying data.}
-
-\declaremodule{standard}{platform}
-\modulesynopsis{Retrieves as much platform identifying data as possible.}
-\moduleauthor{Marc-Andre Lemburg}{mal@egenix.com}
-\sectionauthor{Bjorn Pettersen}{bpettersen@corp.fairisaac.com}
-
-\versionadded{2.3}
-
-\begin{notice}
- Specific platforms listed alphabetically, with Linux included in the
- \UNIX{} section.
-\end{notice}
-
-\subsection{Cross Platform}
-
-\begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''}
- Queries the given executable (defaults to the Python interpreter
- binary) for various architecture information.
-
- Returns a tuple \code{(bits, linkage)} which contain information about
- the bit architecture and the linkage format used for the
- executable. Both values are returned as strings.
-
- Values that cannot be determined are returned as given by the
- parameter presets. If bits is given as \code{''}, the
- \cfunction{sizeof(pointer)}
- (or \cfunction{sizeof(long)} on Python version < 1.5.2) is used as
- indicator for the supported pointer size.
-
- The function relies on the system's \file{file} command to do the
- actual work. This is available on most if not all \UNIX{}
- platforms and some non-\UNIX{} platforms and then only if the
- executable points to the Python interpreter. Reasonable defaults
- are used when the above needs are not met.
-\end{funcdesc}
-
-\begin{funcdesc}{machine}{}
- Returns the machine type, e.g. \code{'i386'}.
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{node}{}
- Returns the computer's network name (may not be fully qualified!).
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{platform}{aliased=0, terse=0}
- Returns a single string identifying the underlying platform
- with as much useful information as possible.
-
- The output is intended to be \emph{human readable} rather than
- machine parseable. It may look different on different platforms and
- this is intended.
-
- If \var{aliased} is true, the function will use aliases for various
- platforms that report system names which differ from their common
- names, for example SunOS will be reported as Solaris. The
- \function{system_alias()} function is used to implement this.
-
- Setting \var{terse} to true causes the function to return only the
- absolute minimum information needed to identify the platform.
-\end{funcdesc}
-
-\begin{funcdesc}{processor}{}
- Returns the (real) processor name, e.g. \code{'amdk6'}.
-
- An empty string is returned if the value cannot be determined. Note
- that many platforms do not provide this information or simply return
- the same value as for \function{machine()}. NetBSD does this.
-\end{funcdesc}
-
-\begin{funcdesc}{python_build}{}
- Returns a tuple \code{(\var{buildno}, \var{builddate})} stating the
- Python build number and date as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{python_compiler}{}
- Returns a string identifying the compiler used for compiling Python.
-\end{funcdesc}
-
-\begin{funcdesc}{python_branch}{}
- Returns a string identifying the Python implementation SCM branch.
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{python_implementation}{}
- Returns a string identifying the Python implementation.
- Possible return values are: 'CPython', 'IronPython', 'Jython'
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{python_revision}{}
- Returns a string identifying the Python implementation SCM revision.
- \versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{python_version}{}
- Returns the Python version as string \code{'major.minor.patchlevel'}
-
- Note that unlike the Python \code{sys.version}, the returned value
- will always include the patchlevel (it defaults to 0).
-\end{funcdesc}
-
-\begin{funcdesc}{python_version_tuple}{}
- Returns the Python version as tuple \code{(\var{major}, \var{minor},
- \var{patchlevel})} of strings.
-
- Note that unlike the Python \code{sys.version}, the returned value
- will always include the patchlevel (it defaults to \code{'0'}).
-\end{funcdesc}
-
-\begin{funcdesc}{release}{}
- Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'}
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{system}{}
- Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'},
- or \code{'Java'}.
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{system_alias}{system, release, version}
- Returns \code{(\var{system}, \var{release}, \var{version})} aliased
- to common marketing names used for some systems. It also does some
- reordering of the information in some cases where it would otherwise
- cause confusion.
-\end{funcdesc}
-
-\begin{funcdesc}{version}{}
- Returns the system's release version, e.g. \code{'\#3 on degas'}.
- An empty string is returned if the value cannot be determined.
-\end{funcdesc}
-
-\begin{funcdesc}{uname}{}
- Fairly portable uname interface. Returns a tuple of strings
- \code{(\var{system}, \var{node}, \var{release}, \var{version},
- \var{machine}, \var{processor})} identifying the underlying
- platform.
-
- Note that unlike the \function{os.uname()} function this also returns
- possible processor information as additional tuple entry.
-
- Entries which cannot be determined are set to \code{''}.
-\end{funcdesc}
-
-
-\subsection{Java Platform}
-
-\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''),
- osinfo=('','','')}
- Version interface for JPython.
-
- Returns a tuple \code{(\var{release}, \var{vendor}, \var{vminfo},
- \var{osinfo})} with \var{vminfo} being a tuple \code{(\var{vm_name},
- \var{vm_release}, \var{vm_vendor})} and \var{osinfo} being a tuple
- \code{(\var{os_name}, \var{os_version}, \var{os_arch})}.
- Values which cannot be determined are set to the defaults
- given as parameters (which all default to \code{''}).
-\end{funcdesc}
-
-
-\subsection{Windows Platform}
-
-\begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''}
- Get additional version information from the Windows Registry
- and return a tuple \code{(\var{version}, \var{csd}, \var{ptype})}
- referring to version number, CSD level and OS type (multi/single
- processor).
-
- As a hint: \var{ptype} is \code{'Uniprocessor Free'} on single
- processor NT machines and \code{'Multiprocessor Free'} on multi
- processor machines. The \emph{'Free'} refers to the OS version being
- free of debugging code. It could also state \emph{'Checked'} which
- means the OS version uses debugging code, i.e. code that
- checks arguments, ranges, etc.
-
- \begin{notice}[note]
- This function only works if Mark Hammond's \module{win32all}
- package is installed and (obviously) only runs on Win32
- compatible platforms.
- \end{notice}
-\end{funcdesc}
-
-\subsubsection{Win95/98 specific}
-
-\begin{funcdesc}{popen}{cmd, mode='r', bufsize=None}
- Portable \function{popen()} interface. Find a working popen
- implementation preferring \function{win32pipe.popen()}. On Windows
- NT, \function{win32pipe.popen()} should work; on Windows 9x it hangs
- due to bugs in the MS C library.
- % This KnowledgeBase article appears to be missing...
- %See also \ulink{MS KnowledgeBase article Q150956}{}.
-\end{funcdesc}
-
-
-\subsection{Mac OS Platform}
-
-\begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''}
- Get Mac OS version information and return it as tuple
- \code{(\var{release}, \var{versioninfo}, \var{machine})} with
- \var{versioninfo} being a tuple \code{(\var{version},
- \var{dev_stage}, \var{non_release_version})}.
-
- Entries which cannot be determined are set to \code{''}. All tuple
- entries are strings.
-
- Documentation for the underlying \cfunction{gestalt()} API is
- available online at \url{http://www.rgaros.nl/gestalt/}.
-\end{funcdesc}
-
-
-\subsection{\UNIX{} Platforms}
-
-\begin{funcdesc}{dist}{distname='', version='', id='',
- supported_dists=('SuSE','debian','redhat','mandrake')}
- Tries to determine the name of the OS distribution name
- Returns a tuple \code{(\var{distname}, \var{version}, \var{id})}
- which defaults to the args given as parameters.
-\end{funcdesc}
-
-% Document linux_distribution()?
-
-\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='',
- version='', chunksize=2048}
- Tries to determine the libc version against which the file
- executable (defaults to the Python interpreter) is linked. Returns
- a tuple of strings \code{(\var{lib}, \var{version})} which default
- to the given parameters in case the lookup fails.
-
- Note that this function has intimate knowledge of how different
- libc versions add symbols to the executable is probably only
- useable for executables compiled using \program{gcc}.
-
- The file is read and scanned in chunks of \var{chunksize} bytes.
-\end{funcdesc}
diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex
deleted file mode 100644
index 9ca5bbd..0000000
--- a/Doc/lib/libpoplib.tex
+++ /dev/null
@@ -1,187 +0,0 @@
-\section{\module{poplib} ---
- POP3 protocol client}
-
-\declaremodule{standard}{poplib}
-\modulesynopsis{POP3 protocol client (requires sockets).}
-
-%By Andrew T. Csillag
-%Even though I put it into LaTeX, I cannot really claim that I wrote
-%it since I just stole most of it from the poplib.py source code and
-%the imaplib ``chapter''.
-%Revised by ESR, January 2000
-
-\indexii{POP3}{protocol}
-
-This module defines a class, \class{POP3}, which encapsulates a
-connection to a POP3 server and implements the protocol as defined in
-\rfc{1725}. The \class{POP3} class supports both the minimal and
-optional command sets. Additionally, this module provides a class
-\class{POP3_SSL}, which provides support for connecting to POP3
-servers that use SSL as an underlying protocol layer.
-
-
-Note that POP3, though widely supported, is obsolescent. The
-implementation quality of POP3 servers varies widely, and too many are
-quite poor. If your mailserver supports IMAP, you would be better off
-using the \class{\refmodule{imaplib}.IMAP4} class, as IMAP
-servers tend to be better implemented.
-
-A single class is provided by the \module{poplib} module:
-
-\begin{classdesc}{POP3}{host\optional{, port\optional{, timeout}}}
-This class implements the actual POP3 protocol. The connection is
-created when the instance is initialized.
-If \var{port} is omitted, the standard POP3 port (110) is used.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{POP3_SSL}{host\optional{, port\optional{, keyfile\optional{, certfile}}}}
-This is a subclass of \class{POP3} that connects to the server over an
-SSL encrypted socket. If \var{port} is not specified, 995, the
-standard POP3-over-SSL port is used. \var{keyfile} and \var{certfile}
-are also optional - they can contain a PEM formatted private key and
-certificate chain file for the SSL connection.
-
-\versionadded{2.4}
-\end{classdesc}
-
-One exception is defined as an attribute of the \module{poplib} module:
-
-\begin{excdesc}{error_proto}
-Exception raised on any errors from this module (errors from
-\module{socket} module are not caught). The reason for the exception
-is passed to the constructor as a string.
-\end{excdesc}
-
-\begin{seealso}
- \seemodule{imaplib}{The standard Python IMAP module.}
- \seetitle[http://www.catb.org/\~{}esr/fetchmail/fetchmail-FAQ.html]
- {Frequently Asked Questions About Fetchmail}
- {The FAQ for the \program{fetchmail} POP/IMAP client collects
- information on POP3 server variations and RFC noncompliance
- that may be useful if you need to write an application based
- on the POP protocol.}
-\end{seealso}
-
-
-\subsection{POP3 Objects \label{pop3-objects}}
-
-All POP3 commands are represented by methods of the same name,
-in lower-case; most return the response text sent by the server.
-
-An \class{POP3} instance has the following methods:
-
-
-\begin{methoddesc}[POP3]{set_debuglevel}{level}
-Set the instance's debugging level. This controls the amount of
-debugging output printed. The default, \code{0}, produces no
-debugging output. A value of \code{1} produces a moderate amount of
-debugging output, generally a single line per request. A value of
-\code{2} or higher produces the maximum amount of debugging output,
-logging each line sent and received on the control connection.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{getwelcome}{}
-Returns the greeting string sent by the POP3 server.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{user}{username}
-Send user command, response should indicate that a password is required.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{pass_}{password}
-Send password, response includes message count and mailbox size.
-Note: the mailbox on the server is locked until \method{quit()} is
-called.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{apop}{user, secret}
-Use the more secure APOP authentication to log into the POP3 server.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{rpop}{user}
-Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{stat}{}
-Get mailbox status. The result is a tuple of 2 integers:
-\code{(\var{message count}, \var{mailbox size})}.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{list}{\optional{which}}
-Request message list, result is in the form
-\code{(\var{response}, ['mesg_num octets', ...], \var{octets})}.
-If \var{which} is set, it is the message to list.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{retr}{which}
-Retrieve whole message number \var{which}, and set its seen flag.
-Result is in form \code{(\var{response}, ['line', ...], \var{octets})}.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{dele}{which}
-Flag message number \var{which} for deletion. On most servers
-deletions are not actually performed until QUIT (the major exception is
-Eudora QPOP, which deliberately violates the RFCs by doing pending
-deletes on any disconnect).
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{rset}{}
-Remove any deletion marks for the mailbox.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{noop}{}
-Do nothing. Might be used as a keep-alive.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{quit}{}
-Signoff: commit changes, unlock mailbox, drop connection.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{top}{which, howmuch}
-Retrieves the message header plus \var{howmuch} lines of the message
-after the header of message number \var{which}. Result is in form
-\code{(\var{response}, ['line', ...], \var{octets})}.
-
-The POP3 TOP command this method uses, unlike the RETR command,
-doesn't set the message's seen flag; unfortunately, TOP is poorly
-specified in the RFCs and is frequently broken in off-brand servers.
-Test this method by hand against the POP3 servers you will use before
-trusting it.
-\end{methoddesc}
-
-\begin{methoddesc}[POP3]{uidl}{\optional{which}}
-Return message digest (unique id) list.
-If \var{which} is specified, result contains the unique id for that
-message in the form \code{'\var{response}\ \var{mesgnum}\ \var{uid}},
-otherwise result is list \code{(\var{response}, ['mesgnum uid', ...],
-\var{octets})}.
-\end{methoddesc}
-
-Instances of \class{POP3_SSL} have no additional methods. The
-interface of this subclass is identical to its parent.
-
-
-\subsection{POP3 Example \label{pop3-example}}
-
-Here is a minimal example (without error checking) that opens a
-mailbox and retrieves and prints all messages:
-
-\begin{verbatim}
-import getpass, poplib
-
-M = poplib.POP3('localhost')
-M.user(getpass.getuser())
-M.pass_(getpass.getpass())
-numMessages = len(M.list()[1])
-for i in range(numMessages):
- for j in M.retr(i+1)[1]:
- print j
-\end{verbatim}
-
-At the end of the module, there is a test section that contains a more
-extensive example of usage.
diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex
deleted file mode 100644
index aee6c0d..0000000
--- a/Doc/lib/libposix.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{\module{posix} ---
- The most common \POSIX{} system calls}
-
-\declaremodule{builtin}{posix}
- \platform{Unix}
-\modulesynopsis{The most common \POSIX\ system calls (normally used
- via module \refmodule{os}).}
-
-
-This module provides access to operating system functionality that is
-standardized by the C Standard and the \POSIX{} standard (a thinly
-disguised \UNIX{} interface).
-
-\strong{Do not import this module directly.} Instead, import the
-module \refmodule{os}, which provides a \emph{portable} version of this
-interface. On \UNIX, the \refmodule{os} module provides a superset of
-the \module{posix} interface. On non-\UNIX{} operating systems the
-\module{posix} module is not available, but a subset is always
-available through the \refmodule{os} interface. Once \refmodule{os} is
-imported, there is \emph{no} performance penalty in using it instead
-of \module{posix}. In addition, \refmodule{os}\refstmodindex{os}
-provides some additional functionality, such as automatically calling
-\function{putenv()} when an entry in \code{os.environ} is changed.
-
-The descriptions below are very terse; refer to the corresponding
-\UNIX{} manual (or \POSIX{} documentation) entry for more information.
-Arguments called \var{path} refer to a pathname given as a string.
-
-Errors are reported as exceptions; the usual exceptions are given for
-type errors, while errors reported by the system calls raise
-\exception{error} (a synonym for the standard exception
-\exception{OSError}), described below.
-
-
-\subsection{Large File Support \label{posix-large-files}}
-\sectionauthor{Steve Clift}{clift@mail.anacapa.net}
-\index{large files}
-\index{file!large files}
-
-
-Several operating systems (including AIX, HPUX, Irix and Solaris)
-provide support for files that are larger than 2 Gb from a C
-programming model where \ctype{int} and \ctype{long} are 32-bit
-values. This is typically accomplished by defining the relevant size
-and offset types as 64-bit values. Such files are sometimes referred
-to as \dfn{large files}.
-
-Large file support is enabled in Python when the size of an
-\ctype{off_t} is larger than a \ctype{long} and the \ctype{long long}
-type is available and is at least as large as an \ctype{off_t}. Python
-longs are then used to represent file sizes, offsets and other values
-that can exceed the range of a Python int. It may be necessary to
-configure and compile Python with certain compiler flags to enable
-this mode. For example, it is enabled by default with recent versions
-of Irix, but with Solaris 2.6 and 2.7 you need to do something like:
-
-\begin{verbatim}
-CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
- ./configure
-\end{verbatim} % $ <-- bow to font-lock
-
-On large-file-capable Linux systems, this might work:
-
-\begin{verbatim}
-CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
- ./configure
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\subsection{Module Contents \label{posix-contents}}
-
-
-Module \module{posix} defines the following data item:
-
-\begin{datadesc}{environ}
-A dictionary representing the string environment at the time the
-interpreter was started. For example, \code{environ['HOME']} is the
-pathname of your home directory, equivalent to
-\code{getenv("HOME")} in C.
-
-Modifying this dictionary does not affect the string environment
-passed on by \function{execv()}, \function{popen()} or
-\function{system()}; if you need to change the environment, pass
-\code{environ} to \function{execve()} or add variable assignments and
-export statements to the command string for \function{system()} or
-\function{popen()}.
-
-\note{The \refmodule{os} module provides an alternate
-implementation of \code{environ} which updates the environment on
-modification. Note also that updating \code{os.environ} will render
-this dictionary obsolete. Use of the \refmodule{os} module version of
-this is recommended over direct access to the \module{posix} module.}
-\end{datadesc}
-
-Additional contents of this module should only be accessed via the
-\refmodule{os} module; refer to the documentation for that module for
-further information.
diff --git a/Doc/lib/libposixpath.tex b/Doc/lib/libposixpath.tex
deleted file mode 100644
index 7684fa0..0000000
--- a/Doc/lib/libposixpath.tex
+++ /dev/null
@@ -1,300 +0,0 @@
-\section{\module{os.path} ---
- Common pathname manipulations}
-\declaremodule{standard}{os.path}
-
-\modulesynopsis{Common pathname manipulations.}
-
-This module implements some useful functions on pathnames.
-\index{path!operations}
-
-\warning{On Windows, many of these functions do not properly
-support UNC pathnames. \function{splitunc()} and \function{ismount()}
-do handle them correctly.}
-
-
-\begin{funcdesc}{abspath}{path}
-Return a normalized absolutized version of the pathname \var{path}.
-On most platforms, this is equivalent to
-\code{normpath(join(os.getcwd(), \var{path}))}.
-\versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{basename}{path}
-Return the base name of pathname \var{path}. This is the second half
-of the pair returned by \code{split(\var{path})}. Note that the
-result of this function is different from the
-\UNIX{} \program{basename} program; where \program{basename} for
-\code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()}
-function returns an empty string (\code{''}).
-\end{funcdesc}
-
-\begin{funcdesc}{commonprefix}{list}
-Return the longest path prefix (taken character-by-character) that is a
-prefix of all paths in
-\var{list}. If \var{list} is empty, return the empty string
-(\code{''}). Note that this may return invalid paths because it works a
-character at a time.
-\end{funcdesc}
-
-\begin{funcdesc}{dirname}{path}
-Return the directory name of pathname \var{path}. This is the first
-half of the pair returned by \code{split(\var{path})}.
-\end{funcdesc}
-
-\begin{funcdesc}{exists}{path}
-Return \code{True} if \var{path} refers to an existing path. Returns
-\code{False} for broken symbolic links. On some platforms, this
-function may return \code{False} if permission is not granted to
-execute \function{os.stat()} on the requested file, even if the
-\var{path} physically exists.
-\end{funcdesc}
-
-\begin{funcdesc}{lexists}{path}
-Return \code{True} if \var{path} refers to an existing path.
-Returns \code{True} for broken symbolic links.
-Equivalent to \function{exists()} on platforms lacking
-\function{os.lstat()}.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{expanduser}{path}
-On \UNIX{} and Windows, return the argument with an initial component of
-\samp{\~} or \samp{\~\var{user}} replaced by that \var{user}'s home directory.
-
-On \UNIX, an initial \samp{\~} is replaced by the environment variable
-\envvar{HOME} if it is set; otherwise the current user's home directory
-is looked up in the password directory through the built-in module
-\refmodule{pwd}\refbimodindex{pwd}.
-An initial \samp{\~\var{user}} is looked up directly in the
-password directory.
-
-On Windows, \envvar{HOME} and \envvar{USERPROFILE} will be used if set,
-otherwise a combination of \envvar{HOMEPATH} and \envvar{HOMEDRIVE} will be
-used. An initial \samp{\~\var{user}} is handled by stripping the last
-directory component from the created user path derived above.
-
-If the expansion fails or if the
-path does not begin with a tilde, the path is returned unchanged.
-\end{funcdesc}
-
-\begin{funcdesc}{expandvars}{path}
-Return the argument with environment variables expanded. Substrings
-of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
-replaced by the value of environment variable \var{name}. Malformed
-variable names and references to non-existing variables are left
-unchanged.
-
-On Windows, \samp{\%\var{name}\%} expansions are supported in addition to
-\samp{\$\var{name}} and \samp{\$\{\var{name}\}}.
-\end{funcdesc}
-
-\begin{funcdesc}{getatime}{path}
-Return the time of last access of \var{path}. The return
-value is a number giving the number of seconds since the epoch (see the
-\refmodule{time} module). Raise \exception{os.error} if the file does
-not exist or is inaccessible.
-\versionadded{1.5.2}
-\versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getmtime}{path}
-Return the time of last modification of \var{path}. The return
-value is a number giving the number of seconds since the epoch (see the
-\refmodule{time} module). Raise \exception{os.error} if the file does
-not exist or is inaccessible.
-\versionadded{1.5.2}
-\versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getctime}{path}
-Return the system's ctime which, on some systems (like \UNIX) is the
-time of the last change, and, on others (like Windows), is the
-creation time for \var{path}. The return
-value is a number giving the number of seconds since the epoch (see the
-\refmodule{time} module). Raise \exception{os.error} if the file does
-not exist or is inaccessible.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getsize}{path}
-Return the size, in bytes, of \var{path}. Raise
-\exception{os.error} if the file does not exist or is inaccessible.
-\versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{isabs}{path}
-Return \code{True} if \var{path} is an absolute pathname (begins with a
-slash).
-\end{funcdesc}
-
-\begin{funcdesc}{isfile}{path}
-Return \code{True} if \var{path} is an existing regular file. This follows
-symbolic links, so both \function{islink()} and \function{isfile()}
-can be true for the same path.
-\end{funcdesc}
-
-\begin{funcdesc}{isdir}{path}
-Return \code{True} if \var{path} is an existing directory. This follows
-symbolic links, so both \function{islink()} and \function{isdir()} can
-be true for the same path.
-\end{funcdesc}
-
-\begin{funcdesc}{islink}{path}
-Return \code{True} if \var{path} refers to a directory entry that is a
-symbolic link. Always \code{False} if symbolic links are not supported.
-\end{funcdesc}
-
-\begin{funcdesc}{ismount}{path}
-Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in
-a file system where a different file system has been mounted. The
-function checks whether \var{path}'s parent, \file{\var{path}/..}, is
-on a different device than \var{path}, or whether \file{\var{path}/..}
-and \var{path} point to the same i-node on the same device --- this
-should detect mount points for all \UNIX{} and \POSIX{} variants.
-\end{funcdesc}
-
-\begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}}
-Join one or more path components intelligently. If any component is
-an absolute path, all previous components (on Windows, including the
-previous drive letter, if there was one) are thrown away, and joining
-continues. The return value is the concatenation of \var{path1}, and
-optionally \var{path2}, etc., with exactly one directory separator
-(\code{os.sep}) inserted between components, unless \var{path2} is
-empty. Note that on Windows, since there is a current directory for
-each drive, \function{os.path.join("c:", "foo")} represents a path
-relative to the current directory on drive \file{C:} (\file{c:foo}), not
-\file{c:\textbackslash\textbackslash foo}.
-\end{funcdesc}
-
-\begin{funcdesc}{normcase}{path}
-Normalize the case of a pathname. On \UNIX, this returns the path
-unchanged; on case-insensitive filesystems, it converts the path to
-lowercase. On Windows, it also converts forward slashes to backward
-slashes.
-\end{funcdesc}
-
-\begin{funcdesc}{normpath}{path}
-Normalize a pathname. This collapses redundant separators and
-up-level references so that \code{A//B}, \code{A/./B} and
-\code{A/foo/../B} all become \code{A/B}. It does not normalize the
-case (use \function{normcase()} for that). On Windows, it converts
-forward slashes to backward slashes. It should be understood that this may
-change the meaning of the path if it contains symbolic links!
-\end{funcdesc}
-
-\begin{funcdesc}{realpath}{path}
-Return the canonical path of the specified filename, eliminating any
-symbolic links encountered in the path (if they are supported by the
-operating system).
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{relpath}{path\optional{, start}}
-Return a relative filepath to \var{path} either from the current
-directory or from an optional \var{start} point.
-
-\var{start} defaults to \member{os.curdir}.
-Availability: Windows, \UNIX.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{samefile}{path1, path2}
-Return \code{True} if both pathname arguments refer to the same file or
-directory (as indicated by device number and i-node number).
-Raise an exception if a \function{os.stat()} call on either pathname
-fails.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{sameopenfile}{fp1, fp2}
-Return \code{True} if the file descriptors \var{fp1} and \var{fp2} refer
-to the same file.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{samestat}{stat1, stat2}
-Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to
-the same file. These structures may have been returned by
-\function{fstat()}, \function{lstat()}, or \function{stat()}. This
-function implements the underlying comparison used by
-\function{samefile()} and \function{sameopenfile()}.
-Availability: Macintosh, \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{split}{path}
-Split the pathname \var{path} into a pair, \code{(\var{head},
-\var{tail})} where \var{tail} is the last pathname component and
-\var{head} is everything leading up to that. The \var{tail} part will
-never contain a slash; if \var{path} ends in a slash, \var{tail} will
-be empty. If there is no slash in \var{path}, \var{head} will be
-empty. If \var{path} is empty, both \var{head} and \var{tail} are
-empty. Trailing slashes are stripped from \var{head} unless it is the
-root (one or more slashes only). In nearly all cases,
-\code{join(\var{head}, \var{tail})} equals \var{path} (the only
-exception being when there were multiple slashes separating \var{head}
-from \var{tail}).
-\end{funcdesc}
-
-\begin{funcdesc}{splitdrive}{path}
-Split the pathname \var{path} into a pair \code{(\var{drive},
-\var{tail})} where \var{drive} is either a drive specification or the
-empty string. On systems which do not use drive specifications,
-\var{drive} will always be the empty string. In all cases,
-\code{\var{drive} + \var{tail}} will be the same as \var{path}.
-\versionadded{1.3}
-\end{funcdesc}
-
-\begin{funcdesc}{splitext}{path}
-Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})}
-such that \code{\var{root} + \var{ext} == \var{path}},
-and \var{ext} is empty or begins with a period and contains
-at most one period. Leading periods on the basename are
-ignored; \code{\var{splitext}.('.cshrc')} returns
-\code{('.cshrc', '')}.
-
-\versionchanged[Earlier versions could produce an empty root when
-the only period was the first character]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{splitunc}{path}
-Split the pathname \var{path} into a pair \code{(\var{unc}, \var{rest})}
-so that \var{unc} is the UNC mount point (such as \code{r'\e\e host\e mount'}),
-if present, and \var{rest} the rest of the path (such as
-\code{r'\e path\e file.ext'}). For paths containing drive letters, \var{unc}
-will always be the empty string.
-Availability: Windows.
-\end{funcdesc}
-
-\begin{funcdesc}{walk}{path, visit, arg}
-Calls the function \var{visit} with arguments
-\code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
-directory tree rooted at \var{path} (including \var{path} itself, if it
-is a directory). The argument \var{dirname} specifies the visited
-directory, the argument \var{names} lists the files in the directory
-(gotten from \code{os.listdir(\var{dirname})}).
-The \var{visit} function may modify \var{names} to
-influence the set of directories visited below \var{dirname}, e.g. to
-avoid visiting certain parts of the tree. (The object referred to by
-\var{names} must be modified in place, using \keyword{del} or slice
-assignment.)
-
-\begin{notice}
-Symbolic links to directories are not treated as subdirectories, and
-that \function{walk()} therefore will not visit them. To visit linked
-directories you must identify them with
-\code{os.path.islink(\var{file})} and
-\code{os.path.isdir(\var{file})}, and invoke \function{walk()} as
-necessary.
-\end{notice}
-
-\note{The newer \function{\refmodule{os}.walk()} generator supplies
- similar functionality and can be easier to use.}
-\end{funcdesc}
-
-\begin{datadesc}{supports_unicode_filenames}
-True if arbitrary Unicode strings can be used as file names (within
-limitations imposed by the file system), and if
-\function{os.listdir()} returns Unicode strings for a Unicode
-argument.
-\versionadded{2.3}
-\end{datadesc}
diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex
deleted file mode 100644
index ce35b44..0000000
--- a/Doc/lib/libpprint.tex
+++ /dev/null
@@ -1,210 +0,0 @@
-\section{\module{pprint} ---
- Data pretty printer}
-
-\declaremodule{standard}{pprint}
-\modulesynopsis{Data pretty printer.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{pprint} module provides a capability to ``pretty-print''
-arbitrary Python data structures in a form which can be used as input
-to the interpreter. If the formatted structures include objects which
-are not fundamental Python types, the representation may not be
-loadable. This may be the case if objects such as files, sockets,
-classes, or instances are included, as well as many other builtin
-objects which are not representable as Python constants.
-
-The formatted representation keeps objects on a single line if it can,
-and breaks them onto multiple lines if they don't fit within the
-allowed width. Construct \class{PrettyPrinter} objects explicitly if
-you need to adjust the width constraint.
-
-\versionchanged[Dictionaries are sorted by key before the display is
-computed; before 2.5, a dictionary was sorted only if its display
-required more than one line, although that wasn't documented]{2.5}
-
-The \module{pprint} module defines one class:
-
-
-% First the implementation class:
-
-\begin{classdesc}{PrettyPrinter}{...}
-Construct a \class{PrettyPrinter} instance. This constructor
-understands several keyword parameters. An output stream may be set
-using the \var{stream} keyword; the only method used on the stream
-object is the file protocol's \method{write()} method. If not
-specified, the \class{PrettyPrinter} adopts \code{sys.stdout}. Three
-additional parameters may be used to control the formatted
-representation. The keywords are \var{indent}, \var{depth}, and
-\var{width}. The amount of indentation added for each recursive level
-is specified by \var{indent}; the default is one. Other values can
-cause output to look a little odd, but can make nesting easier to
-spot. The number of levels which may be printed is controlled by
-\var{depth}; if the data structure being printed is too deep, the next
-contained level is replaced by \samp{...}. By default, there is no
-constraint on the depth of the objects being formatted. The desired
-output width is constrained using the \var{width} parameter; the
-default is eighty characters. If a structure cannot be formatted
-within the constrained width, a best effort will be made.
-
-\begin{verbatim}
->>> import pprint, sys
->>> stuff = sys.path[:]
->>> stuff.insert(0, stuff[:])
->>> pp = pprint.PrettyPrinter(indent=4)
->>> pp.pprint(stuff)
-[ [ '',
- '/usr/local/lib/python1.5',
- '/usr/local/lib/python1.5/test',
- '/usr/local/lib/python1.5/sunos5',
- '/usr/local/lib/python1.5/sharedmodules',
- '/usr/local/lib/python1.5/tkinter'],
- '',
- '/usr/local/lib/python1.5',
- '/usr/local/lib/python1.5/test',
- '/usr/local/lib/python1.5/sunos5',
- '/usr/local/lib/python1.5/sharedmodules',
- '/usr/local/lib/python1.5/tkinter']
->>>
->>> import parser
->>> tup = parser.ast2tuple(
-... parser.suite(open('pprint.py').read()))[1][1][1]
->>> pp = pprint.PrettyPrinter(depth=6)
->>> pp.pprint(tup)
-(266, (267, (307, (287, (288, (...))))))
-\end{verbatim}
-\end{classdesc}
-
-
-% Now the derivative functions:
-
-The \class{PrettyPrinter} class supports several derivative functions:
-
-\begin{funcdesc}{pformat}{object\optional{, indent\optional{,
-width\optional{, depth}}}}
-Return the formatted representation of \var{object} as a string. \var{indent},
-\var{width} and \var{depth} will be passed to the \class{PrettyPrinter}
-constructor as formatting parameters.
-\versionchanged[The parameters \var{indent}, \var{width} and \var{depth}
-were added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{pprint}{object\optional{, stream\optional{,
-indent\optional{, width\optional{, depth}}}}}
-Prints the formatted representation of \var{object} on \var{stream},
-followed by a newline. If \var{stream} is omitted, \code{sys.stdout}
-is used. This may be used in the interactive interpreter instead of a
-\keyword{print} statement for inspecting values. \var{indent},
-\var{width} and \var{depth} will be passed to the \class{PrettyPrinter}
-constructor as formatting parameters.
-
-\begin{verbatim}
->>> stuff = sys.path[:]
->>> stuff.insert(0, stuff)
->>> pprint.pprint(stuff)
-[<Recursion on list with id=869440>,
- '',
- '/usr/local/lib/python1.5',
- '/usr/local/lib/python1.5/test',
- '/usr/local/lib/python1.5/sunos5',
- '/usr/local/lib/python1.5/sharedmodules',
- '/usr/local/lib/python1.5/tkinter']
-\end{verbatim}
-\versionchanged[The parameters \var{indent}, \var{width} and \var{depth}
-were added]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{isreadable}{object}
-Determine if the formatted representation of \var{object} is
-``readable,'' or can be used to reconstruct the value using
-\function{eval()}\bifuncindex{eval}. This always returns \code{False} for
-recursive objects.
-
-\begin{verbatim}
->>> pprint.isreadable(stuff)
-False
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{isrecursive}{object}
-Determine if \var{object} requires a recursive representation.
-\end{funcdesc}
-
-
-One more support function is also defined:
-
-\begin{funcdesc}{saferepr}{object}
-Return a string representation of \var{object}, protected against
-recursive data structures. If the representation of \var{object}
-exposes a recursive entry, the recursive reference will be represented
-as \samp{<Recursion on \var{typename} with id=\var{number}>}. The
-representation is not otherwise formatted.
-\end{funcdesc}
-
-% This example is outside the {funcdesc} to keep it from running over
-% the right margin.
-\begin{verbatim}
->>> pprint.saferepr(stuff)
-"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
-l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
-1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
-\end{verbatim}
-
-
-\subsection{PrettyPrinter Objects}
-\label{PrettyPrinter Objects}
-
-\class{PrettyPrinter} instances have the following methods:
-
-
-\begin{methoddesc}[PrettyPrinter]{pformat}{object}
-Return the formatted representation of \var{object}. This takes into
-account the options passed to the \class{PrettyPrinter} constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[PrettyPrinter]{pprint}{object}
-Print the formatted representation of \var{object} on the configured
-stream, followed by a newline.
-\end{methoddesc}
-
-The following methods provide the implementations for the
-corresponding functions of the same names. Using these methods on an
-instance is slightly more efficient since new \class{PrettyPrinter}
-objects don't need to be created.
-
-\begin{methoddesc}[PrettyPrinter]{isreadable}{object}
-Determine if the formatted representation of the object is
-``readable,'' or can be used to reconstruct the value using
-\function{eval()}\bifuncindex{eval}. Note that this returns \code{False} for
-recursive objects. If the \var{depth} parameter of the
-\class{PrettyPrinter} is set and the object is deeper than allowed,
-this returns \code{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[PrettyPrinter]{isrecursive}{object}
-Determine if the object requires a recursive representation.
-\end{methoddesc}
-
-This method is provided as a hook to allow subclasses to modify the
-way objects are converted to strings. The default implementation uses
-the internals of the \function{saferepr()} implementation.
-
-\begin{methoddesc}[PrettyPrinter]{format}{object, context, maxlevels, level}
-Returns three values: the formatted version of \var{object} as a
-string, a flag indicating whether the result is readable, and a flag
-indicating whether recursion was detected. The first argument is the
-object to be presented. The second is a dictionary which contains the
-\function{id()} of objects that are part of the current presentation
-context (direct and indirect containers for \var{object} that are
-affecting the presentation) as the keys; if an object needs to be
-presented which is already represented in \var{context}, the third
-return value should be \code{True}. Recursive calls to the \method{format()}
-method should add additional entries for containers to this
-dictionary. The third argument, \var{maxlevels}, gives the requested
-limit to recursion; this will be \code{0} if there is no requested
-limit. This argument should be passed unmodified to recursive calls.
-The fourth argument, \var{level}, gives the current level; recursive
-calls should be passed a value less than that of the current call.
-\versionadded{2.3}
-\end{methoddesc}
diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex
deleted file mode 100644
index 79a168c..0000000
--- a/Doc/lib/libprofile.tex
+++ /dev/null
@@ -1,722 +0,0 @@
-\chapter{The Python Profilers \label{profile}}
-
-\sectionauthor{James Roskind}{}
-
-Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved.
-\index{InfoSeek Corporation}
-
-Written by James Roskind.\footnote{
- Updated and converted to \LaTeX\ by Guido van Rossum.
- Further updated by Armin Rigo to integrate the documentation for the new
- \module{cProfile} module of Python 2.5.}
-
-Permission to use, copy, modify, and distribute this Python software
-and its associated documentation for any purpose (subject to the
-restriction in the following sentence) without fee is hereby granted,
-provided that the above copyright notice appears in all copies, and
-that both that copyright notice and this permission notice appear in
-supporting documentation, and that the name of InfoSeek not be used in
-advertising or publicity pertaining to distribution of the software
-without specific, written prior permission. This permission is
-explicitly restricted to the copying and modification of the software
-to remain in Python, compiled Python, or other languages (such as C)
-wherein the modified or derived code is exclusively imported into a
-Python module.
-
-INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
-SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY
-SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
-RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
-CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
-CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
-
-The profiler was written after only programming in Python for 3 weeks.
-As a result, it is probably clumsy code, but I don't know for sure yet
-'cause I'm a beginner :-). I did work hard to make the code run fast,
-so that profiling would be a reasonable thing to do. I tried not to
-repeat code fragments, but I'm sure I did some stuff in really awkward
-ways at times. Please send suggestions for improvements to:
-\email{jar@netscape.com}. I won't promise \emph{any} support. ...but
-I'd appreciate the feedback.
-
-
-\section{Introduction to the profilers}
-\nodename{Profiler Introduction}
-
-A \dfn{profiler} is a program that describes the run time performance
-of a program, providing a variety of statistics. This documentation
-describes the profiler functionality provided in the modules
-\module{profile} and \module{pstats}. This profiler provides
-\dfn{deterministic profiling} of any Python programs. It also
-provides a series of report generation tools to allow users to rapidly
-examine the results of a profile operation.
-\index{deterministic profiling}
-\index{profiling, deterministic}
-
-The Python standard library provides three different profilers:
-
-\begin{enumerate}
-\item \module{profile}, a pure Python module, described in the sequel.
- Copyright \copyright{} 1994, by InfoSeek Corporation.
- \versionchanged[also reports the time spent in calls to built-in
- functions and methods]{2.4}
-
-\item \module{cProfile}, a module written in C, with a reasonable
- overhead that makes it suitable for profiling long-running programs.
- Based on \module{lsprof}, contributed by Brett Rosen and Ted Czotter.
- \versionadded{2.5}
-
-\item \module{hotshot}, a C module focusing on minimizing the overhead
- while profiling, at the expense of long data post-processing times.
- \versionchanged[the results should be more meaningful than in the
- past: the timing core contained a critical bug]{2.5}
-\end{enumerate}
-
-The \module{profile} and \module{cProfile} modules export the same
-interface, so they are mostly interchangeables; \module{cProfile} has a
-much lower overhead but is not so far as well-tested and might not be
-available on all systems. \module{cProfile} is really a compatibility
-layer on top of the internal \module{_lsprof} module. The
-\module{hotshot} module is reserved to specialized usages.
-
-%\section{How Is This Profiler Different From The Old Profiler?}
-%\nodename{Profiler Changes}
-%
-%(This section is of historical importance only; the old profiler
-%discussed here was last seen in Python 1.1.)
-%
-%The big changes from old profiling module are that you get more
-%information, and you pay less CPU time. It's not a trade-off, it's a
-%trade-up.
-%
-%To be specific:
-%
-%\begin{description}
-%
-%\item[Bugs removed:]
-%Local stack frame is no longer molested, execution time is now charged
-%to correct functions.
-%
-%\item[Accuracy increased:]
-%Profiler execution time is no longer charged to user's code,
-%calibration for platform is supported, file reads are not done \emph{by}
-%profiler \emph{during} profiling (and charged to user's code!).
-%
-%\item[Speed increased:]
-%Overhead CPU cost was reduced by more than a factor of two (perhaps a
-%factor of five), lightweight profiler module is all that must be
-%loaded, and the report generating module (\module{pstats}) is not needed
-%during profiling.
-%
-%\item[Recursive functions support:]
-%Cumulative times in recursive functions are correctly calculated;
-%recursive entries are counted.
-%
-%\item[Large growth in report generating UI:]
-%Distinct profiles runs can be added together forming a comprehensive
-%report; functions that import statistics take arbitrary lists of
-%files; sorting criteria is now based on keywords (instead of 4 integer
-%options); reports shows what functions were profiled as well as what
-%profile file was referenced; output format has been improved.
-%
-%\end{description}
-
-
-\section{Instant User's Manual \label{profile-instant}}
-
-This section is provided for users that ``don't want to read the
-manual.'' It provides a very brief overview, and allows a user to
-rapidly perform profiling on an existing application.
-
-To profile an application with a main entry point of \function{foo()},
-you would add the following to your module:
-
-\begin{verbatim}
-import cProfile
-cProfile.run('foo()')
-\end{verbatim}
-
-(Use \module{profile} instead of \module{cProfile} if the latter is not
-available on your system.)
-
-The above action would cause \function{foo()} to be run, and a series of
-informative lines (the profile) to be printed. The above approach is
-most useful when working with the interpreter. If you would like to
-save the results of a profile into a file for later examination, you
-can supply a file name as the second argument to the \function{run()}
-function:
-
-\begin{verbatim}
-import cProfile
-cProfile.run('foo()', 'fooprof')
-\end{verbatim}
-
-The file \file{cProfile.py} can also be invoked as
-a script to profile another script. For example:
-
-\begin{verbatim}
-python -m cProfile myscript.py
-\end{verbatim}
-
-\file{cProfile.py} accepts two optional arguments on the command line:
-
-\begin{verbatim}
-cProfile.py [-o output_file] [-s sort_order]
-\end{verbatim}
-
-\programopt{-s} only applies to standard output (\programopt{-o} is
-not supplied). Look in the \class{Stats} documentation for valid sort
-values.
-
-When you wish to review the profile, you should use the methods in the
-\module{pstats} module. Typically you would load the statistics data as
-follows:
-
-\begin{verbatim}
-import pstats
-p = pstats.Stats('fooprof')
-\end{verbatim}
-
-The class \class{Stats} (the above code just created an instance of
-this class) has a variety of methods for manipulating and printing the
-data that was just read into \code{p}. When you ran
-\function{cProfile.run()} above, what was printed was the result of three
-method calls:
-
-\begin{verbatim}
-p.strip_dirs().sort_stats(-1).print_stats()
-\end{verbatim}
-
-The first method removed the extraneous path from all the module
-names. The second method sorted all the entries according to the
-standard module/line/name string that is printed.
-%(this is to comply with the semantics of the old profiler).
-The third method printed out
-all the statistics. You might try the following sort calls:
-
-\begin{verbatim}
-p.sort_stats('name')
-p.print_stats()
-\end{verbatim}
-
-The first call will actually sort the list by function name, and the
-second call will print out the statistics. The following are some
-interesting calls to experiment with:
-
-\begin{verbatim}
-p.sort_stats('cumulative').print_stats(10)
-\end{verbatim}
-
-This sorts the profile by cumulative time in a function, and then only
-prints the ten most significant lines. If you want to understand what
-algorithms are taking time, the above line is what you would use.
-
-If you were looking to see what functions were looping a lot, and
-taking a lot of time, you would do:
-
-\begin{verbatim}
-p.sort_stats('time').print_stats(10)
-\end{verbatim}
-
-to sort according to time spent within each function, and then print
-the statistics for the top ten functions.
-
-You might also try:
-
-\begin{verbatim}
-p.sort_stats('file').print_stats('__init__')
-\end{verbatim}
-
-This will sort all the statistics by file name, and then print out
-statistics for only the class init methods (since they are spelled
-with \code{__init__} in them). As one final example, you could try:
-
-\begin{verbatim}
-p.sort_stats('time', 'cum').print_stats(.5, 'init')
-\end{verbatim}
-
-This line sorts statistics with a primary key of time, and a secondary
-key of cumulative time, and then prints out some of the statistics.
-To be specific, the list is first culled down to 50\% (re: \samp{.5})
-of its original size, then only lines containing \code{init} are
-maintained, and that sub-sub-list is printed.
-
-If you wondered what functions called the above functions, you could
-now (\code{p} is still sorted according to the last criteria) do:
-
-\begin{verbatim}
-p.print_callers(.5, 'init')
-\end{verbatim}
-
-and you would get a list of callers for each of the listed functions.
-
-If you want more functionality, you're going to have to read the
-manual, or guess what the following functions do:
-
-\begin{verbatim}
-p.print_callees()
-p.add('fooprof')
-\end{verbatim}
-
-Invoked as a script, the \module{pstats} module is a statistics
-browser for reading and examining profile dumps. It has a simple
-line-oriented interface (implemented using \refmodule{cmd}) and
-interactive help.
-
-\section{What Is Deterministic Profiling?}
-\nodename{Deterministic Profiling}
-
-\dfn{Deterministic profiling} is meant to reflect the fact that all
-\emph{function call}, \emph{function return}, and \emph{exception} events
-are monitored, and precise timings are made for the intervals between
-these events (during which time the user's code is executing). In
-contrast, \dfn{statistical profiling} (which is not done by this
-module) randomly samples the effective instruction pointer, and
-deduces where time is being spent. The latter technique traditionally
-involves less overhead (as the code does not need to be instrumented),
-but provides only relative indications of where time is being spent.
-
-In Python, since there is an interpreter active during execution, the
-presence of instrumented code is not required to do deterministic
-profiling. Python automatically provides a \dfn{hook} (optional
-callback) for each event. In addition, the interpreted nature of
-Python tends to add so much overhead to execution, that deterministic
-profiling tends to only add small processing overhead in typical
-applications. The result is that deterministic profiling is not that
-expensive, yet provides extensive run time statistics about the
-execution of a Python program.
-
-Call count statistics can be used to identify bugs in code (surprising
-counts), and to identify possible inline-expansion points (high call
-counts). Internal time statistics can be used to identify ``hot
-loops'' that should be carefully optimized. Cumulative time
-statistics should be used to identify high level errors in the
-selection of algorithms. Note that the unusual handling of cumulative
-times in this profiler allows statistics for recursive implementations
-of algorithms to be directly compared to iterative implementations.
-
-
-\section{Reference Manual -- \module{profile} and \module{cProfile}}
-
-\declaremodule{standard}{profile}
-\declaremodule{standard}{cProfile}
-\modulesynopsis{Python profiler}
-
-
-
-The primary entry point for the profiler is the global function
-\function{profile.run()} (resp. \function{cProfile.run()}).
-It is typically used to create any profile
-information. The reports are formatted and printed using methods of
-the class \class{pstats.Stats}. The following is a description of all
-of these standard entry points and functions. For a more in-depth
-view of some of the code, consider reading the later section on
-Profiler Extensions, which includes discussion of how to derive
-``better'' profilers from the classes presented, or reading the source
-code for these modules.
-
-\begin{funcdesc}{run}{command\optional{, filename}}
-
-This function takes a single argument that can be passed to the
-\function{exec()} function, and an optional file name. In all cases this
-routine attempts to \function{exec()} its first argument, and gather profiling
-statistics from the execution. If no file name is present, then this
-function automatically prints a simple profiling report, sorted by the
-standard name string (file/line/function-name) that is presented in
-each line. The following is a typical output from such a call:
-
-\begin{verbatim}
- 2706 function calls (2004 primitive calls) in 4.504 CPU seconds
-
-Ordered by: standard name
-
-ncalls tottime percall cumtime percall filename:lineno(function)
- 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
- 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
- ...
-\end{verbatim}
-
-The first line indicates that 2706 calls were
-monitored. Of those calls, 2004 were \dfn{primitive}. We define
-\dfn{primitive} to mean that the call was not induced via recursion.
-The next line: \code{Ordered by:\ standard name}, indicates that
-the text string in the far right column was used to sort the output.
-The column headings include:
-
-\begin{description}
-
-\item[ncalls ]
-for the number of calls,
-
-\item[tottime ]
-for the total time spent in the given function (and excluding time
-made in calls to sub-functions),
-
-\item[percall ]
-is the quotient of \code{tottime} divided by \code{ncalls}
-
-\item[cumtime ]
-is the total time spent in this and all subfunctions (from invocation
-till exit). This figure is accurate \emph{even} for recursive
-functions.
-
-\item[percall ]
-is the quotient of \code{cumtime} divided by primitive calls
-
-\item[filename:lineno(function) ]
-provides the respective data of each function
-
-\end{description}
-
-When there are two numbers in the first column (for example,
-\samp{43/3}), then the latter is the number of primitive calls, and
-the former is the actual number of calls. Note that when the function
-does not recurse, these two values are the same, and only the single
-figure is printed.
-
-\end{funcdesc}
-
-\begin{funcdesc}{runctx}{command, globals, locals\optional{, filename}}
-This function is similar to \function{run()}, with added
-arguments to supply the globals and locals dictionaries for the
-\var{command} string.
-\end{funcdesc}
-
-Analysis of the profiler data is done using the \class{Stats} class.
-
-\note{The \class{Stats} class is defined in the \module{pstats} module.}
-
-% now switch modules....
-% (This \stmodindex use may be hard to change ;-( )
-\stmodindex{pstats}
-
-\begin{classdesc}{Stats}{filename\optional{, stream=sys.stdout\optional{, \moreargs}}}
-This class constructor creates an instance of a ``statistics object''
-from a \var{filename} (or set of filenames). \class{Stats} objects are
-manipulated by methods, in order to print useful reports. You may specify
-an alternate output stream by giving the keyword argument, \code{stream}.
-
-The file selected by the above constructor must have been created by the
-corresponding version of \module{profile} or \module{cProfile}. To be
-specific, there is \emph{no} file compatibility guaranteed with future
-versions of this profiler, and there is no compatibility with files produced
-by other profilers.
-%(such as the old system profiler).
-
-If several files are provided, all the statistics for identical
-functions will be coalesced, so that an overall view of several
-processes can be considered in a single report. If additional files
-need to be combined with data in an existing \class{Stats} object, the
-\method{add()} method can be used.
-
-\versionchanged[The \var{stream} parameter was added]{2.5}
-\end{classdesc}
-
-
-\subsection{The \class{Stats} Class \label{profile-stats}}
-
-\class{Stats} objects have the following methods:
-
-\begin{methoddesc}[Stats]{strip_dirs}{}
-This method for the \class{Stats} class removes all leading path
-information from file names. It is very useful in reducing the size
-of the printout to fit within (close to) 80 columns. This method
-modifies the object, and the stripped information is lost. After
-performing a strip operation, the object is considered to have its
-entries in a ``random'' order, as it was just after object
-initialization and loading. If \method{strip_dirs()} causes two
-function names to be indistinguishable (they are on the same
-line of the same filename, and have the same function name), then the
-statistics for these two entries are accumulated into a single entry.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Stats]{add}{filename\optional{, \moreargs}}
-This method of the \class{Stats} class accumulates additional
-profiling information into the current profiling object. Its
-arguments should refer to filenames created by the corresponding
-version of \function{profile.run()} or \function{cProfile.run()}.
-Statistics for identically named
-(re: file, line, name) functions are automatically accumulated into
-single function statistics.
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{dump_stats}{filename}
-Save the data loaded into the \class{Stats} object to a file named
-\var{filename}. The file is created if it does not exist, and is
-overwritten if it already exists. This is equivalent to the method of
-the same name on the \class{profile.Profile} and
-\class{cProfile.Profile} classes.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{sort_stats}{key\optional{, \moreargs}}
-This method modifies the \class{Stats} object by sorting it according
-to the supplied criteria. The argument is typically a string
-identifying the basis of a sort (example: \code{'time'} or
-\code{'name'}).
-
-When more than one key is provided, then additional keys are used as
-secondary criteria when there is equality in all keys selected
-before them. For example, \code{sort_stats('name', 'file')} will sort
-all the entries according to their function name, and resolve all ties
-(identical function names) by sorting by file name.
-
-Abbreviations can be used for any key names, as long as the
-abbreviation is unambiguous. The following are the keys currently
-defined:
-
-\begin{tableii}{l|l}{code}{Valid Arg}{Meaning}
- \lineii{'calls'}{call count}
- \lineii{'cumulative'}{cumulative time}
- \lineii{'file'}{file name}
- \lineii{'module'}{file name}
- \lineii{'pcalls'}{primitive call count}
- \lineii{'line'}{line number}
- \lineii{'name'}{function name}
- \lineii{'nfl'}{name/file/line}
- \lineii{'stdname'}{standard name}
- \lineii{'time'}{internal time}
-\end{tableii}
-
-Note that all sorts on statistics are in descending order (placing
-most time consuming items first), where as name, file, and line number
-searches are in ascending order (alphabetical). The subtle
-distinction between \code{'nfl'} and \code{'stdname'} is that the
-standard name is a sort of the name as printed, which means that the
-embedded line numbers get compared in an odd way. For example, lines
-3, 20, and 40 would (if the file names were the same) appear in the
-string order 20, 3 and 40. In contrast, \code{'nfl'} does a numeric
-compare of the line numbers. In fact, \code{sort_stats('nfl')} is the
-same as \code{sort_stats('name', 'file', 'line')}.
-
-%For compatibility with the old profiler,
-For backward-compatibility reasons, the numeric arguments
-\code{-1}, \code{0}, \code{1}, and \code{2} are permitted. They are
-interpreted as \code{'stdname'}, \code{'calls'}, \code{'time'}, and
-\code{'cumulative'} respectively. If this old style format (numeric)
-is used, only one sort key (the numeric key) will be used, and
-additional arguments will be silently ignored.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Stats]{reverse_order}{}
-This method for the \class{Stats} class reverses the ordering of the basic
-list within the object. %This method is provided primarily for
-%compatibility with the old profiler.
-Note that by default ascending vs descending order is properly selected
-based on the sort key of choice.
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{print_stats}{\optional{restriction, \moreargs}}
-This method for the \class{Stats} class prints out a report as described
-in the \function{profile.run()} definition.
-
-The order of the printing is based on the last \method{sort_stats()}
-operation done on the object (subject to caveats in \method{add()} and
-\method{strip_dirs()}).
-
-The arguments provided (if any) can be used to limit the list down to
-the significant entries. Initially, the list is taken to be the
-complete set of profiled functions. Each restriction is either an
-integer (to select a count of lines), or a decimal fraction between
-0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
-expression (to pattern match the standard name that is printed; as of
-Python 1.5b1, this uses the Perl-style regular expression syntax
-defined by the \refmodule{re} module). If several restrictions are
-provided, then they are applied sequentially. For example:
-
-\begin{verbatim}
-print_stats(.1, 'foo:')
-\end{verbatim}
-
-would first limit the printing to first 10\% of list, and then only
-print functions that were part of filename \file{.*foo:}. In
-contrast, the command:
-
-\begin{verbatim}
-print_stats('foo:', .1)
-\end{verbatim}
-
-would limit the list to all functions having file names \file{.*foo:},
-and then proceed to only print the first 10\% of them.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Stats]{print_callers}{\optional{restriction, \moreargs}}
-This method for the \class{Stats} class prints a list of all functions
-that called each function in the profiled database. The ordering is
-identical to that provided by \method{print_stats()}, and the definition
-of the restricting argument is also identical. Each caller is reported on
-its own line. The format differs slightly depending on the profiler that
-produced the stats:
-
-\begin{itemize}
-\item With \module{profile}, a number is shown in parentheses after each
- caller to show how many times this specific call was made. For
- convenience, a second non-parenthesized number repeats the cumulative
- time spent in the function at the right.
-
-\item With \module{cProfile}, each caller is preceeded by three numbers:
- the number of times this specific call was made, and the total and
- cumulative times spent in the current function while it was invoked by
- this specific caller.
-\end{itemize}
-\end{methoddesc}
-
-\begin{methoddesc}[Stats]{print_callees}{\optional{restriction, \moreargs}}
-This method for the \class{Stats} class prints a list of all function
-that were called by the indicated function. Aside from this reversal
-of direction of calls (re: called vs was called by), the arguments and
-ordering are identical to the \method{print_callers()} method.
-\end{methoddesc}
-
-
-\section{Limitations \label{profile-limits}}
-
-One limitation has to do with accuracy of timing information.
-There is a fundamental problem with deterministic profilers involving
-accuracy. The most obvious restriction is that the underlying ``clock''
-is only ticking at a rate (typically) of about .001 seconds. Hence no
-measurements will be more accurate than the underlying clock. If
-enough measurements are taken, then the ``error'' will tend to average
-out. Unfortunately, removing this first error induces a second source
-of error.
-
-The second problem is that it ``takes a while'' from when an event is
-dispatched until the profiler's call to get the time actually
-\emph{gets} the state of the clock. Similarly, there is a certain lag
-when exiting the profiler event handler from the time that the clock's
-value was obtained (and then squirreled away), until the user's code
-is once again executing. As a result, functions that are called many
-times, or call many functions, will typically accumulate this error.
-The error that accumulates in this fashion is typically less than the
-accuracy of the clock (less than one clock tick), but it
-\emph{can} accumulate and become very significant.
-
-The problem is more important with \module{profile} than with the
-lower-overhead \module{cProfile}. For this reason, \module{profile}
-provides a means of calibrating itself for a given platform so that
-this error can be probabilistically (on the average) removed.
-After the profiler is calibrated, it will be more accurate (in a least
-square sense), but it will sometimes produce negative numbers (when
-call counts are exceptionally low, and the gods of probability work
-against you :-). ) Do \emph{not} be alarmed by negative numbers in
-the profile. They should \emph{only} appear if you have calibrated
-your profiler, and the results are actually better than without
-calibration.
-
-
-\section{Calibration \label{profile-calibration}}
-
-The profiler of the \module{profile} module subtracts a constant from each
-event handling time to compensate for the overhead of calling the time
-function, and socking away the results. By default, the constant is 0.
-The following procedure can
-be used to obtain a better constant for a given platform (see discussion
-in section Limitations above).
-
-\begin{verbatim}
-import profile
-pr = profile.Profile()
-for i in range(5):
- print pr.calibrate(10000)
-\end{verbatim}
-
-The method executes the number of Python calls given by the argument,
-directly and again under the profiler, measuring the time for both.
-It then computes the hidden overhead per profiler event, and returns
-that as a float. For example, on an 800 MHz Pentium running
-Windows 2000, and using Python's time.clock() as the timer,
-the magical number is about 12.5e-6.
-
-The object of this exercise is to get a fairly consistent result.
-If your computer is \emph{very} fast, or your timer function has poor
-resolution, you might have to pass 100000, or even 1000000, to get
-consistent results.
-
-When you have a consistent answer,
-there are three ways you can use it:\footnote{Prior to Python 2.2, it
- was necessary to edit the profiler source code to embed the bias as
- a literal number. You still can, but that method is no longer
- described, because no longer needed.}
-
-\begin{verbatim}
-import profile
-
-# 1. Apply computed bias to all Profile instances created hereafter.
-profile.Profile.bias = your_computed_bias
-
-# 2. Apply computed bias to a specific Profile instance.
-pr = profile.Profile()
-pr.bias = your_computed_bias
-
-# 3. Specify computed bias in instance constructor.
-pr = profile.Profile(bias=your_computed_bias)
-\end{verbatim}
-
-If you have a choice, you are better off choosing a smaller constant, and
-then your results will ``less often'' show up as negative in profile
-statistics.
-
-
-\section{Extensions --- Deriving Better Profilers}
-\nodename{Profiler Extensions}
-
-The \class{Profile} class of both modules, \module{profile} and
-\module{cProfile}, were written so that
-derived classes could be developed to extend the profiler. The details
-are not described here, as doing this successfully requires an expert
-understanding of how the \class{Profile} class works internally. Study
-the source code of the module carefully if you want to
-pursue this.
-
-If all you want to do is change how current time is determined (for
-example, to force use of wall-clock time or elapsed process time),
-pass the timing function you want to the \class{Profile} class
-constructor:
-
-\begin{verbatim}
-pr = profile.Profile(your_time_func)
-\end{verbatim}
-
-The resulting profiler will then call \function{your_time_func()}.
-
-\begin{description}
-\item[\class{profile.Profile}]
-\function{your_time_func()} should return a single number, or a list of
-numbers whose sum is the current time (like what \function{os.times()}
-returns). If the function returns a single time number, or the list of
-returned numbers has length 2, then you will get an especially fast
-version of the dispatch routine.
-
-Be warned that you should calibrate the profiler class for the
-timer function that you choose. For most machines, a timer that
-returns a lone integer value will provide the best results in terms of
-low overhead during profiling. (\function{os.times()} is
-\emph{pretty} bad, as it returns a tuple of floating point values). If
-you want to substitute a better timer in the cleanest fashion,
-derive a class and hardwire a replacement dispatch method that best
-handles your timer call, along with the appropriate calibration
-constant.
-
-\item[\class{cProfile.Profile}]
-\function{your_time_func()} should return a single number. If it returns
-plain integers, you can also invoke the class constructor with a second
-argument specifying the real duration of one unit of time. For example,
-if \function{your_integer_time_func()} returns times measured in thousands
-of seconds, you would constuct the \class{Profile} instance as follows:
-
-\begin{verbatim}
-pr = profile.Profile(your_integer_time_func, 0.001)
-\end{verbatim}
-
-As the \module{cProfile.Profile} class cannot be calibrated, custom
-timer functions should be used with care and should be as fast as
-possible. For the best results with a custom timer, it might be
-necessary to hard-code it in the C source of the internal
-\module{_lsprof} module.
-
-\end{description}
diff --git a/Doc/lib/libpty.tex b/Doc/lib/libpty.tex
deleted file mode 100644
index 2db7503..0000000
--- a/Doc/lib/libpty.tex
+++ /dev/null
@@ -1,44 +0,0 @@
-\section{\module{pty} ---
- Pseudo-terminal utilities}
-\declaremodule{standard}{pty}
- \platform{IRIX, Linux}
-\modulesynopsis{Pseudo-Terminal Handling for SGI and Linux.}
-\moduleauthor{Steen Lumholt}{}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-
-
-The \module{pty} module defines operations for handling the
-pseudo-terminal concept: starting another process and being able to
-write to and read from its controlling terminal programmatically.
-
-Because pseudo-terminal handling is highly platform dependant, there
-is code to do it only for SGI and Linux. (The Linux code is supposed
-to work on other platforms, but hasn't been tested yet.)
-
-The \module{pty} module defines the following functions:
-
-\begin{funcdesc}{fork}{}
-Fork. Connect the child's controlling terminal to a pseudo-terminal.
-Return value is \code{(\var{pid}, \var{fd})}. Note that the child
-gets \var{pid} 0, and the \var{fd} is \emph{invalid}. The parent's
-return value is the \var{pid} of the child, and \var{fd} is a file
-descriptor connected to the child's controlling terminal (and also
-to the child's standard input and output).
-\end{funcdesc}
-
-\begin{funcdesc}{openpty}{}
-Open a new pseudo-terminal pair, using \function{os.openpty()} if
-possible, or emulation code for SGI and generic \UNIX{} systems.
-Return a pair of file descriptors \code{(\var{master}, \var{slave})},
-for the master and the slave end, respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{spawn}{argv\optional{, master_read\optional{, stdin_read}}}
-Spawn a process, and connect its controlling terminal with the current
-process's standard io. This is often used to baffle programs which
-insist on reading from the controlling terminal.
-
-The functions \var{master_read} and \var{stdin_read} should be
-functions which read from a file-descriptor. The defaults try to read
-1024 bytes each time they are called.
-\end{funcdesc}
diff --git a/Doc/lib/libpwd.tex b/Doc/lib/libpwd.tex
deleted file mode 100644
index 0c74d26..0000000
--- a/Doc/lib/libpwd.tex
+++ /dev/null
@@ -1,57 +0,0 @@
-\section{\module{pwd} ---
- The password database}
-
-\declaremodule{builtin}{pwd}
- \platform{Unix}
-\modulesynopsis{The password database (\function{getpwnam()} and friends).}
-
-This module provides access to the \UNIX{} user account and password
-database. It is available on all \UNIX{} versions.
-
-Password database entries are reported as a tuple-like object, whose
-attributes correspond to the members of the \code{passwd} structure
-(Attribute field below, see \code{<pwd.h>}):
-
-\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
- \lineiii{0}{\code{pw_name}}{Login name}
- \lineiii{1}{\code{pw_passwd}}{Optional encrypted password}
- \lineiii{2}{\code{pw_uid}}{Numerical user ID}
- \lineiii{3}{\code{pw_gid}}{Numerical group ID}
- \lineiii{4}{\code{pw_gecos}}{User name or comment field}
- \lineiii{5}{\code{pw_dir}}{User home directory}
- \lineiii{6}{\code{pw_shell}}{User command interpreter}
-\end{tableiii}
-
-The uid and gid items are integers, all others are strings.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-
-\note{In traditional \UNIX{} the field \code{pw_passwd} usually
-contains a password encrypted with a DES derived algorithm (see module
-\refmodule{crypt}\refbimodindex{crypt}). However most modern unices
-use a so-called \emph{shadow password} system. On those unices the
-\var{pw_passwd} field only contains an asterisk (\code{'*'}) or the
-letter \character{x} where the encrypted password is stored in a file
-\file{/etc/shadow} which is not world readable. Whether the \var{pw_passwd}
-field contains anything useful is system-dependent. If available, the
-\module{spwd} module should be used where access to the encrypted password
-is required.}
-
-It defines the following items:
-
-\begin{funcdesc}{getpwuid}{uid}
-Return the password database entry for the given numeric user ID.
-\end{funcdesc}
-
-\begin{funcdesc}{getpwnam}{name}
-Return the password database entry for the given user name.
-\end{funcdesc}
-
-\begin{funcdesc}{getpwall}{}
-Return a list of all available password database entries, in arbitrary order.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{grp}{An interface to the group database, similar to this.}
- \seemodule{spwd}{An interface to the shadow password database, similar to this.}
-\end{seealso}
diff --git a/Doc/lib/libpyclbr.tex b/Doc/lib/libpyclbr.tex
deleted file mode 100644
index 0dedb9e..0000000
--- a/Doc/lib/libpyclbr.tex
+++ /dev/null
@@ -1,102 +0,0 @@
-\section{\module{pyclbr} ---
- Python class browser support}
-
-\declaremodule{standard}{pyclbr}
-\modulesynopsis{Supports information extraction for a Python class
- browser.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{pyclbr} can be used to determine some limited information
-about the classes, methods and top-level functions
-defined in a module. The information
-provided is sufficient to implement a traditional three-pane class
-browser. The information is extracted from the source code rather
-than by importing the module, so this module is safe to use with
-untrusted source code. This restriction makes it impossible to use
-this module with modules not implemented in Python, including many
-standard and optional extension modules.
-
-
-\begin{funcdesc}{readmodule}{module\optional{, path}}
- % The 'inpackage' parameter appears to be for internal use only....
- Read a module and return a dictionary mapping class names to class
- descriptor objects. The parameter \var{module} should be the name
- of a module as a string; it may be the name of a module within a
- package. The \var{path} parameter should be a sequence, and is used
- to augment the value of \code{sys.path}, which is used to locate
- module source code.
-\end{funcdesc}
-
-\begin{funcdesc}{readmodule_ex}{module\optional{, path}}
- % The 'inpackage' parameter appears to be for internal use only....
- Like \function{readmodule()}, but the returned dictionary, in addition
- to mapping class names to class descriptor objects, also maps
- top-level function names to function descriptor objects. Moreover, if
- the module being read is a package, the key \code{'__path__'} in the
- returned dictionary has as its value a list which contains the package
- search path.
-\end{funcdesc}
-
-
-\subsection{Class Descriptor Objects \label{pyclbr-class-objects}}
-
-The class descriptor objects used as values in the dictionary returned
-by \function{readmodule()} and \function{readmodule_ex()}
-provide the following data members:
-
-
-\begin{memberdesc}[class descriptor]{module}
- The name of the module defining the class described by the class
- descriptor.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{name}
- The name of the class.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{super}
- A list of class descriptors which describe the immediate base
- classes of the class being described. Classes which are named as
- superclasses but which are not discoverable by
- \function{readmodule()} are listed as a string with the class name
- instead of class descriptors.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{methods}
- A dictionary mapping method names to line numbers.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{file}
- Name of the file containing the \code{class} statement defining the class.
-\end{memberdesc}
-
-\begin{memberdesc}[class descriptor]{lineno}
- The line number of the \code{class} statement within the file named by
- \member{file}.
-\end{memberdesc}
-
-\subsection{Function Descriptor Objects \label{pyclbr-function-objects}}
-
-The function descriptor objects used as values in the dictionary returned
-by \function{readmodule_ex()} provide the following data members:
-
-
-\begin{memberdesc}[function descriptor]{module}
- The name of the module defining the function described by the function
- descriptor.
-\end{memberdesc}
-
-\begin{memberdesc}[function descriptor]{name}
- The name of the function.
-\end{memberdesc}
-
-\begin{memberdesc}[function descriptor]{file}
- Name of the file containing the \code{def} statement defining the function.
-\end{memberdesc}
-
-\begin{memberdesc}[function descriptor]{lineno}
- The line number of the \code{def} statement within the file named by
- \member{file}.
-\end{memberdesc}
-
diff --git a/Doc/lib/libpycompile.tex b/Doc/lib/libpycompile.tex
deleted file mode 100644
index 85f0aaa..0000000
--- a/Doc/lib/libpycompile.tex
+++ /dev/null
@@ -1,53 +0,0 @@
-\section{\module{py_compile} ---
- Compile Python source files}
-
-% Documentation based on module docstrings, by Fred L. Drake, Jr.
-% <fdrake@acm.org>
-
-\declaremodule[pycompile]{standard}{py_compile}
-
-\modulesynopsis{Compile Python source files to byte-code files.}
-
-
-\indexii{file}{byte-code}
-The \module{py_compile} module provides a function to generate a
-byte-code file from a source file, and another function used when the
-module source file is invoked as a script.
-
-Though not often needed, this function can be useful when installing
-modules for shared use, especially if some of the users may not have
-permission to write the byte-code cache files in the directory
-containing the source code.
-
-\begin{excdesc}{PyCompileError}
-Exception raised when an error occurs while attempting to compile the file.
-\end{excdesc}
-
-\begin{funcdesc}{compile}{file\optional{, cfile\optional{, dfile\optional{, doraise}}}}
- Compile a source file to byte-code and write out the byte-code cache
- file. The source code is loaded from the file name \var{file}. The
- byte-code is written to \var{cfile}, which defaults to \var{file}
- \code{+} \code{'c'} (\code{'o'} if optimization is enabled in the
- current interpreter). If \var{dfile} is specified, it is used as
- the name of the source file in error messages instead of \var{file}.
- If \var{doraise} is true, a \exception{PyCompileError} is raised when
- an error is encountered while compiling \var{file}. If \var{doraise}
- is false (the default), an error string is written to \code{sys.stderr},
- but no exception is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{main}{\optional{args}}
- Compile several source files. The files named in \var{args} (or on
- the command line, if \var{args} is not specified) are compiled and
- the resulting bytecode is cached in the normal manner. This
- function does not search a directory structure to locate source
- files; it only compiles files named explicitly.
-\end{funcdesc}
-
-When this module is run as a script, the \function{main()} is used to
-compile all the files named on the command line.
-
-\begin{seealso}
- \seemodule{compileall}{Utilities to compile all Python source files
- in a directory tree.}
-\end{seealso}
diff --git a/Doc/lib/libpydoc.tex b/Doc/lib/libpydoc.tex
deleted file mode 100644
index bb74df6..0000000
--- a/Doc/lib/libpydoc.tex
+++ /dev/null
@@ -1,67 +0,0 @@
-\section{\module{pydoc} ---
- Documentation generator and online help system}
-
-\declaremodule{standard}{pydoc}
-\modulesynopsis{Documentation generator and online help system.}
-\moduleauthor{Ka-Ping Yee}{ping@lfw.org}
-\sectionauthor{Ka-Ping Yee}{ping@lfw.org}
-
-\versionadded{2.1}
-\index{documentation!generation}
-\index{documentation!online}
-\index{help!online}
-
-The \module{pydoc} module automatically generates documentation from
-Python modules. The documentation can be presented as pages of text
-on the console, served to a Web browser, or saved to HTML files.
-
-The built-in function \function{help()} invokes the online help system
-in the interactive interpreter, which uses \module{pydoc} to generate
-its documentation as text on the console. The same text documentation
-can also be viewed from outside the Python interpreter by running
-\program{pydoc} as a script at the operating system's command prompt.
-For example, running
-
-\begin{verbatim}
-pydoc sys
-\end{verbatim}
-
-at a shell prompt will display documentation on the \refmodule{sys}
-module, in a style similar to the manual pages shown by the \UNIX{}
-\program{man} command. The argument to \program{pydoc} can be the name
-of a function, module, or package, or a dotted reference to a class,
-method, or function within a module or module in a package. If the
-argument to \program{pydoc} looks like a path (that is, it contains the
-path separator for your operating system, such as a slash in \UNIX),
-and refers to an existing Python source file, then documentation is
-produced for that file.
-
-Specifying a \programopt{-w} flag before the argument will cause HTML
-documentation to be written out to a file in the current directory,
-instead of displaying text on the console.
-
-Specifying a \programopt{-k} flag before the argument will search the
-synopsis lines of all available modules for the keyword given as the
-argument, again in a manner similar to the \UNIX{} \program{man}
-command. The synopsis line of a module is the first line of its
-documentation string.
-
-You can also use \program{pydoc} to start an HTTP server on the local
-machine that will serve documentation to visiting Web browsers.
-\program{pydoc} \programopt{-p 1234} will start a HTTP server on port
-1234, allowing you to browse the documentation at
-\code{http://localhost:1234/} in your preferred Web browser.
-\program{pydoc} \programopt{-g} will start the server and additionally
-bring up a small \refmodule{Tkinter}-based graphical interface to help
-you search for documentation pages.
-
-When \program{pydoc} generates documentation, it uses the current
-environment and path to locate modules. Thus, invoking
-\program{pydoc} \programopt{spam} documents precisely the version of
-the module you would get if you started the Python interpreter and
-typed \samp{import spam}.
-
-Module docs for core modules are assumed to reside in
-{}\url{http://www.python.org/doc/current/lib/}. This can be overridden by
-setting the \envvar{PYTHONDOCS} environment variable to a different URL or
-to a local directory containing the Library Reference Manual pages.
diff --git a/Doc/lib/libpyexpat.tex b/Doc/lib/libpyexpat.tex
deleted file mode 100644
index ed0bf6a..0000000
--- a/Doc/lib/libpyexpat.tex
+++ /dev/null
@@ -1,766 +0,0 @@
-\section{\module{xml.parsers.expat} ---
- Fast XML parsing using Expat}
-
-% Markup notes:
-%
-% Many of the attributes of the XMLParser objects are callbacks.
-% Since signature information must be presented, these are described
-% using the methoddesc environment. Since they are attributes which
-% are set by client code, in-text references to these attributes
-% should be marked using the \member macro and should not include the
-% parentheses used when marking functions and methods.
-
-\declaremodule{standard}{xml.parsers.expat}
-\modulesynopsis{An interface to the Expat non-validating XML parser.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
-
-\versionadded{2.0}
-
-The \module{xml.parsers.expat} module is a Python interface to the
-Expat\index{Expat} non-validating XML parser.
-The module provides a single extension type, \class{xmlparser}, that
-represents the current state of an XML parser. After an
-\class{xmlparser} object has been created, various attributes of the object
-can be set to handler functions. When an XML document is then fed to
-the parser, the handler functions are called for the character data
-and markup in the XML document.
-
-This module uses the \module{pyexpat}\refbimodindex{pyexpat} module to
-provide access to the Expat parser. Direct use of the
-\module{pyexpat} module is deprecated.
-
-This module provides one exception and one type object:
-
-\begin{excdesc}{ExpatError}
- The exception raised when Expat reports an error. See section
- \ref{expaterror-objects}, ``ExpatError Exceptions,'' for more
- information on interpreting Expat errors.
-\end{excdesc}
-
-\begin{excdesc}{error}
- Alias for \exception{ExpatError}.
-\end{excdesc}
-
-\begin{datadesc}{XMLParserType}
- The type of the return values from the \function{ParserCreate()}
- function.
-\end{datadesc}
-
-
-The \module{xml.parsers.expat} module contains two functions:
-
-\begin{funcdesc}{ErrorString}{errno}
-Returns an explanatory string for a given error number \var{errno}.
-\end{funcdesc}
-
-\begin{funcdesc}{ParserCreate}{\optional{encoding\optional{,
- namespace_separator}}}
-Creates and returns a new \class{xmlparser} object.
-\var{encoding}, if specified, must be a string naming the encoding
-used by the XML data. Expat doesn't support as many encodings as
-Python does, and its repertoire of encodings can't be extended; it
-supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If
-\var{encoding} is given it will override the implicit or explicit
-encoding of the document.
-
-Expat can optionally do XML namespace processing for you, enabled by
-providing a value for \var{namespace_separator}. The value must be a
-one-character string; a \exception{ValueError} will be raised if the
-string has an illegal length (\code{None} is considered the same as
-omission). When namespace processing is enabled, element type names
-and attribute names that belong to a namespace will be expanded. The
-element name passed to the element handlers
-\member{StartElementHandler} and \member{EndElementHandler}
-will be the concatenation of the namespace URI, the namespace
-separator character, and the local part of the name. If the namespace
-separator is a zero byte (\code{chr(0)}) then the namespace URI and
-the local part will be concatenated without any separator.
-
-For example, if \var{namespace_separator} is set to a space character
-(\character{ }) and the following document is parsed:
-
-\begin{verbatim}
-<?xml version="1.0"?>
-<root xmlns = "http://default-namespace.org/"
- xmlns:py = "http://www.python.org/ns/">
- <py:elem1 />
- <elem2 xmlns="" />
-</root>
-\end{verbatim}
-
-\member{StartElementHandler} will receive the following strings
-for each element:
-
-\begin{verbatim}
-http://default-namespace.org/ root
-http://www.python.org/ns/ elem1
-elem2
-\end{verbatim}
-\end{funcdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.libexpat.org/]{The Expat XML Parser}
- {Home page of the Expat project.}
-\end{seealso}
-
-
-\subsection{XMLParser Objects \label{xmlparser-objects}}
-
-\class{xmlparser} objects have the following methods:
-
-\begin{methoddesc}[xmlparser]{Parse}{data\optional{, isfinal}}
-Parses the contents of the string \var{data}, calling the appropriate
-handler functions to process the parsed data. \var{isfinal} must be
-true on the final call to this method. \var{data} can be the empty
-string at any time.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ParseFile}{file}
-Parse XML data reading from the object \var{file}. \var{file} only
-needs to provide the \method{read(\var{nbytes})} method, returning the
-empty string when there's no more data.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{SetBase}{base}
-Sets the base to be used for resolving relative URIs in system
-identifiers in declarations. Resolving relative identifiers is left
-to the application: this value will be passed through as the
-\var{base} argument to the \function{ExternalEntityRefHandler},
-\function{NotationDeclHandler}, and
-\function{UnparsedEntityDeclHandler} functions.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{GetBase}{}
-Returns a string containing the base set by a previous call to
-\method{SetBase()}, or \code{None} if
-\method{SetBase()} hasn't been called.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{GetInputContext}{}
-Returns the input data that generated the current event as a string.
-The data is in the encoding of the entity which contains the text.
-When called while an event handler is not active, the return value is
-\code{None}.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ExternalEntityParserCreate}{context\optional{,
- encoding}}
-Create a ``child'' parser which can be used to parse an external
-parsed entity referred to by content parsed by the parent parser. The
-\var{context} parameter should be the string passed to the
-\method{ExternalEntityRefHandler()} handler function, described below.
-The child parser is created with the \member{ordered_attributes}
-and \member{specified_attributes} set to the
-values of this parser.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{UseForeignDTD}{\optional{flag}}
-Calling this with a true value for \var{flag} (the default) will cause
-Expat to call the \member{ExternalEntityRefHandler} with
-\constant{None} for all arguments to allow an alternate DTD to be
-loaded. If the document does not contain a document type declaration,
-the \member{ExternalEntityRefHandler} will still be called, but the
-\member{StartDoctypeDeclHandler} and \member{EndDoctypeDeclHandler}
-will not be called.
-
-Passing a false value for \var{flag} will cancel a previous call that
-passed a true value, but otherwise has no effect.
-
-This method can only be called before the \method{Parse()} or
-\method{ParseFile()} methods are called; calling it after either of
-those have been called causes \exception{ExpatError} to be raised with
-the \member{code} attribute set to
-\constant{errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-
-\class{xmlparser} objects have the following attributes:
-
-\begin{memberdesc}[xmlparser]{buffer_size}
-The size of the buffer used when \member{buffer_text} is true. This
-value cannot be changed at this time.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{buffer_text}
-Setting this to true causes the \class{xmlparser} object to buffer
-textual content returned by Expat to avoid multiple calls to the
-\method{CharacterDataHandler()} callback whenever possible. This can
-improve performance substantially since Expat normally breaks
-character data into chunks at every line ending. This attribute is
-false by default, and may be changed at any time.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{buffer_used}
-If \member{buffer_text} is enabled, the number of bytes stored in the
-buffer. These bytes represent UTF-8 encoded text. This attribute has
-no meaningful interpretation when \member{buffer_text} is false.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ordered_attributes}
-Setting this attribute to a non-zero integer causes the attributes to
-be reported as a list rather than a dictionary. The attributes are
-presented in the order found in the document text. For each
-attribute, two list entries are presented: the attribute name and the
-attribute value. (Older versions of this module also used this
-format.) By default, this attribute is false; it may be changed at
-any time.
-\versionadded{2.1}
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{specified_attributes}
-If set to a non-zero integer, the parser will report only those
-attributes which were specified in the document instance and not those
-which were derived from attribute declarations. Applications which
-set this need to be especially careful to use what additional
-information is available from the declarations as needed to comply
-with the standards for the behavior of XML processors. By default,
-this attribute is false; it may be changed at any time.
-\versionadded{2.1}
-\end{memberdesc}
-
-The following attributes contain values relating to the most recent
-error encountered by an \class{xmlparser} object, and will only have
-correct values once a call to \method{Parse()} or \method{ParseFile()}
-has raised a \exception{xml.parsers.expat.ExpatError} exception.
-
-\begin{memberdesc}[xmlparser]{ErrorByteIndex}
-Byte index at which an error occurred.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ErrorCode}
-Numeric code specifying the problem. This value can be passed to the
-\function{ErrorString()} function, or compared to one of the constants
-defined in the \code{errors} object.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ErrorColumnNumber}
-Column number at which an error occurred.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{ErrorLineNumber}
-Line number at which an error occurred.
-\end{memberdesc}
-
-The following attributes contain values relating to the current parse
-location in an \class{xmlparser} object. During a callback reporting
-a parse event they indicate the location of the first of the sequence
-of characters that generated the event. When called outside of a
-callback, the position indicated will be just past the last parse
-event (regardless of whether there was an associated callback).
-\versionadded{2.4}
-
-\begin{memberdesc}[xmlparser]{CurrentByteIndex}
-Current byte index in the parser input.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{CurrentColumnNumber}
-Current column number in the parser input.
-\end{memberdesc}
-
-\begin{memberdesc}[xmlparser]{CurrentLineNumber}
-Current line number in the parser input.
-\end{memberdesc}
-
-Here is the list of handlers that can be set. To set a handler on an
-\class{xmlparser} object \var{o}, use
-\code{\var{o}.\var{handlername} = \var{func}}. \var{handlername} must
-be taken from the following list, and \var{func} must be a callable
-object accepting the correct number of arguments. The arguments are
-all strings, unless otherwise stated.
-
-\begin{methoddesc}[xmlparser]{XmlDeclHandler}{version, encoding, standalone}
-Called when the XML declaration is parsed. The XML declaration is the
-(optional) declaration of the applicable version of the XML
-recommendation, the encoding of the document text, and an optional
-``standalone'' declaration. \var{version} and \var{encoding} will be
-strings, and \var{standalone} will be \code{1} if the document is
-declared standalone, \code{0} if it is declared not to be standalone,
-or \code{-1} if the standalone clause was omitted.
-This is only available with Expat version 1.95.0 or newer.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartDoctypeDeclHandler}{doctypeName,
- systemId, publicId,
- has_internal_subset}
-Called when Expat begins parsing the document type declaration
-(\code{<!DOCTYPE \ldots}). The \var{doctypeName} is provided exactly
-as presented. The \var{systemId} and \var{publicId} parameters give
-the system and public identifiers if specified, or \code{None} if
-omitted. \var{has_internal_subset} will be true if the document
-contains and internal document declaration subset.
-This requires Expat version 1.2 or newer.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndDoctypeDeclHandler}{}
-Called when Expat is done parsing the document type declaration.
-This requires Expat version 1.2 or newer.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ElementDeclHandler}{name, model}
-Called once for each element type declaration. \var{name} is the name
-of the element type, and \var{model} is a representation of the
-content model.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{AttlistDeclHandler}{elname, attname,
- type, default, required}
-Called for each declared attribute for an element type. If an
-attribute list declaration declares three attributes, this handler is
-called three times, once for each attribute. \var{elname} is the name
-of the element to which the declaration applies and \var{attname} is
-the name of the attribute declared. The attribute type is a string
-passed as \var{type}; the possible values are \code{'CDATA'},
-\code{'ID'}, \code{'IDREF'}, ...
-\var{default} gives the default value for the attribute used when the
-attribute is not specified by the document instance, or \code{None} if
-there is no default value (\code{\#IMPLIED} values). If the attribute
-is required to be given in the document instance, \var{required} will
-be true.
-This requires Expat version 1.95.0 or newer.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartElementHandler}{name, attributes}
-Called for the start of every element. \var{name} is a string
-containing the element name, and \var{attributes} is a dictionary
-mapping attribute names to their values.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndElementHandler}{name}
-Called for the end of every element.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ProcessingInstructionHandler}{target, data}
-Called for every processing instruction.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{CharacterDataHandler}{data}
-Called for character data. This will be called for normal character
-data, CDATA marked content, and ignorable whitespace. Applications
-which must distinguish these cases can use the
-\member{StartCdataSectionHandler}, \member{EndCdataSectionHandler},
-and \member{ElementDeclHandler} callbacks to collect the required
-information.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{UnparsedEntityDeclHandler}{entityName, base,
- systemId, publicId,
- notationName}
-Called for unparsed (NDATA) entity declarations. This is only present
-for version 1.2 of the Expat library; for more recent versions, use
-\member{EntityDeclHandler} instead. (The underlying function in the
-Expat library has been declared obsolete.)
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EntityDeclHandler}{entityName,
- is_parameter_entity, value,
- base, systemId,
- publicId,
- notationName}
-Called for all entity declarations. For parameter and internal
-entities, \var{value} will be a string giving the declared contents
-of the entity; this will be \code{None} for external entities. The
-\var{notationName} parameter will be \code{None} for parsed entities,
-and the name of the notation for unparsed entities.
-\var{is_parameter_entity} will be true if the entity is a parameter
-entity or false for general entities (most applications only need to
-be concerned with general entities).
-This is only available starting with version 1.95.0 of the Expat
-library.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{NotationDeclHandler}{notationName, base,
- systemId, publicId}
-Called for notation declarations. \var{notationName}, \var{base}, and
-\var{systemId}, and \var{publicId} are strings if given. If the
-public identifier is omitted, \var{publicId} will be \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartNamespaceDeclHandler}{prefix, uri}
-Called when an element contains a namespace declaration. Namespace
-declarations are processed before the \member{StartElementHandler} is
-called for the element on which declarations are placed.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndNamespaceDeclHandler}{prefix}
-Called when the closing tag is reached for an element
-that contained a namespace declaration. This is called once for each
-namespace declaration on the element in the reverse of the order for
-which the \member{StartNamespaceDeclHandler} was called to indicate
-the start of each namespace declaration's scope. Calls to this
-handler are made after the corresponding \member{EndElementHandler}
-for the end of the element.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{CommentHandler}{data}
-Called for comments. \var{data} is the text of the comment, excluding
-the leading `\code{<!-}\code{-}' and trailing `\code{-}\code{->}'.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{StartCdataSectionHandler}{}
-Called at the start of a CDATA section. This and
-\member{EndCdataSectionHandler} are needed to be able to identify
-the syntactical start and end for CDATA sections.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{EndCdataSectionHandler}{}
-Called at the end of a CDATA section.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{DefaultHandler}{data}
-Called for any characters in the XML document for
-which no applicable handler has been specified. This means
-characters that are part of a construct which could be reported, but
-for which no handler has been supplied.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{DefaultHandlerExpand}{data}
-This is the same as the \function{DefaultHandler},
-but doesn't inhibit expansion of internal entities.
-The entity reference will not be passed to the default handler.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{NotStandaloneHandler}{} Called if the
-XML document hasn't been declared as being a standalone document.
-This happens when there is an external subset or a reference to a
-parameter entity, but the XML declaration does not set standalone to
-\code{yes} in an XML declaration. If this handler returns \code{0},
-then the parser will throw an \constant{XML_ERROR_NOT_STANDALONE}
-error. If this handler is not set, no exception is raised by the
-parser for this condition.
-\end{methoddesc}
-
-\begin{methoddesc}[xmlparser]{ExternalEntityRefHandler}{context, base,
- systemId, publicId}
-Called for references to external entities. \var{base} is the current
-base, as set by a previous call to \method{SetBase()}. The public and
-system identifiers, \var{systemId} and \var{publicId}, are strings if
-given; if the public identifier is not given, \var{publicId} will be
-\code{None}. The \var{context} value is opaque and should only be
-used as described below.
-
-For external entities to be parsed, this handler must be implemented.
-It is responsible for creating the sub-parser using
-\code{ExternalEntityParserCreate(\var{context})}, initializing it with
-the appropriate callbacks, and parsing the entity. This handler
-should return an integer; if it returns \code{0}, the parser will
-throw an \constant{XML_ERROR_EXTERNAL_ENTITY_HANDLING} error,
-otherwise parsing will continue.
-
-If this handler is not provided, external entities are reported by the
-\member{DefaultHandler} callback, if provided.
-\end{methoddesc}
-
-
-\subsection{ExpatError Exceptions \label{expaterror-objects}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\exception{ExpatError} exceptions have a number of interesting
-attributes:
-
-\begin{memberdesc}[ExpatError]{code}
- Expat's internal error number for the specific error. This will
- match one of the constants defined in the \code{errors} object from
- this module.
- \versionadded{2.1}
-\end{memberdesc}
-
-\begin{memberdesc}[ExpatError]{lineno}
- Line number on which the error was detected. The first line is
- numbered \code{1}.
- \versionadded{2.1}
-\end{memberdesc}
-
-\begin{memberdesc}[ExpatError]{offset}
- Character offset into the line where the error occurred. The first
- column is numbered \code{0}.
- \versionadded{2.1}
-\end{memberdesc}
-
-
-\subsection{Example \label{expat-example}}
-
-The following program defines three handlers that just print out their
-arguments.
-
-\begin{verbatim}
-import xml.parsers.expat
-
-# 3 handler functions
-def start_element(name, attrs):
- print 'Start element:', name, attrs
-def end_element(name):
- print 'End element:', name
-def char_data(data):
- print 'Character data:', repr(data)
-
-p = xml.parsers.expat.ParserCreate()
-
-p.StartElementHandler = start_element
-p.EndElementHandler = end_element
-p.CharacterDataHandler = char_data
-
-p.Parse("""<?xml version="1.0"?>
-<parent id="top"><child1 name="paul">Text goes here</child1>
-<child2 name="fred">More text</child2>
-</parent>""", 1)
-\end{verbatim}
-
-The output from this program is:
-
-\begin{verbatim}
-Start element: parent {'id': 'top'}
-Start element: child1 {'name': 'paul'}
-Character data: 'Text goes here'
-End element: child1
-Character data: '\n'
-Start element: child2 {'name': 'fred'}
-Character data: 'More text'
-End element: child2
-Character data: '\n'
-End element: parent
-\end{verbatim}
-
-
-\subsection{Content Model Descriptions \label{expat-content-models}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-Content modules are described using nested tuples. Each tuple
-contains four values: the type, the quantifier, the name, and a tuple
-of children. Children are simply additional content module
-descriptions.
-
-The values of the first two fields are constants defined in the
-\code{model} object of the \module{xml.parsers.expat} module. These
-constants can be collected in two groups: the model type group and the
-quantifier group.
-
-The constants in the model type group are:
-
-\begin{datadescni}{XML_CTYPE_ANY}
-The element named by the model name was declared to have a content
-model of \code{ANY}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_CHOICE}
-The named element allows a choice from a number of options; this is
-used for content models such as \code{(A | B | C)}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_EMPTY}
-Elements which are declared to be \code{EMPTY} have this model type.
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_MIXED}
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_NAME}
-\end{datadescni}
-
-\begin{datadescni}{XML_CTYPE_SEQ}
-Models which represent a series of models which follow one after the
-other are indicated with this model type. This is used for models
-such as \code{(A, B, C)}.
-\end{datadescni}
-
-
-The constants in the quantifier group are:
-
-\begin{datadescni}{XML_CQUANT_NONE}
-No modifier is given, so it can appear exactly once, as for \code{A}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CQUANT_OPT}
-The model is optional: it can appear once or not at all, as for
-\code{A?}.
-\end{datadescni}
-
-\begin{datadescni}{XML_CQUANT_PLUS}
-The model must occur one or more times (like \code{A+}).
-\end{datadescni}
-
-\begin{datadescni}{XML_CQUANT_REP}
-The model must occur zero or more times, as for \code{A*}.
-\end{datadescni}
-
-
-\subsection{Expat error constants \label{expat-errors}}
-
-The following constants are provided in the \code{errors} object of
-the \refmodule{xml.parsers.expat} module. These constants are useful
-in interpreting some of the attributes of the \exception{ExpatError}
-exception objects raised when an error has occurred.
-
-The \code{errors} object has the following attributes:
-
-\begin{datadescni}{XML_ERROR_ASYNC_ENTITY}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF}
-An entity reference in an attribute value referred to an external
-entity instead of an internal entity.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_BAD_CHAR_REF}
-A character reference referred to a character which is illegal in XML
-(for example, character \code{0}, or `\code{\&\#0;}').
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_BINARY_ENTITY_REF}
-An entity reference referred to an entity which was declared with a
-notation, so cannot be parsed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_DUPLICATE_ATTRIBUTE}
-An attribute was used more than once in a start tag.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_INCORRECT_ENCODING}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_INVALID_TOKEN}
-Raised when an input byte could not properly be assigned to a
-character; for example, a NUL byte (value \code{0}) in a UTF-8 input
-stream.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_JUNK_AFTER_DOC_ELEMENT}
-Something other than whitespace occurred after the document element.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_MISPLACED_XML_PI}
-An XML declaration was found somewhere other than the start of the
-input data.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NO_ELEMENTS}
-The document contains no elements (XML requires all documents to
-contain exactly one top-level element)..
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NO_MEMORY}
-Expat was not able to allocate memory internally.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_PARAM_ENTITY_REF}
-A parameter entity reference was found where it was not allowed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_PARTIAL_CHAR}
-An incomplete character was found in the input.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_RECURSIVE_ENTITY_REF}
-An entity reference contained another reference to the same entity;
-possibly via a different name, and possibly indirectly.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_SYNTAX}
-Some unspecified syntax error was encountered.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_TAG_MISMATCH}
-An end tag did not match the innermost open start tag.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNCLOSED_TOKEN}
-Some token (such as a start tag) was not closed before the end of the
-stream or the next token was encountered.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNDEFINED_ENTITY}
-A reference was made to a entity which was not defined.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNKNOWN_ENCODING}
-The document encoding is not supported by Expat.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNCLOSED_CDATA_SECTION}
-A CDATA marked section was not closed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_EXTERNAL_ENTITY_HANDLING}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NOT_STANDALONE}
-The parser determined that the document was not ``standalone'' though
-it declared itself to be in the XML declaration, and the
-\member{NotStandaloneHandler} was set and returned \code{0}.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNEXPECTED_STATE}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_ENTITY_DECLARED_IN_PE}
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_FEATURE_REQUIRES_XML_DTD}
-An operation was requested that requires DTD support to be compiled
-in, but Expat was configured without DTD support. This should never
-be reported by a standard build of the \module{xml.parsers.expat}
-module.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}
-A behavioral change was requested after parsing started that can only
-be changed before parsing has started. This is (currently) only
-raised by \method{UseForeignDTD()}.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNBOUND_PREFIX}
-An undeclared prefix was found when namespace processing was enabled.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_UNDECLARING_PREFIX}
-The document attempted to remove the namespace declaration associated
-with a prefix.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_INCOMPLETE_PE}
-A parameter entity contained incomplete markup.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_XML_DECL}
-The document contained no document element at all.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_TEXT_DECL}
-There was an error parsing a text declaration in an external entity.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_PUBLICID}
-Characters were found in the public id that are not allowed.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_SUSPENDED}
-The requested operation was made on a suspended parser, but isn't
-allowed. This includes attempts to provide additional input or to
-stop the parser.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_NOT_SUSPENDED}
-An attempt to resume the parser was made when the parser had not been
-suspended.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_ABORTED}
-This should not be reported to Python applications.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_FINISHED}
-The requested operation was made on a parser which was finished
-parsing input, but isn't allowed. This includes attempts to provide
-additional input or to stop the parser.
-\end{datadescni}
-
-\begin{datadescni}{XML_ERROR_SUSPEND_PE}
-\end{datadescni}
diff --git a/Doc/lib/libpython.tex b/Doc/lib/libpython.tex
deleted file mode 100644
index c41c386..0000000
--- a/Doc/lib/libpython.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Python Runtime Services
- \label{python}}
-
-The modules described in this chapter provide a wide range of services
-related to the Python interpreter and its interaction with its
-environment. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex
deleted file mode 100644
index 591a910..0000000
--- a/Doc/lib/libqueue.tex
+++ /dev/null
@@ -1,145 +0,0 @@
-
-\section{\module{Queue} ---
- A synchronized queue class}
-
-\declaremodule{standard}{Queue}
-\modulesynopsis{A synchronized queue class.}
-
-
-The \module{Queue} module implements a multi-producer, multi-consumer
-FIFO queue. It is especially useful in threads programming when
-information must be exchanged safely between multiple threads. The
-\class{Queue} class in this module implements all the required locking
-semantics. It depends on the availability of thread support in
-Python.
-
-The \module{Queue} module defines the following class and exception:
-
-
-\begin{classdesc}{Queue}{maxsize}
-Constructor for the class. \var{maxsize} is an integer that sets the
-upperbound limit on the number of items that can be placed in the
-queue. Insertion will block once this size has been reached, until
-queue items are consumed. If \var{maxsize} is less than or equal to
-zero, the queue size is infinite.
-\end{classdesc}
-
-\begin{excdesc}{Empty}
-Exception raised when non-blocking \method{get()} (or
-\method{get_nowait()}) is called on a \class{Queue} object which is
-empty.
-\end{excdesc}
-
-\begin{excdesc}{Full}
-Exception raised when non-blocking \method{put()} (or
-\method{put_nowait()}) is called on a \class{Queue} object which is
-full.
-\end{excdesc}
-
-\subsection{Queue Objects}
-\label{QueueObjects}
-
-Class \class{Queue} implements queue objects and has the methods
-described below. This class can be derived from in order to implement
-other queue organizations (e.g. stack) but the inheritable interface
-is not described here. See the source code for details. The public
-methods are:
-
-\begin{methoddesc}[Queue]{qsize}{}
-Return the approximate size of the queue. Because of multithreading
-semantics, this number is not reliable.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{empty}{}
-Return \code{True} if the queue is empty, \code{False} otherwise.
-Because of multithreading semantics, this is not reliable.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{full}{}
-Return \code{True} if the queue is full, \code{False} otherwise.
-Because of multithreading semantics, this is not reliable.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{put}{item\optional{, block\optional{, timeout}}}
-Put \var{item} into the queue. If optional args \var{block} is true
-and \var{timeout} is None (the default), block if necessary until a
-free slot is available. If \var{timeout} is a positive number, it
-blocks at most \var{timeout} seconds and raises the \exception{Full}
-exception if no free slot was available within that time.
-Otherwise (\var{block} is false), put an item on the queue if a free
-slot is immediately available, else raise the \exception{Full}
-exception (\var{timeout} is ignored in that case).
-
-\versionadded[the timeout parameter]{2.3}
-
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{put_nowait}{item}
-Equivalent to \code{put(\var{item}, False)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{get}{\optional{block\optional{, timeout}}}
-Remove and return an item from the queue. If optional args
-\var{block} is true and \var{timeout} is None (the default),
-block if necessary until an item is available. If \var{timeout} is
-a positive number, it blocks at most \var{timeout} seconds and raises
-the \exception{Empty} exception if no item was available within that
-time. Otherwise (\var{block} is false), return an item if one is
-immediately available, else raise the \exception{Empty} exception
-(\var{timeout} is ignored in that case).
-
-\versionadded[the timeout parameter]{2.3}
-
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{get_nowait}{}
-Equivalent to \code{get(False)}.
-\end{methoddesc}
-
-Two methods are offered to support tracking whether enqueued tasks have
-been fully processed by daemon consumer threads.
-
-\begin{methoddesc}[Queue]{task_done}{}
-Indicate that a formerly enqueued task is complete. Used by queue consumer
-threads. For each \method{get()} used to fetch a task, a subsequent call to
-\method{task_done()} tells the queue that the processing on the task is complete.
-
-If a \method{join()} is currently blocking, it will resume when all items
-have been processed (meaning that a \method{task_done()} call was received
-for every item that had been \method{put()} into the queue).
-
-Raises a \exception{ValueError} if called more times than there were items
-placed in the queue.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[Queue]{join}{}
-Blocks until all items in the queue have been gotten and processed.
-
-The count of unfinished tasks goes up whenever an item is added to the
-queue. The count goes down whenever a consumer thread calls \method{task_done()}
-to indicate that the item was retrieved and all work on it is complete.
-When the count of unfinished tasks drops to zero, join() unblocks.
-\versionadded{2.5}
-\end{methoddesc}
-
-Example of how to wait for enqueued tasks to be completed:
-
-\begin{verbatim}
- def worker():
- while True:
- item = q.get()
- do_work(item)
- q.task_done()
-
- q = Queue()
- for i in range(num_worker_threads):
- t = Thread(target=worker)
- t.setDaemon(True)
- t.start()
-
- for item in source():
- q.put(item)
-
- q.join() # block until all tasks are done
-\end{verbatim}
diff --git a/Doc/lib/libquopri.tex b/Doc/lib/libquopri.tex
deleted file mode 100644
index 9e7895b..0000000
--- a/Doc/lib/libquopri.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\section{\module{quopri} ---
- Encode and decode MIME quoted-printable data}
-
-\declaremodule{standard}{quopri}
-\modulesynopsis{Encode and decode files using the MIME
- quoted-printable encoding.}
-
-
-This module performs quoted-printable transport encoding and decoding,
-as defined in \rfc{1521}: ``MIME (Multipurpose Internet Mail
-Extensions) Part One: Mechanisms for Specifying and Describing the
-Format of Internet Message Bodies''. The quoted-printable encoding is
-designed for data where there are relatively few nonprintable
-characters; the base64 encoding scheme available via the
-\refmodule{base64} module is more compact if there are many such
-characters, as when sending a graphics file.
-\indexii{quoted-printable}{encoding}
-\index{MIME!quoted-printable encoding}
-
-
-\begin{funcdesc}{decode}{input, output\optional{,header}}
-Decode the contents of the \var{input} file and write the resulting
-decoded binary data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.readline()} returns an empty string.
-If the optional argument \var{header} is present and true, underscore
-will be decoded as space. This is used to decode
-``Q''-encoded headers as described in \rfc{1522}: ``MIME (Multipurpose Internet Mail Extensions)
-Part Two: Message Header Extensions for Non-ASCII Text''.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{input, output, quotetabs}
-Encode the contents of the \var{input} file and write the resulting
-quoted-printable data to the \var{output} file.
-\var{input} and \var{output} must either be file objects or objects that
-mimic the file object interface. \var{input} will be read until
-\code{\var{input}.readline()} returns an empty string.
-\var{quotetabs} is a flag which controls whether to encode embedded
-spaces and tabs; when true it encodes such embedded whitespace, and
-when false it leaves them unencoded. Note that spaces and tabs
-appearing at the end of lines are always encoded, as per \rfc{1521}.
-\end{funcdesc}
-
-\begin{funcdesc}{decodestring}{s\optional{,header}}
-Like \function{decode()}, except that it accepts a source string and
-returns the corresponding decoded string.
-\end{funcdesc}
-
-\begin{funcdesc}{encodestring}{s\optional{, quotetabs}}
-Like \function{encode()}, except that it accepts a source string and
-returns the corresponding encoded string. \var{quotetabs} is optional
-(defaulting to 0), and is passed straight through to
-\function{encode()}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{mimify}{General utilities for processing of MIME messages.}
- \seemodule{base64}{Encode and decode MIME base64 data}
-\end{seealso}
diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex
deleted file mode 100644
index a9bd5ac..0000000
--- a/Doc/lib/librandom.tex
+++ /dev/null
@@ -1,309 +0,0 @@
-\section{\module{random} ---
- Generate pseudo-random numbers}
-
-\declaremodule{standard}{random}
-\modulesynopsis{Generate pseudo-random numbers with various common
- distributions.}
-
-
-This module implements pseudo-random number generators for various
-distributions.
-
-For integers, uniform selection from a range.
-For sequences, uniform selection of a random element, a function to
-generate a random permutation of a list in-place, and a function for
-random sampling without replacement.
-
-On the real line, there are functions to compute uniform, normal (Gaussian),
-lognormal, negative exponential, gamma, and beta distributions.
-For generating distributions of angles, the von Mises distribution
-is available.
-
-Almost all module functions depend on the basic function
-\function{random()}, which generates a random float uniformly in
-the semi-open range [0.0, 1.0). Python uses the Mersenne Twister as
-the core generator. It produces 53-bit precision floats and has a
-period of 2**19937-1. The underlying implementation in C
-is both fast and threadsafe. The Mersenne Twister is one of the most
-extensively tested random number generators in existence. However, being
-completely deterministic, it is not suitable for all purposes, and is
-completely unsuitable for cryptographic purposes.
-
-The functions supplied by this module are actually bound methods of a
-hidden instance of the \class{random.Random} class. You can
-instantiate your own instances of \class{Random} to get generators
-that don't share state. This is especially useful for multi-threaded
-programs, creating a different instance of \class{Random} for each
-thread, and using the \method{jumpahead()} method to make it likely that the
-generated sequences seen by each thread don't overlap.
-
-Class \class{Random} can also be subclassed if you want to use a
-different basic generator of your own devising: in that case, override
-the \method{random()}, \method{seed()}, \method{getstate()},
-\method{setstate()} and \method{jumpahead()} methods.
-Optionally, a new generator can supply a \method{getrandombits()}
-method --- this allows \method{randrange()} to produce selections
-over an arbitrarily large range.
-\versionadded[the \method{getrandombits()} method]{2.4}
-
-As an example of subclassing, the \module{random} module provides
-the \class{WichmannHill} class that implements an alternative generator
-in pure Python. The class provides a backward compatible way to
-reproduce results from earlier versions of Python, which used the
-Wichmann-Hill algorithm as the core generator. Note that this Wichmann-Hill
-generator can no longer be recommended: its period is too short by
-contemporary standards, and the sequence generated is known to fail some
-stringent randomness tests. See the references below for a recent
-variant that repairs these flaws.
-\versionchanged[Substituted MersenneTwister for Wichmann-Hill]{2.3}
-
-
-Bookkeeping functions:
-
-\begin{funcdesc}{seed}{\optional{x}}
- Initialize the basic random number generator.
- Optional argument \var{x} can be any hashable object.
- If \var{x} is omitted or \code{None}, current system time is used;
- current system time is also used to initialize the generator when the
- module is first imported. If randomness sources are provided by the
- operating system, they are used instead of the system time (see the
- \function{os.urandom()}
- function for details on availability). \versionchanged[formerly,
- operating system resources were not used]{2.4}
- If \var{x} is not \code{None} or an int or long,
- \code{hash(\var{x})} is used instead.
- If \var{x} is an int or long, \var{x} is used directly.
-\end{funcdesc}
-
-\begin{funcdesc}{getstate}{}
- Return an object capturing the current internal state of the
- generator. This object can be passed to \function{setstate()} to
- restore the state.
- \versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{setstate}{state}
- \var{state} should have been obtained from a previous call to
- \function{getstate()}, and \function{setstate()} restores the
- internal state of the generator to what it was at the time
- \function{setstate()} was called.
- \versionadded{2.1}
-\end{funcdesc}
-
-\begin{funcdesc}{jumpahead}{n}
- Change the internal state to one different from and likely far away from
- the current state. \var{n} is a non-negative integer which is used to
- scramble the current state vector. This is most useful in multi-threaded
- programs, in conjuction with multiple instances of the \class{Random}
- class: \method{setstate()} or \method{seed()} can be used to force all
- instances into the same internal state, and then \method{jumpahead()}
- can be used to force the instances' states far apart.
- \versionadded{2.1}
- \versionchanged[Instead of jumping to a specific state, \var{n} steps
- ahead, \method{jumpahead(\var{n})} jumps to another state likely to be
- separated by many steps]{2.3}
- \end{funcdesc}
-
-\begin{funcdesc}{getrandbits}{k}
- Returns a python \class{long} int with \var{k} random bits.
- This method is supplied with the MersenneTwister generator and some
- other generators may also provide it as an optional part of the API.
- When available, \method{getrandbits()} enables \method{randrange()}
- to handle arbitrarily large ranges.
- \versionadded{2.4}
-\end{funcdesc}
-
-Functions for integers:
-
-\begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}}
- Return a randomly selected element from \code{range(\var{start},
- \var{stop}, \var{step})}. This is equivalent to
- \code{choice(range(\var{start}, \var{stop}, \var{step}))},
- but doesn't actually build a range object.
- \versionadded{1.5.2}
-\end{funcdesc}
-
-\begin{funcdesc}{randint}{a, b}
- Return a random integer \var{N} such that
- \code{\var{a} <= \var{N} <= \var{b}}.
-\end{funcdesc}
-
-
-Functions for sequences:
-
-\begin{funcdesc}{choice}{seq}
- Return a random element from the non-empty sequence \var{seq}.
- If \var{seq} is empty, raises \exception{IndexError}.
-\end{funcdesc}
-
-\begin{funcdesc}{shuffle}{x\optional{, random}}
- Shuffle the sequence \var{x} in place.
- The optional argument \var{random} is a 0-argument function
- returning a random float in [0.0, 1.0); by default, this is the
- function \function{random()}.
-
- Note that for even rather small \code{len(\var{x})}, the total
- number of permutations of \var{x} is larger than the period of most
- random number generators; this implies that most permutations of a
- long sequence can never be generated.
-\end{funcdesc}
-
-\begin{funcdesc}{sample}{population, k}
- Return a \var{k} length list of unique elements chosen from the
- population sequence. Used for random sampling without replacement.
- \versionadded{2.3}
-
- Returns a new list containing elements from the population while
- leaving the original population unchanged. The resulting list is
- in selection order so that all sub-slices will also be valid random
- samples. This allows raffle winners (the sample) to be partitioned
- into grand prize and second place winners (the subslices).
-
- Members of the population need not be hashable or unique. If the
- population contains repeats, then each occurrence is a possible
- selection in the sample.
-
- To choose a sample from a range of integers, use an \function{range()}
- object as an argument. This is especially fast and space efficient for
- sampling from a large population: \code{sample(range(10000000), 60)}.
-\end{funcdesc}
-
-
-The following functions generate specific real-valued distributions.
-Function parameters are named after the corresponding variables in the
-distribution's equation, as used in common mathematical practice; most of
-these equations can be found in any statistics text.
-
-\begin{funcdesc}{random}{}
- Return the next random floating point number in the range [0.0, 1.0).
-\end{funcdesc}
-
-\begin{funcdesc}{uniform}{a, b}
- Return a random real number \var{N} such that
- \code{\var{a} <= \var{N} < \var{b}}.
-\end{funcdesc}
-
-\begin{funcdesc}{betavariate}{alpha, beta}
- Beta distribution. Conditions on the parameters are
- \code{\var{alpha} > 0} and \code{\var{beta} > 0}.
- Returned values range between 0 and 1.
-\end{funcdesc}
-
-\begin{funcdesc}{expovariate}{lambd}
- Exponential distribution. \var{lambd} is 1.0 divided by the desired
- mean. (The parameter would be called ``lambda'', but that is a
- reserved word in Python.) Returned values range from 0 to
- positive infinity.
-\end{funcdesc}
-
-\begin{funcdesc}{gammavariate}{alpha, beta}
- Gamma distribution. (\emph{Not} the gamma function!) Conditions on
- the parameters are \code{\var{alpha} > 0} and \code{\var{beta} > 0}.
-\end{funcdesc}
-
-\begin{funcdesc}{gauss}{mu, sigma}
- Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the
- standard deviation. This is slightly faster than the
- \function{normalvariate()} function defined below.
-\end{funcdesc}
-
-\begin{funcdesc}{lognormvariate}{mu, sigma}
- Log normal distribution. If you take the natural logarithm of this
- distribution, you'll get a normal distribution with mean \var{mu}
- and standard deviation \var{sigma}. \var{mu} can have any value,
- and \var{sigma} must be greater than zero.
-\end{funcdesc}
-
-\begin{funcdesc}{normalvariate}{mu, sigma}
- Normal distribution. \var{mu} is the mean, and \var{sigma} is the
- standard deviation.
-\end{funcdesc}
-
-\begin{funcdesc}{vonmisesvariate}{mu, kappa}
- \var{mu} is the mean angle, expressed in radians between 0 and
- 2*\emph{pi}, and \var{kappa} is the concentration parameter, which
- must be greater than or equal to zero. If \var{kappa} is equal to
- zero, this distribution reduces to a uniform random angle over the
- range 0 to 2*\emph{pi}.
-\end{funcdesc}
-
-\begin{funcdesc}{paretovariate}{alpha}
- Pareto distribution. \var{alpha} is the shape parameter.
-\end{funcdesc}
-
-\begin{funcdesc}{weibullvariate}{alpha, beta}
- Weibull distribution. \var{alpha} is the scale parameter and
- \var{beta} is the shape parameter.
-\end{funcdesc}
-
-Alternative Generators:
-
-\begin{classdesc}{WichmannHill}{\optional{seed}}
-Class that implements the Wichmann-Hill algorithm as the core generator.
-Has all of the same methods as \class{Random} plus the \method{whseed()}
-method described below. Because this class is implemented in pure
-Python, it is not threadsafe and may require locks between calls. The
-period of the generator is 6,953,607,871,644 which is small enough to
-require care that two independent random sequences do not overlap.
-\end{classdesc}
-
-\begin{funcdesc}{whseed}{\optional{x}}
- This is obsolete, supplied for bit-level compatibility with versions
- of Python prior to 2.1.
- See \function{seed()} for details. \function{whseed()} does not guarantee
- that distinct integer arguments yield distinct internal states, and can
- yield no more than about 2**24 distinct internal states in all.
-\end{funcdesc}
-
-\begin{classdesc}{SystemRandom}{\optional{seed}}
-Class that uses the \function{os.urandom()} function for generating
-random numbers from sources provided by the operating system.
-Not available on all systems.
-Does not rely on software state and sequences are not reproducible.
-Accordingly, the \method{seed()} and \method{jumpahead()} methods
-have no effect and are ignored. The \method{getstate()} and
-\method{setstate()} methods raise \exception{NotImplementedError} if
-called.
-\versionadded{2.4}
-\end{classdesc}
-
-Examples of basic usage:
-
-\begin{verbatim}
->>> random.random() # Random float x, 0.0 <= x < 1.0
-0.37444887175646646
->>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0
-1.1800146073117523
->>> random.randint(1, 10) # Integer from 1 to 10, endpoints included
-7
->>> random.randrange(0, 101, 2) # Even integer from 0 to 100
-26
->>> random.choice('abcdefghij') # Choose a random element
-'c'
-
->>> items = [1, 2, 3, 4, 5, 6, 7]
->>> random.shuffle(items)
->>> items
-[7, 3, 2, 5, 6, 4, 1]
-
->>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements
-[4, 1, 5]
-
-\end{verbatim}
-
-\begin{seealso}
- \seetext{M. Matsumoto and T. Nishimura, ``Mersenne Twister: A
- 623-dimensionally equidistributed uniform pseudorandom
- number generator'',
- \citetitle{ACM Transactions on Modeling and Computer Simulation}
- Vol. 8, No. 1, January pp.3-30 1998.}
-
- \seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
- An efficient and portable pseudo-random number generator'',
- \citetitle{Applied Statistics} 31 (1982) 188-190.}
-
- \seeurl{http://www.npl.co.uk/ssfm/download/abstracts.html\#196}{A modern
- variation of the Wichmann-Hill generator that greatly increases
- the period, and passes now-standard statistical tests that the
- original generator failed.}
-\end{seealso}
diff --git a/Doc/lib/libre.tex b/Doc/lib/libre.tex
deleted file mode 100644
index a0b8b51..0000000
--- a/Doc/lib/libre.tex
+++ /dev/null
@@ -1,954 +0,0 @@
-\section{\module{re} ---
- Regular expression operations}
-\declaremodule{standard}{re}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-\sectionauthor{Andrew M. Kuchling}{amk@amk.ca}
-
-
-\modulesynopsis{Regular expression search and match operations with a
- Perl-style expression syntax.}
-
-
-This module provides regular expression matching operations similar to
-those found in Perl. Regular expression pattern strings may not
-contain null bytes, but can specify the null byte using the
-\code{\e\var{number}} notation. Both patterns and strings to be
-searched can be Unicode strings as well as 8-bit strings. The
-\module{re} module is always available.
-
-Regular expressions use the backslash character (\character{\e}) to
-indicate special forms or to allow special characters to be used
-without invoking their special meaning. This collides with Python's
-usage of the same character for the same purpose in string literals;
-for example, to match a literal backslash, one might have to write
-\code{'\e\e\e\e'} as the pattern string, because the regular expression
-must be \samp{\e\e}, and each backslash must be expressed as
-\samp{\e\e} inside a regular Python string literal.
-
-The solution is to use Python's raw string notation for regular
-expression patterns; backslashes are not handled in any special way in
-a string literal prefixed with \character{r}. So \code{r"\e n"} is a
-two-character string containing \character{\e} and \character{n},
-while \code{"\e n"} is a one-character string containing a newline.
-Usually patterns will be expressed in Python code using this raw
-string notation.
-
-\begin{seealso}
- \seetitle{Mastering Regular Expressions}{Book on regular expressions
- by Jeffrey Friedl, published by O'Reilly. The second
- edition of the book no longer covers Python at all,
- but the first edition covered writing good regular expression
- patterns in great detail.}
-\end{seealso}
-
-
-\subsection{Regular Expression Syntax \label{re-syntax}}
-
-A regular expression (or RE) specifies a set of strings that matches
-it; the functions in this module let you check if a particular string
-matches a given regular expression (or if a given regular expression
-matches a particular string, which comes down to the same thing).
-
-Regular expressions can be concatenated to form new regular
-expressions; if \emph{A} and \emph{B} are both regular expressions,
-then \emph{AB} is also a regular expression. In general, if a string
-\emph{p} matches \emph{A} and another string \emph{q} matches \emph{B},
-the string \emph{pq} will match AB. This holds unless \emph{A} or
-\emph{B} contain low precedence operations; boundary conditions between
-\emph{A} and \emph{B}; or have numbered group references. Thus, complex
-expressions can easily be constructed from simpler primitive
-expressions like the ones described here. For details of the theory
-and implementation of regular expressions, consult the Friedl book
-referenced above, or almost any textbook about compiler construction.
-
-A brief explanation of the format of regular expressions follows. For
-further information and a gentler presentation, consult the Regular
-Expression HOWTO, accessible from \url{http://www.python.org/doc/howto/}.
-
-Regular expressions can contain both special and ordinary characters.
-Most ordinary characters, like \character{A}, \character{a}, or
-\character{0}, are the simplest regular expressions; they simply match
-themselves. You can concatenate ordinary characters, so \regexp{last}
-matches the string \code{'last'}. (In the rest of this section, we'll
-write RE's in \regexp{this special style}, usually without quotes, and
-strings to be matched \code{'in single quotes'}.)
-
-Some characters, like \character{|} or \character{(}, are special.
-Special characters either stand for classes of ordinary characters, or
-affect how the regular expressions around them are interpreted.
-
-The special characters are:
-%
-\begin{description}
-
-\item[\character{.}] (Dot.) In the default mode, this matches any
-character except a newline. If the \constant{DOTALL} flag has been
-specified, this matches any character including a newline.
-
-\item[\character{\textasciicircum}] (Caret.) Matches the start of the
-string, and in \constant{MULTILINE} mode also matches immediately
-after each newline.
-
-\item[\character{\$}] Matches the end of the string or just before the
-newline at the end of the string, and in \constant{MULTILINE} mode
-also matches before a newline. \regexp{foo} matches both 'foo' and
-'foobar', while the regular expression \regexp{foo\$} matches only
-'foo'. More interestingly, searching for \regexp{foo.\$} in
-'foo1\textbackslash nfoo2\textbackslash n' matches 'foo2' normally,
-but 'foo1' in \constant{MULTILINE} mode.
-
-\item[\character{*}] Causes the resulting RE to
-match 0 or more repetitions of the preceding RE, as many repetitions
-as are possible. \regexp{ab*} will
-match 'a', 'ab', or 'a' followed by any number of 'b's.
-
-\item[\character{+}] Causes the
-resulting RE to match 1 or more repetitions of the preceding RE.
-\regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it
-will not match just 'a'.
-
-\item[\character{?}] Causes the resulting RE to
-match 0 or 1 repetitions of the preceding RE. \regexp{ab?} will
-match either 'a' or 'ab'.
-
-\item[\code{*?}, \code{+?}, \code{??}] The \character{*},
-\character{+}, and \character{?} qualifiers are all \dfn{greedy}; they
-match as much text as possible. Sometimes this behaviour isn't
-desired; if the RE \regexp{<.*>} is matched against
-\code{'<H1>title</H1>'}, it will match the entire string, and not just
-\code{'<H1>'}. Adding \character{?} after the qualifier makes it
-perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as
-\emph{few} characters as possible will be matched. Using \regexp{.*?}
-in the previous expression will match only \code{'<H1>'}.
-
-\item[\code{\{\var{m}\}}]
-Specifies that exactly \var{m} copies of the previous RE should be
-matched; fewer matches cause the entire RE not to match. For example,
-\regexp{a\{6\}} will match exactly six \character{a} characters, but
-not five.
-
-\item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from
-\var{m} to \var{n} repetitions of the preceding RE, attempting to
-match as many repetitions as possible. For example, \regexp{a\{3,5\}}
-will match from 3 to 5 \character{a} characters. Omitting \var{m}
-specifies a lower bound of zero,
-and omitting \var{n} specifies an infinite upper bound. As an
-example, \regexp{a\{4,\}b} will match \code{aaaab} or a thousand
-\character{a} characters followed by a \code{b}, but not \code{aaab}.
-The comma may not be omitted or the modifier would be confused with
-the previously described form.
-
-\item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to
-match from \var{m} to \var{n} repetitions of the preceding RE,
-attempting to match as \emph{few} repetitions as possible. This is
-the non-greedy version of the previous qualifier. For example, on the
-6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5
-\character{a} characters, while \regexp{a\{3,5\}?} will only match 3
-characters.
-
-\item[\character{\e}] Either escapes special characters (permitting
-you to match characters like \character{*}, \character{?}, and so
-forth), or signals a special sequence; special sequences are discussed
-below.
-
-If you're not using a raw string to
-express the pattern, remember that Python also uses the
-backslash as an escape sequence in string literals; if the escape
-sequence isn't recognized by Python's parser, the backslash and
-subsequent character are included in the resulting string. However,
-if Python would recognize the resulting sequence, the backslash should
-be repeated twice. This is complicated and hard to understand, so
-it's highly recommended that you use raw strings for all but the
-simplest expressions.
-
-\item[\code{[]}] Used to indicate a set of characters. Characters can
-be listed individually, or a range of characters can be indicated by
-giving two characters and separating them by a \character{-}. Special
-characters are not active inside sets. For example, \regexp{[akm\$]}
-will match any of the characters \character{a}, \character{k},
-\character{m}, or \character{\$}; \regexp{[a-z]}
-will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any
-letter or digit. Character classes such as \code{\e w} or \code{\e S}
-(defined below) are also acceptable inside a range. If you want to
-include a \character{]} or a \character{-} inside a set, precede it with a
-backslash, or place it as the first character. The
-pattern \regexp{[]]} will match \code{']'}, for example.
-
-You can match the characters not within a range by \dfn{complementing}
-the set. This is indicated by including a
-\character{\textasciicircum} as the first character of the set;
-\character{\textasciicircum} elsewhere will simply match the
-\character{\textasciicircum} character. For example,
-\regexp{[{\textasciicircum}5]} will match
-any character except \character{5}, and
-\regexp{[\textasciicircum\code{\textasciicircum}]} will match any character
-except \character{\textasciicircum}.
-
-\item[\character{|}]\code{A|B}, where A and B can be arbitrary REs,
-creates a regular expression that will match either A or B. An
-arbitrary number of REs can be separated by the \character{|} in this
-way. This can be used inside groups (see below) as well. As the target
-string is scanned, REs separated by \character{|} are tried from left to
-right. When one pattern completely matches, that branch is accepted.
-This means that once \code{A} matches, \code{B} will not be tested further,
-even if it would produce a longer overall match. In other words, the
-\character{|} operator is never greedy. To match a literal \character{|},
-use \regexp{\e|}, or enclose it inside a character class, as in \regexp{[|]}.
-
-\item[\code{(...)}] Matches whatever regular expression is inside the
-parentheses, and indicates the start and end of a group; the contents
-of a group can be retrieved after a match has been performed, and can
-be matched later in the string with the \regexp{\e \var{number}} special
-sequence, described below. To match the literals \character{(} or
-\character{)}, use \regexp{\e(} or \regexp{\e)}, or enclose them
-inside a character class: \regexp{[(] [)]}.
-
-\item[\code{(?...)}] This is an extension notation (a \character{?}
-following a \character{(} is not meaningful otherwise). The first
-character after the \character{?}
-determines what the meaning and further syntax of the construct is.
-Extensions usually do not create a new group;
-\regexp{(?P<\var{name}>...)} is the only exception to this rule.
-Following are the currently supported extensions.
-
-\item[\code{(?iLmsux)}] (One or more letters from the set \character{i},
-\character{L}, \character{m}, \character{s}, \character{u},
-\character{x}.) The group matches the empty string; the letters set
-the corresponding flags (\constant{re.I}, \constant{re.L},
-\constant{re.M}, \constant{re.S}, \constant{re.U}, \constant{re.X})
-for the entire regular expression. This is useful if you wish to
-include the flags as part of the regular expression, instead of
-passing a \var{flag} argument to the \function{compile()} function.
-
-Note that the \regexp{(?x)} flag changes how the expression is parsed.
-It should be used first in the expression string, or after one or more
-whitespace characters. If there are non-whitespace characters before
-the flag, the results are undefined.
-
-\item[\code{(?:...)}] A non-grouping version of regular parentheses.
-Matches whatever regular expression is inside the parentheses, but the
-substring matched by the
-group \emph{cannot} be retrieved after performing a match or
-referenced later in the pattern.
-
-\item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but
-the substring matched by the group is accessible via the symbolic group
-name \var{name}. Group names must be valid Python identifiers, and
-each group name must be defined only once within a regular expression. A
-symbolic group is also a numbered group, just as if the group were not
-named. So the group named 'id' in the example above can also be
-referenced as the numbered group 1.
-
-For example, if the pattern is
-\regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its
-name in arguments to methods of match objects, such as
-\code{m.group('id')} or \code{m.end('id')}, and also by name in
-pattern text (for example, \regexp{(?P=id)}) and replacement text
-(such as \code{\e g<id>}).
-
-\item[\code{(?P=\var{name})}] Matches whatever text was matched by the
-earlier group named \var{name}.
-
-\item[\code{(?\#...)}] A comment; the contents of the parentheses are
-simply ignored.
-
-\item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't
-consume any of the string. This is called a lookahead assertion. For
-example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's
-followed by \code{'Asimov'}.
-
-\item[\code{(?!...)}] Matches if \regexp{...} doesn't match next. This
-is a negative lookahead assertion. For example,
-\regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not}
-followed by \code{'Asimov'}.
-
-\item[\code{(?<=...)}] Matches if the current position in the string
-is preceded by a match for \regexp{...} that ends at the current
-position. This is called a \dfn{positive lookbehind assertion}.
-\regexp{(?<=abc)def} will find a match in \samp{abcdef}, since the
-lookbehind will back up 3 characters and check if the contained
-pattern matches. The contained pattern must only match strings of
-some fixed length, meaning that \regexp{abc} or \regexp{a|b} are
-allowed, but \regexp{a*} and \regexp{a\{3,4\}} are not. Note that
-patterns which start with positive lookbehind assertions will never
-match at the beginning of the string being searched; you will most
-likely want to use the \function{search()} function rather than the
-\function{match()} function:
-
-\begin{verbatim}
->>> import re
->>> m = re.search('(?<=abc)def', 'abcdef')
->>> m.group(0)
-'def'
-\end{verbatim}
-
-This example looks for a word following a hyphen:
-
-\begin{verbatim}
->>> m = re.search('(?<=-)\w+', 'spam-egg')
->>> m.group(0)
-'egg'
-\end{verbatim}
-
-\item[\code{(?<!...)}] Matches if the current position in the string
-is not preceded by a match for \regexp{...}. This is called a
-\dfn{negative lookbehind assertion}. Similar to positive lookbehind
-assertions, the contained pattern must only match strings of some
-fixed length. Patterns which start with negative lookbehind
-assertions may match at the beginning of the string being searched.
-
-\item[\code{(?(\var{id/name})yes-pattern|no-pattern)}] Will try to match
-with \regexp{yes-pattern} if the group with given \var{id} or \var{name}
-exists, and with \regexp{no-pattern} if it doesn't. \regexp{|no-pattern}
-is optional and can be omitted. For example,
-\regexp{(<)?(\e w+@\e w+(?:\e .\e w+)+)(?(1)>)} is a poor email matching
-pattern, which will match with \code{'<user@host.com>'} as well as
-\code{'user@host.com'}, but not with \code{'<user@host.com'}.
-\versionadded{2.4}
-
-\end{description}
-
-The special sequences consist of \character{\e} and a character from the
-list below. If the ordinary character is not on the list, then the
-resulting RE will match the second character. For example,
-\regexp{\e\$} matches the character \character{\$}.
-%
-\begin{description}
-
-\item[\code{\e \var{number}}] Matches the contents of the group of the
-same number. Groups are numbered starting from 1. For example,
-\regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not
-\code{'the end'} (note
-the space after the group). This special sequence can only be used to
-match one of the first 99 groups. If the first digit of \var{number}
-is 0, or \var{number} is 3 octal digits long, it will not be interpreted
-as a group match, but as the character with octal value \var{number}.
-Inside the \character{[} and \character{]} of a character class, all numeric
-escapes are treated as characters.
-
-\item[\code{\e A}] Matches only at the start of the string.
-
-\item[\code{\e b}] Matches the empty string, but only at the
-beginning or end of a word. A word is defined as a sequence of
-alphanumeric or underscore characters, so the end of a word is indicated by
-whitespace or a non-alphanumeric, non-underscore character. Note that
-{}\code{\e b} is defined as the boundary between \code{\e w} and \code{\e
-W}, so the precise set of characters deemed to be alphanumeric depends on the
-values of the \code{UNICODE} and \code{LOCALE} flags. Inside a character
-range, \regexp{\e b} represents the backspace character, for compatibility
-with Python's string literals.
-
-\item[\code{\e B}] Matches the empty string, but only when it is \emph{not}
-at the beginning or end of a word. This is just the opposite of {}\code{\e
-b}, so is also subject to the settings of \code{LOCALE} and \code{UNICODE}.
-
-\item[\code{\e d}]When the \constant{UNICODE} flag is not specified, matches
-any decimal digit; this is equivalent to the set \regexp{[0-9]}.
-With \constant{UNICODE}, it will match whatever is classified as a digit
-in the Unicode character properties database.
-
-\item[\code{\e D}]When the \constant{UNICODE} flag is not specified, matches
-any non-digit character; this is equivalent to the set
-\regexp{[{\textasciicircum}0-9]}. With \constant{UNICODE}, it will match
-anything other than character marked as digits in the Unicode character
-properties database.
-
-\item[\code{\e s}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any whitespace character; this is
-equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}.
-With \constant{LOCALE}, it will match this set plus whatever characters
-are defined as space for the current locale. If \constant{UNICODE} is set,
-this will match the characters \regexp{[ \e t\e n\e r\e f\e v]} plus
-whatever is classified as space in the Unicode character properties
-database.
-
-\item[\code{\e S}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any non-whitespace character; this is
-equivalent to the set \regexp{[\textasciicircum\ \e t\e n\e r\e f\e v]}
-With \constant{LOCALE}, it will match any character not in this set,
-and not defined as space in the current locale. If \constant{UNICODE}
-is set, this will match anything other than \regexp{[ \e t\e n\e r\e f\e v]}
-and characters marked as space in the Unicode character properties database.
-
-\item[\code{\e w}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any alphanumeric character and the
-underscore; this is equivalent to the set
-\regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set
-\regexp{[0-9_]} plus whatever characters are defined as alphanumeric for
-the current locale. If \constant{UNICODE} is set, this will match the
-characters \regexp{[0-9_]} plus whatever is classified as alphanumeric
-in the Unicode character properties database.
-
-\item[\code{\e W}]When the \constant{LOCALE} and \constant{UNICODE}
-flags are not specified, matches any non-alphanumeric character; this
-is equivalent to the set \regexp{[{\textasciicircum}a-zA-Z0-9_]}. With
-\constant{LOCALE}, it will match any character not in the set
-\regexp{[0-9_]}, and not defined as alphanumeric for the current locale.
-If \constant{UNICODE} is set, this will match anything other than
-\regexp{[0-9_]} and characters marked as alphanumeric in the Unicode
-character properties database.
-
-\item[\code{\e Z}]Matches only at the end of the string.
-
-\end{description}
-
-Most of the standard escapes supported by Python string literals are
-also accepted by the regular expression parser:
-
-\begin{verbatim}
-\a \b \f \n
-\r \t \v \x
-\\
-\end{verbatim}
-
-Octal escapes are included in a limited form: If the first digit is a
-0, or if there are three octal digits, it is considered an octal
-escape. Otherwise, it is a group reference. As for string literals,
-octal escapes are always at most three digits in length.
-
-
-% Note the lack of a period in the section title; it causes problems
-% with readers of the GNU info version. See http://www.python.org/sf/581414.
-\subsection{Matching vs Searching \label{matching-searching}}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-Python offers two different primitive operations based on regular
-expressions: match and search. If you are accustomed to Perl's
-semantics, the search operation is what you're looking for. See the
-\function{search()} function and corresponding method of compiled
-regular expression objects.
-
-Note that match may differ from search using a regular expression
-beginning with \character{\textasciicircum}:
-\character{\textasciicircum} matches only at the
-start of the string, or in \constant{MULTILINE} mode also immediately
-following a newline. The ``match'' operation succeeds only if the
-pattern matches at the start of the string regardless of mode, or at
-the starting position given by the optional \var{pos} argument
-regardless of whether a newline precedes it.
-
-% Examples from Tim Peters:
-\begin{verbatim}
-re.compile("a").match("ba", 1) # succeeds
-re.compile("^a").search("ba", 1) # fails; 'a' not at start
-re.compile("^a").search("\na", 1) # fails; 'a' not at start
-re.compile("^a", re.M).search("\na", 1) # succeeds
-re.compile("^a", re.M).search("ba", 1) # fails; no preceding \n
-\end{verbatim}
-
-
-\subsection{Module Contents}
-\nodename{Contents of Module re}
-
-The module defines several functions, constants, and an exception. Some of the
-functions are simplified versions of the full featured methods for compiled
-regular expressions. Most non-trivial applications always use the compiled
-form.
-
-\begin{funcdesc}{compile}{pattern\optional{, flags}}
- Compile a regular expression pattern into a regular expression
- object, which can be used for matching using its \function{match()} and
- \function{search()} methods, described below.
-
- The expression's behaviour can be modified by specifying a
- \var{flags} value. Values can be any of the following variables,
- combined using bitwise OR (the \code{|} operator).
-
-The sequence
-
-\begin{verbatim}
-prog = re.compile(pat)
-result = prog.match(str)
-\end{verbatim}
-
-is equivalent to
-
-\begin{verbatim}
-result = re.match(pat, str)
-\end{verbatim}
-
-but the version using \function{compile()} is more efficient when the
-expression will be used several times in a single program.
-%(The compiled version of the last pattern passed to
-%\function{re.match()} or \function{re.search()} is cached, so
-%programs that use only a single regular expression at a time needn't
-%worry about compiling regular expressions.)
-\end{funcdesc}
-
-\begin{datadesc}{I}
-\dataline{IGNORECASE}
-Perform case-insensitive matching; expressions like \regexp{[A-Z]}
-will match lowercase letters, too. This is not affected by the
-current locale.
-\end{datadesc}
-
-\begin{datadesc}{L}
-\dataline{LOCALE}
-Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B},
-\regexp{\e s} and \regexp{\e S} dependent on the current locale.
-\end{datadesc}
-
-\begin{datadesc}{M}
-\dataline{MULTILINE}
-When specified, the pattern character \character{\textasciicircum}
-matches at the beginning of the string and at the beginning of each
-line (immediately following each newline); and the pattern character
-\character{\$} matches at the end of the string and at the end of each
-line (immediately preceding each newline). By default,
-\character{\textasciicircum} matches only at the beginning of the
-string, and \character{\$} only at the end of the string and
-immediately before the newline (if any) at the end of the string.
-\end{datadesc}
-
-\begin{datadesc}{S}
-\dataline{DOTALL}
-Make the \character{.} special character match any character at all,
-including a newline; without this flag, \character{.} will match
-anything \emph{except} a newline.
-\end{datadesc}
-
-\begin{datadesc}{U}
-\dataline{UNICODE}
-Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B},
-\regexp{\e d}, \regexp{\e D}, \regexp{\e s} and \regexp{\e S}
-dependent on the Unicode character properties database.
-\versionadded{2.0}
-\end{datadesc}
-
-\begin{datadesc}{X}
-\dataline{VERBOSE}
-This flag allows you to write regular expressions that look nicer.
-Whitespace within the pattern is ignored,
-except when in a character class or preceded by an unescaped
-backslash, and, when a line contains a \character{\#} neither in a
-character class or preceded by an unescaped backslash, all characters
-from the leftmost such \character{\#} through the end of the line are
-ignored.
-% XXX should add an example here
-\end{datadesc}
-
-
-\begin{funcdesc}{search}{pattern, string\optional{, flags}}
- Scan through \var{string} looking for a location where the regular
- expression \var{pattern} produces a match, and return a
- corresponding \class{MatchObject} instance.
- Return \code{None} if no
- position in the string matches the pattern; note that this is
- different from finding a zero-length match at some point in the string.
-\end{funcdesc}
-
-\begin{funcdesc}{match}{pattern, string\optional{, flags}}
- If zero or more characters at the beginning of \var{string} match
- the regular expression \var{pattern}, return a corresponding
- \class{MatchObject} instance. Return \code{None} if the string does not
- match the pattern; note that this is different from a zero-length
- match.
-
- \note{If you want to locate a match anywhere in
- \var{string}, use \method{search()} instead.}
-\end{funcdesc}
-
-\begin{funcdesc}{split}{pattern, string\optional{, maxsplit\code{ = 0}}}
- Split \var{string} by the occurrences of \var{pattern}. If
- capturing parentheses are used in \var{pattern}, then the text of all
- groups in the pattern are also returned as part of the resulting list.
- If \var{maxsplit} is nonzero, at most \var{maxsplit} splits
- occur, and the remainder of the string is returned as the final
- element of the list. (Incompatibility note: in the original Python
- 1.5 release, \var{maxsplit} was ignored. This has been fixed in
- later releases.)
-
-\begin{verbatim}
->>> re.split('\W+', 'Words, words, words.')
-['Words', 'words', 'words', '']
->>> re.split('(\W+)', 'Words, words, words.')
-['Words', ', ', 'words', ', ', 'words', '.', '']
->>> re.split('\W+', 'Words, words, words.', 1)
-['Words', 'words, words.']
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{findall}{pattern, string\optional{, flags}}
- Return a list of all non-overlapping matches of \var{pattern} in
- \var{string}. If one or more groups are present in the pattern,
- return a list of groups; this will be a list of tuples if the
- pattern has more than one group. Empty matches are included in the
- result unless they touch the beginning of another match.
- \versionadded{1.5.2}
- \versionchanged[Added the optional flags argument]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{finditer}{pattern, string\optional{, flags}}
- Return an iterator over all non-overlapping matches for the RE
- \var{pattern} in \var{string}. For each match, the iterator returns
- a match object. Empty matches are included in the result unless they
- touch the beginning of another match.
- \versionadded{2.2}
- \versionchanged[Added the optional flags argument]{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{sub}{pattern, repl, string\optional{, count}}
- Return the string obtained by replacing the leftmost non-overlapping
- occurrences of \var{pattern} in \var{string} by the replacement
- \var{repl}. If the pattern isn't found, \var{string} is returned
- unchanged. \var{repl} can be a string or a function; if it is a
- string, any backslash escapes in it are processed. That is,
- \samp{\e n} is converted to a single newline character, \samp{\e r}
- is converted to a linefeed, and so forth. Unknown escapes such as
- \samp{\e j} are left alone. Backreferences, such as \samp{\e6}, are
- replaced with the substring matched by group 6 in the pattern. For
- example:
-
-\begin{verbatim}
->>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
-... r'static PyObject*\npy_\1(void)\n{',
-... 'def myfunc():')
-'static PyObject*\npy_myfunc(void)\n{'
-\end{verbatim}
-
- If \var{repl} is a function, it is called for every non-overlapping
- occurrence of \var{pattern}. The function takes a single match
- object argument, and returns the replacement string. For example:
-
-\begin{verbatim}
->>> def dashrepl(matchobj):
-... if matchobj.group(0) == '-': return ' '
-... else: return '-'
->>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
-'pro--gram files'
-\end{verbatim}
-
- The pattern may be a string or an RE object; if you need to specify
- regular expression flags, you must use a RE object, or use embedded
- modifiers in a pattern; for example, \samp{sub("(?i)b+", "x", "bbbb
- BBBB")} returns \code{'x x'}.
-
- The optional argument \var{count} is the maximum number of pattern
- occurrences to be replaced; \var{count} must be a non-negative
- integer. If omitted or zero, all occurrences will be replaced.
- Empty matches for the pattern are replaced only when not adjacent to
- a previous match, so \samp{sub('x*', '-', 'abc')} returns
- \code{'-a-b-c-'}.
-
- In addition to character escapes and backreferences as described
- above, \samp{\e g<name>} will use the substring matched by the group
- named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax.
- \samp{\e g<number>} uses the corresponding group number;
- \samp{\e g<2>} is therefore equivalent to \samp{\e 2}, but isn't
- ambiguous in a replacement such as \samp{\e g<2>0}. \samp{\e 20}
- would be interpreted as a reference to group 20, not a reference to
- group 2 followed by the literal character \character{0}. The
- backreference \samp{\e g<0>} substitutes in the entire substring
- matched by the RE.
-\end{funcdesc}
-
-\begin{funcdesc}{subn}{pattern, repl, string\optional{, count}}
- Perform the same operation as \function{sub()}, but return a tuple
- \code{(\var{new_string}, \var{number_of_subs_made})}.
-\end{funcdesc}
-
-\begin{funcdesc}{escape}{string}
- Return \var{string} with all non-alphanumerics backslashed; this is
- useful if you want to match an arbitrary literal string that may have
- regular expression metacharacters in it.
-\end{funcdesc}
-
-\begin{excdesc}{error}
- Exception raised when a string passed to one of the functions here
- is not a valid regular expression (for example, it might contain
- unmatched parentheses) or when some other error occurs during
- compilation or matching. It is never an error if a string contains
- no match for a pattern.
-\end{excdesc}
-
-
-\subsection{Regular Expression Objects \label{re-objects}}
-
-Compiled regular expression objects support the following methods and
-attributes:
-
-\begin{methoddesc}[RegexObject]{match}{string\optional{, pos\optional{,
- endpos}}}
- If zero or more characters at the beginning of \var{string} match
- this regular expression, return a corresponding
- \class{MatchObject} instance. Return \code{None} if the string does not
- match the pattern; note that this is different from a zero-length
- match.
-
- \note{If you want to locate a match anywhere in
- \var{string}, use \method{search()} instead.}
-
- The optional second parameter \var{pos} gives an index in the string
- where the search is to start; it defaults to \code{0}. This is not
- completely equivalent to slicing the string; the
- \code{'\textasciicircum'} pattern
- character matches at the real beginning of the string and at positions
- just after a newline, but not necessarily at the index where the search
- is to start.
-
- The optional parameter \var{endpos} limits how far the string will
- be searched; it will be as if the string is \var{endpos} characters
- long, so only the characters from \var{pos} to \code{\var{endpos} -
- 1} will be searched for a match. If \var{endpos} is less than
- \var{pos}, no match will be found, otherwise, if \var{rx} is a
- compiled regular expression object,
- \code{\var{rx}.match(\var{string}, 0, 50)} is equivalent to
- \code{\var{rx}.match(\var{string}[:50], 0)}.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{search}{string\optional{, pos\optional{,
- endpos}}}
- Scan through \var{string} looking for a location where this regular
- expression produces a match, and return a
- corresponding \class{MatchObject} instance. Return \code{None} if no
- position in the string matches the pattern; note that this is
- different from finding a zero-length match at some point in the string.
-
- The optional \var{pos} and \var{endpos} parameters have the same
- meaning as for the \method{match()} method.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{split}{string\optional{,
- maxsplit\code{ = 0}}}
-Identical to the \function{split()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{findall}{string\optional{, pos\optional{,
- endpos}}}
-Identical to the \function{findall()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{finditer}{string\optional{, pos\optional{,
- endpos}}}
-Identical to the \function{finditer()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}}
-Identical to the \function{sub()} function, using the compiled pattern.
-\end{methoddesc}
-
-\begin{methoddesc}[RegexObject]{subn}{repl, string\optional{,
- count\code{ = 0}}}
-Identical to the \function{subn()} function, using the compiled pattern.
-\end{methoddesc}
-
-
-\begin{memberdesc}[RegexObject]{flags}
-The flags argument used when the RE object was compiled, or
-\code{0} if no flags were provided.
-\end{memberdesc}
-
-\begin{memberdesc}[RegexObject]{groupindex}
-A dictionary mapping any symbolic group names defined by
-\regexp{(?P<\var{id}>)} to group numbers. The dictionary is empty if no
-symbolic groups were used in the pattern.
-\end{memberdesc}
-
-\begin{memberdesc}[RegexObject]{pattern}
-The pattern string from which the RE object was compiled.
-\end{memberdesc}
-
-
-\subsection{Match Objects \label{match-objects}}
-
-\class{MatchObject} instances support the following methods and
-attributes:
-
-\begin{methoddesc}[MatchObject]{expand}{template}
- Return the string obtained by doing backslash substitution on the
-template string \var{template}, as done by the \method{sub()} method.
-Escapes such as \samp{\e n} are converted to the appropriate
-characters, and numeric backreferences (\samp{\e 1}, \samp{\e 2}) and
-named backreferences (\samp{\e g<1>}, \samp{\e g<name>}) are replaced
-by the contents of the corresponding group.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{group}{\optional{group1, \moreargs}}
-Returns one or more subgroups of the match. If there is a single
-argument, the result is a single string; if there are
-multiple arguments, the result is a tuple with one item per argument.
-Without arguments, \var{group1} defaults to zero (the whole match
-is returned).
-If a \var{groupN} argument is zero, the corresponding return value is the
-entire matching string; if it is in the inclusive range [1..99], it is
-the string matching the corresponding parenthesized group. If a
-group number is negative or larger than the number of groups defined
-in the pattern, an \exception{IndexError} exception is raised.
-If a group is contained in a part of the pattern that did not match,
-the corresponding result is \code{None}. If a group is contained in a
-part of the pattern that matched multiple times, the last match is
-returned.
-
-If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax,
-the \var{groupN} arguments may also be strings identifying groups by
-their group name. If a string argument is not used as a group name in
-the pattern, an \exception{IndexError} exception is raised.
-
-A moderately complicated example:
-
-\begin{verbatim}
-m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')
-\end{verbatim}
-
-After performing this match, \code{m.group(1)} is \code{'3'}, as is
-\code{m.group('int')}, and \code{m.group(2)} is \code{'14'}.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{groups}{\optional{default}}
-Return a tuple containing all the subgroups of the match, from 1 up to
-however many groups are in the pattern. The \var{default} argument is
-used for groups that did not participate in the match; it defaults to
-\code{None}. (Incompatibility note: in the original Python 1.5
-release, if the tuple was one element long, a string would be returned
-instead. In later versions (from 1.5.1 on), a singleton tuple is
-returned in such cases.)
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{groupdict}{\optional{default}}
-Return a dictionary containing all the \emph{named} subgroups of the
-match, keyed by the subgroup name. The \var{default} argument is
-used for groups that did not participate in the match; it defaults to
-\code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{start}{\optional{group}}
-\methodline[MatchObject]{end}{\optional{group}}
-Return the indices of the start and end of the substring
-matched by \var{group}; \var{group} defaults to zero (meaning the whole
-matched substring).
-Return \code{-1} if \var{group} exists but
-did not contribute to the match. For a match object
-\var{m}, and a group \var{g} that did contribute to the match, the
-substring matched by group \var{g} (equivalent to
-\code{\var{m}.group(\var{g})}) is
-
-\begin{verbatim}
-m.string[m.start(g):m.end(g)]
-\end{verbatim}
-
-Note that
-\code{m.start(\var{group})} will equal \code{m.end(\var{group})} if
-\var{group} matched a null string. For example, after \code{\var{m} =
-re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1,
-\code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and
-\code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises
-an \exception{IndexError} exception.
-\end{methoddesc}
-
-\begin{methoddesc}[MatchObject]{span}{\optional{group}}
-For \class{MatchObject} \var{m}, return the 2-tuple
-\code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}.
-Note that if \var{group} did not contribute to the match, this is
-\code{(-1, -1)}. Again, \var{group} defaults to zero.
-\end{methoddesc}
-
-\begin{memberdesc}[MatchObject]{pos}
-The value of \var{pos} which was passed to the \function{search()} or
-\function{match()} method of the \class{RegexObject}. This is the
-index into the string at which the RE engine started looking for a
-match.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{endpos}
-The value of \var{endpos} which was passed to the \function{search()}
-or \function{match()} method of the \class{RegexObject}. This is the
-index into the string beyond which the RE engine will not go.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{lastindex}
-The integer index of the last matched capturing group, or \code{None}
-if no group was matched at all. For example, the expressions
-\regexp{(a)b}, \regexp{((a)(b))}, and \regexp{((ab))} will have
-\code{lastindex == 1} if applied to the string \code{'ab'},
-while the expression \regexp{(a)(b)} will have \code{lastindex == 2},
-if applied to the same string.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{lastgroup}
-The name of the last matched capturing group, or \code{None} if the
-group didn't have a name, or if no group was matched at all.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{re}
-The regular expression object whose \method{match()} or
-\method{search()} method produced this \class{MatchObject} instance.
-\end{memberdesc}
-
-\begin{memberdesc}[MatchObject]{string}
-The string passed to \function{match()} or \function{search()}.
-\end{memberdesc}
-
-\subsection{Examples}
-
-\leftline{\strong{Simulating \cfunction{scanf()}}}
-
-Python does not currently have an equivalent to \cfunction{scanf()}.
-\ttindex{scanf()}
-Regular expressions are generally more powerful, though also more
-verbose, than \cfunction{scanf()} format strings. The table below
-offers some more-or-less equivalent mappings between
-\cfunction{scanf()} format tokens and regular expressions.
-
-\begin{tableii}{l|l}{textrm}{\cfunction{scanf()} Token}{Regular Expression}
- \lineii{\code{\%c}}
- {\regexp{.}}
- \lineii{\code{\%5c}}
- {\regexp{.\{5\}}}
- \lineii{\code{\%d}}
- {\regexp{[-+]?\e d+}}
- \lineii{\code{\%e}, \code{\%E}, \code{\%f}, \code{\%g}}
- {\regexp{[-+]?(\e d+(\e.\e d*)?|\e.\e d+)([eE][-+]?\e d+)?}}
- \lineii{\code{\%i}}
- {\regexp{[-+]?(0[xX][\e dA-Fa-f]+|0[0-7]*|\e d+)}}
- \lineii{\code{\%o}}
- {\regexp{0[0-7]*}}
- \lineii{\code{\%s}}
- {\regexp{\e S+}}
- \lineii{\code{\%u}}
- {\regexp{\e d+}}
- \lineii{\code{\%x}, \code{\%X}}
- {\regexp{0[xX][\e dA-Fa-f]+}}
-\end{tableii}
-
-To extract the filename and numbers from a string like
-
-\begin{verbatim}
- /usr/sbin/sendmail - 0 errors, 4 warnings
-\end{verbatim}
-
-you would use a \cfunction{scanf()} format like
-
-\begin{verbatim}
- %s - %d errors, %d warnings
-\end{verbatim}
-
-The equivalent regular expression would be
-
-\begin{verbatim}
- (\S+) - (\d+) errors, (\d+) warnings
-\end{verbatim}
-
-\leftline{\strong{Avoiding recursion}}
-
-If you create regular expressions that require the engine to perform a
-lot of recursion, you may encounter a \exception{RuntimeError} exception with
-the message \code{maximum recursion limit} exceeded. For example,
-
-\begin{verbatim}
->>> import re
->>> s = 'Begin ' + 1000*'a very long string ' + 'end'
->>> re.match('Begin (\w| )*? end', s).end()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
- File "/usr/local/lib/python2.5/re.py", line 132, in match
- return _compile(pattern, flags).match(string)
-RuntimeError: maximum recursion limit exceeded
-\end{verbatim}
-
-You can often restructure your regular expression to avoid recursion.
-
-Starting with Python 2.3, simple uses of the \regexp{*?} pattern are
-special-cased to avoid recursion. Thus, the above regular expression
-can avoid recursion by being recast as
-\regexp{Begin [a-zA-Z0-9_ ]*?end}. As a further benefit, such regular
-expressions will run faster than their recursive equivalents.
diff --git a/Doc/lib/libreadline.tex b/Doc/lib/libreadline.tex
deleted file mode 100644
index dec37b6..0000000
--- a/Doc/lib/libreadline.tex
+++ /dev/null
@@ -1,196 +0,0 @@
-\section{\module{readline} ---
- GNU readline interface}
-
-\declaremodule{builtin}{readline}
- \platform{Unix}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-\modulesynopsis{GNU readline support for Python.}
-
-
-The \module{readline} module defines a number of functions to
-facilitate completion and reading/writing of history files from the
-Python interpreter. This module can be used directly or via the
-\refmodule{rlcompleter} module. Settings made using
-this module affect the behaviour of both the interpreter's interactive prompt
-and the prompts offered by the \function{raw_input()} and \function{input()}
-built-in functions.
-
-The \module{readline} module defines the following functions:
-
-
-\begin{funcdesc}{parse_and_bind}{string}
-Parse and execute single line of a readline init file.
-\end{funcdesc}
-
-\begin{funcdesc}{get_line_buffer}{}
-Return the current contents of the line buffer.
-\end{funcdesc}
-
-\begin{funcdesc}{insert_text}{string}
-Insert text into the command line.
-\end{funcdesc}
-
-\begin{funcdesc}{read_init_file}{\optional{filename}}
-Parse a readline initialization file.
-The default filename is the last filename used.
-\end{funcdesc}
-
-\begin{funcdesc}{read_history_file}{\optional{filename}}
-Load a readline history file.
-The default filename is \file{\~{}/.history}.
-\end{funcdesc}
-
-\begin{funcdesc}{write_history_file}{\optional{filename}}
-Save a readline history file.
-The default filename is \file{\~{}/.history}.
-\end{funcdesc}
-
-\begin{funcdesc}{clear_history}{}
-Clear the current history. (Note: this function is not available if
-the installed version of GNU readline doesn't support it.)
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{get_history_length}{}
-Return the desired length of the history file. Negative values imply
-unlimited history file size.
-\end{funcdesc}
-
-\begin{funcdesc}{set_history_length}{length}
-Set the number of lines to save in the history file.
-\function{write_history_file()} uses this value to truncate the
-history file when saving. Negative values imply unlimited history
-file size.
-\end{funcdesc}
-
-\begin{funcdesc}{get_current_history_length}{}
-Return the number of lines currently in the history. (This is different
-from \function{get_history_length()}, which returns the maximum number of
-lines that will be written to a history file.) \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{get_history_item}{index}
-Return the current contents of history item at \var{index}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{remove_history_item}{pos}
-Remove history item specified by its position from the history.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{replace_history_item}{pos, line}
-Replace history item specified by its position with the given line.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{redisplay}{}
-Change what's displayed on the screen to reflect the current contents
-of the line buffer. \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{set_startup_hook}{\optional{function}}
-Set or remove the startup_hook function. If \var{function} is specified,
-it will be used as the new startup_hook function; if omitted or
-\code{None}, any hook function already installed is removed. The
-startup_hook function is called with no arguments just
-before readline prints the first prompt.
-\end{funcdesc}
-
-\begin{funcdesc}{set_pre_input_hook}{\optional{function}}
-Set or remove the pre_input_hook function. If \var{function} is specified,
-it will be used as the new pre_input_hook function; if omitted or
-\code{None}, any hook function already installed is removed. The
-pre_input_hook function is called with no arguments after the first prompt
-has been printed and just before readline starts reading input characters.
-\end{funcdesc}
-
-\begin{funcdesc}{set_completer}{\optional{function}}
-Set or remove the completer function. If \var{function} is specified,
-it will be used as the new completer function; if omitted or
-\code{None}, any completer function already installed is removed. The
-completer function is called as \code{\var{function}(\var{text},
-\var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ...,
-until it returns a non-string value. It should return the next
-possible completion starting with \var{text}.
-\end{funcdesc}
-
-\begin{funcdesc}{get_completer}{}
-Get the completer function, or \code{None} if no completer function
-has been set. \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{get_begidx}{}
-Get the beginning index of the readline tab-completion scope.
-\end{funcdesc}
-
-\begin{funcdesc}{get_endidx}{}
-Get the ending index of the readline tab-completion scope.
-\end{funcdesc}
-
-\begin{funcdesc}{set_completer_delims}{string}
-Set the readline word delimiters for tab-completion.
-\end{funcdesc}
-
-\begin{funcdesc}{get_completer_delims}{}
-Get the readline word delimiters for tab-completion.
-\end{funcdesc}
-
-\begin{funcdesc}{add_history}{line}
-Append a line to the history buffer, as if it was the last line typed.
-\end{funcdesc}
-
-\begin{seealso}
- \seemodule{rlcompleter}{Completion of Python identifiers at the
- interactive prompt.}
-\end{seealso}
-
-
-\subsection{Example \label{readline-example}}
-
-The following example demonstrates how to use the
-\module{readline} module's history reading and writing functions to
-automatically load and save a history file named \file{.pyhist} from
-the user's home directory. The code below would normally be executed
-automatically during interactive sessions from the user's
-\envvar{PYTHONSTARTUP} file.
-
-\begin{verbatim}
-import os
-histfile = os.path.join(os.environ["HOME"], ".pyhist")
-try:
- readline.read_history_file(histfile)
-except IOError:
- pass
-import atexit
-atexit.register(readline.write_history_file, histfile)
-del os, histfile
-\end{verbatim}
-
-The following example extends the \class{code.InteractiveConsole} class to
-support history save/restore.
-
-\begin{verbatim}
-import code
-import readline
-import atexit
-import os
-
-class HistoryConsole(code.InteractiveConsole):
- def __init__(self, locals=None, filename="<console>",
- histfile=os.path.expanduser("~/.console-history")):
- code.InteractiveConsole.__init__(self)
- self.init_history(histfile)
-
- def init_history(self, histfile):
- readline.parse_and_bind("tab: complete")
- if hasattr(readline, "read_history_file"):
- try:
- readline.read_history_file(histfile)
- except IOError:
- pass
- atexit.register(self.save_history, histfile)
-
- def save_history(self, histfile):
- readline.write_history_file(histfile)
-\end{verbatim}
diff --git a/Doc/lib/librepr.tex b/Doc/lib/librepr.tex
deleted file mode 100644
index 2876448..0000000
--- a/Doc/lib/librepr.tex
+++ /dev/null
@@ -1,133 +0,0 @@
-\section{\module{repr} ---
- Alternate \function{repr()} implementation}
-
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\declaremodule{standard}{repr}
-\modulesynopsis{Alternate \function{repr()} implementation with size limits.}
-
-
-The \module{repr} module provides a means for producing object
-representations with limits on the size of the resulting strings.
-This is used in the Python debugger and may be useful in other
-contexts as well.
-
-This module provides a class, an instance, and a function:
-
-
-\begin{classdesc}{Repr}{}
- Class which provides formatting services useful in implementing
- functions similar to the built-in \function{repr()}; size limits for
- different object types are added to avoid the generation of
- representations which are excessively long.
-\end{classdesc}
-
-
-\begin{datadesc}{aRepr}
- This is an instance of \class{Repr} which is used to provide the
- \function{repr()} function described below. Changing the attributes
- of this object will affect the size limits used by \function{repr()}
- and the Python debugger.
-\end{datadesc}
-
-
-\begin{funcdesc}{repr}{obj}
- This is the \method{repr()} method of \code{aRepr}. It returns a
- string similar to that returned by the built-in function of the same
- name, but with limits on most sizes.
-\end{funcdesc}
-
-
-\subsection{Repr Objects \label{Repr-objects}}
-
-\class{Repr} instances provide several members which can be used to
-provide size limits for the representations of different object types,
-and methods which format specific object types.
-
-
-\begin{memberdesc}[Repr]{maxlevel}
- Depth limit on the creation of recursive representations. The
- default is \code{6}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxdict}
-\memberline[Repr]{maxlist}
-\memberline[Repr]{maxtuple}
-\memberline[Repr]{maxset}
-\memberline[Repr]{maxfrozenset}
-\memberline[Repr]{maxdeque}
-\memberline[Repr]{maxarray}
- Limits on the number of entries represented for the named object
- type. The default is \code{4} for \member{maxdict}, \code{5} for
- \member{maxarray}, and \code{6} for the others.
- \versionadded[\member{maxset}, \member{maxfrozenset},
- and \member{set}]{2.4}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxlong}
- Maximum number of characters in the representation for a long
- integer. Digits are dropped from the middle. The default is
- \code{40}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxstring}
- Limit on the number of characters in the representation of the
- string. Note that the ``normal'' representation of the string is
- used as the character source: if escape sequences are needed in the
- representation, these may be mangled when the representation is
- shortened. The default is \code{30}.
-\end{memberdesc}
-
-\begin{memberdesc}[Repr]{maxother}
- This limit is used to control the size of object types for which no
- specific formatting method is available on the \class{Repr} object.
- It is applied in a similar manner as \member{maxstring}. The
- default is \code{20}.
-\end{memberdesc}
-
-\begin{methoddesc}[Repr]{repr}{obj}
- The equivalent to the built-in \function{repr()} that uses the
- formatting imposed by the instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Repr]{repr1}{obj, level}
- Recursive implementation used by \method{repr()}. This uses the
- type of \var{obj} to determine which formatting method to call,
- passing it \var{obj} and \var{level}. The type-specific methods
- should call \method{repr1()} to perform recursive formatting, with
- \code{\var{level} - 1} for the value of \var{level} in the recursive
- call.
-\end{methoddesc}
-
-\begin{methoddescni}[Repr]{repr_\var{type}}{obj, level}
- Formatting methods for specific types are implemented as methods
- with a name based on the type name. In the method name, \var{type}
- is replaced by
- \code{string.join(string.split(type(\var{obj}).__name__, '_'))}.
- Dispatch to these methods is handled by \method{repr1()}.
- Type-specific methods which need to recursively format a value
- should call \samp{self.repr1(\var{subobj}, \var{level} - 1)}.
-\end{methoddescni}
-
-
-\subsection{Subclassing Repr Objects \label{subclassing-reprs}}
-
-The use of dynamic dispatching by \method{Repr.repr1()} allows
-subclasses of \class{Repr} to add support for additional built-in
-object types or to modify the handling of types already supported.
-This example shows how special support for file objects could be
-added:
-
-\begin{verbatim}
-import repr
-import sys
-
-class MyRepr(repr.Repr):
- def repr_file(self, obj, level):
- if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
- return obj.name
- else:
- return `obj`
-
-aRepr = MyRepr()
-print aRepr.repr(sys.stdin) # prints '<stdin>'
-\end{verbatim}
diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex
deleted file mode 100644
index 8e102b8..0000000
--- a/Doc/lib/libresource.tex
+++ /dev/null
@@ -1,215 +0,0 @@
-\section{\module{resource} ---
- Resource usage information}
-
-\declaremodule{builtin}{resource}
- \platform{Unix}
-\modulesynopsis{An interface to provide resource usage information on
- the current process.}
-\moduleauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
-\sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu}
-
-
-This module provides basic mechanisms for measuring and controlling
-system resources utilized by a program.
-
-Symbolic constants are used to specify particular system resources and
-to request usage information about either the current process or its
-children.
-
-A single exception is defined for errors:
-
-
-\begin{excdesc}{error}
- The functions described below may raise this error if the underlying
- system call failures unexpectedly.
-\end{excdesc}
-
-\subsection{Resource Limits}
-
-Resources usage can be limited using the \function{setrlimit()} function
-described below. Each resource is controlled by a pair of limits: a
-soft limit and a hard limit. The soft limit is the current limit, and
-may be lowered or raised by a process over time. The soft limit can
-never exceed the hard limit. The hard limit can be lowered to any
-value greater than the soft limit, but not raised. (Only processes with
-the effective UID of the super-user can raise a hard limit.)
-
-The specific resources that can be limited are system dependent. They
-are described in the \manpage{getrlimit}{2} man page. The resources
-listed below are supported when the underlying operating system
-supports them; resources which cannot be checked or controlled by the
-operating system are not defined in this module for those platforms.
-
-\begin{funcdesc}{getrlimit}{resource}
- Returns a tuple \code{(\var{soft}, \var{hard})} with the current
- soft and hard limits of \var{resource}. Raises \exception{ValueError} if
- an invalid resource is specified, or \exception{error} if the
- underlying system call fails unexpectedly.
-\end{funcdesc}
-
-\begin{funcdesc}{setrlimit}{resource, limits}
- Sets new limits of consumption of \var{resource}. The \var{limits}
- argument must be a tuple \code{(\var{soft}, \var{hard})} of two
- integers describing the new limits. A value of \code{-1} can be used to
- specify the maximum possible upper limit.
-
- Raises \exception{ValueError} if an invalid resource is specified,
- if the new soft limit exceeds the hard limit, or if a process tries
- to raise its hard limit (unless the process has an effective UID of
- super-user). Can also raise \exception{error} if the underlying
- system call fails.
-\end{funcdesc}
-
-These symbols define resources whose consumption can be controlled
-using the \function{setrlimit()} and \function{getrlimit()} functions
-described below. The values of these symbols are exactly the constants
-used by \C{} programs.
-
-The \UNIX{} man page for \manpage{getrlimit}{2} lists the available
-resources. Note that not all systems use the same symbol or same
-value to denote the same resource. This module does not attempt to
-mask platform differences --- symbols not defined for a platform will
-not be available from this module on that platform.
-
-\begin{datadesc}{RLIMIT_CORE}
- The maximum size (in bytes) of a core file that the current process
- can create. This may result in the creation of a partial core file
- if a larger core would be required to contain the entire process
- image.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_CPU}
- The maximum amount of processor time (in seconds) that a process can
- use. If this limit is exceeded, a \constant{SIGXCPU} signal is sent to
- the process. (See the \refmodule{signal} module documentation for
- information about how to catch this signal and do something useful,
- e.g. flush open files to disk.)
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_FSIZE}
- The maximum size of a file which the process may create. This only
- affects the stack of the main thread in a multi-threaded process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_DATA}
- The maximum size (in bytes) of the process's heap.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_STACK}
- The maximum size (in bytes) of the call stack for the current
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_RSS}
- The maximum resident set size that should be made available to the
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_NPROC}
- The maximum number of processes the current process may create.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_NOFILE}
- The maximum number of open file descriptors for the current
- process.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_OFILE}
- The BSD name for \constant{RLIMIT_NOFILE}.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_MEMLOCK}
- The maximum address space which may be locked in memory.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_VMEM}
- The largest area of mapped memory which the process may occupy.
-\end{datadesc}
-
-\begin{datadesc}{RLIMIT_AS}
- The maximum area (in bytes) of address space which may be taken by
- the process.
-\end{datadesc}
-
-\subsection{Resource Usage}
-
-These functions are used to retrieve resource usage information:
-
-\begin{funcdesc}{getrusage}{who}
- This function returns an object that describes the resources
- consumed by either the current process or its children, as specified
- by the \var{who} parameter. The \var{who} parameter should be
- specified using one of the \constant{RUSAGE_*} constants described
- below.
-
- The fields of the return value each describe how a particular system
- resource has been used, e.g. amount of time spent running is user mode
- or number of times the process was swapped out of main memory. Some
- values are dependent on the clock tick internal, e.g. the amount of
- memory the process is using.
-
- For backward compatibility, the return value is also accessible as
- a tuple of 16 elements.
-
- The fields \member{ru_utime} and \member{ru_stime} of the return value
- are floating point values representing the amount of time spent
- executing in user mode and the amount of time spent executing in system
- mode, respectively. The remaining values are integers. Consult the
- \manpage{getrusage}{2} man page for detailed information about these
- values. A brief summary is presented here:
-
-\begin{tableiii}{r|l|l}{code}{Index}{Field}{Resource}
- \lineiii{0}{\member{ru_utime}}{time in user mode (float)}
- \lineiii{1}{\member{ru_stime}}{time in system mode (float)}
- \lineiii{2}{\member{ru_maxrss}}{maximum resident set size}
- \lineiii{3}{\member{ru_ixrss}}{shared memory size}
- \lineiii{4}{\member{ru_idrss}}{unshared memory size}
- \lineiii{5}{\member{ru_isrss}}{unshared stack size}
- \lineiii{6}{\member{ru_minflt}}{page faults not requiring I/O}
- \lineiii{7}{\member{ru_majflt}}{page faults requiring I/O}
- \lineiii{8}{\member{ru_nswap}}{number of swap outs}
- \lineiii{9}{\member{ru_inblock}}{block input operations}
- \lineiii{10}{\member{ru_oublock}}{block output operations}
- \lineiii{11}{\member{ru_msgsnd}}{messages sent}
- \lineiii{12}{\member{ru_msgrcv}}{messages received}
- \lineiii{13}{\member{ru_nsignals}}{signals received}
- \lineiii{14}{\member{ru_nvcsw}}{voluntary context switches}
- \lineiii{15}{\member{ru_nivcsw}}{involuntary context switches}
-\end{tableiii}
-
- This function will raise a \exception{ValueError} if an invalid
- \var{who} parameter is specified. It may also raise
- \exception{error} exception in unusual circumstances.
-
- \versionchanged[Added access to values as attributes of the
- returned object]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getpagesize}{}
- Returns the number of bytes in a system page. (This need not be the
- same as the hardware page size.) This function is useful for
- determining the number of bytes of memory a process is using. The
- third element of the tuple returned by \function{getrusage()} describes
- memory usage in pages; multiplying by page size produces number of
- bytes.
-\end{funcdesc}
-
-The following \constant{RUSAGE_*} symbols are passed to the
-\function{getrusage()} function to specify which processes information
-should be provided for.
-
-\begin{datadesc}{RUSAGE_SELF}
- \constant{RUSAGE_SELF} should be used to
- request information pertaining only to the process itself.
-\end{datadesc}
-
-\begin{datadesc}{RUSAGE_CHILDREN}
- Pass to \function{getrusage()} to request resource information for
- child processes of the calling process.
-\end{datadesc}
-
-\begin{datadesc}{RUSAGE_BOTH}
- Pass to \function{getrusage()} to request resources consumed by both
- the current process and child processes. May not be available on all
- systems.
-\end{datadesc}
diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
deleted file mode 100644
index b59e6ad..0000000
--- a/Doc/lib/librfc822.tex
+++ /dev/null
@@ -1,336 +0,0 @@
-\section{\module{rfc822} ---
- Parse RFC 2822 mail headers}
-
-\declaremodule{standard}{rfc822}
-\modulesynopsis{Parse \rfc{2822} style mail messages.}
-
-\deprecated{2.3}{The \refmodule{email} package should be used in
- preference to the \module{rfc822} module. This
- module is present only to maintain backward
- compatibility.}
-
-This module defines a class, \class{Message}, which represents an
-``email message'' as defined by the Internet standard
-\rfc{2822}.\footnote{This module originally conformed to \rfc{822},
-hence the name. Since then, \rfc{2822} has been released as an
-update to \rfc{822}. This module should be considered
-\rfc{2822}-conformant, especially in cases where the
-syntax or semantics have changed since \rfc{822}.} Such messages
-consist of a collection of message headers, and a message body. This
-module also defines a helper class
-\class{AddressList} for parsing \rfc{2822} addresses. Please refer to
-the RFC for information on the specific syntax of \rfc{2822} messages.
-
-The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes
-to read mailboxes produced by various end-user mail programs.
-
-\begin{classdesc}{Message}{file\optional{, seekable}}
-A \class{Message} instance is instantiated with an input object as
-parameter. Message relies only on the input object having a
-\method{readline()} method; in particular, ordinary file objects
-qualify. Instantiation reads headers from the input object up to a
-delimiter line (normally a blank line) and stores them in the
-instance. The message body, following the headers, is not consumed.
-
-This class can work with any input object that supports a
-\method{readline()} method. If the input object has seek and tell
-capability, the \method{rewindbody()} method will work; also, illegal
-lines will be pushed back onto the input stream. If the input object
-lacks seek but has an \method{unread()} method that can push back a
-line of input, \class{Message} will use that to push back illegal
-lines. Thus this class can be used to parse messages coming from a
-buffered stream.
-
-The optional \var{seekable} argument is provided as a workaround for
-certain stdio libraries in which \cfunction{tell()} discards buffered
-data before discovering that the \cfunction{lseek()} system call
-doesn't work. For maximum portability, you should set the seekable
-argument to zero to prevent that initial \method{tell()} when passing
-in an unseekable object such as a file object created from a socket
-object.
-
-Input lines as read from the file may either be terminated by CR-LF or
-by a single linefeed; a terminating CR-LF is replaced by a single
-linefeed before the line is stored.
-
-All header matching is done independent of upper or lower case;
-e.g.\ \code{\var{m}['From']}, \code{\var{m}['from']} and
-\code{\var{m}['FROM']} all yield the same result.
-\end{classdesc}
-
-\begin{classdesc}{AddressList}{field}
-You may instantiate the \class{AddressList} helper class using a single
-string parameter, a comma-separated list of \rfc{2822} addresses to be
-parsed. (The parameter \code{None} yields an empty list.)
-\end{classdesc}
-
-\begin{funcdesc}{quote}{str}
-Return a new string with backslashes in \var{str} replaced by two
-backslashes and double quotes replaced by backslash-double quote.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote}{str}
-Return a new string which is an \emph{unquoted} version of \var{str}.
-If \var{str} ends and begins with double quotes, they are stripped
-off. Likewise if \var{str} ends and begins with angle brackets, they
-are stripped off.
-\end{funcdesc}
-
-\begin{funcdesc}{parseaddr}{address}
-Parse \var{address}, which should be the value of some
-address-containing field such as \mailheader{To} or \mailheader{Cc},
-into its constituent ``realname'' and ``email address'' parts.
-Returns a tuple of that information, unless the parse fails, in which
-case a 2-tuple \code{(None, None)} is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{dump_address_pair}{pair}
-The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
-\code{(\var{realname}, \var{email_address})} and returns the string
-value suitable for a \mailheader{To} or \mailheader{Cc} header. If
-the first element of \var{pair} is false, then the second element is
-returned unmodified.
-\end{funcdesc}
-
-\begin{funcdesc}{parsedate}{date}
-Attempts to parse a date according to the rules in \rfc{2822}.
-however, some mailers don't follow that format as specified, so
-\function{parsedate()} tries to guess correctly in such cases.
-\var{date} is a string containing an \rfc{2822} date, such as
-\code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing
-the date, \function{parsedate()} returns a 9-tuple that can be passed
-directly to \function{time.mktime()}; otherwise \code{None} will be
-returned. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{parsedate_tz}{date}
-Performs the same function as \function{parsedate()}, but returns
-either \code{None} or a 10-tuple; the first 9 elements make up a tuple
-that can be passed directly to \function{time.mktime()}, and the tenth
-is the offset of the date's timezone from UTC (which is the official
-term for Greenwich Mean Time). (Note that the sign of the timezone
-offset is the opposite of the sign of the \code{time.timezone}
-variable for the same timezone; the latter variable follows the
-\POSIX{} standard while this module follows \rfc{2822}.) If the input
-string has no timezone, the last element of the tuple returned is
-\code{None}. Note that indexes 6, 7, and 8 of the result tuple are not
-usable.
-\end{funcdesc}
-
-\begin{funcdesc}{mktime_tz}{tuple}
-Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
-timestamp. If the timezone item in the tuple is \code{None}, assume
-local time. Minor deficiency: this first interprets the first 8
-elements as a local time and then compensates for the timezone
-difference; this may yield a slight error around daylight savings time
-switch dates. Not enough to worry about for common use.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{email}{Comprehensive email handling package; supersedes
- the \module{rfc822} module.}
- \seemodule{mailbox}{Classes to read various mailbox formats produced
- by end-user mail programs.}
- \seemodule{mimetools}{Subclass of \class{rfc822.Message} that
- handles MIME encoded messages.}
-\end{seealso}
-
-
-\subsection{Message Objects \label{message-objects}}
-
-A \class{Message} instance has the following methods:
-
-\begin{methoddesc}[Message]{rewindbody}{}
-Seek to the start of the message body. This only works if the file
-object is seekable.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{isheader}{line}
-Returns a line's canonicalized fieldname (the dictionary key that will
-be used to index it) if the line is a legal \rfc{2822} header; otherwise
-returns \code{None} (implying that parsing should stop here and the
-line be pushed back on the input stream). It is sometimes useful to
-override this method in a subclass.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{islast}{line}
-Return true if the given line is a delimiter on which Message should
-stop. The delimiter line is consumed, and the file object's read
-location positioned immediately after it. By default this method just
-checks that the line is blank, but you can override it in a subclass.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{iscomment}{line}
-Return \code{True} if the given line should be ignored entirely, just skipped.
-By default this is a stub that always returns \code{False}, but you can
-override it in a subclass.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getallmatchingheaders}{name}
-Return a list of lines consisting of all headers matching
-\var{name}, if any. Each physical line, whether it is a continuation
-line or not, is a separate list item. Return the empty list if no
-header matches \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getfirstmatchingheader}{name}
-Return a list of lines comprising the first header matching
-\var{name}, and its continuation line(s), if any. Return
-\code{None} if there is no header matching \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getrawheader}{name}
-Return a single string consisting of the text after the colon in the
-first header matching \var{name}. This includes leading whitespace,
-the trailing linefeed, and internal linefeeds and whitespace if there
-any continuation line(s) were present. Return \code{None} if there is
-no header matching \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getheader}{name\optional{, default}}
-Like \code{getrawheader(\var{name})}, but strip leading and trailing
-whitespace. Internal whitespace is not stripped. The optional
-\var{default} argument can be used to specify a different default to
-be returned when there is no header matching \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get}{name\optional{, default}}
-An alias for \method{getheader()}, to make the interface more compatible
-with regular dictionaries.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getaddr}{name}
-Return a pair \code{(\var{full name}, \var{email address})} parsed
-from the string returned by \code{getheader(\var{name})}. If no
-header matching \var{name} exists, return \code{(None, None)};
-otherwise both the full name and the address are (possibly empty)
-strings.
-
-Example: If \var{m}'s first \mailheader{From} header contains the
-string \code{'jack@cwi.nl (Jack Jansen)'}, then
-\code{m.getaddr('From')} will yield the pair
-\code{('Jack Jansen', 'jack@cwi.nl')}.
-If the header contained
-\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
-exact same result.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getaddrlist}{name}
-This is similar to \code{getaddr(\var{list})}, but parses a header
-containing a list of email addresses (e.g.\ a \mailheader{To} header) and
-returns a list of \code{(\var{full name}, \var{email address})} pairs
-(even if there was only one address in the header). If there is no
-header matching \var{name}, return an empty list.
-
-If multiple headers exist that match the named header (e.g. if there
-are several \mailheader{Cc} headers), all are parsed for addresses.
-Any continuation lines the named headers contain are also parsed.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getdate}{name}
-Retrieve a header using \method{getheader()} and parse it into a 9-tuple
-compatible with \function{time.mktime()}; note that fields 6, 7, and 8
-are not usable. If there is no header matching
-\var{name}, or it is unparsable, return \code{None}.
-
-Date parsing appears to be a black art, and not all mailers adhere to
-the standard. While it has been tested and found correct on a large
-collection of email from many sources, it is still possible that this
-function may occasionally yield an incorrect result.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{getdate_tz}{name}
-Retrieve a header using \method{getheader()} and parse it into a
-10-tuple; the first 9 elements will make a tuple compatible with
-\function{time.mktime()}, and the 10th is a number giving the offset
-of the date's timezone from UTC. Note that fields 6, 7, and 8
-are not usable. Similarly to \method{getdate()}, if
-there is no header matching \var{name}, or it is unparsable, return
-\code{None}.
-\end{methoddesc}
-
-\class{Message} instances also support a limited mapping interface.
-In particular: \code{\var{m}[name]} is like
-\code{\var{m}.getheader(name)} but raises \exception{KeyError} if
-there is no matching header; and \code{len(\var{m})},
-\code{\var{m}.get(\var{name}\optional{, \var{default}})},
-\code{\var{m}.has_key(\var{name})}, \code{\var{m}.keys()},
-\code{\var{m}.values()} \code{\var{m}.items()}, and
-\code{\var{m}.setdefault(\var{name}\optional{, \var{default}})} act as
-expected, with the one difference that \method{setdefault()} uses
-an empty string as the default value. \class{Message} instances
-also support the mapping writable interface \code{\var{m}[name] =
-value} and \code{del \var{m}[name]}. \class{Message} objects do not
-support the \method{clear()}, \method{copy()}, \method{popitem()}, or
-\method{update()} methods of the mapping interface. (Support for
-\method{get()} and \method{setdefault()} was only added in Python
-2.2.)
-
-Finally, \class{Message} instances have some public instance variables:
-
-\begin{memberdesc}[Message]{headers}
-A list containing the entire set of header lines, in the order in
-which they were read (except that setitem calls may disturb this
-order). Each line contains a trailing newline. The
-blank line terminating the headers is not contained in the list.
-\end{memberdesc}
-
-\begin{memberdesc}[Message]{fp}
-The file or file-like object passed at instantiation time. This can
-be used to read the message content.
-\end{memberdesc}
-
-\begin{memberdesc}[Message]{unixfrom}
-The \UNIX{} \samp{From~} line, if the message had one, or an empty
-string. This is needed to regenerate the message in some contexts,
-such as an \code{mbox}-style mailbox file.
-\end{memberdesc}
-
-
-\subsection{AddressList Objects \label{addresslist-objects}}
-
-An \class{AddressList} instance has the following methods:
-
-\begin{methoddesc}[AddressList]{__len__}{}
-Return the number of addresses in the address list.
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__str__}{}
-Return a canonicalized string representation of the address list.
-Addresses are rendered in "name" <host@domain> form, comma-separated.
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__add__}{alist}
-Return a new \class{AddressList} instance that contains all addresses
-in both \class{AddressList} operands, with duplicates removed (set
-union).
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__iadd__}{alist}
-In-place version of \method{__add__()}; turns this \class{AddressList}
-instance into the union of itself and the right-hand instance,
-\var{alist}.
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__sub__}{alist}
-Return a new \class{AddressList} instance that contains every address
-in the left-hand \class{AddressList} operand that is not present in
-the right-hand address operand (set difference).
-\end{methoddesc}
-
-\begin{methoddesc}[AddressList]{__isub__}{alist}
-In-place version of \method{__sub__()}, removing addresses in this
-list which are also in \var{alist}.
-\end{methoddesc}
-
-
-Finally, \class{AddressList} instances have one public instance variable:
-
-\begin{memberdesc}[AddressList]{addresslist}
-A list of tuple string pairs, one per address. In each member, the
-first is the canonicalized name part, the second is the
-actual route-address (\character{@}-separated username-host.domain
-pair).
-\end{memberdesc}
diff --git a/Doc/lib/librlcompleter.tex b/Doc/lib/librlcompleter.tex
deleted file mode 100644
index cb2ac59..0000000
--- a/Doc/lib/librlcompleter.tex
+++ /dev/null
@@ -1,65 +0,0 @@
-\section{\module{rlcompleter} ---
- Completion function for GNU readline}
-
-\declaremodule{standard}{rlcompleter}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Python identifier completion, suitable for the GNU readline library.}
-
-The \module{rlcompleter} module defines a completion function suitable for
-the \refmodule{readline} module by completing valid Python identifiers
-and keywords.
-
-When this module is imported on a \UNIX\ platform with the \module{readline}
-module available, an instance of the \class{Completer} class is automatically
-created and its \method{complete} method is set as the \module{readline}
-completer.
-
-Example:
-
-\begin{verbatim}
->>> import rlcompleter
->>> import readline
->>> readline.parse_and_bind("tab: complete")
->>> readline. <TAB PRESSED>
-readline.__doc__ readline.get_line_buffer readline.read_init_file
-readline.__file__ readline.insert_text readline.set_completer
-readline.__name__ readline.parse_and_bind
->>> readline.
-\end{verbatim}
-
-The \module{rlcompleter} module is designed for use with Python's
-interactive mode. A user can add the following lines to his or her
-initialization file (identified by the \envvar{PYTHONSTARTUP}
-environment variable) to get automatic \kbd{Tab} completion:
-
-\begin{verbatim}
-try:
- import readline
-except ImportError:
- print "Module readline not available."
-else:
- import rlcompleter
- readline.parse_and_bind("tab: complete")
-\end{verbatim}
-
-
-On platforms without \module{readline}, the \class{Completer} class defined
-by this module can still be used for custom purposes.
-
-\subsection{Completer Objects \label{completer-objects}}
-
-Completer objects have the following method:
-
-\begin{methoddesc}[Completer]{complete}{text, state}
-Return the \var{state}th completion for \var{text}.
-
-If called for \var{text} that doesn't include a period character
-(\character{.}), it will complete from names currently defined in
-\refmodule[main]{__main__}, \refmodule[builtin]{__builtin__} and
-keywords (as defined by the \refmodule{keyword} module).
-
-If called for a dotted name, it will try to evaluate anything without
-obvious side-effects (functions will not be evaluated, but it
-can generate calls to \method{__getattr__()}) up to the last part, and
-find matches for the rest via the \function{dir()} function.
-\end{methoddesc}
diff --git a/Doc/lib/librobotparser.tex b/Doc/lib/librobotparser.tex
deleted file mode 100644
index 5eac528..0000000
--- a/Doc/lib/librobotparser.tex
+++ /dev/null
@@ -1,66 +0,0 @@
-\section{\module{robotparser} ---
- Parser for robots.txt}
-
-\declaremodule{standard}{robotparser}
-\modulesynopsis{Loads a \protect\file{robots.txt} file and
- answers questions about fetchability of other URLs.}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\index{WWW}
-\index{World Wide Web}
-\index{URL}
-\index{robots.txt}
-
-This module provides a single class, \class{RobotFileParser}, which answers
-questions about whether or not a particular user agent can fetch a URL on
-the Web site that published the \file{robots.txt} file. For more details on
-the structure of \file{robots.txt} files, see
-\url{http://www.robotstxt.org/wc/norobots.html}.
-
-\begin{classdesc}{RobotFileParser}{}
-
-This class provides a set of methods to read, parse and answer questions
-about a single \file{robots.txt} file.
-
-\begin{methoddesc}{set_url}{url}
-Sets the URL referring to a \file{robots.txt} file.
-\end{methoddesc}
-
-\begin{methoddesc}{read}{}
-Reads the \file{robots.txt} URL and feeds it to the parser.
-\end{methoddesc}
-
-\begin{methoddesc}{parse}{lines}
-Parses the lines argument.
-\end{methoddesc}
-
-\begin{methoddesc}{can_fetch}{useragent, url}
-Returns \code{True} if the \var{useragent} is allowed to fetch the \var{url}
-according to the rules contained in the parsed \file{robots.txt} file.
-\end{methoddesc}
-
-\begin{methoddesc}{mtime}{}
-Returns the time the \code{robots.txt} file was last fetched. This is
-useful for long-running web spiders that need to check for new
-\code{robots.txt} files periodically.
-\end{methoddesc}
-
-\begin{methoddesc}{modified}{}
-Sets the time the \code{robots.txt} file was last fetched to the current
-time.
-\end{methoddesc}
-
-\end{classdesc}
-
-The following example demonstrates basic use of the RobotFileParser class.
-
-\begin{verbatim}
->>> import robotparser
->>> rp = robotparser.RobotFileParser()
->>> rp.set_url("http://www.musi-cal.com/robots.txt")
->>> rp.read()
->>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
-False
->>> rp.can_fetch("*", "http://www.musi-cal.com/")
-True
-\end{verbatim}
diff --git a/Doc/lib/librunpy.tex b/Doc/lib/librunpy.tex
deleted file mode 100644
index 60707ca..0000000
--- a/Doc/lib/librunpy.tex
+++ /dev/null
@@ -1,76 +0,0 @@
-\section{\module{runpy} ---
- Locating and executing Python modules.}
-
-\declaremodule{standard}{runpy} % standard library, in Python
-
-\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com}
-
-\modulesynopsis{Locate and execute Python modules as scripts}
-
-\versionadded{2.5}
-
-The \module{runpy} module is used to locate and run Python modules
-without importing them first. Its main use is to implement the
-\programopt{-m} command line switch that allows scripts to be located
-using the Python module namespace rather than the filesystem.
-
-When executed as a script, the module effectively operates as follows:
-\begin{verbatim}
- del sys.argv[0] # Remove the runpy module from the arguments
- run_module(sys.argv[0], run_name="__main__", alter_sys=True)
-\end{verbatim}
-
-The \module{runpy} module provides a single function:
-
-\begin{funcdesc}{run_module}{mod_name\optional{, init_globals}
-\optional{, run_name}\optional{, alter_sys}}
-Execute the code of the specified module and return the resulting
-module globals dictionary. The module's code is first located using
-the standard import mechanism (refer to PEP 302 for details) and
-then executed in a fresh module namespace.
-
-The optional dictionary argument \var{init_globals} may be used to
-pre-populate the globals dictionary before the code is executed.
-The supplied dictionary will not be modified. If any of the special
-global variables below are defined in the supplied dictionary, those
-definitions are overridden by the \code{run_module} function.
-
-The special global variables \code{__name__}, \code{__file__},
-\code{__loader__} and \code{__builtins__} are set in the globals
-dictionary before the module code is executed.
-
-\code{__name__} is set to \var{run_name} if this optional argument is
-supplied, and the \var{mod_name} argument otherwise.
-
-\code{__loader__} is set to the PEP 302 module loader used to retrieve
-the code for the module (This loader may be a wrapper around the
-standard import mechanism).
-
-\code{__file__} is set to the name provided by the module loader. If
-the loader does not make filename information available, this
-variable is set to \code{None}.
-
-\code{__builtins__} is automatically initialised with a reference to
-the top level namespace of the \module{__builtin__} module.
-
-If the argument \var{alter_sys} is supplied and evaluates to
-\code{True}, then \code{sys.argv[0]} is updated with the value of
-\code{__file__} and \code{sys.modules[__name__]} is updated with a
-new module object for the module being executed. Note that neither
-\code{sys.argv[0]} nor \code{sys.modules[__name__]} are restored to
-their original values before the function returns - if client code
-needs these values preserved, it must either save them explicitly or
-else avoid enabling the automatic alterations to \module{sys}.
-
-Note that this manipulation of \module{sys} is not thread-safe. Other
-threads may see the partially initialised module, as well as the
-altered list of arguments. It is recommended that the \module{sys}
-module be left alone when invoking this function from threaded code.
-\end{funcdesc}
-
-\begin{seealso}
-
-\seepep{338}{Executing modules as scripts}{PEP written and
-implemented by Nick Coghlan.}
-
-\end{seealso}
diff --git a/Doc/lib/libsched.tex b/Doc/lib/libsched.tex
deleted file mode 100644
index 75bab7e..0000000
--- a/Doc/lib/libsched.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{\module{sched} ---
- Event scheduler}
-
-% LaTeXed and enhanced from comments in file
-
-\declaremodule{standard}{sched}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{General purpose event scheduler.}
-
-The \module{sched} module defines a class which implements a general
-purpose event scheduler:\index{event scheduling}
-
-\begin{classdesc}{scheduler}{timefunc, delayfunc}
-The \class{scheduler} class defines a generic interface to scheduling
-events. It needs two functions to actually deal with the ``outside world''
---- \var{timefunc} should be callable without arguments, and return
-a number (the ``time'', in any units whatsoever). The \var{delayfunc}
-function should be callable with one argument, compatible with the output
-of \var{timefunc}, and should delay that many time units.
-\var{delayfunc} will also be called with the argument \code{0} after
-each event is run to allow other threads an opportunity to run in
-multi-threaded applications.
-\end{classdesc}
-
-Example:
-
-\begin{verbatim}
->>> import sched, time
->>> s=sched.scheduler(time.time, time.sleep)
->>> def print_time(): print "From print_time", time.time()
-...
->>> def print_some_times():
-... print time.time()
-... s.enter(5, 1, print_time, ())
-... s.enter(10, 1, print_time, ())
-... s.run()
-... print time.time()
-...
->>> print_some_times()
-930343690.257
-From print_time 930343695.274
-From print_time 930343700.273
-930343700.276
-\end{verbatim}
-
-
-\subsection{Scheduler Objects \label{scheduler-objects}}
-
-\class{scheduler} instances have the following methods:
-
-\begin{methoddesc}[scheduler]{enterabs}{time, priority, action, argument}
-Schedule a new event. The \var{time} argument should be a numeric type
-compatible with the return value of the \var{timefunc} function passed
-to the constructor. Events scheduled for
-the same \var{time} will be executed in the order of their
-\var{priority}.
-
-Executing the event means executing
-\code{\var{action}(*\var{argument})}. \var{argument} must be a
-sequence holding the parameters for \var{action}.
-
-Return value is an event which may be used for later cancellation of
-the event (see \method{cancel()}).
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{enter}{delay, priority, action, argument}
-Schedule an event for \var{delay} more time units. Other then the
-relative time, the other arguments, the effect and the return value
-are the same as those for \method{enterabs()}.
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{cancel}{event}
-Remove the event from the queue. If \var{event} is not an event
-currently in the queue, this method will raise a
-\exception{RuntimeError}.
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{empty}{}
-Return true if the event queue is empty.
-\end{methoddesc}
-
-\begin{methoddesc}[scheduler]{run}{}
-Run all scheduled events. This function will wait
-(using the \function{delayfunc} function passed to the constructor)
-for the next event, then execute it and so on until there are no more
-scheduled events.
-
-Either \var{action} or \var{delayfunc} can raise an exception. In
-either case, the scheduler will maintain a consistent state and
-propagate the exception. If an exception is raised by \var{action},
-the event will not be attempted in future calls to \method{run()}.
-
-If a sequence of events takes longer to run than the time available
-before the next event, the scheduler will simply fall behind. No
-events will be dropped; the calling code is responsible for canceling
-events which are no longer pertinent.
-\end{methoddesc}
diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex
deleted file mode 100644
index 69583d4..0000000
--- a/Doc/lib/libselect.tex
+++ /dev/null
@@ -1,132 +0,0 @@
-\section{\module{select} ---
- Waiting for I/O completion}
-
-\declaremodule{builtin}{select}
-\modulesynopsis{Wait for I/O completion on multiple streams.}
-
-
-This module provides access to the \cfunction{select()}
-and \cfunction{poll()} functions
-available in most operating systems. Note that on Windows, it only
-works for sockets; on other operating systems, it also works for other
-file types (in particular, on \UNIX, it works on pipes). It cannot
-be used on regular files to determine whether a file has grown since
-it was last read.
-
-The module defines the following:
-
-\begin{excdesc}{error}
-The exception raised when an error occurs. The accompanying value is
-a pair containing the numeric error code from \cdata{errno} and the
-corresponding string, as would be printed by the \C{} function
-\cfunction{perror()}.
-\end{excdesc}
-
-\begin{funcdesc}{poll}{}
-(Not supported by all operating systems.) Returns a polling object,
-which supports registering and unregistering file descriptors, and
-then polling them for I/O events;
-see section~\ref{poll-objects} below for the methods supported by
-polling objects.
-\end{funcdesc}
-
-\begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
-This is a straightforward interface to the \UNIX{} \cfunction{select()}
-system call. The first three arguments are sequences of `waitable
-objects': either integers representing file descriptors or
-objects with a parameterless method named \method{fileno()} returning
-such an integer. The three sequences of waitable objects are for input,
-output and `exceptional conditions', respectively. Empty sequences are
-allowed, but acceptance of three empty sequences is platform-dependent.
-(It is known to work on \UNIX{} but not on Windows.) The optional
-\var{timeout} argument specifies a time-out as a floating point number
-in seconds. When the \var{timeout} argument is omitted the function
-blocks until at least one file descriptor is ready. A time-out value
-of zero specifies a poll and never blocks.
-
-The return value is a triple of lists of objects that are ready:
-subsets of the first three arguments. When the time-out is reached
-without a file descriptor becoming ready, three empty lists are
-returned.
-
-Among the acceptable object types in the sequences are Python file
-objects (e.g. \code{sys.stdin}, or objects returned by
-\function{open()} or \function{os.popen()}), socket objects
-returned by \function{socket.socket()}.%
-\withsubitem{(in module socket)}{\ttindex{socket()}}
-\withsubitem{(in module os)}{\ttindex{popen()}}
-You may also define a \dfn{wrapper} class yourself, as long as it has
-an appropriate \method{fileno()} method (that really returns a file
-descriptor, not just a random integer).
-\note{File objects on Windows are not acceptable, but sockets
-are.\index{WinSock} On Windows, the underlying \cfunction{select()}
-function is provided by the WinSock library, and does not handle file
-descriptors that don't originate from WinSock.}
-\end{funcdesc}
-
-\subsection{Polling Objects
- \label{poll-objects}}
-
-The \cfunction{poll()} system call, supported on most \UNIX{} systems,
-provides better scalability for network servers that service many,
-many clients at the same time.
-\cfunction{poll()} scales better because the system call only
-requires listing the file descriptors of interest, while \cfunction{select()}
-builds a bitmap, turns on bits for the fds of interest, and then
-afterward the whole bitmap has to be linearly scanned again.
-\cfunction{select()} is O(highest file descriptor), while
-\cfunction{poll()} is O(number of file descriptors).
-
-\begin{methoddesc}[poll]{register}{fd\optional{, eventmask}}
-Register a file descriptor with the polling object. Future calls to
-the \method{poll()} method will then check whether the file descriptor
-has any pending I/O events. \var{fd} can be either an integer, or an
-object with a \method{fileno()} method that returns an integer. File
-objects implement
-\method{fileno()}, so they can also be used as the argument.
-
-\var{eventmask} is an optional bitmask describing the type of events you
-want to check for, and can be a combination of the constants
-\constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT},
-described in the table below. If not specified, the default value
-used will check for all 3 types of events.
-
-\begin{tableii}{l|l}{constant}{Constant}{Meaning}
- \lineii{POLLIN}{There is data to read}
- \lineii{POLLPRI}{There is urgent data to read}
- \lineii{POLLOUT}{Ready for output: writing will not block}
- \lineii{POLLERR}{Error condition of some sort}
- \lineii{POLLHUP}{Hung up}
- \lineii{POLLNVAL}{Invalid request: descriptor not open}
-\end{tableii}
-
-Registering a file descriptor that's already registered is not an
-error, and has the same effect as registering the descriptor exactly
-once.
-\end{methoddesc}
-
-\begin{methoddesc}[poll]{unregister}{fd}
-Remove a file descriptor being tracked by a polling object. Just like
-the \method{register()} method, \var{fd} can be an integer or an
-object with a \method{fileno()} method that returns an integer.
-
-Attempting to remove a file descriptor that was never registered
-causes a \exception{KeyError} exception to be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[poll]{poll}{\optional{timeout}}
-Polls the set of registered file descriptors, and returns a
-possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples
-for the descriptors that have events or errors to report.
-\var{fd} is the file descriptor, and \var{event} is a bitmask
-with bits set for the reported events for that descriptor
---- \constant{POLLIN} for waiting input,
-\constant{POLLOUT} to indicate that the descriptor can be written to, and
-so forth.
-An empty list indicates that the call timed out and no file
-descriptors had any events to report.
-If \var{timeout} is given, it specifies the length of time in
-milliseconds which the system will wait for events before returning.
-If \var{timeout} is omitted, negative, or \constant{None}, the call will
-block until there is an event for this poll object.
-\end{methoddesc}
diff --git a/Doc/lib/libsgmllib.tex b/Doc/lib/libsgmllib.tex
deleted file mode 100644
index 1fe0d63..0000000
--- a/Doc/lib/libsgmllib.tex
+++ /dev/null
@@ -1,271 +0,0 @@
-\section{\module{sgmllib} ---
- Simple SGML parser}
-
-\declaremodule{standard}{sgmllib}
-\modulesynopsis{Only as much of an SGML parser as needed to parse HTML.}
-
-\index{SGML}
-
-This module defines a class \class{SGMLParser} which serves as the
-basis for parsing text files formatted in SGML (Standard Generalized
-Mark-up Language). In fact, it does not provide a full SGML parser
---- it only parses SGML insofar as it is used by HTML, and the module
-only exists as a base for the \refmodule{htmllib} module. Another
-HTML parser which supports XHTML and offers a somewhat different
-interface is available in the \refmodule{HTMLParser} module.
-
-\begin{classdesc}{SGMLParser}{}
-The \class{SGMLParser} class is instantiated without arguments.
-The parser is hardcoded to recognize the following
-constructs:
-
-\begin{itemize}
-\item
-Opening and closing tags of the form
-\samp{<\var{tag} \var{attr}="\var{value}" ...>} and
-\samp{</\var{tag}>}, respectively.
-
-\item
-Numeric character references of the form \samp{\&\#\var{name};}.
-
-\item
-Entity references of the form \samp{\&\var{name};}.
-
-\item
-SGML comments of the form \samp{<!--\var{text}-->}. Note that
-spaces, tabs, and newlines are allowed between the trailing
-\samp{>} and the immediately preceding \samp{--}.
-
-\end{itemize}
-\end{classdesc}
-
-A single exception is defined as well:
-
-\begin{excdesc}{SGMLParseError}
-Exception raised by the \class{SGMLParser} class when it encounters an
-error while parsing.
-\versionadded{2.1}
-\end{excdesc}
-
-
-\class{SGMLParser} instances have the following methods:
-
-
-\begin{methoddesc}{reset}{}
-Reset the instance. Loses all unprocessed data. This is called
-implicitly at instantiation time.
-\end{methoddesc}
-
-\begin{methoddesc}{setnomoretags}{}
-Stop processing tags. Treat all following input as literal input
-(CDATA). (This is only provided so the HTML tag
-\code{<PLAINTEXT>} can be implemented.)
-\end{methoddesc}
-
-\begin{methoddesc}{setliteral}{}
-Enter literal mode (CDATA mode).
-\end{methoddesc}
-
-\begin{methoddesc}{feed}{data}
-Feed some text to the parser. It is processed insofar as it consists
-of complete elements; incomplete data is buffered until more data is
-fed or \method{close()} is called.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Force processing of all buffered data as if it were followed by an
-end-of-file mark. This method may be redefined by a derived class to
-define additional processing at the end of the input, but the
-redefined version should always call \method{close()}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_starttag_text}{}
-Return the text of the most recently opened start tag. This should
-not normally be needed for structured processing, but may be useful in
-dealing with HTML ``as deployed'' or for re-generating input with
-minimal changes (whitespace between attributes can be preserved,
-etc.).
-\end{methoddesc}
-
-\begin{methoddesc}{handle_starttag}{tag, method, attributes}
-This method is called to handle start tags for which either a
-\method{start_\var{tag}()} or \method{do_\var{tag}()} method has been
-defined. The \var{tag} argument is the name of the tag converted to
-lower case, and the \var{method} argument is the bound method which
-should be used to support semantic interpretation of the start tag.
-The \var{attributes} argument is a list of \code{(\var{name},
-\var{value})} pairs containing the attributes found inside the tag's
-\code{<>} brackets.
-
-The \var{name} has been translated to lower case.
-Double quotes and backslashes in the \var{value} have been interpreted,
-as well as known character references and known entity references
-terminated by a semicolon (normally, entity references can be terminated
-by any non-alphanumerical character, but this would break the very
-common case of \code{<A HREF="url?spam=1\&eggs=2">} when \code{eggs}
-is a valid entity name).
-
-For instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this
-method would be called as \samp{unknown_starttag('a', [('href',
-'http://www.cwi.nl/')])}. The base implementation simply calls
-\var{method} with \var{attributes} as the only argument.
-\versionadded[Handling of entity and character references within
- attribute values]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{handle_endtag}{tag, method}
-This method is called to handle endtags for which an
-\method{end_\var{tag}()} method has been defined. The
-\var{tag} argument is the name of the tag converted to lower case, and
-the \var{method} argument is the bound method which should be used to
-support semantic interpretation of the end tag. If no
-\method{end_\var{tag}()} method is defined for the closing element,
-this handler is not called. The base implementation simply calls
-\var{method}.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_data}{data}
-This method is called to process arbitrary data. It is intended to be
-overridden by a derived class; the base class implementation does
-nothing.
-\end{methoddesc}
-
-\begin{methoddesc}{handle_charref}{ref}
-This method is called to process a character reference of the form
-\samp{\&\#\var{ref};}. The base implementation uses
-\method{convert_charref()} to convert the reference to a string. If
-that method returns a string, it is passed to \method{handle_data()},
-otherwise \method{unknown_charref(\var{ref})} is called to handle the
-error.
-\versionchanged[Use \method{convert_charref()} instead of hard-coding
-the conversion]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{convert_charref}{ref}
-Convert a character reference to a string, or \code{None}. \var{ref}
-is the reference passed in as a string. In the base implementation,
-\var{ref} must be a decimal number in the range 0-255. It converts
-the code point found using the \method{convert_codepoint()} method.
-If \var{ref} is invalid or out of range, this method returns
-\code{None}. This method is called by the default
-\method{handle_charref()} implementation and by the attribute value
-parser.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{convert_codepoint}{codepoint}
-Convert a codepoint to a \class{str} value. Encodings can be handled
-here if appropriate, though the rest of \module{sgmllib} is oblivious
-on this matter.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{handle_entityref}{ref}
-This method is called to process a general entity reference of the
-form \samp{\&\var{ref};} where \var{ref} is an general entity
-reference. It converts \var{ref} by passing it to
-\method{convert_entityref()}. If a translation is returned, it
-calls the method \method{handle_data()} with the translation;
-otherwise, it calls the method \code{unknown_entityref(\var{ref})}.
-The default \member{entitydefs} defines translations for
-\code{\&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/libshelve.tex b/Doc/lib/libshelve.tex
deleted file mode 100644
index 6ca3576..0000000
--- a/Doc/lib/libshelve.tex
+++ /dev/null
@@ -1,174 +0,0 @@
-\section{\module{shelve} ---
- Python object persistence}
-
-\declaremodule{standard}{shelve}
-\modulesynopsis{Python object persistence.}
-
-
-A ``shelf'' is a persistent, dictionary-like object. The difference
-with ``dbm'' databases is that the values (not the keys!) in a shelf
-can be essentially arbitrary Python objects --- anything that the
-\refmodule{pickle} module can handle. This includes most class
-instances, recursive data types, and objects containing lots of shared
-sub-objects. The keys are ordinary strings.
-\refstmodindex{pickle}
-
-\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}}}}}
-Open a persistent dictionary. The filename specified is the base filename
-for the underlying database. As a side-effect, an extension may be added to
-the filename and more than one file may be created. By default, the
-underlying database file is opened for reading and writing. The optional
-{}\var{flag} parameter has the same interpretation as the \var{flag}
-parameter of \function{anydbm.open}.
-
-By default, version 0 pickles are used to serialize values.
-The version of the pickle protocol can be specified with the
-\var{protocol} parameter. \versionchanged[The \var{protocol}
-parameter was added]{2.3}
-
-By default, mutations to persistent-dictionary mutable entries are not
-automatically written back. If the optional \var{writeback} parameter
-is set to {}\var{True}, all entries accessed are cached in memory, and
-written back at close time; this can make it handier to mutate mutable
-entries in the persistent dictionary, but, if many entries are
-accessed, it can consume vast amounts of memory for the cache, and it
-can make the close operation very slow since all accessed entries are
-written back (there is no way to determine which accessed entries are
-mutable, nor which ones were actually mutated).
-
-\end{funcdesc}
-
-Shelve objects support all methods supported by dictionaries. This eases
-the transition from dictionary based scripts to those requiring persistent
-storage.
-
-One additional method is supported:
-\begin{methoddesc}[Shelf]{sync}{}
-Write back all entries in the cache if the shelf was opened with
-\var{writeback} set to \var{True}. Also empty the cache and synchronize
-the persistent dictionary on disk, if feasible. This is called automatically
-when the shelf is closed with \method{close()}.
-\end{methoddesc}
-
-\subsection{Restrictions}
-
-\begin{itemize}
-
-\item
-The choice of which database package will be used
-(such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) depends on
-which interface is available. Therefore it is not safe to open the database
-directly using \refmodule{dbm}. The database is also (unfortunately) subject
-to the limitations of \refmodule{dbm}, if it is used --- this means
-that (the pickled representation of) the objects stored in the
-database should be fairly small, and in rare cases key collisions may
-cause the database to refuse updates.
-\refbimodindex{dbm}
-\refbimodindex{gdbm}
-\refbimodindex{bsddb}
-
-\item
-Depending on the implementation, closing a persistent dictionary may
-or may not be necessary to flush changes to disk. The \method{__del__}
-method of the \class{Shelf} class calls the \method{close} method, so the
-programmer generally need not do this explicitly.
-
-\item
-The \module{shelve} module does not support \emph{concurrent} read/write
-access to shelved objects. (Multiple simultaneous read accesses are
-safe.) When a program has a shelf open for writing, no other program
-should have it open for reading or writing. \UNIX{} file locking can
-be used to solve this, but this differs across \UNIX{} versions and
-requires knowledge about the database implementation used.
-
-\end{itemize}
-
-\begin{classdesc}{Shelf}{dict\optional{, protocol=None\optional{, writeback=False}}}
-A subclass of \class{UserDict.DictMixin} which stores pickled values in the
-\var{dict} object.
-
-By default, version 0 pickles are used to serialize values. The
-version of the pickle protocol can be specified with the
-\var{protocol} parameter. See the \module{pickle} documentation for a
-discussion of the pickle protocols. \versionchanged[The \var{protocol}
-parameter was added]{2.3}
-
-If the \var{writeback} parameter is \code{True}, the object will hold a
-cache of all entries accessed and write them back to the \var{dict} at
-sync and close times. This allows natural operations on mutable entries,
-but can consume much more memory and make sync and close take a long time.
-\end{classdesc}
-
-\begin{classdesc}{BsdDbShelf}{dict\optional{, protocol=None\optional{, writeback=False}}}
-
-A subclass of \class{Shelf} which exposes \method{first},
-\method{next}, \method{previous}, \method{last} and
-\method{set_location} which are available in the \module{bsddb} module
-but not in other database modules. The \var{dict} object passed to
-the constructor must support those methods. This is generally
-accomplished by calling one of \function{bsddb.hashopen},
-\function{bsddb.btopen} or \function{bsddb.rnopen}. The optional
-\var{protocol} and \var{writeback} parameters have the
-same interpretation as for the \class{Shelf} class.
-
-\end{classdesc}
-
-\begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, protocol=None\optional{, writeback=False}}}}
-
-A subclass of \class{Shelf} which accepts a \var{filename} instead of
-a dict-like object. The underlying file will be opened using
-{}\function{anydbm.open}. By default, the file will be created and
-opened for both read and write. The optional \var{flag} parameter has
-the same interpretation as for the \function{open} function. The
-optional \var{protocol} and \var{writeback} parameters
-have the same interpretation as for the \class{Shelf} class.
-
-\end{classdesc}
-
-\subsection{Example}
-
-To summarize the interface (\code{key} is a string, \code{data} is an
-arbitrary object):
-
-\begin{verbatim}
-import shelve
-
-d = shelve.open(filename) # open -- file may get suffix added by low-level
- # library
-
-d[key] = data # store data at key (overwrites old data if
- # using an existing key)
-data = d[key] # retrieve a COPY of data at key (raise KeyError if no
- # such key)
-del d[key] # delete data stored at key (raises KeyError
- # if no such key)
-flag = d.has_key(key) # true if the key exists
-klist = d.keys() # a list of all existing keys (slow!)
-
-# as d was opened WITHOUT writeback=True, beware:
-d['xx'] = range(4) # this works as expected, but...
-d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!!
-
-# having opened d without writeback=True, you need to code carefully:
-temp = d['xx'] # extracts the copy
-temp.append(5) # mutates the copy
-d['xx'] = temp # stores the copy right back, to persist it
-
-# or, d=shelve.open(filename,writeback=True) would let you just code
-# d['xx'].append(5) and have it work as expected, BUT it would also
-# consume more memory and make the d.close() operation slower.
-
-d.close() # close it
-\end{verbatim}
-
-\begin{seealso}
- \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
- \seemodule{bsddb}{BSD \code{db} database interface.}
- \seemodule{dbhash}{Thin layer around the \module{bsddb} which provides an
- \function{open} function like the other database modules.}
- \seemodule{dbm}{Standard \UNIX{} database interface.}
- \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
- \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
- \seemodule{pickle}{Object serialization used by \module{shelve}.}
- \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
-\end{seealso}
diff --git a/Doc/lib/libshlex.tex b/Doc/lib/libshlex.tex
deleted file mode 100644
index 230ae9f..0000000
--- a/Doc/lib/libshlex.tex
+++ /dev/null
@@ -1,279 +0,0 @@
-\section{\module{shlex} ---
- Simple lexical analysis}
-
-\declaremodule{standard}{shlex}
-\modulesynopsis{Simple lexical analysis for \UNIX\ shell-like languages.}
-\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
-
-\versionadded{1.5.2}
-
-The \class{shlex} class makes it easy to write lexical analyzers for
-simple syntaxes resembling that of the \UNIX{} shell. This will often
-be useful for writing minilanguages, (for example, in run control
-files for Python applications) or for parsing quoted strings.
-
-\note{The \module{shlex} module currently does not support Unicode input.}
-
-The \module{shlex} module defines the following functions:
-
-\begin{funcdesc}{split}{s\optional{, comments\optional{, posix}}}
-Split the string \var{s} using shell-like syntax. If \var{comments} is
-\constant{False} (the default), the parsing of comments in the given
-string will be disabled (setting the \member{commenters} member of the
-\class{shlex} instance to the empty string). This function operates
-in \POSIX{} mode by default, but uses non-\POSIX{} mode if the
-\var{posix} argument is false.
-\versionadded{2.3}
-\versionchanged[Added the \var{posix} parameter]{2.6}
-\note{Since the \function{split()} function instantiates a \class{shlex}
- instance, passing \code{None} for \var{s} will read the string
- to split from standard input.}
-\end{funcdesc}
-
-The \module{shlex} module defines the following class:
-
-\begin{classdesc}{shlex}{\optional{instream\optional{,
- infile\optional{, posix}}}}
-A \class{shlex} instance or subclass instance is a lexical analyzer
-object. The initialization argument, if present, specifies where to
-read characters from. It must be a file-/stream-like object with
-\method{read()} and \method{readline()} methods, or a string (strings
-are accepted since Python 2.3). If no argument is given, input will be
-taken from \code{sys.stdin}. The second optional argument is a filename
-string, which sets the initial value of the \member{infile} member. If
-the \var{instream} argument is omitted or equal to \code{sys.stdin},
-this second argument defaults to ``stdin''. The \var{posix} argument
-was introduced in Python 2.3, and defines the operational mode. When
-\var{posix} is not true (default), the \class{shlex} instance will
-operate in compatibility mode. When operating in \POSIX{} mode,
-\class{shlex} will try to be as close as possible to the \POSIX{} shell
-parsing rules. See section~\ref{shlex-objects}.
-\end{classdesc}
-
-\begin{seealso}
- \seemodule{ConfigParser}{Parser for configuration files similar to the
- Windows \file{.ini} files.}
-\end{seealso}
-
-
-\subsection{shlex Objects \label{shlex-objects}}
-
-A \class{shlex} instance has the following methods:
-
-\begin{methoddesc}[shlex]{get_token}{}
-Return a token. If tokens have been stacked using
-\method{push_token()}, pop a token off the stack. Otherwise, read one
-from the input stream. If reading encounters an immediate
-end-of-file, \member{self.eof} is returned (the empty string (\code{''})
-in non-\POSIX{} mode, and \code{None} in \POSIX{} mode).
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{push_token}{str}
-Push the argument onto the token stack.
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{read_token}{}
-Read a raw token. Ignore the pushback stack, and do not interpret source
-requests. (This is not ordinarily a useful entry point, and is
-documented here only for the sake of completeness.)
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{sourcehook}{filename}
-When \class{shlex} detects a source request (see
-\member{source} below) this method is given the following token as
-argument, and expected to return a tuple consisting of a filename and
-an open file-like object.
-
-Normally, this method first strips any quotes off the argument. If
-the result is an absolute pathname, or there was no previous source
-request in effect, or the previous source was a stream
-(such as \code{sys.stdin}), the result is left alone. Otherwise, if the
-result is a relative pathname, the directory part of the name of the
-file immediately before it on the source inclusion stack is prepended
-(this behavior is like the way the C preprocessor handles
-\code{\#include "file.h"}).
-
-The result of the manipulations is treated as a filename, and returned
-as the first component of the tuple, with
-\function{open()} called on it to yield the second component. (Note:
-this is the reverse of the order of arguments in instance initialization!)
-
-This hook is exposed so that you can use it to implement directory
-search paths, addition of file extensions, and other namespace hacks.
-There is no corresponding `close' hook, but a shlex instance will call
-the \method{close()} method of the sourced input stream when it
-returns \EOF.
-
-For more explicit control of source stacking, use the
-\method{push_source()} and \method{pop_source()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{push_source}{stream\optional{, filename}}
-Push an input source stream onto the input stack. If the filename
-argument is specified it will later be available for use in error
-messages. This is the same method used internally by the
-\method{sourcehook} method.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{pop_source}{}
-Pop the last-pushed input source from the input stack.
-This is the same method used internally when the lexer reaches
-\EOF{} on a stacked input stream.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[shlex]{error_leader}{\optional{file\optional{, line}}}
-This method generates an error message leader in the format of a
-\UNIX{} C compiler error label; the format is \code{'"\%s", line \%d: '},
-where the \samp{\%s} is replaced with the name of the current source
-file and the \samp{\%d} with the current input line number (the
-optional arguments can be used to override these).
-
-This convenience is provided to encourage \module{shlex} users to
-generate error messages in the standard, parseable format understood
-by Emacs and other \UNIX{} tools.
-\end{methoddesc}
-
-Instances of \class{shlex} subclasses have some public instance
-variables which either control lexical analysis or can be used for
-debugging:
-
-\begin{memberdesc}[shlex]{commenters}
-The string of characters that are recognized as comment beginners.
-All characters from the comment beginner to end of line are ignored.
-Includes just \character{\#} by default.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{wordchars}
-The string of characters that will accumulate into multi-character
-tokens. By default, includes all \ASCII{} alphanumerics and
-underscore.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{whitespace}
-Characters that will be considered whitespace and skipped. Whitespace
-bounds tokens. By default, includes space, tab, linefeed and
-carriage-return.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{escape}
-Characters that will be considered as escape. This will be only used
-in \POSIX{} mode, and includes just \character{\textbackslash} by default.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{quotes}
-Characters that will be considered string quotes. The token
-accumulates until the same quote is encountered again (thus, different
-quote types protect each other as in the shell.) By default, includes
-\ASCII{} single and double quotes.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{escapedquotes}
-Characters in \member{quotes} that will interpret escape characters
-defined in \member{escape}. This is only used in \POSIX{} mode, and
-includes just \character{"} by default.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{whitespace_split}
-If \code{True}, tokens will only be split in whitespaces. This is useful, for
-example, for parsing command lines with \class{shlex}, getting tokens
-in a similar way to shell arguments.
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{infile}
-The name of the current input file, as initially set at class
-instantiation time or stacked by later source requests. It may
-be useful to examine this when constructing error messages.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{instream}
-The input stream from which this \class{shlex} instance is reading
-characters.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{source}
-This member is \code{None} by default. If you assign a string to it,
-that string will be recognized as a lexical-level inclusion request
-similar to the \samp{source} keyword in various shells. That is, the
-immediately following token will opened as a filename and input taken
-from that stream until \EOF, at which point the \method{close()}
-method of that stream will be called and the input source will again
-become the original input stream. Source requests may be stacked any
-number of levels deep.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{debug}
-If this member is numeric and \code{1} or more, a \class{shlex}
-instance will print verbose progress output on its behavior. If you
-need to use this, you can read the module source code to learn the
-details.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{lineno}
-Source line number (count of newlines seen so far plus one).
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{token}
-The token buffer. It may be useful to examine this when catching
-exceptions.
-\end{memberdesc}
-
-\begin{memberdesc}[shlex]{eof}
-Token used to determine end of file. This will be set to the empty
-string (\code{''}), in non-\POSIX{} mode, and to \code{None} in
-\POSIX{} mode.
-\versionadded{2.3}
-\end{memberdesc}
-
-\subsection{Parsing Rules\label{shlex-parsing-rules}}
-
-When operating in non-\POSIX{} mode, \class{shlex} will try to obey to
-the following rules.
-
-\begin{itemize}
-\item Quote characters are not recognized within words
- (\code{Do"Not"Separate} is parsed as the single word
- \code{Do"Not"Separate});
-\item Escape characters are not recognized;
-\item Enclosing characters in quotes preserve the literal value of
- all characters within the quotes;
-\item Closing quotes separate words (\code{"Do"Separate} is parsed
- as \code{"Do"} and \code{Separate});
-\item If \member{whitespace_split} is \code{False}, any character not
- declared to be a word character, whitespace, or a quote will be
- returned as a single-character token. If it is \code{True},
- \class{shlex} will only split words in whitespaces;
-\item EOF is signaled with an empty string (\code{''});
-\item It's not possible to parse empty strings, even if quoted.
-\end{itemize}
-
-When operating in \POSIX{} mode, \class{shlex} will try to obey to the
-following parsing rules.
-
-\begin{itemize}
-\item Quotes are stripped out, and do not separate words
- (\code{"Do"Not"Separate"} is parsed as the single word
- \code{DoNotSeparate});
-\item Non-quoted escape characters (e.g. \character{\textbackslash})
- preserve the literal value of the next character that follows;
-\item Enclosing characters in quotes which are not part of
- \member{escapedquotes} (e.g. \character{'}) preserve the literal
- value of all characters within the quotes;
-\item Enclosing characters in quotes which are part of
- \member{escapedquotes} (e.g. \character{"}) preserves the literal
- value of all characters within the quotes, with the exception of
- the characters mentioned in \member{escape}. The escape characters
- retain its special meaning only when followed by the quote in use,
- or the escape character itself. Otherwise the escape character
- will be considered a normal character.
-\item EOF is signaled with a \constant{None} value;
-\item Quoted empty strings (\code{''}) are allowed;
-\end{itemize}
-
diff --git a/Doc/lib/libshutil.tex b/Doc/lib/libshutil.tex
deleted file mode 100644
index 65cba54..0000000
--- a/Doc/lib/libshutil.tex
+++ /dev/null
@@ -1,152 +0,0 @@
-\section{\module{shutil} ---
- High-level file operations}
-
-\declaremodule{standard}{shutil}
-\modulesynopsis{High-level file operations, including copying.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-% partly based on the docstrings
-
-
-The \module{shutil} module offers a number of high-level operations on
-files and collections of files. In particular, functions are provided
-which support file copying and removal.
-\index{file!copying}
-\index{copying files}
-
-\strong{Caveat:} On MacOS, the resource fork and other metadata are
-not used. For file copies, this means that resources will be lost and
-file type and creator codes will not be correct.
-
-
-\begin{funcdesc}{copyfile}{src, dst}
- Copy the contents of the file named \var{src} to a file named
- \var{dst}. The destination location must be writable; otherwise,
- an \exception{IOError} exception will be raised.
- If \var{dst} already exists, it will be replaced.
- Special files such as character or block devices
- and pipes cannot be copied with this function. \var{src} and
- \var{dst} are path names given as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}}
- Copy the contents of the file-like object \var{fsrc} to the
- file-like object \var{fdst}. The integer \var{length}, if given,
- is the buffer size. In particular, a negative \var{length} value
- means to copy the data without looping over the source data in
- chunks; by default the data is read in chunks to avoid uncontrolled
- memory consumption. Note that if the current file position of the
- \var{fsrc} object is not 0, only the contents from the current file
- position to the end of the file will be copied.
-\end{funcdesc}
-
-\begin{funcdesc}{copymode}{src, dst}
- Copy the permission bits from \var{src} to \var{dst}. The file
- contents, owner, and group are unaffected. \var{src} and \var{dst}
- are path names given as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copystat}{src, dst}
- Copy the permission bits, last access time, last modification time,
- and flags from \var{src} to \var{dst}. The file contents, owner, and
- group are unaffected. \var{src} and \var{dst} are path names given
- as strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copy}{src, dst}
- Copy the file \var{src} to the file or directory \var{dst}. If
- \var{dst} is a directory, a file with the same basename as \var{src}
- is created (or overwritten) in the directory specified. Permission
- bits are copied. \var{src} and \var{dst} are path names given as
- strings.
-\end{funcdesc}
-
-\begin{funcdesc}{copy2}{src, dst}
- Similar to \function{copy()}, but last access time and last
- modification time are copied as well. This is similar to the
- \UNIX{} command \program{cp} \programopt{-p}.
-\end{funcdesc}
-
-\begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
- Recursively copy an entire directory tree rooted at \var{src}. The
- destination directory, named by \var{dst}, must not already exist;
- it will be created as well as missing parent directories.
- Permissions and times of directories are copied with \function{copystat()},
- individual files are copied using \function{copy2()}.
- If \var{symlinks} is true, symbolic links in
- the source tree are represented as symbolic links in the new tree;
- if false or omitted, the contents of the linked files are copied to
- the new tree. If exception(s) occur, an \exception{Error} is raised
- with a list of reasons.
-
- The source code for this should be considered an example rather than
- a tool.
-
- \versionchanged[\exception{Error} is raised if any exceptions occur during
- copying, rather than printing a message]{2.3}
-
- \versionchanged[Create intermediate directories needed to create \var{dst},
- rather than raising an error. Copy permissions and times of
- directories using \function{copystat()}]{2.5}
-
-\end{funcdesc}
-
-\begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
- \index{directory!deleting}
- Delete an entire directory tree (\var{path} must point to a directory).
- If \var{ignore_errors} is true, errors resulting from failed removals
- will be ignored; if false or omitted, such errors are handled by
- calling a handler specified by \var{onerror} or, if that is omitted,
- they raise an exception.
-
- If \var{onerror} is provided, it must be a callable that accepts
- three parameters: \var{function}, \var{path}, and \var{excinfo}.
- The first parameter, \var{function}, is the function which raised
- the exception; it will be \function{os.listdir()}, \function{os.remove()} or
- \function{os.rmdir()}. The second parameter, \var{path}, will be
- the path name passed to \var{function}. The third parameter,
- \var{excinfo}, will be the exception information return by
- \function{sys.exc_info()}. Exceptions raised by \var{onerror} will
- not be caught.
-\end{funcdesc}
-
-\begin{funcdesc}{move}{src, dst}
-Recursively move a file or directory to another location.
-
-If the destination is on our current filesystem, then simply use
-rename. Otherwise, copy src to the dst and then remove src.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-This exception collects exceptions that raised during a mult-file
-operation. For \function{copytree}, the exception argument is a
-list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}).
-
-\versionadded{2.3}
-\end{excdesc}
-
-\subsection{Example \label{shutil-example}}
-
-This example is the implementation of the \function{copytree()}
-function, described above, with the docstring omitted. It
-demonstrates many of the other functions provided by this module.
-
-\begin{verbatim}
-def copytree(src, dst, symlinks=0):
- names = os.listdir(src)
- os.mkdir(dst)
- for name in names:
- srcname = os.path.join(src, name)
- dstname = os.path.join(dst, name)
- try:
- if symlinks and os.path.islink(srcname):
- linkto = os.readlink(srcname)
- os.symlink(linkto, dstname)
- elif os.path.isdir(srcname):
- copytree(srcname, dstname, symlinks)
- else:
- copy2(srcname, dstname)
- except (IOError, os.error) as why:
- print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
-\end{verbatim}
diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex
deleted file mode 100644
index e98aa90..0000000
--- a/Doc/lib/libsignal.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{signal} ---
- Set handlers for asynchronous events}
-
-\declaremodule{builtin}{signal}
-\modulesynopsis{Set handlers for asynchronous events.}
-
-
-This module provides mechanisms to use signal handlers in Python.
-Some general rules for working with signals and their handlers:
-
-\begin{itemize}
-
-\item
-A handler for a particular signal, once set, remains installed until
-it is explicitly reset (Python emulates the BSD style interface
-regardless of the underlying implementation), with the exception of
-the handler for \constant{SIGCHLD}, which follows the underlying
-implementation.
-
-\item
-There is no way to ``block'' signals temporarily from critical
-sections (since this is not supported by all \UNIX{} flavors).
-
-\item
-Although Python signal handlers are called asynchronously as far as
-the Python user is concerned, they can only occur between the
-``atomic'' instructions of the Python interpreter. This means that
-signals arriving during long calculations implemented purely in C
-(such as regular expression matches on large bodies of text) may be
-delayed for an arbitrary amount of time.
-
-\item
-When a signal arrives during an I/O operation, it is possible that the
-I/O operation raises an exception after the signal handler returns.
-This is dependent on the underlying \UNIX{} system's semantics regarding
-interrupted system calls.
-
-\item
-Because the \C{} signal handler always returns, it makes little sense to
-catch synchronous errors like \constant{SIGFPE} or \constant{SIGSEGV}.
-
-\item
-Python installs a small number of signal handlers by default:
-\constant{SIGPIPE} is ignored (so write errors on pipes and sockets can be
-reported as ordinary Python exceptions) and \constant{SIGINT} is translated
-into a \exception{KeyboardInterrupt} exception. All of these can be
-overridden.
-
-\item
-Some care must be taken if both signals and threads are used in the
-same program. The fundamental thing to remember in using signals and
-threads simultaneously is:\ always perform \function{signal()} operations
-in the main thread of execution. Any thread can perform an
-\function{alarm()}, \function{getsignal()}, or \function{pause()};
-only the main thread can set a new signal handler, and the main thread
-will be the only one to receive signals (this is enforced by the
-Python \module{signal} module, even if the underlying thread
-implementation supports sending signals to individual threads). This
-means that signals can't be used as a means of inter-thread
-communication. Use locks instead.
-
-\end{itemize}
-
-The variables defined in the \module{signal} module are:
-
-\begin{datadesc}{SIG_DFL}
- This is one of two standard signal handling options; it will simply
- perform the default function for the signal. For example, on most
- systems the default action for \constant{SIGQUIT} is to dump core
- and exit, while the default action for \constant{SIGCLD} is to
- simply ignore it.
-\end{datadesc}
-
-\begin{datadesc}{SIG_IGN}
- This is another standard signal handler, which will simply ignore
- the given signal.
-\end{datadesc}
-
-\begin{datadesc}{SIG*}
- All the signal numbers are defined symbolically. For example, the
- hangup signal is defined as \constant{signal.SIGHUP}; the variable names
- are identical to the names used in C programs, as found in
- \code{<signal.h>}.
- The \UNIX{} man page for `\cfunction{signal()}' lists the existing
- signals (on some systems this is \manpage{signal}{2}, on others the
- list is in \manpage{signal}{7}).
- Note that not all systems define the same set of signal names; only
- those names defined by the system are defined by this module.
-\end{datadesc}
-
-\begin{datadesc}{NSIG}
- One more than the number of the highest signal number.
-\end{datadesc}
-
-The \module{signal} module defines the following functions:
-
-\begin{funcdesc}{alarm}{time}
- If \var{time} is non-zero, this function requests that a
- \constant{SIGALRM} signal be sent to the process in \var{time} seconds.
- Any previously scheduled alarm is canceled (only one alarm can
- be scheduled at any time). The returned value is then the number of
- seconds before any previously set alarm was to have been delivered.
- If \var{time} is zero, no alarm is scheduled, and any scheduled
- alarm is canceled. If the return value
- is zero, no alarm is currently scheduled. (See the \UNIX{} man page
- \manpage{alarm}{2}.)
- Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{getsignal}{signalnum}
- Return the current signal handler for the signal \var{signalnum}.
- The returned value may be a callable Python object, or one of the
- special values \constant{signal.SIG_IGN}, \constant{signal.SIG_DFL} or
- \constant{None}. Here, \constant{signal.SIG_IGN} means that the
- signal was previously ignored, \constant{signal.SIG_DFL} means that the
- default way of handling the signal was previously in use, and
- \code{None} means that the previous signal handler was not installed
- from Python.
-\end{funcdesc}
-
-\begin{funcdesc}{pause}{}
- Cause the process to sleep until a signal is received; the
- appropriate handler will then be called. Returns nothing. Not on
- Windows. (See the \UNIX{} man page \manpage{signal}{2}.)
-\end{funcdesc}
-
-\begin{funcdesc}{signal}{signalnum, handler}
- Set the handler for signal \var{signalnum} to the function
- \var{handler}. \var{handler} can be a callable Python object
- taking two arguments (see below), or
- one of the special values \constant{signal.SIG_IGN} or
- \constant{signal.SIG_DFL}. The previous signal handler will be returned
- (see the description of \function{getsignal()} above). (See the
- \UNIX{} man page \manpage{signal}{2}.)
-
- When threads are enabled, this function can only be called from the
- main thread; attempting to call it from other threads will cause a
- \exception{ValueError} exception to be raised.
-
- The \var{handler} is called with two arguments: the signal number
- and the current stack frame (\code{None} or a frame object;
- for a description of frame objects, see the reference manual section
- on the standard type hierarchy or see the attribute descriptions in
- the \refmodule{inspect} module).
-\end{funcdesc}
-
-\subsection{Example}
-\nodename{Signal Example}
-
-Here is a minimal example program. It uses the \function{alarm()}
-function to limit the time spent waiting to open a file; this is
-useful if the file is for a serial device that may not be turned on,
-which would normally cause the \function{os.open()} to hang
-indefinitely. The solution is to set a 5-second alarm before opening
-the file; if the operation takes too long, the alarm signal will be
-sent, and the handler raises an exception.
-
-\begin{verbatim}
-import signal, os
-
-def handler(signum, frame):
- print 'Signal handler called with signal', signum
- raise IOError, "Couldn't open device!"
-
-# Set the signal handler and a 5-second alarm
-signal.signal(signal.SIGALRM, handler)
-signal.alarm(5)
-
-# This open() may hang indefinitely
-fd = os.open('/dev/ttyS0', os.O_RDWR)
-
-signal.alarm(0) # Disable the alarm
-\end{verbatim}
diff --git a/Doc/lib/libsimplehttp.tex b/Doc/lib/libsimplehttp.tex
deleted file mode 100644
index efb40ec..0000000
--- a/Doc/lib/libsimplehttp.tex
+++ /dev/null
@@ -1,86 +0,0 @@
-\section{\module{SimpleHTTPServer} ---
- Simple HTTP request handler}
-
-\declaremodule{standard}{SimpleHTTPServer}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{This module provides a basic request handler for HTTP
- servers.}
-
-
-The \module{SimpleHTTPServer} module defines a request-handler class,
-interface-compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler},
-that serves files only from a base directory.
-
-The \module{SimpleHTTPServer} module defines the following class:
-
-\begin{classdesc}{SimpleHTTPRequestHandler}{request, client_address, server}
-This class is used to serve files from the current directory and below,
-directly mapping the directory structure to HTTP requests.
-
-A lot of the work, such as parsing the request, is done by the base
-class \class{BaseHTTPServer.BaseHTTPRequestHandler}. This class
-implements the \function{do_GET()} and \function{do_HEAD()} functions.
-\end{classdesc}
-
-The \class{SimpleHTTPRequestHandler} defines the following member
-variables:
-
-\begin{memberdesc}{server_version}
-This will be \code{"SimpleHTTP/" + __version__}, where \code{__version__}
-is defined in the module.
-\end{memberdesc}
-
-\begin{memberdesc}{extensions_map}
-A dictionary mapping suffixes into MIME types. The default is signified
-by an empty string, and is considered to be \code{application/octet-stream}.
-The mapping is used case-insensitively, and so should contain only
-lower-cased keys.
-\end{memberdesc}
-
-The \class{SimpleHTTPRequestHandler} defines the following methods:
-
-\begin{methoddesc}{do_HEAD}{}
-This method serves the \code{'HEAD'} request type: it sends the
-headers it would send for the equivalent \code{GET} request. See the
-\method{do_GET()} method for a more complete explanation of the possible
-headers.
-\end{methoddesc}
-
-\begin{methoddesc}{do_GET}{}
-The request is mapped to a local file by interpreting the request as
-a path relative to the current working directory.
-
-If the request was mapped to a directory, the directory is checked for
-a file named \code{index.html} or \code{index.htm} (in that order).
-If found, the file's contents are returned; otherwise a directory
-listing is generated by calling the \method{list_directory()} method.
-This method uses \function{os.listdir()} to scan the directory, and
-returns a \code{404} error response if the \function{listdir()} fails.
-
-If the request was mapped to a file, it is opened and the contents are
-returned. Any \exception{IOError} exception in opening the requested
-file is mapped to a \code{404}, \code{'File not found'}
-error. Otherwise, the content type is guessed by calling the
-\method{guess_type()} method, which in turn uses the
-\var{extensions_map} variable.
-
-A \code{'Content-type:'} header with the guessed content type is
-output, followed by a \code{'Content-Length:'} header with the file's
-size and a \code{'Last-Modified:'} header with the file's modification
-time.
-
-Then follows a blank line signifying the end of the headers,
-and then the contents of the file are output. If the file's MIME type
-starts with \code{text/} the file is opened in text mode; otherwise
-binary mode is used.
-
-For example usage, see the implementation of the \function{test()}
-function.
-\versionadded[The \code{'Last-Modified'} header]{2.5}
-\end{methoddesc}
-
-
-\begin{seealso}
- \seemodule{BaseHTTPServer}{Base class implementation for Web server
- and request handler.}
-\end{seealso}
diff --git a/Doc/lib/libsimplexmlrpc.tex b/Doc/lib/libsimplexmlrpc.tex
deleted file mode 100644
index 235905e..0000000
--- a/Doc/lib/libsimplexmlrpc.tex
+++ /dev/null
@@ -1,235 +0,0 @@
-\section{\module{SimpleXMLRPCServer} ---
- Basic XML-RPC server}
-
-\declaremodule{standard}{SimpleXMLRPCServer}
-\modulesynopsis{Basic XML-RPC server implementation.}
-\moduleauthor{Brian Quinlan}{brianq@activestate.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{2.2}
-
-The \module{SimpleXMLRPCServer} module provides a basic server
-framework for XML-RPC servers written in Python. Servers can either
-be free standing, using \class{SimpleXMLRPCServer}, or embedded in a
-CGI environment, using \class{CGIXMLRPCRequestHandler}.
-
-\begin{classdesc}{SimpleXMLRPCServer}{addr\optional{,
- requestHandler\optional{,
- logRequests\optional{,
- allow_none\optional{,
- encoding}}}}}
-
- Create a new server instance. This class
- provides methods for registration of functions that can be called by
- the XML-RPC protocol. The \var{requestHandler} parameter
- should be a factory for request handler instances; it defaults to
- \class{SimpleXMLRPCRequestHandler}. The \var{addr} and
- \var{requestHandler} parameters are passed to the
- \class{\refmodule{SocketServer}.TCPServer} constructor. If
- \var{logRequests} is true (the default), requests will be logged;
- setting this parameter to false will turn off logging.
- The \var{allow_none} and \var{encoding} parameters are passed on to
- \module{xmlrpclib} and control the XML-RPC responses that will be returned
- from the server. The \var{bind_and_activate} parameter controls whether
- \method{server_bind()} and \method{server_activate()} are called immediately
- by the constructor; it defaults to true. Setting it to false allows code to
- manipulate the \var{allow_reuse_address} class variable before the address
- is bound.
- \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
- \versionchanged[The \var{bind_and_activate} parameter was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{CGIXMLRPCRequestHandler}{\optional{allow_none\optional{, encoding}}}
- Create a new instance to handle XML-RPC requests in a CGI
- environment.
- The \var{allow_none} and \var{encoding} parameters are passed on to
- \module{xmlrpclib} and control the XML-RPC responses that will be returned
- from the server.
- \versionadded{2.3}
- \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5}
-\end{classdesc}
-
-\begin{classdesc}{SimpleXMLRPCRequestHandler}{}
- Create a new request handler instance. This request handler
- supports \code{POST} requests and modifies logging so that the
- \var{logRequests} parameter to the \class{SimpleXMLRPCServer}
- constructor parameter is honored.
-\end{classdesc}
-
-
-\subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}}
-
-The \class{SimpleXMLRPCServer} class is based on
-\class{SocketServer.TCPServer} and provides a means of creating
-simple, stand alone XML-RPC servers.
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{,
- name}}
- Register a function that can respond to XML-RPC requests. If
- \var{name} is given, it will be the method name associated with
- \var{function}, otherwise \code{\var{function}.__name__} will be
- used. \var{name} can be either a normal or Unicode string, and may
- contain characters not legal in Python identifiers, including the
- period character.
-\end{methoddesc}
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{,
- allow_dotted_names}}
- Register an object which is used to expose method names which have
- not been registered using \method{register_function()}. If
- \var{instance} contains a \method{_dispatch()} method, it is called
- with the requested method name and the parameters from the request. Its
- API is \code{def \method{_dispatch}(self, method, params)} (note that
- \var{params} does not represent a variable argument list). If it calls an
- underlying function to perform its task, that function is called as
- \code{func(*params)}, expanding the parameter list.
- The return value from \method{_dispatch()} is returned to the client as
- the result. If
- \var{instance} does not have a \method{_dispatch()} method, it is
- searched for an attribute matching the name of the requested method.
-
- If the optional \var{allow_dotted_names} argument is true and the
- instance does not have a \method{_dispatch()} method, then
- if the requested method name contains periods, each component of the
- method name is searched for individually, with the effect that a
- simple hierarchical search is performed. The value found from this
- search is then called with the parameters from the request, and the
- return value is passed back to the client.
-
- \begin{notice}[warning]
- Enabling the \var{allow_dotted_names} option allows intruders to access
- your module's global variables and may allow intruders to execute
- arbitrary code on your machine. Only use this option on a secure,
- closed network.
- \end{notice}
-
- \versionchanged[\var{allow_dotted_names} was added to plug a security hole;
- prior versions are insecure]{2.3.5, 2.4.1}
-
-\end{methoddesc}
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_introspection_functions}{}
- Registers the XML-RPC introspection functions \code{system.listMethods},
- \code{system.methodHelp} and \code{system.methodSignature}.
- \versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[SimpleXMLRPCServer]{register_multicall_functions}{}
- Registers the XML-RPC multicall function system.multicall.
-\end{methoddesc}
-
-\begin{memberdesc}[SimpleXMLRPCServer]{rpc_paths}
-An attribute value that must be a tuple listing valid path portions of
-the URL for receiving XML-RPC requests. Requests posted to other
-paths will result in a 404 ``no such page'' HTTP error. If this
-tuple is empty, all paths will be considered valid.
-The default value is \code{('/', '/RPC2')}.
- \versionadded{2.5}
-\end{memberdesc}
-
-Example:
-
-\begin{verbatim}
-from SimpleXMLRPCServer import SimpleXMLRPCServer
-
-# Create server
-server = SimpleXMLRPCServer(("localhost", 8000))
-server.register_introspection_functions()
-
-# Register pow() function; this will use the value of
-# pow.__name__ as the name, which is just 'pow'.
-server.register_function(pow)
-
-# Register a function under a different name
-def adder_function(x,y):
- return x + y
-server.register_function(adder_function, 'add')
-
-# Register an instance; all the methods of the instance are
-# published as XML-RPC methods (in this case, just 'div').
-class MyFuncs:
- def div(self, x, y):
- return x // y
-
-server.register_instance(MyFuncs())
-
-# Run the server's main loop
-server.serve_forever()
-\end{verbatim}
-
-The following client code will call the methods made available by
-the preceding server:
-
-\begin{verbatim}
-import xmlrpclib
-
-s = xmlrpclib.Server('http://localhost:8000')
-print s.pow(2,3) # Returns 2**3 = 8
-print s.add(2,3) # Returns 5
-print s.div(5,2) # Returns 5//2 = 2
-
-# Print list of available methods
-print s.system.listMethods()
-\end{verbatim}
-
-
-\subsection{CGIXMLRPCRequestHandler}
-
-The \class{CGIXMLRPCRequestHandler} class can be used to
-handle XML-RPC requests sent to Python CGI scripts.
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_function}{function\optional{, name}}
-Register a function that can respond to XML-RPC requests. If
-\var{name} is given, it will be the method name associated with
-function, otherwise \var{function.__name__} will be used. \var{name}
-can be either a normal or Unicode string, and may contain
-characters not legal in Python identifiers, including the period
-character.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_instance}{instance}
-Register an object which is used to expose method names
-which have not been registered using \method{register_function()}. If
-instance contains a \method{_dispatch()} method, it is called with the
-requested method name and the parameters from the
-request; the return value is returned to the client as the result.
-If instance does not have a \method{_dispatch()} method, it is searched
-for an attribute matching the name of the requested method; if
-the requested method name contains periods, each
-component of the method name is searched for individually,
-with the effect that a simple hierarchical search is performed.
-The value found from this search is then called with the
-parameters from the request, and the return value is passed
-back to the client.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_introspection_functions}{}
-Register the XML-RPC introspection functions
-\code{system.listMethods}, \code{system.methodHelp} and
-\code{system.methodSignature}.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_multicall_functions}{}
-Register the XML-RPC multicall function \code{system.multicall}.
-\end{methoddesc}
-
-\begin{methoddesc}[CGIXMLRPCRequestHandler]{handle_request}{\optional{request_text = None}}
-Handle a XML-RPC request. If \var{request_text} is given, it
-should be the POST data provided by the HTTP server,
-otherwise the contents of stdin will be used.
-\end{methoddesc}
-
-Example:
-
-\begin{verbatim}
-class MyFuncs:
- def div(self, x, y) : return x // y
-
-
-handler = CGIXMLRPCRequestHandler()
-handler.register_function(pow)
-handler.register_function(lambda x,y: x+y, 'add')
-handler.register_introspection_functions()
-handler.register_instance(MyFuncs())
-handler.handle_request()
-\end{verbatim}
diff --git a/Doc/lib/libsite.tex b/Doc/lib/libsite.tex
deleted file mode 100644
index 11858d1..0000000
--- a/Doc/lib/libsite.tex
+++ /dev/null
@@ -1,93 +0,0 @@
-\section{\module{site} ---
- Site-specific configuration hook}
-
-\declaremodule{standard}{site}
-\modulesynopsis{A standard way to reference site-specific modules.}
-
-
-\strong{This module is automatically imported during initialization.}
-The automatic import can be suppressed using the interpreter's
-\programopt{-S} option.
-
-Importing this module will append site-specific paths to the module
-search path.
-\indexiii{module}{search}{path}
-
-It starts by constructing up to four directories from a head and a
-tail part. For the head part, it uses \code{sys.prefix} and
-\code{sys.exec_prefix}; empty heads are skipped. For
-the tail part, it uses the empty string and then
-\file{lib/site-packages} (on Windows) or
-\file{lib/python\shortversion/site-packages} and then
-\file{lib/site-python} (on \UNIX{} and Macintosh). For each of the
-distinct head-tail combinations, it sees if it refers to an existing
-directory, and if so, adds it to \code{sys.path} and also inspects
-the newly added path for configuration files.
-\indexii{site-python}{directory}
-\indexii{site-packages}{directory}
-
-A path configuration file is a file whose name has the form
-\file{\var{package}.pth} and exists in one of the four directories
-mentioned above; its contents are additional items (one per line) to
-be added to \code{sys.path}. Non-existing items are never added to
-\code{sys.path}, but no check is made that the item refers to a
-directory (rather than a file). No item is added to \code{sys.path}
-more than once. Blank lines and lines beginning with \code{\#} are
-skipped. Lines starting with \code{import} (followed by space or tab)
-are executed.
-
-\versionchanged[A space or tab is now required after the import
-keyword]{2.6}
-
-\index{package}
-\indexiii{path}{configuration}{file}
-
-For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are
-set to \file{/usr/local}. The Python \version\ library is then
-installed in \file{/usr/local/lib/python\shortversion} (where only the
-first three characters of \code{sys.version} are used to form the
-installation path name). Suppose this has a subdirectory
-\file{/usr/local/lib/python\shortversion/site-packages} with three
-subsubdirectories, \file{foo}, \file{bar} and \file{spam}, and two
-path configuration files, \file{foo.pth} and \file{bar.pth}. Assume
-\file{foo.pth} contains the following:
-
-\begin{verbatim}
-# foo package configuration
-
-foo
-bar
-bletch
-\end{verbatim}
-
-and \file{bar.pth} contains:
-
-\begin{verbatim}
-# bar package configuration
-
-bar
-\end{verbatim}
-
-Then the following directories are added to \code{sys.path}, in this
-order:
-
-\begin{verbatim}
-/usr/local/lib/python2.3/site-packages/bar
-/usr/local/lib/python2.3/site-packages/foo
-\end{verbatim}
-
-Note that \file{bletch} is omitted because it doesn't exist; the
-\file{bar} directory precedes the \file{foo} directory because
-\file{bar.pth} comes alphabetically before \file{foo.pth}; and
-\file{spam} is omitted because it is not mentioned in either path
-configuration file.
-
-After these path manipulations, an attempt is made to import a module
-named \module{sitecustomize}\refmodindex{sitecustomize}, which can
-perform arbitrary site-specific customizations. If this import fails
-with an \exception{ImportError} exception, it is silently ignored.
-
-Note that for some non-\UNIX{} systems, \code{sys.prefix} and
-\code{sys.exec_prefix} are empty, and the path manipulations are
-skipped; however the import of
-\module{sitecustomize}\refmodindex{sitecustomize} is still attempted.
diff --git a/Doc/lib/libsmtpd.tex b/Doc/lib/libsmtpd.tex
deleted file mode 100644
index 657050d..0000000
--- a/Doc/lib/libsmtpd.tex
+++ /dev/null
@@ -1,63 +0,0 @@
-\section{\module{smtpd} ---
- SMTP Server}
-
-\declaremodule{standard}{smtpd}
-
-\moduleauthor{Barry Warsaw}{barry@zope.com}
-\sectionauthor{Moshe Zadka}{moshez@moshez.org}
-
-\modulesynopsis{Implement a flexible SMTP server}
-
-This module offers several classes to implement SMTP servers. One is
-a generic do-nothing implementation, which can be overridden, while
-the other two offer specific mail-sending strategies.
-
-
-\subsection{SMTPServer Objects}
-
-\begin{classdesc}{SMTPServer}{localaddr, remoteaddr}
-Create a new \class{SMTPServer} object, which binds to local address
-\var{localaddr}. It will treat \var{remoteaddr} as an upstream SMTP
-relayer. It inherits from \class{asyncore.dispatcher}, and so will
-insert itself into \refmodule{asyncore}'s event loop on instantiation.
-\end{classdesc}
-
-\begin{methoddesc}[SMTPServer]{process_message}{peer, mailfrom, rcpttos, data}
-Raise \exception{NotImplementedError} exception. Override this in
-subclasses to do something useful with this message. Whatever was
-passed in the constructor as \var{remoteaddr} will be available as the
-\member{_remoteaddr} attribute. \var{peer} is the remote host's address,
-\var{mailfrom} is the envelope originator, \var{rcpttos} are the
-envelope recipients and \var{data} is a string containing the contents
-of the e-mail (which should be in \rfc{2822} format).
-\end{methoddesc}
-
-
-\subsection{DebuggingServer Objects}
-
-\begin{classdesc}{DebuggingServer}{localaddr, remoteaddr}
-Create a new debugging server. Arguments are as per
-\class{SMTPServer}. Messages will be discarded, and printed on
-stdout.
-\end{classdesc}
-
-
-\subsection{PureProxy Objects}
-
-\begin{classdesc}{PureProxy}{localaddr, remoteaddr}
-Create a new pure proxy server. Arguments are as per \class{SMTPServer}.
-Everything will be relayed to \var{remoteaddr}. Note that running
-this has a good chance to make you into an open relay, so please be
-careful.
-\end{classdesc}
-
-
-\subsection{MailmanProxy Objects}
-
-\begin{classdesc}{MailmanProxy}{localaddr, remoteaddr}
-Create a new pure proxy server. Arguments are as per
-\class{SMTPServer}. Everything will be relayed to \var{remoteaddr},
-unless local mailman configurations knows about an address, in which
-case it will be handled via mailman. Note that running this has a
-good chance to make you into an open relay, so please be careful.
-\end{classdesc}
diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex
deleted file mode 100644
index 7786102..0000000
--- a/Doc/lib/libsmtplib.tex
+++ /dev/null
@@ -1,344 +0,0 @@
-\section{\module{smtplib} ---
- SMTP protocol client}
-
-\declaremodule{standard}{smtplib}
-\modulesynopsis{SMTP protocol client (requires sockets).}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-\indexii{SMTP}{protocol}
-\index{Simple Mail Transfer Protocol}
-
-The \module{smtplib} module defines an SMTP client session object that
-can be used to send mail to any Internet machine with an SMTP or ESMTP
-listener daemon. For details of SMTP and ESMTP operation, consult
-\rfc{821} (\citetitle{Simple Mail Transfer Protocol}) and \rfc{1869}
-(\citetitle{SMTP Service Extensions}).
-
-\begin{classdesc}{SMTP}{\optional{host\optional{, port\optional{,
- local_hostname\optional{, timeout}}}}}
-A \class{SMTP} instance encapsulates an SMTP connection. It has
-methods that support a full repertoire of SMTP and ESMTP
-operations. If the optional host and port parameters are given, the
-SMTP \method{connect()} method is called with those parameters during
-initialization. An \exception{SMTPConnectError} is raised if the
-specified host doesn't respond correctly.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global
-default timeout setting will be used).
-
-For normal use, you should only require the initialization/connect,
-\method{sendmail()}, and \method{quit()} methods. An example is
-included below.
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{SMTP_SSL}{\optional{host\optional{, port\optional{,
- local_hostname\optional{,
- keyfile\optional{,
- certfile\optional{, timeout}}}}}}}
-A \class{SMTP_SSL} instance behaves exactly the same as instances of \class{SMTP}.
-\class{SMTP_SSL} should be used for situations where SSL is required from
-the beginning of the connection and using \method{starttls()} is not appropriate.
-If \var{host} is not specified, the local host is used. If \var{port} is
-omitted, the standard SMTP-over-SSL port (465) is used. \var{keyfile} and \var{certfile}
-are also optional, and can contain a PEM formatted private key and
-certificate chain file for the SSL connection.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global
-default timeout setting will be used).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-\begin{classdesc}{LMTP}{\optional{host\optional{, port\optional{,
- local_hostname}}}}
-
-The LMTP protocol, which is very similar to ESMTP, is heavily based
-on the standard SMTP client. It's common to use Unix sockets for LMTP,
-so our connect() method must support that as well as a regular
-host:port server. To specify a Unix socket, you must use an absolute
-path for \var{host}, starting with a '/'.
-
-Authentication is supported, using the regular SMTP mechanism. When
-using a Unix socket, LMTP generally don't support or require any
-authentication, but your mileage might vary.
-
-\versionadded{2.6}
-
-\end{classdesc}
-
-A nice selection of exceptions is defined as well:
-
-\begin{excdesc}{SMTPException}
- Base exception class for all exceptions raised by this module.
-\end{excdesc}
-
-\begin{excdesc}{SMTPServerDisconnected}
- This exception is raised when the server unexpectedly disconnects,
- or when an attempt is made to use the \class{SMTP} instance before
- connecting it to a server.
-\end{excdesc}
-
-\begin{excdesc}{SMTPResponseException}
- Base class for all exceptions that include an SMTP error code.
- These exceptions are generated in some instances when the SMTP
- server returns an error code. The error code is stored in the
- \member{smtp_code} attribute of the error, and the
- \member{smtp_error} attribute is set to the error message.
-\end{excdesc}
-
-\begin{excdesc}{SMTPSenderRefused}
- Sender address refused. In addition to the attributes set by on all
- \exception{SMTPResponseException} exceptions, this sets `sender' to
- the string that the SMTP server refused.
-\end{excdesc}
-
-\begin{excdesc}{SMTPRecipientsRefused}
- All recipient addresses refused. The errors for each recipient are
- accessible through the attribute \member{recipients}, which is a
- dictionary of exactly the same sort as \method{SMTP.sendmail()}
- returns.
-\end{excdesc}
-
-\begin{excdesc}{SMTPDataError}
- The SMTP server refused to accept the message data.
-\end{excdesc}
-
-\begin{excdesc}{SMTPConnectError}
- Error occurred during establishment of a connection with the server.
-\end{excdesc}
-
-\begin{excdesc}{SMTPHeloError}
- The server refused our \samp{HELO} message.
-\end{excdesc}
-
-\begin{excdesc}{SMTPAuthenticationError}
- SMTP authentication went wrong. Most probably the server didn't accept
- the username/password combination provided.
-\end{excdesc}
-
-\begin{seealso}
- \seerfc{821}{Simple Mail Transfer Protocol}{Protocol definition for
- SMTP. This document covers the model, operating procedure,
- and protocol details for SMTP.}
- \seerfc{1869}{SMTP Service Extensions}{Definition of the ESMTP
- extensions for SMTP. This describes a framework for
- extending SMTP with new commands, supporting dynamic
- discovery of the commands provided by the server, and
- defines a few additional commands.}
-\end{seealso}
-
-
-\subsection{SMTP Objects \label{SMTP-objects}}
-
-An \class{SMTP} instance has the following methods:
-
-\begin{methoddesc}[SMTP]{set_debuglevel}{level}
-Set the debug output level. A true value for \var{level} results in
-debug messages for connection and for all messages sent to and
-received from the server.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{connect}{\optional{host\optional{, port}}}
-Connect to a host on a given port. The defaults are to connect to the
-local host at the standard SMTP port (25).
-If the hostname ends with a colon (\character{:}) followed by a
-number, that suffix will be stripped off and the number interpreted as
-the port number to use.
-This method is automatically invoked by the constructor if a
-host is specified during instantiation.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{docmd}{cmd, \optional{, argstring}}
-Send a command \var{cmd} to the server. The optional argument
-\var{argstring} is simply concatenated to the command, separated by a
-space.
-
-This returns a 2-tuple composed of a numeric response code and the
-actual response line (multiline responses are joined into one long
-line.)
-
-In normal operation it should not be necessary to call this method
-explicitly. It is used to implement other methods and may be useful
-for testing private extensions.
-
-If the connection to the server is lost while waiting for the reply,
-\exception{SMTPServerDisconnected} will be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{helo}{\optional{hostname}}
-Identify yourself to the SMTP server using \samp{HELO}. The hostname
-argument defaults to the fully qualified domain name of the local
-host.
-
-In normal operation it should not be necessary to call this method
-explicitly. It will be implicitly called by the \method{sendmail()}
-when necessary.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{ehlo}{\optional{hostname}}
-Identify yourself to an ESMTP server using \samp{EHLO}. The hostname
-argument defaults to the fully qualified domain name of the local
-host. Examine the response for ESMTP option and store them for use by
-\method{has_extn()}.
-
-Unless you wish to use \method{has_extn()} before sending
-mail, it should not be necessary to call this method explicitly. It
-will be implicitly called by \method{sendmail()} when necessary.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{has_extn}{name}
-Return \constant{True} if \var{name} is in the set of SMTP service
-extensions returned by the server, \constant{False} otherwise.
-Case is ignored.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{verify}{address}
-Check the validity of an address on this server using SMTP \samp{VRFY}.
-Returns a tuple consisting of code 250 and a full \rfc{822} address
-(including human name) if the user address is valid. Otherwise returns
-an SMTP error code of 400 or greater and an error string.
-
-\note{Many sites disable SMTP \samp{VRFY} in order to foil spammers.}
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{login}{user, password}
-Log in on an SMTP server that requires authentication.
-The arguments are the username and the password to authenticate with.
-If there has been no previous \samp{EHLO} or \samp{HELO} command this
-session, this method tries ESMTP \samp{EHLO} first.
-This method will return normally if the authentication was successful,
-or may raise the following exceptions:
-
-\begin{description}
- \item[\exception{SMTPHeloError}]
- The server didn't reply properly to the \samp{HELO} greeting.
- \item[\exception{SMTPAuthenticationError}]
- The server didn't accept the username/password combination.
- \item[\exception{SMTPException}]
- No suitable authentication method was found.
-\end{description}
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{starttls}{\optional{keyfile\optional{, certfile}}}
-Put the SMTP connection in TLS (Transport Layer Security) mode. All
-SMTP commands that follow will be encrypted. You should then call
-\method{ehlo()} again.
-
-If \var{keyfile} and \var{certfile} are provided, these are passed to
-the \refmodule{socket} module's \function{ssl()} function.
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{sendmail}{from_addr, to_addrs, msg\optional{,
- mail_options, rcpt_options}}
-Send mail. The required arguments are an \rfc{822} from-address
-string, a list of \rfc{822} to-address strings (a bare string will be
-treated as a list with 1 address), and a message string. The caller
-may pass a list of ESMTP options (such as \samp{8bitmime}) to be used
-in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP options
-(such as \samp{DSN} commands) that should be used with all \samp{RCPT}
-commands can be passed as \var{rcpt_options}. (If you need to use
-different ESMTP options to different recipients you have to use the
-low-level methods such as \method{mail}, \method{rcpt} and
-\method{data} to send the message.)
-
-\note{The \var{from_addr} and \var{to_addrs} parameters are
-used to construct the message envelope used by the transport agents.
-The \class{SMTP} does not modify the message headers in any way.}
-
-If there has been no previous \samp{EHLO} or \samp{HELO} command this
-session, this method tries ESMTP \samp{EHLO} first. If the server does
-ESMTP, message size and each of the specified options will be passed
-to it (if the option is in the feature set the server advertises). If
-\samp{EHLO} fails, \samp{HELO} will be tried and ESMTP options
-suppressed.
-
-This method will return normally if the mail is accepted for at least
-one recipient. Otherwise it will throw an exception. That is, if this
-method does not throw an exception, then someone should get your mail.
-If this method does not throw an exception, it returns a dictionary,
-with one entry for each recipient that was refused. Each entry
-contains a tuple of the SMTP error code and the accompanying error
-message sent by the server.
-
-This method may raise the following exceptions:
-
-\begin{description}
-\item[\exception{SMTPRecipientsRefused}]
-All recipients were refused. Nobody got the mail. The
-\member{recipients} attribute of the exception object is a dictionary
-with information about the refused recipients (like the one returned
-when at least one recipient was accepted).
-
-\item[\exception{SMTPHeloError}]
-The server didn't reply properly to the \samp{HELO} greeting.
-
-\item[\exception{SMTPSenderRefused}]
-The server didn't accept the \var{from_addr}.
-
-\item[\exception{SMTPDataError}]
-The server replied with an unexpected error code (other than a refusal
-of a recipient).
-\end{description}
-
-Unless otherwise noted, the connection will be open even after
-an exception is raised.
-
-\end{methoddesc}
-
-\begin{methoddesc}[SMTP]{quit}{}
-Terminate the SMTP session and close the connection.
-\end{methoddesc}
-
-Low-level methods corresponding to the standard SMTP/ESMTP commands
-\samp{HELP}, \samp{RSET}, \samp{NOOP}, \samp{MAIL}, \samp{RCPT}, and
-\samp{DATA} are also supported. Normally these do not need to be
-called directly, so they are not documented here. For details,
-consult the module code.
-
-
-\subsection{SMTP Example \label{SMTP-example}}
-
-This example prompts the user for addresses needed in the message
-envelope (`To' and `From' addresses), and the message to be
-delivered. Note that the headers to be included with the message must
-be included in the message as entered; this example doesn't do any
-processing of the \rfc{822} headers. In particular, the `To' and
-`From' addresses must be included in the message headers explicitly.
-
-\begin{verbatim}
-import smtplib
-
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-def prompt(prompt):
- return raw_input(prompt).strip()
-
-fromaddr = prompt("From: ")
-toaddrs = prompt("To: ").split()
-print "Enter message, end with ^D (Unix) or ^Z (Windows):"
-
-# Add the From: and To: headers at the start!
-msg = ("From: %s\r\nTo: %s\r\n\r\n"
- % (fromaddr, ", ".join(toaddrs)))
-while 1:
- try:
- line = raw_input()
- except EOFError:
- break
- if not line:
- break
- msg = msg + line
-
-print "Message length is " + repr(len(msg))
-
-server = smtplib.SMTP('localhost')
-server.set_debuglevel(1)
-server.sendmail(fromaddr, toaddrs, msg)
-server.quit()
-\end{verbatim}
diff --git a/Doc/lib/libsndhdr.tex b/Doc/lib/libsndhdr.tex
deleted file mode 100644
index a7f8c6e..0000000
--- a/Doc/lib/libsndhdr.tex
+++ /dev/null
@@ -1,41 +0,0 @@
-\section{\module{sndhdr} ---
- Determine type of sound file}
-
-\declaremodule{standard}{sndhdr}
-\modulesynopsis{Determine type of a sound file.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-% Based on comments in the module source file.
-
-
-The \module{sndhdr} provides utility functions which attempt to
-determine the type of sound data which is in a file. When these
-functions are able to determine what type of sound data is stored in a
-file, they return a tuple \code{(\var{type}, \var{sampling_rate},
-\var{channels}, \var{frames}, \var{bits_per_sample})}. The value for
-\var{type} indicates the data type and will be one of the strings
-\code{'aifc'}, \code{'aiff'}, \code{'au'}, \code{'hcom'},
-\code{'sndr'}, \code{'sndt'}, \code{'voc'}, \code{'wav'},
-\code{'8svx'}, \code{'sb'}, \code{'ub'}, or \code{'ul'}. The
-\var{sampling_rate} will be either the actual value or \code{0} if
-unknown or difficult to decode. Similarly, \var{channels} will be
-either the number of channels or \code{0} if it cannot be determined
-or if the value is difficult to decode. The value for \var{frames}
-will be either the number of frames or \code{-1}. The last item in
-the tuple, \var{bits_per_sample}, will either be the sample size in
-bits or \code{'A'} for A-LAW\index{A-LAW} or \code{'U'} for
-u-LAW\index{u-LAW}.
-
-
-\begin{funcdesc}{what}{filename}
- Determines the type of sound data stored in the file \var{filename}
- using \function{whathdr()}. If it succeeds, returns a tuple as
- described above, otherwise \code{None} is returned.
-\end{funcdesc}
-
-
-\begin{funcdesc}{whathdr}{filename}
- Determines the type of sound data stored in a file based on the file
- header. The name of the file is given by \var{filename}. This
- function returns a tuple as described above on success, or
- \code{None}.
-\end{funcdesc}
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
deleted file mode 100644
index e3fce23..0000000
--- a/Doc/lib/libsocket.tex
+++ /dev/null
@@ -1,921 +0,0 @@
-\section{\module{socket} ---
- Low-level networking interface}
-
-\declaremodule{builtin}{socket}
-\modulesynopsis{Low-level networking interface.}
-
-
-This module provides access to the BSD \emph{socket} interface.
-It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
-OS/2, and probably additional platforms. \note{Some behavior may be
-platform dependent, since calls are made to the operating system socket APIs.}
-
-For an introduction to socket programming (in C), see the following
-papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
-Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
-Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
-both in the \citetitle{UNIX Programmer's Manual, Supplementary Documents 1}
-(sections PS1:7 and PS1:8). The platform-specific reference material
-for the various socket-related system calls are also a valuable source
-of information on the details of socket semantics. For \UNIX, refer
-to the manual pages; for Windows, see the WinSock (or Winsock 2)
-specification.
-For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled
-\citetitle{Basic Socket Interface Extensions for IPv6}.
-
-The Python interface is a straightforward transliteration of the
-\UNIX{} system call and library interface for sockets to Python's
-object-oriented style: the \function{socket()} function returns a
-\dfn{socket object}\obindex{socket} whose methods implement the
-various socket system calls. Parameter types are somewhat
-higher-level than in the C interface: as with \method{read()} and
-\method{write()} operations on Python files, buffer allocation on
-receive operations is automatic, and buffer length is implicit on send
-operations.
-
-Socket addresses are represented as follows:
-A single string is used for the \constant{AF_UNIX} address family.
-A pair \code{(\var{host}, \var{port})} is used for the
-\constant{AF_INET} address family, where \var{host} is a string
-representing either a hostname in Internet domain notation like
-\code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'},
-and \var{port} is an integral port number.
-For \constant{AF_INET6} address family, a four-tuple
-\code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is
-used, where \var{flowinfo} and \var{scopeid} represents
-\code{sin6_flowinfo} and \code{sin6_scope_id} member in
-\constant{struct sockaddr_in6} in C.
-For \module{socket} module methods, \var{flowinfo} and \var{scopeid}
-can be omitted just for backward compatibility. Note, however,
-omission of \var{scopeid} can cause problems in manipulating scoped
-IPv6 addresses. Other address families are currently not supported.
-The address format required by a particular socket object is
-automatically selected based on the address family specified when the
-socket object was created.
-
-For IPv4 addresses, two special forms are accepted instead of a host
-address: the empty string represents \constant{INADDR_ANY}, and the string
-\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
-The behavior is not available for IPv6 for backward compatibility,
-therefore, you may want to avoid these if you intend to support IPv6 with
-your Python programs.
-
-If you use a hostname in the \var{host} portion of IPv4/v6 socket
-address, the program may show a nondeterministic behavior, as Python
-uses the first address returned from the DNS resolution. The socket
-address will be resolved differently into an actual IPv4/v6 address,
-depending on the results from DNS resolution and/or the host
-configuration. For deterministic behavior use a numeric address in
-\var{host} portion.
-
-\versionadded[AF_NETLINK sockets are represented as
-pairs \code{\var{pid}, \var{groups}}]{2.5}
-
-All errors raise exceptions. The normal exceptions for invalid
-argument types and out-of-memory conditions can be raised; errors
-related to socket or address semantics raise the error
-\exception{socket.error}.
-
-Non-blocking mode is supported through
-\method{setblocking()}. A generalization of this based on timeouts
-is supported through \method{settimeout()}.
-
-The module \module{socket} exports the following constants and functions:
-
-
-\begin{excdesc}{error}
-This exception is raised for socket-related errors.
-The accompanying value is either a string telling what went wrong or a
-pair \code{(\var{errno}, \var{string})}
-representing an error returned by a system
-call, similar to the value accompanying \exception{os.error}.
-See the module \refmodule{errno}\refbimodindex{errno}, which contains
-names for the error codes defined by the underlying operating system.
-\end{excdesc}
-
-\begin{excdesc}{herror}
-This exception is raised for address-related errors, i.e. for
-functions that use \var{h_errno} in the C API, including
-\function{gethostbyname_ex()} and \function{gethostbyaddr()}.
-
-The accompanying value is a pair \code{(\var{h_errno}, \var{string})}
-representing an error returned by a library call. \var{string}
-represents the description of \var{h_errno}, as returned by
-the \cfunction{hstrerror()} C function.
-\end{excdesc}
-
-\begin{excdesc}{gaierror}
-This exception is raised for address-related errors, for
-\function{getaddrinfo()} and \function{getnameinfo()}.
-The accompanying value is a pair \code{(\var{error}, \var{string})}
-representing an error returned by a library call.
-\var{string} represents the description of \var{error}, as returned
-by the \cfunction{gai_strerror()} C function.
-The \var{error} value will match one of the \constant{EAI_*} constants
-defined in this module.
-\end{excdesc}
-
-\begin{excdesc}{timeout}
-This exception is raised when a timeout occurs on a socket which has
-had timeouts enabled via a prior call to \method{settimeout()}. The
-accompanying value is a string whose value is currently always ``timed
-out''.
-\versionadded{2.3}
-\end{excdesc}
-
-\begin{datadesc}{AF_UNIX}
-\dataline{AF_INET}
-\dataline{AF_INET6}
-These constants represent the address (and protocol) families,
-used for the first argument to \function{socket()}. If the
-\constant{AF_UNIX} constant is not defined then this protocol is
-unsupported.
-\end{datadesc}
-
-\begin{datadesc}{SOCK_STREAM}
-\dataline{SOCK_DGRAM}
-\dataline{SOCK_RAW}
-\dataline{SOCK_RDM}
-\dataline{SOCK_SEQPACKET}
-These constants represent the socket types,
-used for the second argument to \function{socket()}.
-(Only \constant{SOCK_STREAM} and
-\constant{SOCK_DGRAM} appear to be generally useful.)
-\end{datadesc}
-
-\begin{datadesc}{SO_*}
-\dataline{SOMAXCONN}
-\dataline{MSG_*}
-\dataline{SOL_*}
-\dataline{IPPROTO_*}
-\dataline{IPPORT_*}
-\dataline{INADDR_*}
-\dataline{IP_*}
-\dataline{IPV6_*}
-\dataline{EAI_*}
-\dataline{AI_*}
-\dataline{NI_*}
-\dataline{TCP_*}
-Many constants of these forms, documented in the \UNIX{} documentation on
-sockets and/or the IP protocol, are also defined in the socket module.
-They are generally used in arguments to the \method{setsockopt()} and
-\method{getsockopt()} methods of socket objects. In most cases, only
-those symbols that are defined in the \UNIX{} header files are defined;
-for a few symbols, default values are provided.
-\end{datadesc}
-
-\begin{datadesc}{has_ipv6}
-This constant contains a boolean value which indicates if IPv6 is
-supported on this platform.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{funcdesc}{create_connection}{address\optional{, timeout}}
-Connects to the \var{address} received (as usual, a \code{(host, port)}
-pair), with an optional timeout for the connection. Specially useful for
-higher-level protocols, it is not normally used directly from
-application-level code. Passing the optional \var{timeout} parameter
-will set the timeout on the socket instance (if it is not given or
-\code{None}, the global default timeout setting is used).
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{,
- socktype\optional{, proto\optional{,
- flags}}}}}
-Resolves the \var{host}/\var{port} argument, into a sequence of
-5-tuples that contain all the necessary argument for the sockets
-manipulation. \var{host} is a domain name, a string representation of
-IPv4/v6 address or \code{None}.
-\var{port} is a string service name (like \code{'http'}), a numeric
-port number or \code{None}.
-
-The rest of the arguments are optional and must be numeric if
-specified. For \var{host} and \var{port}, by passing either an empty
-string or \code{None}, you can pass \code{NULL} to the C API. The
-\function{getaddrinfo()} function returns a list of 5-tuples with
-the following structure:
-
-\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
- \var{sockaddr})}
-
-\var{family}, \var{socktype}, \var{proto} are all integer and are meant to
-be passed to the \function{socket()} function.
-\var{canonname} is a string representing the canonical name of the \var{host}.
-It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified
-for a numeric \var{host}.
-\var{sockaddr} is a tuple describing a socket address, as described above.
-See the source for the \refmodule{httplib} and other library modules
-for a typical usage of the function.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{getfqdn}{\optional{name}}
-Return a fully qualified domain name for \var{name}.
-If \var{name} is omitted or empty, it is interpreted as the local
-host. To find the fully qualified name, the hostname returned by
-\function{gethostbyaddr()} is checked, then aliases for the host, if
-available. The first name which includes a period is selected. In
-case no fully qualified domain name is available, the hostname as
-returned by \function{gethostname()} is returned.
-\versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{gethostbyname}{hostname}
-Translate a host name to IPv4 address format. The IPv4 address is
-returned as a string, such as \code{'100.50.200.5'}. If the host name
-is an IPv4 address itself it is returned unchanged. See
-\function{gethostbyname_ex()} for a more complete interface.
-\function{gethostbyname()} does not support IPv6 name resolution, and
-\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
-\end{funcdesc}
-
-\begin{funcdesc}{gethostbyname_ex}{hostname}
-Translate a host name to IPv4 address format, extended interface.
-Return a triple \code{(\var{hostname}, \var{aliaslist},
-\var{ipaddrlist})} where
-\var{hostname} is the primary host name responding to the given
-\var{ip_address}, \var{aliaslist} is a (possibly empty) list of
-alternative host names for the same address, and \var{ipaddrlist} is
-a list of IPv4 addresses for the same interface on the same
-host (often but not always a single address).
-\function{gethostbyname_ex()} does not support IPv6 name resolution, and
-\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
-\end{funcdesc}
-
-\begin{funcdesc}{gethostname}{}
-Return a string containing the hostname of the machine where
-the Python interpreter is currently executing.
-If you want to know the current machine's IP address, you may want to use
-\code{gethostbyname(gethostname())}.
-This operation assumes that there is a valid address-to-host mapping for
-the host, and the assumption does not always hold.
-Note: \function{gethostname()} doesn't always return the fully qualified
-domain name; use \code{getfqdn()}
-(see above).
-\end{funcdesc}
-
-\begin{funcdesc}{gethostbyaddr}{ip_address}
-Return a triple \code{(\var{hostname}, \var{aliaslist},
-\var{ipaddrlist})} where \var{hostname} is the primary host name
-responding to the given \var{ip_address}, \var{aliaslist} is a
-(possibly empty) list of alternative host names for the same address,
-and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface
-on the same host (most likely containing only a single address).
-To find the fully qualified domain name, use the function
-\function{getfqdn()}.
-\function{gethostbyaddr} supports both IPv4 and IPv6.
-\end{funcdesc}
-
-\begin{funcdesc}{getnameinfo}{sockaddr, flags}
-Translate a socket address \var{sockaddr} into a 2-tuple
-\code{(\var{host}, \var{port})}.
-Depending on the settings of \var{flags}, the result can contain a
-fully-qualified domain name or numeric address representation in
-\var{host}. Similarly, \var{port} can contain a string port name or a
-numeric port number.
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{getprotobyname}{protocolname}
-Translate an Internet protocol name (for example, \code{'icmp'}) to a constant
-suitable for passing as the (optional) third argument to the
-\function{socket()} function. This is usually only needed for sockets
-opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
-modes, the correct protocol is chosen automatically if the protocol is
-omitted or zero.
-\end{funcdesc}
-
-\begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}}
-Translate an Internet service name and protocol name to a port number
-for that service. The optional protocol name, if given, should be
-\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
-\end{funcdesc}
-
-\begin{funcdesc}{getservbyport}{port\optional{, protocolname}}
-Translate an Internet port number and protocol name to a service name
-for that service. The optional protocol name, if given, should be
-\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
-\end{funcdesc}
-
-\begin{funcdesc}{socket}{\optional{family\optional{,
- type\optional{, proto}}}}
-Create a new socket using the given address family, socket type and
-protocol number. The address family should be \constant{AF_INET} (the
-default), \constant{AF_INET6} or \constant{AF_UNIX}. The socket type
-should be \constant{SOCK_STREAM} (the default), \constant{SOCK_DGRAM}
-or perhaps one of the other \samp{SOCK_} constants. The protocol
-number is usually zero and may be omitted in that case.
-\end{funcdesc}
-
-\begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}}
-Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is
-the name of a PEM formatted file that contains your private
-key. \var{certfile} is a PEM formatted certificate chain file. On
-success, a new \class{SSLObject} is returned.
-
-\warning{This does not do any certificate verification!}
-\end{funcdesc}
-
-\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}}
-Build a pair of connected socket objects using the given address
-family, socket type, and protocol number. Address family, socket type,
-and protocol number are as for the \function{socket()} function above.
-The default family is \constant{AF_UNIX} if defined on the platform;
-otherwise, the default is \constant{AF_INET}.
-Availability: \UNIX. \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
-Duplicate the file descriptor \var{fd} (an integer as returned by a file
-object's \method{fileno()} method) and build a socket object from the
-result. Address family, socket type and protocol number are as for the
-\function{socket()} function above.
-The file descriptor should refer to a socket, but this is not
-checked --- subsequent operations on the object may fail if the file
-descriptor is invalid. This function is rarely needed, but can be
-used to get or set socket options on a socket passed to a program as
-standard input or output (such as a server started by the \UNIX{} inet
-daemon). The socket is assumed to be in blocking mode.
-Availability: \UNIX.
-\end{funcdesc}
-
-\begin{funcdesc}{ntohl}{x}
-Convert 32-bit positive integers from network to host byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 4-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{ntohs}{x}
-Convert 16-bit positive integers from network to host byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 2-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{htonl}{x}
-Convert 32-bit positive integers from host to network byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 4-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{htons}{x}
-Convert 16-bit positive integers from host to network byte order. On machines
-where the host byte order is the same as network byte order, this is a
-no-op; otherwise, it performs a 2-byte swap operation.
-\end{funcdesc}
-
-\begin{funcdesc}{inet_aton}{ip_string}
-Convert an IPv4 address from dotted-quad string format (for example,
-'123.45.67.89') to 32-bit packed binary format, as a string four
-characters in length. This is useful when conversing with a program
-that uses the standard C library and needs objects of type
-\ctype{struct in_addr}, which is the C type for the 32-bit packed
-binary this function returns.
-
-If the IPv4 address string passed to this function is invalid,
-\exception{socket.error} will be raised. Note that exactly what is
-valid depends on the underlying C implementation of
-\cfunction{inet_aton()}.
-
-\function{inet_aton()} does not support IPv6, and
-\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
-support.
-\end{funcdesc}
-
-\begin{funcdesc}{inet_ntoa}{packed_ip}
-Convert a 32-bit packed IPv4 address (a string four characters in
-length) to its standard dotted-quad string representation (for
-example, '123.45.67.89'). This is useful when conversing with a
-program that uses the standard C library and needs objects of type
-\ctype{struct in_addr}, which is the C type for the 32-bit packed
-binary data this function takes as an argument.
-
-If the string passed to this function is not exactly 4 bytes in
-length, \exception{socket.error} will be raised.
-\function{inet_ntoa()} does not support IPv6, and
-\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
-support.
-\end{funcdesc}
-
-\begin{funcdesc}{inet_pton}{address_family, ip_string}
-Convert an IP address from its family-specific string format to a packed,
-binary format.
-\function{inet_pton()} is useful when a library or network protocol calls for
-an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
-or \ctype{struct in6_addr}.
-
-Supported values for \var{address_family} are currently
-\constant{AF_INET} and \constant{AF_INET6}.
-If the IP address string \var{ip_string} is invalid,
-\exception{socket.error} will be raised. Note that exactly what is valid
-depends on both the value of \var{address_family} and the underlying
-implementation of \cfunction{inet_pton()}.
-
-Availability: \UNIX{} (maybe not all platforms).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{inet_ntop}{address_family, packed_ip}
-Convert a packed IP address (a string of some number of characters) to
-its standard, family-specific string representation (for example,
-\code{'7.10.0.5'} or \code{'5aef:2b::8'})
-\function{inet_ntop()} is useful when a library or network protocol returns
-an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
-or \ctype{struct in6_addr}.
-
-Supported values for \var{address_family} are currently
-\constant{AF_INET} and \constant{AF_INET6}.
-If the string \var{packed_ip} is not the correct length for the
-specified address family, \exception{ValueError} will be raised. A
-\exception{socket.error} is raised for errors from the call to
-\function{inet_ntop()}.
-
-Availability: \UNIX{} (maybe not all platforms).
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getdefaulttimeout}{}
-Return the default timeout in floating seconds for new socket objects.
-A value of \code{None} indicates that new socket objects have no timeout.
-When the socket module is first imported, the default is \code{None}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setdefaulttimeout}{timeout}
-Set the default timeout in floating seconds for new socket objects.
-A value of \code{None} indicates that new socket objects have no timeout.
-When the socket module is first imported, the default is \code{None}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{SocketType}
-This is a Python type object that represents the socket object type.
-It is the same as \code{type(socket(...))}.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{SocketServer}{Classes that simplify writing network servers.}
-\end{seealso}
-
-
-\subsection{Socket Objects \label{socket-objects}}
-
-Socket objects have the following methods. Except for
-\method{makefile()} these correspond to \UNIX{} system calls
-applicable to sockets.
-
-\begin{methoddesc}[socket]{accept}{}
-Accept a connection.
-The socket must be bound to an address and listening for connections.
-The return value is a pair \code{(\var{conn}, \var{address})}
-where \var{conn} is a \emph{new} socket object usable to send and
-receive data on the connection, and \var{address} is the address bound
-to the socket on the other end of the connection.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{bind}{address}
-Bind the socket to \var{address}. The socket must not already be bound.
-(The format of \var{address} depends on the address family --- see
-above.) \note{This method has historically accepted a pair
-of parameters for \constant{AF_INET} addresses instead of only a
-tuple. This was never intentional and is no longer available in
-Python 2.0 and later.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{close}{}
-Close the socket. All future operations on the socket object will fail.
-The remote end will receive no more data (after queued data is flushed).
-Sockets are automatically closed when they are garbage-collected.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{connect}{address}
-Connect to a remote socket at \var{address}.
-(The format of \var{address} depends on the address family --- see
-above.) \note{This method has historically accepted a pair
-of parameters for \constant{AF_INET} addresses instead of only a
-tuple. This was never intentional and is no longer available in
-Python 2.0 and later.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{connect_ex}{address}
-Like \code{connect(\var{address})}, but return an error indicator
-instead of raising an exception for errors returned by the C-level
-\cfunction{connect()} call (other problems, such as ``host not found,''
-can still raise exceptions). The error indicator is \code{0} if the
-operation succeeded, otherwise the value of the \cdata{errno}
-variable. This is useful to support, for example, asynchronous connects.
-\note{This method has historically accepted a pair of
-parameters for \constant{AF_INET} addresses instead of only a tuple.
-This was never intentional and is no longer available in Python
-2.0 and later.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{fileno}{}
-Return the socket's file descriptor (a small integer). This is useful
-with \function{select.select()}.
-
-Under Windows the small integer returned by this method cannot be used where
-a file descriptor can be used (such as \function{os.fdopen()}). \UNIX{} does
-not have this limitation.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{getpeername}{}
-Return the remote address to which the socket is connected. This is
-useful to find out the port number of a remote IPv4/v6 socket, for instance.
-(The format of the address returned depends on the address family ---
-see above.) On some systems this function is not supported.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{getsockname}{}
-Return the socket's own address. This is useful to find out the port
-number of an IPv4/v6 socket, for instance.
-(The format of the address returned depends on the address family ---
-see above.)
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}}
-Return the value of the given socket option (see the \UNIX{} man page
-\manpage{getsockopt}{2}). The needed symbolic constants
-(\constant{SO_*} etc.) are defined in this module. If \var{buflen}
-is absent, an integer option is assumed and its integer value
-is returned by the function. If \var{buflen} is present, it specifies
-the maximum length of the buffer used to receive the option in, and
-this buffer is returned as a string. It is up to the caller to decode
-the contents of the buffer (see the optional built-in module
-\refmodule{struct} for a way to decode C structures encoded as strings).
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{listen}{backlog}
-Listen for connections made to the socket. The \var{backlog} argument
-specifies the maximum number of queued connections and should be at
-least 1; the maximum value is system-dependent (usually 5).
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}}
-Return a \dfn{file object} associated with the socket. (File objects
-are described in \ref{bltin-file-objects}, ``File Objects.'')
-The file object references a \cfunction{dup()}ped version of the
-socket file descriptor, so the file object and socket object may be
-closed or garbage-collected independently.
-The socket must be in blocking mode (it can not have a timeout).
-\index{I/O control!buffering}The optional \var{mode}
-and \var{bufsize} arguments are interpreted the same way as by the
-built-in \function{file()} function; see ``Built-in Functions''
-(section \ref{built-in-funcs}) for more information.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
-Receive data from the socket. The return value is a string representing
-the data received. The maximum amount of data to be received
-at once is specified by \var{bufsize}. See the \UNIX{} manual page
-\manpage{recv}{2} for the meaning of the optional argument
-\var{flags}; it defaults to zero.
-\note{For best match with hardware and network realities, the value of
-\var{bufsize} should be a relatively small power of 2, for example, 4096.}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
-Receive data from the socket. The return value is a pair
-\code{(\var{string}, \var{address})} where \var{string} is a string
-representing the data received and \var{address} is the address of the
-socket sending the data. See the \UNIX{} manual page
-\manpage{recv}{2} for the meaning of the optional argument
-\var{flags}; it defaults to zero.
-(The format of \var{address} depends on the address family --- see above.)
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}}
-Receive data from the socket, writing it into \var{buffer} instead of
-creating a new string. The return value is a pair
-\code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number
-of bytes received and \var{address} is the address of the socket
-sending the data. See the \UNIX{} manual page
-\manpage{recv}{2} for the meaning of the optional argument
-\var{flags}; it defaults to zero. (The format of \var{address}
-depends on the address family --- see above.)
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}}
-Receive up to \var{nbytes} bytes from the socket,
-storing the data into a buffer rather than creating a new string.
-If \var{nbytes} is not specified (or 0),
-receive up to the size available in the given buffer.
-See the \UNIX{} manual page \manpage{recv}{2} for the meaning of the
-optional argument \var{flags}; it defaults to zero.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{send}{string\optional{, flags}}
-Send data to the socket. The socket must be connected to a remote
-socket. The optional \var{flags} argument has the same meaning as for
-\method{recv()} above. Returns the number of bytes sent.
-Applications are responsible for checking that all data has been sent;
-if only some of the data was transmitted, the application needs to
-attempt delivery of the remaining data.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{sendall}{string\optional{, flags}}
-Send data to the socket. The socket must be connected to a remote
-socket. The optional \var{flags} argument has the same meaning as for
-\method{recv()} above. Unlike \method{send()}, this method continues
-to send data from \var{string} until either all data has been sent or
-an error occurs. \code{None} is returned on success. On error, an
-exception is raised, and there is no way to determine how much data,
-if any, was successfully sent.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address}
-Send data to the socket. The socket should not be connected to a
-remote socket, since the destination socket is specified by
-\var{address}. The optional \var{flags} argument has the same
-meaning as for \method{recv()} above. Return the number of bytes sent.
-(The format of \var{address} depends on the address family --- see above.)
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{setblocking}{flag}
-Set blocking or non-blocking mode of the socket: if \var{flag} is 0,
-the socket is set to non-blocking, else to blocking mode. Initially
-all sockets are in blocking mode. In non-blocking mode, if a
-\method{recv()} call doesn't find any data, or if a
-\method{send()} call can't immediately dispose of the data, a
-\exception{error} exception is raised; in blocking mode, the calls
-block until they can proceed.
-\code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)};
-\code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}.
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{settimeout}{value}
-Set a timeout on blocking socket operations. The \var{value} argument
-can be a nonnegative float expressing seconds, or \code{None}.
-If a float is
-given, subsequent socket operations will raise an \exception{timeout}
-exception if the timeout period \var{value} has elapsed before the
-operation has completed. Setting a timeout of \code{None} disables
-timeouts on socket operations.
-\code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)};
-\code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{gettimeout}{}
-Return the timeout in floating seconds associated with socket
-operations, or \code{None} if no timeout is set. This reflects
-the last call to \method{setblocking()} or \method{settimeout()}.
-\versionadded{2.3}
-\end{methoddesc}
-
-Some notes on socket blocking and timeouts: A socket object can be in
-one of three modes: blocking, non-blocking, or timeout. Sockets are
-always created in blocking mode. In blocking mode, operations block
-until complete. In non-blocking mode, operations fail (with an error
-that is unfortunately system-dependent) if they cannot be completed
-immediately. In timeout mode, operations fail if they cannot be
-completed within the timeout specified for the socket. The
-\method{setblocking()} method is simply a shorthand for certain
-\method{settimeout()} calls.
-
-Timeout mode internally sets the socket in non-blocking mode. The
-blocking and timeout modes are shared between file descriptors and
-socket objects that refer to the same network endpoint. A consequence
-of this is that file objects returned by the \method{makefile()}
-method must only be used when the socket is in blocking mode; in
-timeout or non-blocking mode file operations that cannot be completed
-immediately will fail.
-
-Note that the \method{connect()} operation is subject to the timeout
-setting, and in general it is recommended to call
-\method{settimeout()} before calling \method{connect()}.
-
-\begin{methoddesc}[socket]{setsockopt}{level, optname, value}
-Set the value of the given socket option (see the \UNIX{} manual page
-\manpage{setsockopt}{2}). The needed symbolic constants are defined in
-the \module{socket} module (\constant{SO_*} etc.). The value can be an
-integer or a string representing a buffer. In the latter case it is
-up to the caller to ensure that the string contains the proper bits
-(see the optional built-in module
-\refmodule{struct}\refbimodindex{struct} for a way to encode C
-structures as strings).
-\end{methoddesc}
-
-\begin{methoddesc}[socket]{shutdown}{how}
-Shut down one or both halves of the connection. If \var{how} is
-\constant{SHUT_RD}, further receives are disallowed. If \var{how} is \constant{SHUT_WR},
-further sends are disallowed. If \var{how} is \constant{SHUT_RDWR}, further sends
-and receives are disallowed.
-\end{methoddesc}
-
-Note that there are no methods \method{read()} or \method{write()};
-use \method{recv()} and \method{send()} without \var{flags} argument
-instead.
-
-
-Socket objects also have these (read-only) attributes that correspond
-to the values given to the \class{socket} constructor.
-
-\begin{memberdesc}[socket]{family}
-The socket family.
-\versionadded{2.5}
-\end{memberdesc}
-
-\begin{memberdesc}[socket]{type}
-The socket type.
-\versionadded{2.5}
-\end{memberdesc}
-
-\begin{memberdesc}[socket]{proto}
-The socket protocol.
-\versionadded{2.5}
-\end{memberdesc}
-
-
-\subsection{SSL Objects \label{ssl-objects}}
-
-SSL objects have the following methods.
-
-\begin{methoddesc}[SSL]{write}{s}
-Writes the string \var{s} to the on the object's SSL connection.
-The return value is the number of bytes written.
-\end{methoddesc}
-
-\begin{methoddesc}[SSL]{read}{\optional{n}}
-If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise
-read until EOF. The return value is a string of the bytes read.
-\end{methoddesc}
-
-\begin{methoddesc}[SSL]{server}{}
-Returns a string describing the server's certificate.
-Useful for debugging purposes; do not parse the content of this string
-because its format can't be parsed unambiguously.
-\end{methoddesc}
-
-\begin{methoddesc}[SSL]{issuer}{}
-Returns a string describing the issuer of the server's certificate.
-Useful for debugging purposes; do not parse the content of this string
-because its format can't be parsed unambiguously.
-\end{methoddesc}
-
-\subsection{Example \label{socket-example}}
-
-Here are four minimal example programs using the TCP/IP protocol:\ a
-server that echoes all data that it receives back (servicing only one
-client), and a client using it. Note that a server must perform the
-sequence \function{socket()}, \method{bind()}, \method{listen()},
-\method{accept()} (possibly repeating the \method{accept()} to service
-more than one client), while a client only needs the sequence
-\function{socket()}, \method{connect()}. Also note that the server
-does not \method{send()}/\method{recv()} on the
-socket it is listening on but on the new socket returned by
-\method{accept()}.
-
-The first two examples support IPv4 only.
-
-\begin{verbatim}
-# Echo server program
-import socket
-
-HOST = '' # Symbolic name meaning the local host
-PORT = 50007 # Arbitrary non-privileged port
-s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-s.bind((HOST, PORT))
-s.listen(1)
-conn, addr = s.accept()
-print 'Connected by', addr
-while 1:
- data = conn.recv(1024)
- if not data: break
- conn.send(data)
-conn.close()
-\end{verbatim}
-
-\begin{verbatim}
-# Echo client program
-import socket
-
-HOST = 'daring.cwi.nl' # The remote host
-PORT = 50007 # The same port as used by the server
-s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-s.connect((HOST, PORT))
-s.send('Hello, world')
-data = s.recv(1024)
-s.close()
-print 'Received', repr(data)
-\end{verbatim}
-
-The next two examples are identical to the above two, but support both
-IPv4 and IPv6.
-The server side will listen to the first address family available
-(it should listen to both instead).
-On most of IPv6-ready systems, IPv6 will take precedence
-and the server may not accept IPv4 traffic.
-The client side will try to connect to the all addresses returned as a result
-of the name resolution, and sends traffic to the first one connected
-successfully.
-
-\begin{verbatim}
-# Echo server program
-import socket
-import sys
-
-HOST = '' # Symbolic name meaning the local host
-PORT = 50007 # Arbitrary non-privileged port
-s = None
-for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
- af, socktype, proto, canonname, sa = res
- try:
- s = socket.socket(af, socktype, proto)
- except socket.error as msg:
- s = None
- continue
- try:
- s.bind(sa)
- s.listen(1)
- except socket.error as msg:
- s.close()
- s = None
- continue
- break
-if s is None:
- print 'could not open socket'
- sys.exit(1)
-conn, addr = s.accept()
-print 'Connected by', addr
-while 1:
- data = conn.recv(1024)
- if not data: break
- conn.send(data)
-conn.close()
-\end{verbatim}
-
-\begin{verbatim}
-# Echo client program
-import socket
-import sys
-
-HOST = 'daring.cwi.nl' # The remote host
-PORT = 50007 # The same port as used by the server
-s = None
-for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
- af, socktype, proto, canonname, sa = res
- try:
- s = socket.socket(af, socktype, proto)
- except socket.error as msg:
- s = None
- continue
- try:
- s.connect(sa)
- except socket.error as msg:
- s.close()
- s = None
- continue
- break
-if s is None:
- print 'could not open socket'
- sys.exit(1)
-s.send('Hello, world')
-data = s.recv(1024)
-s.close()
-print 'Received', repr(data)
-\end{verbatim}
-
-This example connects to an SSL server, prints the
-server and issuer's distinguished names, sends some bytes,
-and reads part of the response:
-
-\begin{verbatim}
-import socket
-
-s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-s.connect(('www.verisign.com', 443))
-
-ssl_sock = socket.ssl(s)
-
-print repr(ssl_sock.server())
-print repr(ssl_sock.issuer())
-
-# Set a simple HTTP request -- use httplib in actual code.
-ssl_sock.write("""GET / HTTP/1.0\r
-Host: www.verisign.com\r\n\r\n""")
-
-# Read a chunk of data. Will not necessarily
-# read all the data returned by the server.
-data = ssl_sock.read()
-
-# Note that you need to close the underlying socket, not the SSL object.
-del ssl_sock
-s.close()
-\end{verbatim}
-
-At this writing, this SSL example prints the following output (line
-breaks inserted for readability):
-
-\begin{verbatim}
-'/C=US/ST=California/L=Mountain View/
- O=VeriSign, Inc./OU=Production Services/
- OU=Terms of use at www.verisign.com/rpa (c)00/
- CN=www.verisign.com'
-'/O=VeriSign Trust Network/OU=VeriSign, Inc./
- OU=VeriSign International Server CA - Class 3/
- OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
-\end{verbatim}
diff --git a/Doc/lib/libsocksvr.tex b/Doc/lib/libsocksvr.tex
deleted file mode 100644
index c7b28ea..0000000
--- a/Doc/lib/libsocksvr.tex
+++ /dev/null
@@ -1,293 +0,0 @@
-\section{\module{SocketServer} ---
- A framework for network servers}
-
-\declaremodule{standard}{SocketServer}
-\modulesynopsis{A framework for network servers.}
-
-
-The \module{SocketServer} module simplifies the task of writing network
-servers.
-
-There are four basic server classes: \class{TCPServer} uses the
-Internet TCP protocol, which provides for continuous streams of data
-between the client and server. \class{UDPServer} uses datagrams, which
-are discrete packets of information that may arrive out of order or be
-lost while in transit. The more infrequently used
-\class{UnixStreamServer} and \class{UnixDatagramServer} classes are
-similar, but use \UNIX{} domain sockets; they're not available on
-non-\UNIX{} platforms. For more details on network programming, consult
-a book such as W. Richard Steven's \citetitle{UNIX Network Programming}
-or Ralph Davis's \citetitle{Win32 Network Programming}.
-
-These four classes process requests \dfn{synchronously}; each request
-must be completed before the next request can be started. This isn't
-suitable if each request takes a long time to complete, because it
-requires a lot of computation, or because it returns a lot of data
-which the client is slow to process. The solution is to create a
-separate process or thread to handle each request; the
-\class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes can be
-used to support asynchronous behaviour.
-
-Creating a server requires several steps. First, you must create a
-request handler class by subclassing the \class{BaseRequestHandler}
-class and overriding its \method{handle()} method; this method will
-process incoming requests. Second, you must instantiate one of the
-server classes, passing it the server's address and the request
-handler class. Finally, call the \method{handle_request()} or
-\method{serve_forever()} method of the server object to process one or
-many requests.
-
-When inheriting from \class{ThreadingMixIn} for threaded connection
-behavior, you should explicitly declare how you want your threads
-to behave on an abrupt shutdown. The \class{ThreadingMixIn} class
-defines an attribute \var{daemon_threads}, which indicates whether
-or not the server should wait for thread termination. You should
-set the flag explicitly if you would like threads to behave
-autonomously; the default is \constant{False}, meaning that Python
-will not exit until all threads created by \class{ThreadingMixIn} have
-exited.
-
-Server classes have the same external methods and attributes, no
-matter what network protocol they use:
-
-\setindexsubitem{(SocketServer protocol)}
-
-\subsection{Server Creation Notes}
-
-There are five classes in an inheritance diagram, four of which represent
-synchronous servers of four types:
-
-\begin{verbatim}
- +------------+
- | BaseServer |
- +------------+
- |
- v
- +-----------+ +------------------+
- | TCPServer |------->| UnixStreamServer |
- +-----------+ +------------------+
- |
- v
- +-----------+ +--------------------+
- | UDPServer |------->| UnixDatagramServer |
- +-----------+ +--------------------+
-\end{verbatim}
-
-Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not
-from \class{UnixStreamServer} --- the only difference between an IP and a
-\UNIX{} stream server is the address family, which is simply repeated in both
-\UNIX{} server classes.
-
-Forking and threading versions of each type of server can be created using
-the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For
-instance, a threading UDP server class is created as follows:
-
-\begin{verbatim}
- class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass
-\end{verbatim}
-
-The mix-in class must come first, since it overrides a method defined in
-\class{UDPServer}. Setting the various member variables also changes the
-behavior of the underlying server mechanism.
-
-To implement a service, you must derive a class from
-\class{BaseRequestHandler} and redefine its \method{handle()} method. You
-can then run various versions of the service by combining one of the server
-classes with your request handler class. The request handler class must be
-different for datagram or stream services. This can be hidden by using the
-handler subclasses \class{StreamRequestHandler} or \class{DatagramRequestHandler}.
-
-Of course, you still have to use your head! For instance, it makes no sense
-to use a forking server if the service contains state in memory that can be
-modified by different requests, since the modifications in the child process
-would never reach the initial state kept in the parent process and passed to
-each child. In this case, you can use a threading server, but you will
-probably have to use locks to protect the integrity of the shared data.
-
-On the other hand, if you are building an HTTP server where all data is
-stored externally (for instance, in the file system), a synchronous class
-will essentially render the service "deaf" while one request is being
-handled -- which may be for a very long time if a client is slow to receive
-all the data it has requested. Here a threading or forking server is
-appropriate.
-
-In some cases, it may be appropriate to process part of a request
-synchronously, but to finish processing in a forked child depending on the
-request data. This can be implemented by using a synchronous server and
-doing an explicit fork in the request handler class \method{handle()}
-method.
-
-Another approach to handling multiple simultaneous requests in an
-environment that supports neither threads nor \function{fork()} (or where
-these are too expensive or inappropriate for the service) is to maintain an
-explicit table of partially finished requests and to use \function{select()}
-to decide which request to work on next (or whether to handle a new incoming
-request). This is particularly important for stream services where each
-client can potentially be connected for a long time (if threads or
-subprocesses cannot be used).
-
-%XXX should data and methods be intermingled, or separate?
-% how should the distinction between class and instance variables be
-% drawn?
-
-\subsection{Server Objects}
-
-\begin{funcdesc}{fileno}{}
-Return an integer file descriptor for the socket on which the server
-is listening. This function is most commonly passed to
-\function{select.select()}, to allow monitoring multiple servers in the
-same process.
-\end{funcdesc}
-
-\begin{funcdesc}{handle_request}{}
-Process a single request. This function calls the following methods
-in order: \method{get_request()}, \method{verify_request()}, and
-\method{process_request()}. If the user-provided \method{handle()}
-method of the handler class raises an exception, the server's
-\method{handle_error()} method will be called.
-\end{funcdesc}
-
-\begin{funcdesc}{serve_forever}{}
-Handle an infinite number of requests. This simply calls
-\method{handle_request()} inside an infinite loop.
-\end{funcdesc}
-
-\begin{datadesc}{address_family}
-The family of protocols to which the server's socket belongs.
-\constant{socket.AF_INET} and \constant{socket.AF_UNIX} are two
-possible values.
-\end{datadesc}
-
-\begin{datadesc}{RequestHandlerClass}
-The user-provided request handler class; an instance of this class is
-created for each request.
-\end{datadesc}
-
-\begin{datadesc}{server_address}
-The address on which the server is listening. The format of addresses
-varies depending on the protocol family; see the documentation for the
-socket module for details. For Internet protocols, this is a tuple
-containing a string giving the address, and an integer port number:
-\code{('127.0.0.1', 80)}, for example.
-\end{datadesc}
-
-\begin{datadesc}{socket}
-The socket object on which the server will listen for incoming requests.
-\end{datadesc}
-
-% XXX should class variables be covered before instance variables, or
-% vice versa?
-
-The server classes support the following class variables:
-
-\begin{datadesc}{allow_reuse_address}
-Whether the server will allow the reuse of an address. This defaults
-to \constant{False}, and can be set in subclasses to change the policy.
-\end{datadesc}
-
-\begin{datadesc}{request_queue_size}
-The size of the request queue. If it takes a long time to process a
-single request, any requests that arrive while the server is busy are
-placed into a queue, up to \member{request_queue_size} requests. Once
-the queue is full, further requests from clients will get a
-``Connection denied'' error. The default value is usually 5, but this
-can be overridden by subclasses.
-\end{datadesc}
-
-\begin{datadesc}{socket_type}
-The type of socket used by the server; \constant{socket.SOCK_STREAM}
-and \constant{socket.SOCK_DGRAM} are two possible values.
-\end{datadesc}
-
-There are various server methods that can be overridden by subclasses
-of base server classes like \class{TCPServer}; these methods aren't
-useful to external users of the server object.
-
-% should the default implementations of these be documented, or should
-% it be assumed that the user will look at SocketServer.py?
-
-\begin{funcdesc}{finish_request}{}
-Actually processes the request by instantiating
-\member{RequestHandlerClass} and calling its \method{handle()} method.
-\end{funcdesc}
-
-\begin{funcdesc}{get_request}{}
-Must accept a request from the socket, and return a 2-tuple containing
-the \emph{new} socket object to be used to communicate with the
-client, and the client's address.
-\end{funcdesc}
-
-\begin{funcdesc}{handle_error}{request, client_address}
-This function is called if the \member{RequestHandlerClass}'s
-\method{handle()} method raises an exception. The default action is
-to print the traceback to standard output and continue handling
-further requests.
-\end{funcdesc}
-
-\begin{funcdesc}{process_request}{request, client_address}
-Calls \method{finish_request()} to create an instance of the
-\member{RequestHandlerClass}. If desired, this function can create a
-new process or thread to handle the request; the \class{ForkingMixIn}
-and \class{ThreadingMixIn} classes do this.
-\end{funcdesc}
-
-% Is there any point in documenting the following two functions?
-% What would the purpose of overriding them be: initializing server
-% instance variables, adding new network families?
-
-\begin{funcdesc}{server_activate}{}
-Called by the server's constructor to activate the server. The default
-behavior just \method{listen}s to the server's socket.
-May be overridden.
-\end{funcdesc}
-
-\begin{funcdesc}{server_bind}{}
-Called by the server's constructor to bind the socket to the desired
-address. May be overridden.
-\end{funcdesc}
-
-\begin{funcdesc}{verify_request}{request, client_address}
-Must return a Boolean value; if the value is \constant{True}, the request will be
-processed, and if it's \constant{False}, the request will be denied.
-This function can be overridden to implement access controls for a server.
-The default implementation always returns \constant{True}.
-\end{funcdesc}
-
-\subsection{RequestHandler Objects}
-
-The request handler class must define a new \method{handle()} method,
-and can override any of the following methods. A new instance is
-created for each request.
-
-\begin{funcdesc}{finish}{}
-Called after the \method{handle()} method to perform any clean-up
-actions required. The default implementation does nothing. If
-\method{setup()} or \method{handle()} raise an exception, this
-function will not be called.
-\end{funcdesc}
-
-\begin{funcdesc}{handle}{}
-This function must do all the work required to service a request.
-The default implementation does nothing.
-Several instance attributes are available to it; the request is
-available as \member{self.request}; the client address as
-\member{self.client_address}; and the server instance as
-\member{self.server}, in case it needs access to per-server
-information.
-
-The type of \member{self.request} is different for datagram or stream
-services. For stream services, \member{self.request} is a socket
-object; for datagram services, \member{self.request} is a string.
-However, this can be hidden by using the request handler subclasses
-\class{StreamRequestHandler} or \class{DatagramRequestHandler}, which
-override the \method{setup()} and \method{finish()} methods, and
-provide \member{self.rfile} and \member{self.wfile} attributes.
-\member{self.rfile} and \member{self.wfile} can be read or written,
-respectively, to get the request data or return data to the client.
-\end{funcdesc}
-
-\begin{funcdesc}{setup}{}
-Called before the \method{handle()} method to perform any
-initialization actions required. The default implementation does
-nothing.
-\end{funcdesc}
diff --git a/Doc/lib/libsomeos.tex b/Doc/lib/libsomeos.tex
deleted file mode 100644
index 680c590..0000000
--- a/Doc/lib/libsomeos.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{Optional Operating System Services}
-\label{someos}
-
-The modules described in this chapter provide interfaces to operating
-system features that are available on selected operating systems only.
-The interfaces are generally modeled after the \UNIX{} or \C{}
-interfaces but they are available on some other systems as well
-(e.g. Windows or NT). Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/libspwd.tex b/Doc/lib/libspwd.tex
deleted file mode 100644
index 5f0e6f1..0000000
--- a/Doc/lib/libspwd.tex
+++ /dev/null
@@ -1,48 +0,0 @@
-\section{\module{spwd} ---
- The shadow password database}
-
-\declaremodule{builtin}{spwd}
- \platform{Unix}
-\modulesynopsis{The shadow password database (\function{getspnam()} and friends).}
-\versionadded{2.5}
-
-This module provides access to the \UNIX{} shadow password database.
-It is available on various \UNIX{} versions.
-
-You must have enough privileges to access the shadow password database
-(this usually means you have to be root).
-
-Shadow password database entries are reported as a tuple-like object, whose
-attributes correspond to the members of the \code{spwd} structure
-(Attribute field below, see \code{<shadow.h>}):
-
-\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning}
- \lineiii{0}{\code{sp_nam}}{Login name}
- \lineiii{1}{\code{sp_pwd}}{Encrypted password}
- \lineiii{2}{\code{sp_lstchg}}{Date of last change}
- \lineiii{3}{\code{sp_min}}{Minimal number of days between changes}
- \lineiii{4}{\code{sp_max}}{Maximum number of days between changes}
- \lineiii{5}{\code{sp_warn}}{Number of days before password expires to warn user about it}
- \lineiii{6}{\code{sp_inact}}{Number of days after password expires until account is blocked}
- \lineiii{7}{\code{sp_expire}}{Number of days since 1970-01-01 until account is disabled}
- \lineiii{8}{\code{sp_flag}}{Reserved}
-\end{tableiii}
-
-The sp_nam and sp_pwd items are strings, all others are integers.
-\exception{KeyError} is raised if the entry asked for cannot be found.
-
-It defines the following items:
-
-\begin{funcdesc}{getspnam}{name}
-Return the shadow password database entry for the given user name.
-\end{funcdesc}
-
-\begin{funcdesc}{getspall}{}
-Return a list of all available shadow password database entries, in arbitrary order.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{grp}{An interface to the group database, similar to this.}
- \seemodule{pwd}{An interface to the normal password database, similar to this.}
-\end{seealso}
diff --git a/Doc/lib/libsqlite3.tex b/Doc/lib/libsqlite3.tex
deleted file mode 100644
index a7a0e94..0000000
--- a/Doc/lib/libsqlite3.tex
+++ /dev/null
@@ -1,648 +0,0 @@
-\section{\module{sqlite3} ---
- DB-API 2.0 interface for SQLite databases}
-
-\declaremodule{builtin}{sqlite3}
-\modulesynopsis{A DB-API 2.0 implementation using SQLite 3.x.}
-\sectionauthor{Gerhard Häring}{gh@ghaering.de}
-\versionadded{2.5}
-
-SQLite is a C library that provides a lightweight disk-based database
-that doesn't require a separate server process and allows accessing
-the database using a nonstandard variant of the SQL query language.
-Some applications can use SQLite for internal data storage. It's also
-possible to prototype an application using SQLite and then port the
-code to a larger database such as PostgreSQL or Oracle.
-
-pysqlite was written by Gerhard H\"aring and provides a SQL interface
-compliant with the DB-API 2.0 specification described by
-\pep{249}.
-
-To use the module, you must first create a \class{Connection} object
-that represents the database. Here the data will be stored in the
-\file{/tmp/example} file:
-
-\begin{verbatim}
-conn = sqlite3.connect('/tmp/example')
-\end{verbatim}
-
-You can also supply the special name \samp{:memory:} to create
-a database in RAM.
-
-Once you have a \class{Connection}, you can create a \class{Cursor}
-object and call its \method{execute()} method to perform SQL commands:
-
-\begin{verbatim}
-c = conn.cursor()
-
-# Create table
-c.execute('''create table stocks
-(date text, trans text, symbol text,
- qty real, price real)''')
-
-# Insert a row of data
-c.execute("""insert into stocks
- values ('2006-01-05','BUY','RHAT',100,35.14)""")
-
-# Save (commit) the changes
-conn.commit()
-
-# We can also close the cursor if we are done with it
-c.close()
-\end{verbatim}
-
-Usually your SQL operations will need to use values from Python
-variables. You shouldn't assemble your query using Python's string
-operations because doing so is insecure; it makes your program
-vulnerable to an SQL injection attack.
-
-Instead, use the DB-API's parameter substitution. Put \samp{?} as a
-placeholder wherever you want to use a value, and then provide a tuple
-of values as the second argument to the cursor's \method{execute()}
-method. (Other database modules may use a different placeholder,
-such as \samp{\%s} or \samp{:1}.) For example:
-
-\begin{verbatim}
-# Never do this -- insecure!
-symbol = 'IBM'
-c.execute("... where symbol = '%s'" % symbol)
-
-# Do this instead
-t = (symbol,)
-c.execute('select * from stocks where symbol=?', t)
-
-# Larger example
-for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
- ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
- ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
- ):
- c.execute('insert into stocks values (?,?,?,?,?)', t)
-\end{verbatim}
-
-To retrieve data after executing a SELECT statement, you can either
-treat the cursor as an iterator, call the cursor's \method{fetchone()}
-method to retrieve a single matching row,
-or call \method{fetchall()} to get a list of the matching rows.
-
-This example uses the iterator form:
-
-\begin{verbatim}
->>> c = conn.cursor()
->>> c.execute('select * from stocks order by price')
->>> for row in c:
-... print row
-...
-(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001)
-(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
-(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
-(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0)
->>>
-\end{verbatim}
-
-\begin{seealso}
-
-\seeurl{http://www.pysqlite.org}
-{The pysqlite web page.}
-
-\seeurl{http://www.sqlite.org}
-{The SQLite web page; the documentation describes the syntax and the
-available data types for the supported SQL dialect.}
-
-\seepep{249}{Database API Specification 2.0}{PEP written by
-Marc-Andr\'e Lemburg.}
-
-\end{seealso}
-
-
-\subsection{Module functions and constants\label{sqlite3-Module-Contents}}
-
-\begin{datadesc}{PARSE_DECLTYPES}
-This constant is meant to be used with the \var{detect_types} parameter of the
-\function{connect} function.
-
-Setting it makes the \module{sqlite3} module parse the declared type for each column it
-returns. It will parse out the first word of the declared type, i. e. for
-"integer primary key", it will parse out "integer". Then for that column, it
-will look into the converters dictionary and use the converter function
-registered for that type there. Converter names are case-sensitive!
-\end{datadesc}
-
-
-\begin{datadesc}{PARSE_COLNAMES}
-This constant is meant to be used with the \var{detect_types} parameter of the
-\function{connect} function.
-
-Setting this makes the SQLite interface parse the column name for each column
-it returns. It will look for a string formed [mytype] in there, and then
-decide that 'mytype' is the type of the column. It will try to find an entry of
-'mytype' in the converters dictionary and then use the converter function found
-there to return the value. The column name found in \member{cursor.description} is only
-the first word of the column name, i. e. if you use something like
-\code{'as "x [datetime]"'} in your SQL, then we will parse out everything until the
-first blank for the column name: the column name would simply be "x".
-\end{datadesc}
-
-\begin{funcdesc}{connect}{database\optional{, timeout, isolation_level, detect_types, factory}}
-Opens a connection to the SQLite database file \var{database}. You can use
-\code{":memory:"} to open a database connection to a database that resides in
-RAM instead of on disk.
-
-When a database is accessed by multiple connections, and one of the processes
-modifies the database, the SQLite database is locked until that transaction is
-committed. The \var{timeout} parameter specifies how long the connection should
-wait for the lock to go away until raising an exception. The default for the
-timeout parameter is 5.0 (five seconds).
-
-For the \var{isolation_level} parameter, please see the \member{isolation_level}
-property of \class{Connection} objects in section~\ref{sqlite3-Connection-IsolationLevel}.
-
-SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If
-you want to use other types you must add support for them yourself.
-The \var{detect_types} parameter and the using custom \strong{converters} registered with
-the module-level \function{register_converter} function allow you to easily do that.
-
-\var{detect_types} defaults to 0 (i. e. off, no type detection), you can set it
-to any combination of \constant{PARSE_DECLTYPES} and \constant{PARSE_COLNAMES} to turn type
-detection on.
-
-By default, the \module{sqlite3} module uses its \class{Connection} class for the
-connect call. You can, however, subclass the \class{Connection} class and make
-\function{connect} use your class instead by providing your class for the
-\var{factory} parameter.
-
-Consult the section \ref{sqlite3-Types} of this manual for details.
-
-The \module{sqlite3} module internally uses a statement cache to avoid SQL parsing
-overhead. If you want to explicitly set the number of statements that are
-cached for the connection, you can set the \var{cached_statements} parameter.
-The currently implemented default is to cache 100 statements.
-\end{funcdesc}
-
-\begin{funcdesc}{register_converter}{typename, callable}
-Registers a callable to convert a bytestring from the database into a custom
-Python type. The callable will be invoked for all database values that are of
-the type \var{typename}. Confer the parameter \var{detect_types} of the
-\function{connect} function for how the type detection works. Note that the case of
-\var{typename} and the name of the type in your query must match!
-\end{funcdesc}
-
-\begin{funcdesc}{register_adapter}{type, callable}
-Registers a callable to convert the custom Python type \var{type} into one of
-SQLite's supported types. The callable \var{callable} accepts as single
-parameter the Python value, and must return a value of the following types:
-int, long, float, str (UTF-8 encoded), unicode or buffer.
-\end{funcdesc}
-
-\begin{funcdesc}{complete_statement}{sql}
-Returns \constant{True} if the string \var{sql} contains one or more complete SQL
-statements terminated by semicolons. It does not verify that the SQL is
-syntactically correct, only that there are no unclosed string literals and the
-statement is terminated by a semicolon.
-
-This can be used to build a shell for SQLite, as in the following example:
-
- \verbatiminput{sqlite3/complete_statement.py}
-\end{funcdesc}
-
-\begin{funcdesc}{enable_callback_tracebacks}{flag}
-By default you will not get any tracebacks in user-defined functions,
-aggregates, converters, authorizer callbacks etc. If you want to debug them,
-you can call this function with \var{flag} as True. Afterwards, you will get
-tracebacks from callbacks on \code{sys.stderr}. Use \constant{False} to disable
-the feature again.
-\end{funcdesc}
-
-\subsection{Connection Objects \label{sqlite3-Connection-Objects}}
-
-A \class{Connection} instance has the following attributes and methods:
-
-\label{sqlite3-Connection-IsolationLevel}
-\begin{memberdesc}[Connection]{isolation_level}
- Get or set the current isolation level. None for autocommit mode or one of
- "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See ``Controlling Transactions'',
- section~\ref{sqlite3-Controlling-Transactions}, for a more detailed explanation.
-\end{memberdesc}
-
-\begin{methoddesc}[Connection]{cursor}{\optional{cursorClass}}
- The cursor method accepts a single optional parameter \var{cursorClass}.
- If supplied, this must be a custom cursor class that extends
- \class{sqlite3.Cursor}.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{execute}{sql, \optional{parameters}}
-This is a nonstandard shortcut that creates an intermediate cursor object by
-calling the cursor method, then calls the cursor's \method{execute} method with the
-parameters given.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{executemany}{sql, \optional{parameters}}
-This is a nonstandard shortcut that creates an intermediate cursor object by
-calling the cursor method, then calls the cursor's \method{executemany} method with the
-parameters given.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{executescript}{sql_script}
-This is a nonstandard shortcut that creates an intermediate cursor object by
-calling the cursor method, then calls the cursor's \method{executescript} method with the
-parameters given.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{create_function}{name, num_params, func}
-
-Creates a user-defined function that you can later use from within SQL
-statements under the function name \var{name}. \var{num_params} is the number
-of parameters the function accepts, and \var{func} is a Python callable that is
-called as the SQL function.
-
-The function can return any of the types supported by SQLite: unicode, str,
-int, long, float, buffer and None.
-
-Example:
-
- \verbatiminput{sqlite3/md5func.py}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{create_aggregate}{name, num_params, aggregate_class}
-
-Creates a user-defined aggregate function.
-
-The aggregate class must implement a \code{step} method, which accepts the
-number of parameters \var{num_params}, and a \code{finalize} method which
-will return the final result of the aggregate.
-
-The \code{finalize} method can return any of the types supported by SQLite:
-unicode, str, int, long, float, buffer and None.
-
-Example:
-
- \verbatiminput{sqlite3/mysumaggr.py}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{create_collation}{name, callable}
-
-Creates a collation with the specified \var{name} and \var{callable}. The
-callable will be passed two string arguments. It should return -1 if the first
-is ordered lower than the second, 0 if they are ordered equal and 1 if the
-first is ordered higher than the second. Note that this controls sorting
-(ORDER BY in SQL) so your comparisons don't affect other SQL operations.
-
-Note that the callable will get its parameters as Python bytestrings, which
-will normally be encoded in UTF-8.
-
-The following example shows a custom collation that sorts "the wrong way":
-
- \verbatiminput{sqlite3/collation_reverse.py}
-
-To remove a collation, call \code{create_collation} with None as callable:
-
-\begin{verbatim}
- con.create_collation("reverse", None)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{interrupt}{}
-
-You can call this method from a different thread to abort any queries that
-might be executing on the connection. The query will then abort and the caller
-will get an exception.
-\end{methoddesc}
-
-\begin{methoddesc}[Connection]{set_authorizer}{authorizer_callback}
-
-This routine registers a callback. The callback is invoked for each attempt to
-access a column of a table in the database. The callback should return
-\constant{SQLITE_OK} if access is allowed, \constant{SQLITE_DENY} if the entire
-SQL statement should be aborted with an error and \constant{SQLITE_IGNORE} if
-the column should be treated as a NULL value. These constants are available in
-the \module{sqlite3} module.
-
-The first argument to the callback signifies what kind of operation is to be
-authorized. The second and third argument will be arguments or \constant{None}
-depending on the first argument. The 4th argument is the name of the database
-("main", "temp", etc.) if applicable. The 5th argument is the name of the
-inner-most trigger or view that is responsible for the access attempt or
-\constant{None} if this access attempt is directly from input SQL code.
-
-Please consult the SQLite documentation about the possible values for the first
-argument and the meaning of the second and third argument depending on the
-first one. All necessary constants are available in the \module{sqlite3}
-module.
-\end{methoddesc}
-
-\begin{memberdesc}[Connection]{row_factory}
- You can change this attribute to a callable that accepts the cursor and
- the original row as a tuple and will return the real result row. This
- way, you can implement more advanced ways of returning results, such
- as returning an object that can also access columns by name.
-
- Example:
-
- \verbatiminput{sqlite3/row_factory.py}
-
- If returning a tuple doesn't suffice and you want name-based
- access to columns, you should consider setting \member{row_factory} to the
- highly-optimized \class{sqlite3.Row} type. \class{Row} provides both
- index-based and case-insensitive name-based access to columns with almost
- no memory overhead. It will probably be better than your own custom
- dictionary-based approach or even a db_row based solution.
- % XXX what's a db_row-based solution?
-\end{memberdesc}
-
-\begin{memberdesc}[Connection]{text_factory}
- Using this attribute you can control what objects are returned for the
- TEXT data type. By default, this attribute is set to \class{unicode} and
- the \module{sqlite3} module will return Unicode objects for TEXT. If you want to return
- bytestrings instead, you can set it to \class{str}.
-
- For efficiency reasons, there's also a way to return Unicode objects only
- for non-ASCII data, and bytestrings otherwise. To activate it, set this
- attribute to \constant{sqlite3.OptimizedUnicode}.
-
- You can also set it to any other callable that accepts a single bytestring
- parameter and returns the resulting object.
-
- See the following example code for illustration:
-
- \verbatiminput{sqlite3/text_factory.py}
-\end{memberdesc}
-
-\begin{memberdesc}[Connection]{total_changes}
- Returns the total number of database rows that have been modified, inserted,
- or deleted since the database connection was opened.
-\end{memberdesc}
-
-
-
-
-
-\subsection{Cursor Objects \label{sqlite3-Cursor-Objects}}
-
-A \class{Cursor} instance has the following attributes and methods:
-
-\begin{methoddesc}[Cursor]{execute}{sql, \optional{parameters}}
-
-Executes a SQL statement. The SQL statement may be parametrized (i. e.
-placeholders instead of SQL literals). The \module{sqlite3} module supports two kinds of
-placeholders: question marks (qmark style) and named placeholders (named
-style).
-
-This example shows how to use parameters with qmark style:
-
- \verbatiminput{sqlite3/execute_1.py}
-
-This example shows how to use the named style:
-
- \verbatiminput{sqlite3/execute_2.py}
-
- \method{execute()} will only execute a single SQL statement. If you try to
- execute more than one statement with it, it will raise a Warning. Use
- \method{executescript()} if you want to execute multiple SQL statements with one
- call.
-\end{methoddesc}
-
-
-\begin{methoddesc}[Cursor]{executemany}{sql, seq_of_parameters}
-Executes a SQL command against all parameter sequences or mappings found in the
-sequence \var{sql}. The \module{sqlite3} module also allows
-using an iterator yielding parameters instead of a sequence.
-
-\verbatiminput{sqlite3/executemany_1.py}
-
-Here's a shorter example using a generator:
-
-\verbatiminput{sqlite3/executemany_2.py}
-\end{methoddesc}
-
-\begin{methoddesc}[Cursor]{executescript}{sql_script}
-
-This is a nonstandard convenience method for executing multiple SQL statements
-at once. It issues a COMMIT statement first, then executes the SQL script it
-gets as a parameter.
-
-\var{sql_script} can be a bytestring or a Unicode string.
-
-Example:
-
-\verbatiminput{sqlite3/executescript.py}
-\end{methoddesc}
-
-\begin{memberdesc}[Cursor]{rowcount}
- Although the \class{Cursor} class of the \module{sqlite3} module implements this
- attribute, the database engine's own support for the determination of "rows
- affected"/"rows selected" is quirky.
-
- For \code{SELECT} statements, \member{rowcount} is always None because we cannot
- determine the number of rows a query produced until all rows were fetched.
-
- For \code{DELETE} statements, SQLite reports \member{rowcount} as 0 if you make a
- \code{DELETE FROM table} without any condition.
-
- For \method{executemany} statements, the number of modifications are summed
- up into \member{rowcount}.
-
- As required by the Python DB API Spec, the \member{rowcount} attribute "is -1
- in case no executeXX() has been performed on the cursor or the rowcount
- of the last operation is not determinable by the interface".
-\end{memberdesc}
-
-\subsection{SQLite and Python types\label{sqlite3-Types}}
-
-\subsubsection{Introduction}
-
-SQLite natively supports the following types: NULL, INTEGER, REAL, TEXT, BLOB.
-
-The following Python types can thus be sent to SQLite without any problem:
-
-\begin{tableii} {c|l}{code}{Python type}{SQLite type}
-\lineii{None}{NULL}
-\lineii{int}{INTEGER}
-\lineii{long}{INTEGER}
-\lineii{float}{REAL}
-\lineii{str (UTF8-encoded)}{TEXT}
-\lineii{unicode}{TEXT}
-\lineii{buffer}{BLOB}
-\end{tableii}
-
-This is how SQLite types are converted to Python types by default:
-
-\begin{tableii} {c|l}{code}{SQLite type}{Python type}
-\lineii{NULL}{None}
-\lineii{INTEGER}{int or long, depending on size}
-\lineii{REAL}{float}
-\lineii{TEXT}{depends on text_factory, unicode by default}
-\lineii{BLOB}{buffer}
-\end{tableii}
-
-The type system of the \module{sqlite3} module is extensible in two ways: you can store
-additional Python types in a SQLite database via object adaptation, and you can
-let the \module{sqlite3} module convert SQLite types to different Python types via
-converters.
-
-\subsubsection{Using adapters to store additional Python types in SQLite databases}
-
-As described before, SQLite supports only a limited set of types natively. To
-use other Python types with SQLite, you must \strong{adapt} them to one of the sqlite3
-module's supported types for SQLite: one of NoneType, int, long, float,
-str, unicode, buffer.
-
-The \module{sqlite3} module uses Python object adaptation, as described in \pep{246} for this. The protocol to use is \class{PrepareProtocol}.
-
-There are two ways to enable the \module{sqlite3} module to adapt a custom Python type
-to one of the supported ones.
-
-\paragraph{Letting your object adapt itself}
-
-This is a good approach if you write the class yourself. Let's suppose you have
-a class like this:
-
-\begin{verbatim}
-class Point(object):
- def __init__(self, x, y):
- self.x, self.y = x, y
-\end{verbatim}
-
-Now you want to store the point in a single SQLite column. First you'll have to
-choose one of the supported types first to be used for representing the point.
-Let's just use str and separate the coordinates using a semicolon. Then you
-need to give your class a method \code{__conform__(self, protocol)} which must
-return the converted value. The parameter \var{protocol} will be
-\class{PrepareProtocol}.
-
-\verbatiminput{sqlite3/adapter_point_1.py}
-
-\paragraph{Registering an adapter callable}
-
-The other possibility is to create a function that converts the type to the
-string representation and register the function with \method{register_adapter}.
-
-\begin{notice}
-The type/class to adapt must be a new-style class, i. e. it must have
-\class{object} as one of its bases.
-\end{notice}
-
- \verbatiminput{sqlite3/adapter_point_2.py}
-
-The \module{sqlite3} module has two default adapters for Python's built-in
-\class{datetime.date} and \class{datetime.datetime} types. Now let's suppose
-we want to store \class{datetime.datetime} objects not in ISO representation,
-but as a \UNIX{} timestamp.
-
- \verbatiminput{sqlite3/adapter_datetime.py}
-
-\subsubsection{Converting SQLite values to custom Python types}
-
-Writing an adapter lets you send custom Python types to SQLite.
-But to make it really useful we need to make the Python to SQLite to Python
-roundtrip work.
-
-Enter converters.
-
-Let's go back to the \class{Point} class. We stored the x and y
-coordinates separated via semicolons as strings in SQLite.
-
-First, we'll define a converter function that accepts the string as a
-parameter and constructs a \class{Point} object from it.
-
-\begin{notice}
-Converter functions \strong{always} get called with a string, no matter
-under which data type you sent the value to SQLite.
-\end{notice}
-
-\begin{notice}
-Converter names are looked up in a case-sensitive manner.
-\end{notice}
-
-
-\begin{verbatim}
- def convert_point(s):
- x, y = map(float, s.split(";"))
- return Point(x, y)
-\end{verbatim}
-
-Now you need to make the \module{sqlite3} module know that what you select from the
-database is actually a point. There are two ways of doing this:
-
-\begin{itemize}
- \item Implicitly via the declared type
- \item Explicitly via the column name
-\end{itemize}
-
-Both ways are described in ``Module Constants'', section~\ref{sqlite3-Module-Contents}, in
-the entries for the constants \constant{PARSE_DECLTYPES} and
-\constant{PARSE_COLNAMES}.
-
-
-The following example illustrates both approaches.
-
- \verbatiminput{sqlite3/converter_point.py}
-
-\subsubsection{Default adapters and converters}
-
-There are default adapters for the date and datetime types in the datetime
-module. They will be sent as ISO dates/ISO timestamps to SQLite.
-
-The default converters are registered under the name "date" for \class{datetime.date}
-and under the name "timestamp" for \class{datetime.datetime}.
-
-This way, you can use date/timestamps from Python without any additional
-fiddling in most cases. The format of the adapters is also compatible with the
-experimental SQLite date/time functions.
-
-The following example demonstrates this.
-
- \verbatiminput{sqlite3/pysqlite_datetime.py}
-
-\subsection{Controlling Transactions \label{sqlite3-Controlling-Transactions}}
-
-By default, the \module{sqlite3} module opens transactions implicitly before a Data Modification Language (DML)
-statement (i.e. INSERT/UPDATE/DELETE/REPLACE), and commits transactions implicitly
-before a non-DML, non-query statement (i. e. anything other than
-SELECT/INSERT/UPDATE/DELETE/REPLACE).
-
-So if you are within a transaction and issue a command like \code{CREATE TABLE
-...}, \code{VACUUM}, \code{PRAGMA}, the \module{sqlite3} module will commit implicitly
-before executing that command. There are two reasons for doing that. The first
-is that some of these commands don't work within transactions. The other reason
-is that pysqlite needs to keep track of the transaction state (if a transaction
-is active or not).
-
-You can control which kind of "BEGIN" statements pysqlite implicitly executes
-(or none at all) via the \var{isolation_level} parameter to the
-\function{connect} call, or via the \member{isolation_level} property of
-connections.
-
-If you want \strong{autocommit mode}, then set \member{isolation_level} to None.
-
-Otherwise leave it at its default, which will result in a plain "BEGIN"
-statement, or set it to one of SQLite's supported isolation levels: DEFERRED,
-IMMEDIATE or EXCLUSIVE.
-
-As the \module{sqlite3} module needs to keep track of the transaction state, you should
-not use \code{OR ROLLBACK} or \code{ON CONFLICT ROLLBACK} in your SQL. Instead,
-catch the \exception{IntegrityError} and call the \method{rollback} method of
-the connection yourself.
-
-\subsection{Using pysqlite efficiently}
-
-\subsubsection{Using shortcut methods}
-
-Using the nonstandard \method{execute}, \method{executemany} and
-\method{executescript} methods of the \class{Connection} object, your code can
-be written more concisely because you don't have to create the (often
-superfluous) \class{Cursor} objects explicitly. Instead, the \class{Cursor}
-objects are created implicitly and these shortcut methods return the cursor
-objects. This way, you can execute a SELECT statement and iterate
-over it directly using only a single call on the \class{Connection} object.
-
- \verbatiminput{sqlite3/shortcut_methods.py}
-
-\subsubsection{Accessing columns by name instead of by index}
-
-One useful feature of the \module{sqlite3} module is the builtin \class{sqlite3.Row} class
-designed to be used as a row factory.
-
-Rows wrapped with this class can be accessed both by index (like tuples) and
-case-insensitively by name:
-
- \verbatiminput{sqlite3/rowclass.py}
-
-
diff --git a/Doc/lib/libstat.tex b/Doc/lib/libstat.tex
deleted file mode 100644
index d5353f1..0000000
--- a/Doc/lib/libstat.tex
+++ /dev/null
@@ -1,157 +0,0 @@
-\section{\module{stat} ---
- Interpreting \function{stat()} results}
-
-\declaremodule{standard}{stat}
-\modulesynopsis{Utilities for interpreting the results of
- \function{os.stat()}, \function{os.lstat()} and \function{os.fstat()}.}
-\sectionauthor{Skip Montanaro}{skip@automatrix.com}
-
-
-The \module{stat} module defines constants and functions for
-interpreting the results of \function{os.stat()},
-\function{os.fstat()} and \function{os.lstat()} (if they exist). For
-complete details about the \cfunction{stat()}, \cfunction{fstat()} and
-\cfunction{lstat()} calls, consult the documentation for your system.
-
-The \module{stat} module defines the following functions to test for
-specific file types:
-
-
-\begin{funcdesc}{S_ISDIR}{mode}
-Return non-zero if the mode is from a directory.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISCHR}{mode}
-Return non-zero if the mode is from a character special device file.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISBLK}{mode}
-Return non-zero if the mode is from a block special device file.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISREG}{mode}
-Return non-zero if the mode is from a regular file.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISFIFO}{mode}
-Return non-zero if the mode is from a FIFO (named pipe).
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISLNK}{mode}
-Return non-zero if the mode is from a symbolic link.
-\end{funcdesc}
-
-\begin{funcdesc}{S_ISSOCK}{mode}
-Return non-zero if the mode is from a socket.
-\end{funcdesc}
-
-Two additional functions are defined for more general manipulation of
-the file's mode:
-
-\begin{funcdesc}{S_IMODE}{mode}
-Return the portion of the file's mode that can be set by
-\function{os.chmod()}---that is, the file's permission bits, plus the
-sticky bit, set-group-id, and set-user-id bits (on systems that support
-them).
-\end{funcdesc}
-
-\begin{funcdesc}{S_IFMT}{mode}
-Return the portion of the file's mode that describes the file type (used
-by the \function{S_IS*()} functions above).
-\end{funcdesc}
-
-Normally, you would use the \function{os.path.is*()} functions for
-testing the type of a file; the functions here are useful when you are
-doing multiple tests of the same file and wish to avoid the overhead of
-the \cfunction{stat()} system call for each test. These are also
-useful when checking for information about a file that isn't handled
-by \refmodule{os.path}, like the tests for block and character
-devices.
-
-All the variables below are simply symbolic indexes into the 10-tuple
-returned by \function{os.stat()}, \function{os.fstat()} or
-\function{os.lstat()}.
-
-\begin{datadesc}{ST_MODE}
-Inode protection mode.
-\end{datadesc}
-
-\begin{datadesc}{ST_INO}
-Inode number.
-\end{datadesc}
-
-\begin{datadesc}{ST_DEV}
-Device inode resides on.
-\end{datadesc}
-
-\begin{datadesc}{ST_NLINK}
-Number of links to the inode.
-\end{datadesc}
-
-\begin{datadesc}{ST_UID}
-User id of the owner.
-\end{datadesc}
-
-\begin{datadesc}{ST_GID}
-Group id of the owner.
-\end{datadesc}
-
-\begin{datadesc}{ST_SIZE}
-Size in bytes of a plain file; amount of data waiting on some special
-files.
-\end{datadesc}
-
-\begin{datadesc}{ST_ATIME}
-Time of last access.
-\end{datadesc}
-
-\begin{datadesc}{ST_MTIME}
-Time of last modification.
-\end{datadesc}
-
-\begin{datadesc}{ST_CTIME}
-The ``ctime'' as reported by the operating system. On some systems
-(like \UNIX) is the time of the last metadata change, and, on others
-(like Windows), is the creation time (see platform documentation for
-details).
-\end{datadesc}
-
-The interpretation of ``file size'' changes according to the file
-type. For plain files this is the size of the file in bytes. For
-FIFOs and sockets under most flavors of \UNIX{} (including Linux in
-particular), the ``size'' is the number of bytes waiting to be read at
-the time of the call to \function{os.stat()}, \function{os.fstat()},
-or \function{os.lstat()}; this can sometimes be useful, especially for
-polling one of these special files after a non-blocking open. The
-meaning of the size field for other character and block devices varies
-more, depending on the implementation of the underlying system call.
-
-Example:
-
-\begin{verbatim}
-import os, sys
-from stat import *
-
-def walktree(top, callback):
- '''recursively descend the directory tree rooted at top,
- calling the callback function for each regular file'''
-
- for f in os.listdir(top):
- pathname = os.path.join(top, f)
- mode = os.stat(pathname)[ST_MODE]
- if S_ISDIR(mode):
- # It's a directory, recurse into it
- walktree(pathname, callback)
- elif S_ISREG(mode):
- # It's a file, call the callback function
- callback(pathname)
- else:
- # Unknown file type, print a message
- print 'Skipping %s' % pathname
-
-def visitfile(file):
- print 'visiting', file
-
-if __name__ == '__main__':
- walktree(sys.argv[1], visitfile)
-\end{verbatim}
diff --git a/Doc/lib/libstatvfs.tex b/Doc/lib/libstatvfs.tex
deleted file mode 100644
index 2dc8933..0000000
--- a/Doc/lib/libstatvfs.tex
+++ /dev/null
@@ -1,55 +0,0 @@
-\section{\module{statvfs} ---
- Constants used with \function{os.statvfs()}}
-
-\declaremodule{standard}{statvfs}
-% LaTeX'ed from comments in module
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Constants for interpreting the result of
- \function{os.statvfs()}.}
-
-The \module{statvfs} module defines constants so interpreting the result
-if \function{os.statvfs()}, which returns a tuple, can be made without
-remembering ``magic numbers.'' Each of the constants defined in this
-module is the \emph{index} of the entry in the tuple returned by
-\function{os.statvfs()} that contains the specified information.
-
-
-\begin{datadesc}{F_BSIZE}
-Preferred file system block size.
-\end{datadesc}
-
-\begin{datadesc}{F_FRSIZE}
-Fundamental file system block size.
-\end{datadesc}
-
-\begin{datadesc}{F_BLOCKS}
-Total number of blocks in the filesystem.
-\end{datadesc}
-
-\begin{datadesc}{F_BFREE}
-Total number of free blocks.
-\end{datadesc}
-
-\begin{datadesc}{F_BAVAIL}
-Free blocks available to non-super user.
-\end{datadesc}
-
-\begin{datadesc}{F_FILES}
-Total number of file nodes.
-\end{datadesc}
-
-\begin{datadesc}{F_FFREE}
-Total number of free file nodes.
-\end{datadesc}
-
-\begin{datadesc}{F_FAVAIL}
-Free nodes available to non-super user.
-\end{datadesc}
-
-\begin{datadesc}{F_FLAG}
-Flags. System dependent: see \cfunction{statvfs()} man page.
-\end{datadesc}
-
-\begin{datadesc}{F_NAMEMAX}
-Maximum file name length.
-\end{datadesc}
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
deleted file mode 100644
index 95033f9..0000000
--- a/Doc/lib/libstdtypes.tex
+++ /dev/null
@@ -1,2070 +0,0 @@
-\chapter{Built-in Types \label{types}}
-
-The following sections describe the standard types that are built into
-the interpreter.
-\note{Historically (until release 2.2), Python's built-in types have
-differed from user-defined types because it was not possible to use
-the built-in types as the basis for object-oriented inheritance.
-This limitation does not exist any longer.}
-
-The principal built-in types are numerics, sequences, mappings, files,
-classes, instances and exceptions.
-\indexii{built-in}{types}
-
-Some operations are supported by several object types; in particular,
-practically all objects can be compared, tested for truth value,
-and converted to a string (with
-the \function{repr()} function or the slightly different
-\function{str()} function). The latter
-function is implicitly used when an object is written by the
-\keyword{print}\stindex{print} statement.
-(Information on the \ulink{\keyword{print} statement}{../ref/print.html}
-and other language statements can be found in the
-\citetitle[../ref/ref.html]{Python Reference Manual} and the
-\citetitle[../tut/tut.html]{Python Tutorial}.)
-
-
-\section{Truth Value Testing\label{truth}}
-
-Any object can be tested for truth value, for use in an \keyword{if} or
-\keyword{while} condition or as operand of the Boolean operations below.
-The following values are considered false:
-\stindex{if}
-\stindex{while}
-\indexii{truth}{value}
-\indexii{Boolean}{operations}
-\index{false}
-
-\begin{itemize}
-
-\item \code{None}
- \withsubitem{(Built-in object)}{\ttindex{None}}
-
-\item \code{False}
- \withsubitem{(Built-in object)}{\ttindex{False}}
-
-\item zero of any numeric type, for example, \code{0}, \code{0L},
- \code{0.0}, \code{0j}.
-
-\item any empty sequence, for example, \code{''}, \code{()}, \code{[]}.
-
-\item any empty mapping, for example, \code{\{\}}.
-
-\item instances of user-defined classes, if the class defines a
- \method{__bool__()} or \method{__len__()} method, when that
- method returns the integer zero or \class{bool} value
- \code{False}.\footnote{Additional
-information on these special methods may be found in the
-\citetitle[../ref/ref.html]{Python Reference Manual}.}
-
-\end{itemize}
-
-All other values are considered true --- so objects of many types are
-always true.
-\index{true}
-
-Operations and built-in functions that have a Boolean result always
-return \code{0} or \code{False} for false and \code{1} or \code{True}
-for true, unless otherwise stated. (Important exception: the Boolean
-operations \samp{or}\opindex{or} and \samp{and}\opindex{and} always
-return one of their operands.)
-\index{False}
-\index{True}
-
-\section{Boolean Operations ---
- \keyword{and}, \keyword{or}, \keyword{not}
- \label{boolean}}
-
-These are the Boolean operations, ordered by ascending priority:
-\indexii{Boolean}{operations}
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} or \var{y}}
- {if \var{x} is false, then \var{y}, else \var{x}}{(1)}
- \lineiii{\var{x} and \var{y}}
- {if \var{x} is false, then \var{x}, else \var{y}}{(1)}
- \hline
- \lineiii{not \var{x}}
- {if \var{x} is false, then \code{True}, else \code{False}}{(2)}
-\end{tableiii}
-\opindex{and}
-\opindex{or}
-\opindex{not}
-
-\noindent
-Notes:
-
-\begin{description}
-
-\item[(1)]
-These only evaluate their second argument if needed for their outcome.
-
-\item[(2)]
-\samp{not} has a lower priority than non-Boolean operators, so
-\code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} ==
-\var{b})}, and \code{\var{a} == not \var{b}} is a syntax error.
-
-\end{description}
-
-
-\section{Comparisons \label{comparisons}}
-
-Comparison operations are supported by all objects. They all have the
-same priority (which is higher than that of the Boolean operations).
-Comparisons can be chained arbitrarily; for example, \code{\var{x} <
-\var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and
-\var{y} <= \var{z}}, except that \var{y} is evaluated only once (but
-in both cases \var{z} is not evaluated at all when \code{\var{x} <
-\var{y}} is found to be false).
-\indexii{chaining}{comparisons}
-
-This table summarizes the comparison operations:
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes}
- \lineiii{<}{strictly less than}{}
- \lineiii{<=}{less than or equal}{}
- \lineiii{>}{strictly greater than}{}
- \lineiii{>=}{greater than or equal}{}
- \lineiii{==}{equal}{}
- \lineiii{!=}{not equal}{}
- \lineiii{is}{object identity}{}
- \lineiii{is not}{negated object identity}{}
-\end{tableiii}
-\indexii{operator}{comparison}
-\opindex{==} % XXX *All* others have funny characters < ! >
-\opindex{is}
-\opindex{is not}
-
-Objects of different types, except different numeric types and different string types, never
-compare equal; such objects are ordered consistently but arbitrarily
-(so that sorting a heterogeneous array yields a consistent result).
-Furthermore, some types (for example, file objects) support only a
-degenerate notion of comparison where any two objects of that type are
-unequal. Again, such objects are ordered arbitrarily but
-consistently. The \code{<}, \code{<=}, \code{>} and \code{>=}
-operators will raise a \exception{TypeError} exception when any operand
-is a complex number.
-\indexii{object}{numeric}
-\indexii{objects}{comparing}
-
-Instances of a class normally compare as non-equal unless the class
-\withsubitem{(instance method)}{\ttindex{__cmp__()}}
-defines the \method{__cmp__()} method. Refer to the
-\citetitle[../ref/customization.html]{Python Reference Manual} for
-information on the use of this method to effect object comparisons.
-
-\strong{Implementation note:} Objects of different types except
-numbers are ordered by their type names; objects of the same types
-that don't support proper comparison are ordered by their address.
-
-Two more operations with the same syntactic priority,
-\samp{in}\opindex{in} and \samp{not in}\opindex{not in}, are supported
-only by sequence types (below).
-
-
-\section{Numeric Types ---
- \class{int}, \class{float}, \class{long}, \class{complex}
- \label{typesnumeric}}
-
-There are four distinct numeric types: \dfn{plain integers},
-\dfn{long integers},
-\dfn{floating point numbers}, and \dfn{complex numbers}.
-In addition, Booleans are a subtype of plain integers.
-Plain integers (also just called \dfn{integers})
-are implemented using \ctype{long} in C, which gives them at least 32
-bits of precision (\code{sys.maxint} is always set to the maximum
-plain integer value for the current platform, the minimum value is
-\code{-sys.maxint - 1}). Long integers have unlimited precision.
-Floating point numbers are implemented using \ctype{double} in C.
-All bets on their precision are off unless you happen to know the
-machine you are working with.
-\obindex{numeric}
-\obindex{Boolean}
-\obindex{integer}
-\obindex{long integer}
-\obindex{floating point}
-\obindex{complex number}
-\indexii{C}{language}
-
-Complex numbers have a real and imaginary part, which are each
-implemented using \ctype{double} in C. To extract these parts from
-a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
-
-Numbers are created by numeric literals or as the result of built-in
-functions and operators. Unadorned integer literals (including hex
-and octal numbers) yield plain integers unless the value they denote
-is too large to be represented as a plain integer, in which case
-they yield a long integer. Integer literals with an
-\character{L} or \character{l} suffix yield long integers
-(\character{L} is preferred because \samp{1l} looks too much like
-eleven!). Numeric literals containing a decimal point or an exponent
-sign yield floating point numbers. Appending \character{j} or
-\character{J} to a numeric literal yields a complex number with a
-zero real part. A complex numeric literal is the sum of a real and
-an imaginary part.
-\indexii{numeric}{literals}
-\indexii{integer}{literals}
-\indexiii{long}{integer}{literals}
-\indexii{floating point}{literals}
-\indexii{complex number}{literals}
-\indexii{hexadecimal}{literals}
-\indexii{octal}{literals}
-
-Python fully supports mixed arithmetic: when a binary arithmetic
-operator has operands of different numeric types, the operand with the
-``narrower'' type is widened to that of the other, where plain
-integer is narrower than long integer is narrower than floating point is
-narrower than complex.
-Comparisons between numbers of mixed type use the same rule.\footnote{
- As a consequence, the list \code{[1, 2]} is considered equal
- to \code{[1.0, 2.0]}, and similarly for tuples.
-} The constructors \function{int()}, \function{long()}, \function{float()},
-and \function{complex()} can be used
-to produce numbers of a specific type.
-\index{arithmetic}
-\bifuncindex{int}
-\bifuncindex{long}
-\bifuncindex{float}
-\bifuncindex{complex}
-
-All numeric types (except complex) support the following operations,
-sorted by ascending priority (operations in the same box have the same
-priority; all numeric operations have a higher priority than
-comparison operations):
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
- \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
- \hline
- \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
- \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
- \lineiii{\var{x} // \var{y}}{(floored) quotient of \var{x} and \var{y}}{(5)}
- \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
- \hline
- \lineiii{-\var{x}}{\var{x} negated}{}
- \lineiii{+\var{x}}{\var{x} unchanged}{}
- \hline
- \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{}
- \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)}
- \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)}
- \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
- \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
- \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
- \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} // \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
- \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
- \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
-\end{tableiii}
-\indexiii{operations on}{numeric}{types}
-\withsubitem{(complex number method)}{\ttindex{conjugate()}}
-
-\noindent
-Notes:
-\begin{description}
-
-\item[(1)]
-For (plain or long) integer division, the result is an integer.
-The result is always rounded towards minus infinity: 1/2 is 0,
-(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result
-is a long integer if either operand is a long integer, regardless of
-the numeric value.
-\indexii{integer}{division}
-\indexiii{long}{integer}{division}
-
-\item[(2)]
-Conversion from floating point to (long or plain) integer may round or
-truncate as in C; see functions \function{floor()} and
-\function{ceil()} in the \refmodule{math}\refbimodindex{math} module
-for well-defined conversions.
-\withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
-\indexii{numeric}{conversions}
-\indexii{C}{language}
-
-\item[(3)]
-See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
-description.
-
-\item[(4)]
-Complex floor division operator, modulo operator, and \function{divmod()}.
-
-\deprecated{2.3}{Instead convert to float using \function{abs()}
-if appropriate.}
-
-\item[(5)]
-Also referred to as integer division. The resultant value is a whole integer,
-though the result's type is not necessarily int.
-\end{description}
-% XXXJH exceptions: overflow (when? what operations?) zerodivision
-
-\subsection{Bit-string Operations on Integer Types \label{bitstring-ops}}
-\nodename{Bit-string Operations}
-
-Plain and long integer types support additional operations that make
-sense only for bit-strings. Negative numbers are treated as their 2's
-complement value (for long integers, this assumes a sufficiently large
-number of bits that no overflow occurs during the operation).
-
-The priorities of the binary bit-wise operations are all lower than
-the numeric operations and higher than the comparisons; the unary
-operation \samp{\~} has the same priority as the other unary numeric
-operations (\samp{+} and \samp{-}).
-
-This table lists the bit-string operations sorted in ascending
-priority (operations in the same box have the same priority):
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
- \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
- \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
- % The empty groups below prevent conversion to guillemets.
- \lineiii{\var{x} <{}< \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
- \lineiii{\var{x} >{}> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
- \hline
- \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
-\end{tableiii}
-\indexiii{operations on}{integer}{types}
-\indexii{bit-string}{operations}
-\indexii{shifting}{operations}
-\indexii{masking}{operations}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)] Negative shift counts are illegal and cause a
-\exception{ValueError} to be raised.
-\item[(2)] A left shift by \var{n} bits is equivalent to
-multiplication by \code{pow(2, \var{n})} without overflow check.
-\item[(3)] A right shift by \var{n} bits is equivalent to
-division by \code{pow(2, \var{n})} without overflow check.
-\end{description}
-
-
-\section{Iterator Types \label{typeiter}}
-
-\versionadded{2.2}
-\index{iterator protocol}
-\index{protocol!iterator}
-\index{sequence!iteration}
-\index{container!iteration over}
-
-Python supports a concept of iteration over containers. This is
-implemented using two distinct methods; these are used to allow
-user-defined classes to support iteration. Sequences, described below
-in more detail, always support the iteration methods.
-
-One method needs to be defined for container objects to provide
-iteration support:
-
-\begin{methoddesc}[container]{__iter__}{}
- Return an iterator object. The object is required to support the
- iterator protocol described below. If a container supports
- different types of iteration, additional methods can be provided to
- specifically request iterators for those iteration types. (An
- example of an object supporting multiple forms of iteration would be
- a tree structure which supports both breadth-first and depth-first
- traversal.) This method corresponds to the \member{tp_iter} slot of
- the type structure for Python objects in the Python/C API.
-\end{methoddesc}
-
-The iterator objects themselves are required to support the following
-two methods, which together form the \dfn{iterator protocol}:
-
-\begin{methoddesc}[iterator]{__iter__}{}
- Return the iterator object itself. This is required to allow both
- containers and iterators to be used with the \keyword{for} and
- \keyword{in} statements. This method corresponds to the
- \member{tp_iter} slot of the type structure for Python objects in
- the Python/C API.
-\end{methoddesc}
-
-\begin{methoddesc}[iterator]{next}{}
- Return the next item from the container. If there are no further
- items, raise the \exception{StopIteration} exception. This method
- corresponds to the \member{tp_iternext} slot of the type structure
- for Python objects in the Python/C API.
-\end{methoddesc}
-
-Python defines several iterator objects to support iteration over
-general and specific sequence types, dictionaries, and other more
-specialized forms. The specific types are not important beyond their
-implementation of the iterator protocol.
-
-The intention of the protocol is that once an iterator's \method{__next__()}
-method raises \exception{StopIteration}, it will continue to do so on subsequent
-calls. Implementations that do not obey this property are deemed broken. (This
-constraint was added in Python 2.3; in Python 2.2, various iterators are broken
-according to this rule.)
-
-Python's generators provide a convenient way to implement the iterator protocol.
-If a container object's \method{__iter__()} method is implemented as a
-generator, it will automatically return an iterator object (technically, a
-generator object) supplying the \method{__iter__()} and \method{__next__()}
-methods.
-
-
-\section{Sequence Types ---
- \class{str}, \class{unicode}, \class{list},
- \class{tuple}, \class{buffer}, \class{range}
- \label{typesseq}}
-
-There are six sequence types: strings, Unicode strings, lists,
-tuples, buffers, and range objects.
-
-String literals are written in single or double quotes:
-\code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the
-\citetitle[../ref/strings.html]{Python Reference Manual} for more about
-string literals. Unicode strings are much like strings, but are
-specified in the syntax using a preceding \character{u} character:
-\code{u'abc'}, \code{u"def"}. Lists are constructed with square brackets,
-separating items with commas: \code{[a, b, c]}. Tuples are
-constructed by the comma operator (not within square brackets), with
-or without enclosing parentheses, but an empty tuple must have the
-enclosing parentheses, such as \code{a, b, c} or \code{()}. A single
-item tuple must have a trailing comma, such as \code{(d,)}.
-\obindex{sequence}
-\obindex{string}
-\obindex{Unicode}
-\obindex{tuple}
-\obindex{list}
-
-Buffer objects are not directly supported by Python syntax, but can be
-created by calling the builtin function
-\function{buffer()}.\bifuncindex{buffer} They don't support
-concatenation or repetition.
-\obindex{buffer}
-
-Xrange objects are similar to buffers in that there is no specific
-syntax to create them, but they are created using the \function{range()}
-function.\bifuncindex{range} They don't support slicing,
-concatenation or repetition, and using \code{in}, \code{not in},
-\function{min()} or \function{max()} on them is inefficient.
-\obindex{range}
-
-Most sequence types support the following operations. The \samp{in} and
-\samp{not in} operations have the same priorities as the comparison
-operations. The \samp{+} and \samp{*} operations have the same
-priority as the corresponding numeric operations.\footnote{They must
-have since the parser can't tell the type of the operands.}
-
-This table lists the sequence operations sorted in ascending priority
-(operations in the same box have the same priority). In the table,
-\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i}
-and \var{j} are integers:
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{x} in \var{s}}{\code{True} if an item of \var{s} is equal to \var{x}, else \code{False}}{(1)}
- \lineiii{\var{x} not in \var{s}}{\code{False} if an item of \var{s} is
-equal to \var{x}, else \code{True}}{(1)}
- \hline
- \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{(6)}
- \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(2)}
- \hline
- \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(3)}
- \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(3), (4)}
- \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(3), (5)}
- \hline
- \lineiii{len(\var{s})}{length of \var{s}}{}
- \lineiii{min(\var{s})}{smallest item of \var{s}}{}
- \lineiii{max(\var{s})}{largest item of \var{s}}{}
-\end{tableiii}
-\indexiii{operations on}{sequence}{types}
-\bifuncindex{len}
-\bifuncindex{min}
-\bifuncindex{max}
-\indexii{concatenation}{operation}
-\indexii{repetition}{operation}
-\indexii{subscript}{operation}
-\indexii{slice}{operation}
-\indexii{extended slice}{operation}
-\opindex{in}
-\opindex{not in}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)] When \var{s} is a string or Unicode string object the
-\code{in} and \code{not in} operations act like a substring test. In
-Python versions before 2.3, \var{x} had to be a string of length 1.
-In Python 2.3 and beyond, \var{x} may be a string of any length.
-
-\item[(2)] Values of \var{n} less than \code{0} are treated as
- \code{0} (which yields an empty sequence of the same type as
- \var{s}). Note also that the copies are shallow; nested structures
- are not copied. This often haunts new Python programmers; consider:
-
-\begin{verbatim}
->>> lists = [[]] * 3
->>> lists
-[[], [], []]
->>> lists[0].append(3)
->>> lists
-[[3], [3], [3]]
-\end{verbatim}
-
- What has happened is that \code{[[]]} is a one-element list containing
- an empty list, so all three elements of \code{[[]] * 3} are (pointers to)
- this single empty list. Modifying any of the elements of \code{lists}
- modifies this single list. You can create a list of different lists this
- way:
-
-\begin{verbatim}
->>> lists = [[] for i in range(3)]
->>> lists[0].append(3)
->>> lists[1].append(5)
->>> lists[2].append(7)
->>> lists
-[[3], [5], [7]]
-\end{verbatim}
-
-\item[(3)] If \var{i} or \var{j} is negative, the index is relative to
- the end of the string: \code{len(\var{s}) + \var{i}} or
- \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
- still \code{0}.
-
-\item[(4)] The slice of \var{s} from \var{i} to \var{j} is defined as
- the sequence of items with index \var{k} such that \code{\var{i} <=
- \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
- \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted
- or \code{None}, use \code{0}. If \var{j} is omitted or \code{None},
- use \code{len(\var{s})}. If \var{i} is greater than or equal to \var{j},
- the slice is empty.
-
-\item[(5)] The slice of \var{s} from \var{i} to \var{j} with step
- \var{k} is defined as the sequence of items with index
- \code{\var{x} = \var{i} + \var{n}*\var{k}} such that
- $0 \leq n < \frac{j-i}{k}$. In other words, the indices
- are \code{i}, \code{i+k}, \code{i+2*k}, \code{i+3*k} and so on, stopping when
- \var{j} is reached (but never including \var{j}). If \var{i} or \var{j}
- is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If
- \var{i} or \var{j} are omitted or \code{None}, they become ``end'' values
- (which end depends on the sign of \var{k}). Note, \var{k} cannot
- be zero. If \var{k} is \code{None}, it is treated like \code{1}.
-
-\item[(6)] If \var{s} and \var{t} are both strings, some Python
-implementations such as CPython can usually perform an in-place optimization
-for assignments of the form \code{\var{s}=\var{s}+\var{t}} or
-\code{\var{s}+=\var{t}}. When applicable, this optimization makes
-quadratic run-time much less likely. This optimization is both version
-and implementation dependent. For performance sensitive code, it is
-preferable to use the \method{str.join()} method which assures consistent
-linear concatenation performance across versions and implementations.
-\versionchanged[Formerly, string concatenation never occurred in-place]{2.4}
-
-\end{description}
-
-
-\subsection{String Methods \label{string-methods}}
-\indexii{string}{methods}
-
-These are the string methods which both 8-bit strings and Unicode
-objects support:
-
-\begin{methoddesc}[str]{capitalize}{}
-Return a copy of the string with only its first character capitalized.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{center}{width\optional{, fillchar}}
-Return centered in a string of length \var{width}. Padding is done
-using the specified \var{fillchar} (default is a space).
-\versionchanged[Support for the \var{fillchar} argument]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{count}{sub\optional{, start\optional{, end}}}
-Return the number of occurrences of substring \var{sub} in string
-S\code{[\var{start}:\var{end}]}. Optional arguments \var{start} and
-\var{end} are interpreted as in slice notation.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{decode}{\optional{encoding\optional{, errors}}}
-Decodes the string using the codec registered for \var{encoding}.
-\var{encoding} defaults to the default string encoding. \var{errors}
-may be given to set a different error handling scheme. The default is
-\code{'strict'}, meaning that encoding errors raise
-\exception{UnicodeError}. Other possible values are \code{'ignore'},
-\code{'replace'} and any other name registered via
-\function{codecs.register_error}, see section~\ref{codec-base-classes}.
-\versionadded{2.2}
-\versionchanged[Support for other error handling schemes added]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{encode}{\optional{encoding\optional{,errors}}}
-Return an encoded version of the string. Default encoding is the current
-default string encoding. \var{errors} may be given to set a different
-error handling scheme. The default for \var{errors} is
-\code{'strict'}, meaning that encoding errors raise a
-\exception{UnicodeError}. Other possible values are \code{'ignore'},
-\code{'replace'}, \code{'xmlcharrefreplace'}, \code{'backslashreplace'}
-and any other name registered via \function{codecs.register_error},
-see section~\ref{codec-base-classes}.
-For a list of possible encodings, see section~\ref{standard-encodings}.
-\versionadded{2.0}
-\versionchanged[Support for \code{'xmlcharrefreplace'} and
-\code{'backslashreplace'} and other error handling schemes added]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{endswith}{suffix\optional{, start\optional{, end}}}
-Return \code{True} if the string ends with the specified \var{suffix},
-otherwise return \code{False}. \var{suffix} can also be a tuple of
-suffixes to look for. With optional \var{start}, test beginning at
-that position. With optional \var{end}, stop comparing at that position.
-
-\versionchanged[Accept tuples as \var{suffix}]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{expandtabs}{\optional{tabsize}}
-Return a copy of the string where all tab characters are expanded
-using spaces. If \var{tabsize} is not given, a tab size of \code{8}
-characters is assumed.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{find}{sub\optional{, start\optional{, end}}}
-Return the lowest index in the string where substring \var{sub} is
-found, such that \var{sub} is contained in the range [\var{start},
-\var{end}]. Optional arguments \var{start} and \var{end} are
-interpreted as in slice notation. Return \code{-1} if \var{sub} is
-not found.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{index}{sub\optional{, start\optional{, end}}}
-Like \method{find()}, but raise \exception{ValueError} when the
-substring is not found.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isalnum}{}
-Return true if all characters in the string are alphanumeric and there
-is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isalpha}{}
-Return true if all characters in the string are alphabetic and there
-is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isdigit}{}
-Return true if all characters in the string are digits and there
-is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isidentifier}{}
-Return True if S is a valid identifier according
-to the language definition.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{islower}{}
-Return true if all cased characters in the string are lowercase and
-there is at least one cased character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isspace}{}
-Return true if there are only whitespace characters in the string and
-there is at least one character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{istitle}{}
-Return true if the string is a titlecased string and there is at least one
-character, for example uppercase characters may only follow uncased
-characters and lowercase characters only cased ones. Return false
-otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{isupper}{}
-Return true if all cased characters in the string are uppercase and
-there is at least one cased character, false otherwise.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{join}{seq}
-Return a string which is the concatenation of the strings in the
-sequence \var{seq}. The separator between elements is the string
-providing this method.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{ljust}{width\optional{, fillchar}}
-Return the string left justified in a string of length \var{width}.
-Padding is done using the specified \var{fillchar} (default is a
-space). The original string is returned if
-\var{width} is less than \code{len(\var{s})}.
-\versionchanged[Support for the \var{fillchar} argument]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{lower}{}
-Return a copy of the string converted to lowercase.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{lstrip}{\optional{chars}}
-Return a copy of the string with leading characters removed. The
-\var{chars} argument is a string specifying the set of characters
-to be removed. If omitted or \code{None}, the \var{chars} argument
-defaults to removing whitespace. The \var{chars} argument is not
-a prefix; rather, all combinations of its values are stripped:
-\begin{verbatim}
- >>> ' spacious '.lstrip()
- 'spacious '
- >>> 'www.example.com'.lstrip('cmowz.')
- 'example.com'
-\end{verbatim}
-\versionchanged[Support for the \var{chars} argument]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{partition}{sep}
-Split the string at the first occurrence of \var{sep}, and return
-a 3-tuple containing the part before the separator, the separator
-itself, and the part after the separator. If the separator is not
-found, return a 3-tuple containing the string itself, followed by
-two empty strings.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{replace}{old, new\optional{, count}}
-Return a copy of the string with all occurrences of substring
-\var{old} replaced by \var{new}. If the optional argument
-\var{count} is given, only the first \var{count} occurrences are
-replaced.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rfind}{sub \optional{,start \optional{,end}}}
-Return the highest index in the string where substring \var{sub} is
-found, such that \var{sub} is contained within s[start,end]. Optional
-arguments \var{start} and \var{end} are interpreted as in slice
-notation. Return \code{-1} on failure.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rindex}{sub\optional{, start\optional{, end}}}
-Like \method{rfind()} but raises \exception{ValueError} when the
-substring \var{sub} is not found.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rjust}{width\optional{, fillchar}}
-Return the string right justified in a string of length \var{width}.
-Padding is done using the specified \var{fillchar} (default is a space).
-The original string is returned if
-\var{width} is less than \code{len(\var{s})}.
-\versionchanged[Support for the \var{fillchar} argument]{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rpartition}{sep}
-Split the string at the last occurrence of \var{sep}, and return
-a 3-tuple containing the part before the separator, the separator
-itself, and the part after the separator. If the separator is not
-found, return a 3-tuple containing two empty strings, followed by
-the string itself.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rsplit}{\optional{sep \optional{,maxsplit}}}
-Return a list of the words in the string, using \var{sep} as the
-delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
-splits are done, the \emph{rightmost} ones. If \var{sep} is not specified
-or \code{None}, any whitespace string is a separator. Except for splitting
-from the right, \method{rsplit()} behaves like \method{split()} which
-is described in detail below.
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{rstrip}{\optional{chars}}
-Return a copy of the string with trailing characters removed. The
-\var{chars} argument is a string specifying the set of characters
-to be removed. If omitted or \code{None}, the \var{chars} argument
-defaults to removing whitespace. The \var{chars} argument is not
-a suffix; rather, all combinations of its values are stripped:
-\begin{verbatim}
- >>> ' spacious '.rstrip()
- ' spacious'
- >>> 'mississippi'.rstrip('ipz')
- 'mississ'
-\end{verbatim}
-\versionchanged[Support for the \var{chars} argument]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{split}{\optional{sep \optional{,maxsplit}}}
-Return a list of the words in the string, using \var{sep} as the
-delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
-splits are done. (thus, the list will have at most \code{\var{maxsplit}+1}
-elements). If \var{maxsplit} is not specified, then there
-is no limit on the number of splits (all possible splits are made).
-Consecutive delimiters are not grouped together and are
-deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')}
-returns \samp{['1', '', '2']}). The \var{sep} argument may consist of
-multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns
-\samp{['1', '2', '3']}). Splitting an empty string with a specified
-separator returns \samp{['']}.
-
-If \var{sep} is not specified or is \code{None}, a different splitting
-algorithm is applied. First, whitespace characters (spaces, tabs,
-newlines, returns, and formfeeds) are stripped from both ends. Then,
-words are separated by arbitrary length strings of whitespace
-characters. Consecutive whitespace delimiters are treated as a single
-delimiter (\samp{'1 2 3'.split()} returns \samp{['1', '2', '3']}).
-Splitting an empty string or a string consisting of just whitespace
-returns an empty list.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{splitlines}{\optional{keepends}}
-Return a list of the lines in the string, breaking at line
-boundaries. Line breaks are not included in the resulting list unless
-\var{keepends} is given and true.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{startswith}{prefix\optional{,
- start\optional{, end}}}
-Return \code{True} if string starts with the \var{prefix}, otherwise
-return \code{False}. \var{prefix} can also be a tuple of
-prefixes to look for. With optional \var{start}, test string beginning at
-that position. With optional \var{end}, stop comparing string at that
-position.
-
-\versionchanged[Accept tuples as \var{prefix}]{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{strip}{\optional{chars}}
-Return a copy of the string with the leading and trailing characters
-removed. The \var{chars} argument is a string specifying the set of
-characters to be removed. If omitted or \code{None}, the \var{chars}
-argument defaults to removing whitespace. The \var{chars} argument is not
-a prefix or suffix; rather, all combinations of its values are stripped:
-\begin{verbatim}
- >>> ' spacious '.strip()
- 'spacious'
- >>> 'www.example.com'.strip('cmowz.')
- 'example'
-\end{verbatim}
-\versionchanged[Support for the \var{chars} argument]{2.2.2}
-\end{methoddesc}
-
-\begin{methoddesc}[str]{swapcase}{}
-Return a copy of the string with uppercase characters converted to
-lowercase and vice versa.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{title}{}
-Return a titlecased version of the string: words start with uppercase
-characters, all remaining cased characters are lowercase.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{translate}{table\optional{, deletechars}}
-Return a copy of the string where all characters occurring in the
-optional argument \var{deletechars} are removed, and the remaining
-characters have been mapped through the given translation table, which
-must be a string of length 256.
-
-You can use the \function{maketrans()} helper function in the
-\refmodule{string} module to create a translation table.
-For string objects, set the \var{table} argument to \code{None}
-for translations that only delete characters:
-\begin{verbatim}
- >>> 'read this short text'.translate(None, 'aeiou')
- 'rd ths shrt txt'
-\end{verbatim}
-\versionadded[Support for a \code{None} \var{table} argument]{2.6}
-
-For Unicode objects, the \method{translate()} method does not
-accept the optional \var{deletechars} argument. Instead, it
-returns a copy of the \var{s} where all characters have been mapped
-through the given translation table which must be a mapping of
-Unicode ordinals to Unicode ordinals, Unicode strings or \code{None}.
-Unmapped characters are left untouched. Characters mapped to \code{None}
-are deleted. Note, a more flexible approach is to create a custom
-character mapping codec using the \refmodule{codecs} module (see
-\module{encodings.cp1251} for an example).
-\end{methoddesc}
-
-\begin{methoddesc}[str]{upper}{}
-Return a copy of the string converted to uppercase.
-
-For 8-bit strings, this method is locale-dependent.
-\end{methoddesc}
-
-\begin{methoddesc}[str]{zfill}{width}
-Return the numeric string left filled with zeros in a string
-of length \var{width}. The original string is returned if
-\var{width} is less than \code{len(\var{s})}.
-\versionadded{2.2.2}
-\end{methoddesc}
-
-
-\subsection{String Formatting Operations \label{typesseq-strings}}
-
-\index{formatting, string (\%{})}
-\index{interpolation, string (\%{})}
-\index{string!formatting}
-\index{string!interpolation}
-\index{printf-style formatting}
-\index{sprintf-style formatting}
-\index{\protect\%{} formatting}
-\index{\protect\%{} interpolation}
-
-String and Unicode objects have one unique built-in operation: the
-\code{\%} operator (modulo). This is also known as the string
-\emph{formatting} or \emph{interpolation} operator. Given
-\code{\var{format} \% \var{values}} (where \var{format} is a string or
-Unicode object), \code{\%} conversion specifications in \var{format}
-are replaced with zero or more elements of \var{values}. The effect
-is similar to the using \cfunction{sprintf()} in the C language. If
-\var{format} is a Unicode object, or if any of the objects being
-converted using the \code{\%s} conversion are Unicode objects, the
-result will also be a Unicode object.
-
-If \var{format} requires a single argument, \var{values} may be a
-single non-tuple object.\footnote{To format only a tuple you
-should therefore provide a singleton tuple whose only element
-is the tuple to be formatted.} Otherwise, \var{values} must be a tuple with
-exactly the number of items specified by the format string, or a
-single mapping object (for example, a dictionary).
-
-A conversion specifier contains two or more characters and has the
-following components, which must occur in this order:
-
-\begin{enumerate}
- \item The \character{\%} character, which marks the start of the
- specifier.
- \item Mapping key (optional), consisting of a parenthesised sequence
- of characters (for example, \code{(somename)}).
- \item Conversion flags (optional), which affect the result of some
- conversion types.
- \item Minimum field width (optional). If specified as an
- \character{*} (asterisk), the actual width is read from the
- next element of the tuple in \var{values}, and the object to
- convert comes after the minimum field width and optional
- precision.
- \item Precision (optional), given as a \character{.} (dot) followed
- by the precision. If specified as \character{*} (an
- asterisk), the actual width is read from the next element of
- the tuple in \var{values}, and the value to convert comes after
- the precision.
- \item Length modifier (optional).
- \item Conversion type.
-\end{enumerate}
-
-When the right argument is a dictionary (or other mapping type), then
-the formats in the string \emph{must} include a parenthesised mapping key into
-that dictionary inserted immediately after the \character{\%}
-character. The mapping key selects the value to be formatted from the
-mapping. For example:
-
-\begin{verbatim}
->>> print '%(language)s has %(#)03d quote types.' % \
- {'language': "Python", "#": 2}
-Python has 002 quote types.
-\end{verbatim}
-
-In this case no \code{*} specifiers may occur in a format (since they
-require a sequential parameter list).
-
-The conversion flag characters are:
-
-\begin{tableii}{c|l}{character}{Flag}{Meaning}
- \lineii{\#}{The value conversion will use the ``alternate form''
- (where defined below).}
- \lineii{0}{The conversion will be zero padded for numeric values.}
- \lineii{-}{The converted value is left adjusted (overrides
- the \character{0} conversion if both are given).}
- \lineii{{~}}{(a space) A blank should be left before a positive number
- (or empty string) produced by a signed conversion.}
- \lineii{+}{A sign character (\character{+} or \character{-}) will
- precede the conversion (overrides a "space" flag).}
-\end{tableii}
-
-A length modifier (\code{h}, \code{l}, or \code{L}) may be
-present, but is ignored as it is not necessary for Python.
-
-The conversion types are:
-
-\begin{tableiii}{c|l|c}{character}{Conversion}{Meaning}{Notes}
- \lineiii{d}{Signed integer decimal.}{}
- \lineiii{i}{Signed integer decimal.}{}
- \lineiii{o}{Unsigned octal.}{(1)}
- \lineiii{u}{Unsigned decimal.}{}
- \lineiii{x}{Unsigned hexadecimal (lowercase).}{(2)}
- \lineiii{X}{Unsigned hexadecimal (uppercase).}{(2)}
- \lineiii{e}{Floating point exponential format (lowercase).}{(3)}
- \lineiii{E}{Floating point exponential format (uppercase).}{(3)}
- \lineiii{f}{Floating point decimal format.}{(3)}
- \lineiii{F}{Floating point decimal format.}{(3)}
- \lineiii{g}{Floating point format. Uses exponential format
- if exponent is greater than -4 or less than precision,
- decimal format otherwise.}{(4)}
- \lineiii{G}{Floating point format. Uses exponential format
- if exponent is greater than -4 or less than precision,
- decimal format otherwise.}{(4)}
- \lineiii{c}{Single character (accepts integer or single character
- string).}{}
- \lineiii{r}{String (converts any python object using
- \function{repr()}).}{(5)}
- \lineiii{s}{String (converts any python object using
- \function{str()}).}{(6)}
- \lineiii{\%}{No argument is converted, results in a \character{\%}
- character in the result.}{}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
- \item[(1)]
- The alternate form causes a leading zero (\character{0}) to be
- inserted between left-hand padding and the formatting of the
- number if the leading character of the result is not already a
- zero.
- \item[(2)]
- The alternate form causes a leading \code{'0x'} or \code{'0X'}
- (depending on whether the \character{x} or \character{X} format
- was used) to be inserted between left-hand padding and the
- formatting of the number if the leading character of the result is
- not already a zero.
- \item[(3)]
- The alternate form causes the result to always contain a decimal
- point, even if no digits follow it.
-
- The precision determines the number of digits after the decimal
- point and defaults to 6.
- \item[(4)]
- The alternate form causes the result to always contain a decimal
- point, and trailing zeroes are not removed as they would
- otherwise be.
-
- The precision determines the number of significant digits before
- and after the decimal point and defaults to 6.
- \item[(5)]
- The \code{\%r} conversion was added in Python 2.0.
-
- The precision determines the maximal number of characters used.
- \item[(6)]
- If the object or format provided is a \class{unicode} string,
- the resulting string will also be \class{unicode}.
-
- The precision determines the maximal number of characters used.
-\end{description}
-
-% XXX Examples?
-
-Since Python strings have an explicit length, \code{\%s} conversions
-do not assume that \code{'\e0'} is the end of the string.
-
-For safety reasons, floating point precisions are clipped to 50;
-\code{\%f} conversions for numbers whose absolute value is over 1e25
-are replaced by \code{\%g} conversions.\footnote{
- These numbers are fairly arbitrary. They are intended to
- avoid printing endless strings of meaningless digits without hampering
- correct use and without having to know the exact precision of floating
- point values on a particular machine.
-} All other errors raise exceptions.
-
-Additional string operations are defined in standard modules
-\refmodule{string}\refstmodindex{string}\ and
-\refmodule{re}.\refstmodindex{re}
-
-
-\subsection{XRange Type \label{typesseq-range}}
-
-The \class{range}\obindex{range} type is an immutable sequence which
-is commonly used for looping. The advantage of the \class{range}
-type is that an \class{range} object will always take the same amount
-of memory, no matter the size of the range it represents. There are
-no consistent performance advantages.
-
-XRange objects have very little behavior: they only support indexing,
-iteration, and the \function{len()} function.
-
-
-\subsection{Mutable Sequence Types \label{typesseq-mutable}}
-
-List objects support additional operations that allow in-place
-modification of the object.
-Other mutable sequence types (when added to the language) should
-also support these operations.
-Strings and tuples are immutable sequence types: such objects cannot
-be modified once created.
-The following operations are defined on mutable sequence types (where
-\var{x} is an arbitrary object):
-\indexiii{mutable}{sequence}{types}
-\obindex{list}
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{\var{s}[\var{i}] = \var{x}}
- {item \var{i} of \var{s} is replaced by \var{x}}{}
- \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
- {slice of \var{s} from \var{i} to \var{j}
- is replaced by the contents of the iterable \var{t}}{}
- \lineiii{del \var{s}[\var{i}:\var{j}]}
- {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
- \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}}
- {the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} are replaced by those of \var{t}}{(1)}
- \lineiii{del \var{s}[\var{i}:\var{j}:\var{k}]}
- {removes the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} from the list}{}
- \lineiii{\var{s}.append(\var{x})}
- {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(2)}
- \lineiii{\var{s}.extend(\var{x})}
- {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(3)}
- \lineiii{\var{s}.count(\var{x})}
- {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
- \lineiii{\var{s}.index(\var{x}\optional{, \var{i}\optional{, \var{j}}})}
- {return smallest \var{k} such that \code{\var{s}[\var{k}] == \var{x}} and
- \code{\var{i} <= \var{k} < \var{j}}}{(4)}
- \lineiii{\var{s}.insert(\var{i}, \var{x})}
- {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{(5)}
- \lineiii{\var{s}.pop(\optional{\var{i}})}
- {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(6)}
- \lineiii{\var{s}.remove(\var{x})}
- {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)}
- \lineiii{\var{s}.reverse()}
- {reverses the items of \var{s} in place}{(7)}
- \lineiii{\var{s}.sort(\optional{\var{cmp}\optional{,
- \var{key}\optional{, \var{reverse}}}})}
- {sort the items of \var{s} in place}{(7), (8), (9), (10)}
-\end{tableiii}
-\indexiv{operations on}{mutable}{sequence}{types}
-\indexiii{operations on}{sequence}{types}
-\indexiii{operations on}{list}{type}
-\indexii{subscript}{assignment}
-\indexii{slice}{assignment}
-\indexii{extended slice}{assignment}
-\stindex{del}
-\withsubitem{(list method)}{
- \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()}
- \ttindex{insert()}\ttindex{pop()}\ttindex{remove()}\ttindex{reverse()}
- \ttindex{sort()}}
-\noindent
-Notes:
-\begin{description}
-\item[(1)] \var{t} must have the same length as the slice it is
- replacing.
-
-\item[(2)] The C implementation of Python has historically accepted
- multiple parameters and implicitly joined them into a tuple; this
- no longer works in Python 2.0. Use of this misfeature has been
- deprecated since Python 1.4.
-
-\item[(3)] \var{x} can be any iterable object.
-
-\item[(4)] Raises \exception{ValueError} when \var{x} is not found in
- \var{s}. When a negative index is passed as the second or third parameter
- to the \method{index()} method, the list length is added, as for slice
- indices. If it is still negative, it is truncated to zero, as for
- slice indices. \versionchanged[Previously, \method{index()} didn't
- have arguments for specifying start and stop positions]{2.3}
-
-\item[(5)] When a negative index is passed as the first parameter to
- the \method{insert()} method, the list length is added, as for slice
- indices. If it is still negative, it is truncated to zero, as for
- slice indices. \versionchanged[Previously, all negative indices
- were truncated to zero]{2.3}
-
-\item[(6)] The \method{pop()} method is only supported by the list and
- array types. The optional argument \var{i} defaults to \code{-1},
- so that by default the last item is removed and returned.
-
-\item[(7)] The \method{sort()} and \method{reverse()} methods modify the
- list in place for economy of space when sorting or reversing a large
- list. To remind you that they operate by side effect, they don't return
- the sorted or reversed list.
-
-\item[(8)] The \method{sort()} method takes optional arguments for
- controlling the comparisons.
-
- \var{cmp} specifies a custom comparison function of two arguments
- (list items) which should return a negative, zero or positive number
- depending on whether the first argument is considered smaller than,
- equal to, or larger than the second argument:
- \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
- \function{cmp}(x.lower(), y.lower())}
-
- \var{key} specifies a function of one argument that is used to
- extract a comparison key from each list element:
- \samp{\var{key}=\function{str.lower}}
-
- \var{reverse} is a boolean value. If set to \code{True}, then the
- list elements are sorted as if each comparison were reversed.
-
- In general, the \var{key} and \var{reverse} conversion processes are
- much faster than specifying an equivalent \var{cmp} function. This is
- because \var{cmp} is called multiple times for each list element while
- \var{key} and \var{reverse} touch each element only once.
-
- \versionchanged[Support for \code{None} as an equivalent to omitting
- \var{cmp} was added]{2.3}
-
- \versionchanged[Support for \var{key} and \var{reverse} was added]{2.4}
-
-\item[(9)] Starting with Python 2.3, the \method{sort()} method is
- guaranteed to be stable. A sort is stable if it guarantees not to
- change the relative order of elements that compare equal --- this is
- helpful for sorting in multiple passes (for example, sort by
- department, then by salary grade).
-
-\item[(10)] While a list is being sorted, the effect of attempting to
- mutate, or even inspect, the list is undefined. The C
- implementation of Python 2.3 and newer makes the list appear empty
- for the duration, and raises \exception{ValueError} if it can detect
- that the list has been mutated during a sort.
-\end{description}
-
-\section{Set Types ---
- \class{set}, \class{frozenset}
- \label{types-set}}
-\obindex{set}
-
-A \dfn{set} object is an unordered collection of distinct hashable objects.
-Common uses include membership testing, removing duplicates from a sequence,
-and computing mathematical operations such as intersection, union, difference,
-and symmetric difference.
-\versionadded{2.4}
-
-Like other collections, sets support \code{\var{x} in \var{set}},
-\code{len(\var{set})}, and \code{for \var{x} in \var{set}}. Being an
-unordered collection, sets do not record element position or order of
-insertion. Accordingly, sets do not support indexing, slicing, or
-other sequence-like behavior.
-
-There are currently two builtin set types, \class{set} and \class{frozenset}.
-The \class{set} type is mutable --- the contents can be changed using methods
-like \method{add()} and \method{remove()}. Since it is mutable, it has no
-hash value and cannot be used as either a dictionary key or as an element of
-another set. The \class{frozenset} type is immutable and hashable --- its
-contents cannot be altered after is created; however, it can be used as
-a dictionary key or as an element of another set.
-
-Instances of \class{set} and \class{frozenset} provide the following operations:
-
-\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
- \lineiii{len(\var{s})}{}{cardinality of set \var{s}}
-
- \hline
- \lineiii{\var{x} in \var{s}}{}
- {test \var{x} for membership in \var{s}}
- \lineiii{\var{x} not in \var{s}}{}
- {test \var{x} for non-membership in \var{s}}
- \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}}
- {test whether every element in \var{s} is in \var{t}}
- \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
- {test whether every element in \var{t} is in \var{s}}
-
- \hline
- \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}}
- {new set with elements from both \var{s} and \var{t}}
- \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}}
- {new set with elements common to \var{s} and \var{t}}
- \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}}
- {new set with elements in \var{s} but not in \var{t}}
- \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}}
- {new set with elements in either \var{s} or \var{t} but not both}
- \lineiii{\var{s}.copy()}{}
- {new set with a shallow copy of \var{s}}
-\end{tableiii}
-
-Note, the non-operator versions of \method{union()}, \method{intersection()},
-\method{difference()}, and \method{symmetric_difference()},
-\method{issubset()}, and \method{issuperset()} methods will accept any
-iterable as an argument. In contrast, their operator based counterparts
-require their arguments to be sets. This precludes error-prone constructions
-like \code{set('abc') \&\ 'cbs'} in favor of the more readable
-\code{set('abc').intersection('cbs')}.
-
-Both \class{set} and \class{frozenset} support set to set comparisons.
-Two sets are equal if and only if every element of each set is contained in
-the other (each is a subset of the other).
-A set is less than another set if and only if the first set is a proper
-subset of the second set (is a subset, but is not equal).
-A set is greater than another set if and only if the first set is a proper
-superset of the second set (is a superset, but is not equal).
-
-Instances of \class{set} are compared to instances of \class{frozenset} based
-on their members. For example, \samp{set('abc') == frozenset('abc')} returns
-\code{True}.
-
-The subset and equality comparisons do not generalize to a complete
-ordering function. For example, any two disjoint sets are not equal and
-are not subsets of each other, so \emph{all} of the following return
-\code{False}: \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or
-\code{\var{a}>\var{b}}.
-Accordingly, sets do not implement the \method{__cmp__} method.
-
-Since sets only define partial ordering (subset relationships), the output
-of the \method{list.sort()} method is undefined for lists of sets.
-
-Set elements are like dictionary keys; they need to define both
-\method{__hash__} and \method{__eq__} methods.
-
-Binary operations that mix \class{set} instances with \class{frozenset}
-return the type of the first operand. For example:
-\samp{frozenset('ab') | set('bc')} returns an instance of \class{frozenset}.
-
-The following table lists operations available for \class{set}
-that do not apply to immutable instances of \class{frozenset}:
-
-\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result}
- \lineiii{\var{s}.update(\var{t})}
- {\var{s} |= \var{t}}
- {update set \var{s}, adding elements from \var{t}}
- \lineiii{\var{s}.intersection_update(\var{t})}
- {\var{s} \&= \var{t}}
- {update set \var{s}, keeping only elements found in both \var{s} and \var{t}}
- \lineiii{\var{s}.difference_update(\var{t})}
- {\var{s} -= \var{t}}
- {update set \var{s}, removing elements found in \var{t}}
- \lineiii{\var{s}.symmetric_difference_update(\var{t})}
- {\var{s} \textasciicircum= \var{t}}
- {update set \var{s}, keeping only elements found in either \var{s} or \var{t}
- but not in both}
-
- \hline
- \lineiii{\var{s}.add(\var{x})}{}
- {add element \var{x} to set \var{s}}
- \lineiii{\var{s}.remove(\var{x})}{}
- {remove \var{x} from set \var{s}; raises \exception{KeyError}
- if not present}
- \lineiii{\var{s}.discard(\var{x})}{}
- {removes \var{x} from set \var{s} if present}
- \lineiii{\var{s}.pop()}{}
- {remove and return an arbitrary element from \var{s}; raises
- \exception{KeyError} if empty}
- \lineiii{\var{s}.clear()}{}
- {remove all elements from set \var{s}}
-\end{tableiii}
-
-Note, the non-operator versions of the \method{update()},
-\method{intersection_update()}, \method{difference_update()}, and
-\method{symmetric_difference_update()} methods will accept any iterable
-as an argument.
-
-
-\section{Mapping Types --- \class{dict} \label{typesmapping}}
-\obindex{mapping}
-\obindex{dictionary}
-
-A \dfn{mapping} object maps immutable values to
-arbitrary objects. Mappings are mutable objects. There is currently
-only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
-almost arbitrary values. Only values containing lists, dictionaries
-or other mutable types (that are compared by value rather than by
-object identity) may not be used as keys.
-Numeric types used for keys obey the normal rules for numeric
-comparison: if two numbers compare equal (such as \code{1} and
-\code{1.0}) then they can be used interchangeably to index the same
-dictionary entry.
-
-Dictionaries are created by placing a comma-separated list of
-\code{\var{key}: \var{value}} pairs within braces, for example:
-\code{\{'jack': 4098, 'sjoerd': 4127\}} or
-\code{\{4098: 'jack', 4127: 'sjoerd'\}}.
-
-The following operations are defined on mappings (where \var{a} and
-\var{b} are mappings, \var{k} is a key, and \var{v} and \var{x} are
-arbitrary objects):
-\indexiii{operations on}{mapping}{types}
-\indexiii{operations on}{dictionary}{type}
-\stindex{del}
-\bifuncindex{len}
-\withsubitem{(dictionary method)}{
- \ttindex{clear()}
- \ttindex{copy()}
- \ttindex{has_key()}
- \ttindex{fromkeys()}
- \ttindex{items()}
- \ttindex{keys()}
- \ttindex{update()}
- \ttindex{values()}
- \ttindex{get()}
- \ttindex{setdefault()}
- \ttindex{pop()}
- \ttindex{popitem()}
- \ttindex{iteritems()}
- \ttindex{iterkeys()}
- \ttindex{itervalues()}}
-
-\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes}
- \lineiii{len(\var{a})}{the number of items in \var{a}}{}
- \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1), (10)}
- \lineiii{\var{a}[\var{k}] = \var{v}}
- {set \code{\var{a}[\var{k}]} to \var{v}}
- {}
- \lineiii{del \var{a}[\var{k}]}
- {remove \code{\var{a}[\var{k}]} from \var{a}}
- {(1)}
- \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
- \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
- \lineiii{\var{k} in \var{a}}
- {\code{True} if \var{a} has a key \var{k}, else \code{False}}
- {(2)}
- \lineiii{\var{k} not in \var{a}}
- {Equivalent to \code{not} \var{k} in \var{a}}
- {(2)}
- \lineiii{\var{a}.has_key(\var{k})}
- {Equivalent to \var{k} \code{in} \var{a}, use that form in new code}
- {}
- \lineiii{\var{a}.items()}
- {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
- {(3)}
- \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)}
- \lineiii{\var{a}.update(\optional{\var{b}})}
- {updates \var{a} with key/value pairs from \var{b}, overwriting
- existing keys, returns \code{None}}
- {(9)}
- \lineiii{\var{a}.fromkeys(\var{seq}\optional{, \var{value}})}
- {Creates a new dictionary with keys from \var{seq} and values set to \var{value}}
- {(7)}
- \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(3)}
- \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
- {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
- else \var{x}}
- {(4)}
- \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
- {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
- else \var{x} (also setting it)}
- {(5)}
- \lineiii{\var{a}.pop(\var{k}\optional{, \var{x}})}
- {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
- else \var{x} (and remove k)}
- {(8)}
- \lineiii{\var{a}.popitem()}
- {remove and return an arbitrary (\var{key}, \var{value}) pair}
- {(6)}
- \lineiii{\var{a}.iteritems()}
- {return an iterator over (\var{key}, \var{value}) pairs}
- {(2), (3)}
- \lineiii{\var{a}.iterkeys()}
- {return an iterator over the mapping's keys}
- {(2), (3)}
- \lineiii{\var{a}.itervalues()}
- {return an iterator over the mapping's values}
- {(2), (3)}
-\end{tableiii}
-
-\noindent
-Notes:
-\begin{description}
-\item[(1)] Raises a \exception{KeyError} exception if \var{k} is not
-in the map.
-
-\item[(2)] \versionadded{2.2}
-
-\item[(3)] Keys and values are listed in an arbitrary order which is
-non-random, varies across Python implementations, and depends on the
-dictionary's history of insertions and deletions.
-If \method{items()}, \method{keys()}, \method{values()},
-\method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
-are called with no intervening modifications to the dictionary, the
-lists will directly correspond. This allows the creation of
-\code{(\var{value}, \var{key})} pairs using \function{zip()}:
-\samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same
-relationship holds for the \method{iterkeys()} and
-\method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
-\var{a}.iterkeys())} provides the same value for \code{pairs}.
-Another way to create the same list is \samp{pairs = [(v, k) for (k,
-v) in \var{a}.iteritems()]}.
-
-\item[(4)] Never raises an exception if \var{k} is not in the map,
-instead it returns \var{x}. \var{x} is optional; when \var{x} is not
-provided and \var{k} is not in the map, \code{None} is returned.
-
-\item[(5)] \function{setdefault()} is like \function{get()}, except
-that if \var{k} is missing, \var{x} is both returned and inserted into
-the dictionary as the value of \var{k}. \var{x} defaults to \code{None}.
-
-\item[(6)] \function{popitem()} is useful to destructively iterate
-over a dictionary, as often used in set algorithms. If the dictionary
-is empty, calling \function{popitem()} raises a \exception{KeyError}.
-
-\item[(7)] \function{fromkeys()} is a class method that returns a
-new dictionary. \var{value} defaults to \code{None}. \versionadded{2.3}
-
-\item[(8)] \function{pop()} raises a \exception{KeyError} when no default
-value is given and the key is not found. \versionadded{2.3}
-
-\item[(9)] \function{update()} accepts either another mapping object
-or an iterable of key/value pairs (as a tuple or other iterable of
-length two). If keyword arguments are specified, the mapping is
-then is updated with those key/value pairs:
-\samp{d.update(red=1, blue=2)}.
-\versionchanged[Allowed the argument to be an iterable of key/value
- pairs and allowed keyword arguments]{2.4}
-
-\item[(10)] If a subclass of dict defines a method \method{__missing__},
-if the key \var{k} is not present, the \var{a}[\var{k}] operation calls
-that method with the key \var{k} as argument. The \var{a}[\var{k}]
-operation then returns or raises whatever is returned or raised by the
-\function{__missing__}(\var{k}) call if the key is not present.
-No other operations or methods invoke \method{__missing__}().
-If \method{__missing__} is not defined, \exception{KeyError} is raised.
-\method{__missing__} must be a method; it cannot be an instance variable.
-For an example, see \module{collections}.\class{defaultdict}.
-\versionadded{2.5}
-
-\end{description}
-
-\section{File Objects
- \label{bltin-file-objects}}
-
-File objects\obindex{file} are implemented using C's \code{stdio}
-package and can be created with the built-in constructor
-\function{file()}\bifuncindex{file} described in section
-\ref{built-in-funcs}, ``Built-in Functions.''\footnote{\function{file()}
-is new in Python 2.2. The older built-in \function{open()} is an
-alias for \function{file()}.} File objects are also returned
-by some other built-in functions and methods, such as
-\function{os.popen()} and \function{os.fdopen()} and the
-\method{makefile()} method of socket objects.
-\refstmodindex{os}
-\refbimodindex{socket}
-
-When a file operation fails for an I/O-related reason, the exception
-\exception{IOError} is raised. This includes situations where the
-operation is not defined for some reason, like \method{seek()} on a tty
-device or writing a file opened for reading.
-
-Files have the following methods:
-
-
-\begin{methoddesc}[file]{close}{}
- Close the file. A closed file cannot be read or written any more.
- Any operation which requires that the file be open will raise a
- \exception{ValueError} after the file has been closed. Calling
- \method{close()} more than once is allowed.
-
- As of Python 2.5, you can avoid having to call this method explicitly
- if you use the \keyword{with} statement. For example, the following
- code will automatically close \code{f} when the \keyword{with} block
- is exited:
-
-\begin{verbatim}
-from __future__ import with_statement
-
-with open("hello.txt") as f:
- for line in f:
- print line
-\end{verbatim}
-
- In older versions of Python, you would have needed to do this to get
- the same effect:
-
-\begin{verbatim}
-f = open("hello.txt")
-try:
- for line in f:
- print line
-finally:
- f.close()
-\end{verbatim}
-
- \note{Not all ``file-like'' types in Python support use as a context
- manager for the \keyword{with} statement. If your code is intended to
- work with any file-like object, you can use the \function{closing()}
- function in the \module{contextlib} module instead of using the object
- directly. See section~\ref{context-closing} for details.}
-
-\end{methoddesc}
-
-\begin{methoddesc}[file]{flush}{}
- Flush the internal buffer, like \code{stdio}'s
- \cfunction{fflush()}. This may be a no-op on some file-like
- objects.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{fileno}{}
- \index{file descriptor}
- \index{descriptor, file}
- Return the integer ``file descriptor'' that is used by the
- underlying implementation to request I/O operations from the
- operating system. This can be useful for other, lower level
- interfaces that use file descriptors, such as the
- \refmodule{fcntl}\refbimodindex{fcntl} module or
- \function{os.read()} and friends. \note{File-like objects
- which do not have a real file descriptor should \emph{not} provide
- this method!}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{isatty}{}
- Return \code{True} if the file is connected to a tty(-like) device, else
- \code{False}. \note{If a file-like object is not associated
- with a real file, this method should \emph{not} be implemented.}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{__next__}{}
-A file object is its own iterator, for example \code{iter(\var{f})} returns
-\var{f} (unless \var{f} is closed). When a file is used as an
-iterator, typically in a \keyword{for} loop (for example,
-\code{for line in f: print line}), the \method{__next__()} method is
-called repeatedly. This method returns the next input line, or raises
-\exception{StopIteration} when \EOF{} is hit when the file is open for
-reading (behavior is undefined when the file is open for writing). In
-order to make a \keyword{for} loop the most efficient way of looping
-over the lines of a file (a very common operation), the
-\method{__next__()} method uses a hidden read-ahead buffer. As a
-consequence of using a read-ahead buffer, combining \method{__next__()}
-with other file methods (like \method{readline()}) does not work
-right. However, using \method{seek()} to reposition the file to an
-absolute position will flush the read-ahead buffer.
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{read}{\optional{size}}
- Read at most \var{size} bytes from the file (less if the read hits
- \EOF{} before obtaining \var{size} bytes). If the \var{size}
- argument is negative or omitted, read all data until \EOF{} is
- reached. The bytes are returned as a string object. An empty
- string is returned when \EOF{} is encountered immediately. (For
- certain files, like ttys, it makes sense to continue reading after
- an \EOF{} is hit.) Note that this method may call the underlying
- C function \cfunction{fread()} more than once in an effort to
- acquire as close to \var{size} bytes as possible. Also note that
- when in non-blocking mode, less data than what was requested may
- be returned, even if no \var{size} parameter was given.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{readline}{\optional{size}}
- Read one entire line from the file. A trailing newline character is
- kept in the string (but may be absent when a file ends with an
- incomplete line).\footnote{
- The advantage of leaving the newline on is that
- returning an empty string is then an unambiguous \EOF{}
- indication. It is also possible (in cases where it might
- matter, for example, if you
- want to make an exact copy of a file while scanning its lines)
- to tell whether the last line of a file ended in a newline
- or not (yes this happens!).
- } If the \var{size} argument is present and
- non-negative, it is a maximum byte count (including the trailing
- newline) and an incomplete line may be returned.
- An empty string is returned \emph{only} when \EOF{} is encountered
- immediately. \note{Unlike \code{stdio}'s \cfunction{fgets()}, the
- returned string contains null characters (\code{'\e 0'}) if they
- occurred in the input.}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{readlines}{\optional{sizehint}}
- Read until \EOF{} using \method{readline()} and return a list containing
- the lines thus read. If the optional \var{sizehint} argument is
- present, instead of reading up to \EOF, whole lines totalling
- approximately \var{sizehint} bytes (possibly after rounding up to an
- internal buffer size) are read. Objects implementing a file-like
- interface may choose to ignore \var{sizehint} if it cannot be
- implemented, or cannot be implemented efficiently.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{seek}{offset\optional{, whence}}
- Set the file's current position, like \code{stdio}'s \cfunction{fseek()}.
- The \var{whence} argument is optional and defaults to
- \code{os.SEEK_SET} or \code{0}
- (absolute file positioning); other values are \code{os.SEEK_CUR} or \code{1}
- (seek
- relative to the current position) and \code{os.SEEK_END} or \code{2}
- (seek relative to the
- file's end). There is no return value. Note that if the file is
- opened for appending (mode \code{'a'} or \code{'a+'}), any
- \method{seek()} operations will be undone at the next write. If the
- file is only opened for writing in append mode (mode \code{'a'}),
- this method is essentially a no-op, but it remains useful for files
- opened in append mode with reading enabled (mode \code{'a+'}). If the
- file is opened in text mode (without \code{'b'}), only offsets returned
- by \method{tell()} are legal. Use of other offsets causes undefined
- behavior.
-
- Note that not all file objects are seekable.
- \versionchanged{Passing float values as offset has been deprecated}[2.6]
-\end{methoddesc}
-
-\begin{methoddesc}[file]{tell}{}
- Return the file's current position, like \code{stdio}'s
- \cfunction{ftell()}.
-
- \note{On Windows, \method{tell()} can return illegal values (after an
- \cfunction{fgets()}) when reading files with \UNIX{}-style line-endings.
- Use binary mode (\code{'rb'}) to circumvent this problem.}
-\end{methoddesc}
-
-\begin{methoddesc}[file]{truncate}{\optional{size}}
- Truncate the file's size. If the optional \var{size} argument is
- present, the file is truncated to (at most) that size. The size
- defaults to the current position. The current file position is
- not changed. Note that if a specified size exceeds the file's
- current size, the result is platform-dependent: possibilities
- include that the file may remain unchanged, increase to the specified
- size as if zero-filled, or increase to the specified size with
- undefined new content.
- Availability: Windows, many \UNIX{} variants.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{write}{str}
- Write a string to the file. There is no return value. Due to
- buffering, the string may not actually show up in the file until
- the \method{flush()} or \method{close()} method is called.
-\end{methoddesc}
-
-\begin{methoddesc}[file]{writelines}{sequence}
- Write a sequence of strings to the file. The sequence can be any
- iterable object producing strings, typically a list of strings.
- There is no return value.
- (The name is intended to match \method{readlines()};
- \method{writelines()} does not add line separators.)
-\end{methoddesc}
-
-
-Files support the iterator protocol. Each iteration returns the same
-result as \code{\var{file}.readline()}, and iteration ends when the
-\method{readline()} method returns an empty string.
-
-
-File objects also offer a number of other interesting attributes.
-These are not required for file-like objects, but should be
-implemented if they make sense for the particular object.
-
-\begin{memberdesc}[file]{closed}
-bool indicating the current state of the file object. This is a
-read-only attribute; the \method{close()} method changes the value.
-It may not be available on all file-like objects.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{encoding}
-The encoding that this file uses. When Unicode strings are written
-to a file, they will be converted to byte strings using this encoding.
-In addition, when the file is connected to a terminal, the attribute
-gives the encoding that the terminal is likely to use (that
-information might be incorrect if the user has misconfigured the
-terminal). The attribute is read-only and may not be present on
-all file-like objects. It may also be \code{None}, in which case
-the file uses the system default encoding for converting Unicode
-strings.
-
-\versionadded{2.3}
-\end{memberdesc}
-
-\begin{memberdesc}[file]{mode}
-The I/O mode for the file. If the file was created using the
-\function{open()} built-in function, this will be the value of the
-\var{mode} parameter. This is a read-only attribute and may not be
-present on all file-like objects.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{name}
-If the file object was created using \function{open()}, the name of
-the file. Otherwise, some string that indicates the source of the
-file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
-attribute and may not be present on all file-like objects.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{newlines}
-If Python was built with the \longprogramopt{with-universal-newlines}
-option to \program{configure} (the default) this read-only attribute
-exists, and for files opened in
-universal newline read mode it keeps track of the types of newlines
-encountered while reading the file. The values it can take are
-\code{'\e r'}, \code{'\e n'}, \code{'\e r\e n'}, \code{None} (unknown,
-no newlines read yet) or a tuple containing all the newline
-types seen, to indicate that multiple
-newline conventions were encountered. For files not opened in universal
-newline read mode the value of this attribute will be \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[file]{softspace}
-Boolean that indicates whether a space character needs to be printed
-before another value when using the \keyword{print} statement.
-Classes that are trying to simulate a file object should also have a
-writable \member{softspace} attribute, which should be initialized to
-zero. This will be automatic for most classes implemented in Python
-(care may be needed for objects that override attribute access); types
-implemented in C will have to provide a writable
-\member{softspace} attribute.
-\note{This attribute is not used to control the
-\keyword{print} statement, but to allow the implementation of
-\keyword{print} to keep track of its internal state.}
-\end{memberdesc}
-
-
-\section{Context Manager Types \label{typecontextmanager}}
-
-\versionadded{2.5}
-\index{context manager}
-\index{context management protocol}
-\index{protocol!context management}
-
-Python's \keyword{with} statement supports the concept of a runtime
-context defined by a context manager. This is implemented using
-two separate methods that allow user-defined classes to define
-a runtime context that is entered before the statement body is
-executed and exited when the statement ends.
-
-The \dfn{context management protocol} consists of a pair of
-methods that need to be provided for a context manager object to
-define a runtime context:
-
-\begin{methoddesc}[context manager]{__enter__}{}
- Enter the runtime context and return either this object or another
- object related to the runtime context. The value returned by this
- method is bound to the identifier in the \keyword{as} clause of
- \keyword{with} statements using this context manager.
-
- An example of a context manager that returns itself is a file object.
- File objects return themselves from __enter__() to allow
- \function{open()} to be used as the context expression in a
- \keyword{with} statement.
-
- An example of a context manager that returns a related
- object is the one returned by \code{decimal.Context.get_manager()}.
- These managers set the active decimal context to a copy of the
- original decimal context and then return the copy. This allows
- changes to be made to the current decimal context in the body of
- the \keyword{with} statement without affecting code outside
- the \keyword{with} statement.
-\end{methoddesc}
-
-\begin{methoddesc}[context manager]{__exit__}{exc_type, exc_val, exc_tb}
- Exit the runtime context and return a Boolean flag indicating if any
- expection that occurred should be suppressed. If an exception
- occurred while executing the body of the \keyword{with} statement, the
- arguments contain the exception type, value and traceback information.
- Otherwise, all three arguments are \code{None}.
-
- Returning a true value from this method will cause the \keyword{with}
- statement to suppress the exception and continue execution with the
- statement immediately following the \keyword{with} statement. Otherwise
- the exception continues propagating after this method has finished
- executing. Exceptions that occur during execution of this method will
- replace any exception that occurred in the body of the \keyword{with}
- statement.
-
- The exception passed in should never be reraised explicitly - instead,
- this method should return a false value to indicate that the method
- completed successfully and does not want to suppress the raised
- exception. This allows context management code (such as
- \code{contextlib.nested}) to easily detect whether or not an
- \method{__exit__()} method has actually failed.
-\end{methoddesc}
-
-Python defines several context managers to support easy thread
-synchronisation, prompt closure of files or other objects, and
-simpler manipulation of the active decimal arithmetic
-context. The specific types are not treated specially beyond
-their implementation of the context management protocol.
-
-Python's generators and the \code{contextlib.contextfactory} decorator
-provide a convenient way to implement these protocols. If a generator
-function is decorated with the \code{contextlib.contextfactory}
-decorator, it will return a context manager implementing the necessary
-\method{__enter__()} and \method{__exit__()} methods, rather than the
-iterator produced by an undecorated generator function.
-
-Note that there is no specific slot for any of these methods in the
-type structure for Python objects in the Python/C API. Extension
-types wanting to define these methods must provide them as a normal
-Python accessible method. Compared to the overhead of setting up the
-runtime context, the overhead of a single class dictionary lookup
-is negligible.
-
-
-\section{Other Built-in Types \label{typesother}}
-
-The interpreter supports several other kinds of objects.
-Most of these support only one or two operations.
-
-
-\subsection{Modules \label{typesmodules}}
-
-The only special operation on a module is attribute access:
-\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
-accesses a name defined in \var{m}'s symbol table. Module attributes
-can be assigned to. (Note that the \keyword{import} statement is not,
-strictly speaking, an operation on a module object; \code{import
-\var{foo}} does not require a module object named \var{foo} to exist,
-rather it requires an (external) \emph{definition} for a module named
-\var{foo} somewhere.)
-
-A special member of every module is \member{__dict__}.
-This is the dictionary containing the module's symbol table.
-Modifying this dictionary will actually change the module's symbol
-table, but direct assignment to the \member{__dict__} attribute is not
-possible (you can write \code{\var{m}.__dict__['a'] = 1}, which
-defines \code{\var{m}.a} to be \code{1}, but you can't write
-\code{\var{m}.__dict__ = \{\}}). Modifying \member{__dict__} directly
-is not recommended.
-
-Modules built into the interpreter are written like this:
-\code{<module 'sys' (built-in)>}. If loaded from a file, they are
-written as \code{<module 'os' from
-'/usr/local/lib/python\shortversion/os.pyc'>}.
-
-
-\subsection{Classes and Class Instances \label{typesobjects}}
-\nodename{Classes and Instances}
-
-See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
-Reference Manual} for these.
-
-
-\subsection{Functions \label{typesfunctions}}
-
-Function objects are created by function definitions. The only
-operation on a function object is to call it:
-\code{\var{func}(\var{argument-list})}.
-
-There are really two flavors of function objects: built-in functions
-and user-defined functions. Both support the same operation (to call
-the function), but the implementation is different, hence the
-different object types.
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
-information.
-
-\subsection{Methods \label{typesmethods}}
-\obindex{method}
-
-Methods are functions that are called using the attribute notation.
-There are two flavors: built-in methods (such as \method{append()} on
-lists) and class instance methods. Built-in methods are described
-with the types that support them.
-
-The implementation adds two special read-only attributes to class
-instance methods: \code{\var{m}.im_self} is the object on which the
-method operates, and \code{\var{m}.im_func} is the function
-implementing the method. Calling \code{\var{m}(\var{arg-1},
-\var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
-calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
-\var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
-
-Class instance methods are either \emph{bound} or \emph{unbound},
-referring to whether the method was accessed through an instance or a
-class, respectively. When a method is unbound, its \code{im_self}
-attribute will be \code{None} and if called, an explicit \code{self}
-object must be passed as the first argument. In this case,
-\code{self} must be an instance of the unbound method's class (or a
-subclass of that class), otherwise a \exception{TypeError} is raised.
-
-Like function objects, methods objects support getting
-arbitrary attributes. However, since method attributes are actually
-stored on the underlying function object (\code{meth.im_func}),
-setting method attributes on either bound or unbound methods is
-disallowed. Attempting to set a method attribute results in a
-\exception{TypeError} being raised. In order to set a method attribute,
-you need to explicitly set it on the underlying function object:
-
-\begin{verbatim}
-class C:
- def method(self):
- pass
-
-c = C()
-c.method.im_func.whoami = 'my name is c'
-\end{verbatim}
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
-information.
-
-
-\subsection{Code Objects \label{bltin-code-objects}}
-\obindex{code}
-
-Code objects are used by the implementation to represent
-``pseudo-compiled'' executable Python code such as a function body.
-They differ from function objects because they don't contain a
-reference to their global execution environment. Code objects are
-returned by the built-in \function{compile()} function and can be
-extracted from function objects through their \member{__code__}
-attribute.
-\bifuncindex{compile}
-\withsubitem{(function object attribute)}{\ttindex{__code__}}
-
-A code object can be executed or evaluated by passing it (instead of a
-source string) to the \function{exec()} or \function{eval()}
-built-in functions.
-\bifuncindex{exec}
-\bifuncindex{eval}
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
-information.
-
-
-\subsection{Type Objects \label{bltin-type-objects}}
-
-Type objects represent the various object types. An object's type is
-accessed by the built-in function \function{type()}. There are no special
-operations on types. The standard module \refmodule{types} defines names
-for all standard built-in types.
-\bifuncindex{type}
-\refstmodindex{types}
-
-Types are written like this: \code{<type 'int'>}.
-
-
-\subsection{The Null Object \label{bltin-null-object}}
-
-This object is returned by functions that don't explicitly return a
-value. It supports no special operations. There is exactly one null
-object, named \code{None} (a built-in name).
-
-It is written as \code{None}.
-
-
-\subsection{The Ellipsis Object \label{bltin-ellipsis-object}}
-
-This object is mostly used by extended slice notation (see the
-\citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
-special operations. There is exactly one ellipsis object, named
-\constant{Ellipsis} (a built-in name).
-
-It is written as \code{Ellipsis} or \code{...}.
-
-\subsection{Boolean Values}
-
-Boolean values are the two constant objects \code{False} and
-\code{True}. They are used to represent truth values (although other
-values can also be considered false or true). In numeric contexts
-(for example when used as the argument to an arithmetic operator),
-they behave like the integers 0 and 1, respectively. The built-in
-function \function{bool()} can be used to cast any value to a Boolean,
-if the value can be interpreted as a truth value (see section Truth
-Value Testing above).
-
-They are written as \code{False} and \code{True}, respectively.
-\index{False}
-\index{True}
-\indexii{Boolean}{values}
-
-
-\subsection{Internal Objects \label{typesinternal}}
-
-See the \citetitle[../ref/ref.html]{Python Reference Manual} for this
-information. It describes stack frame objects, traceback objects, and
-slice objects.
-
-
-\section{Special Attributes \label{specialattrs}}
-
-The implementation adds a few special read-only attributes to several
-object types, where they are relevant. Some of these are not reported
-by the \function{dir()} built-in function.
-
-\begin{memberdesc}[object]{__dict__}
-A dictionary or other mapping object used to store an
-object's (writable) attributes.
-\end{memberdesc}
-
-\begin{memberdesc}[instance]{__class__}
-The class to which a class instance belongs.
-\end{memberdesc}
-
-\begin{memberdesc}[class]{__bases__}
-The tuple of base classes of a class object. If there are no base
-classes, this will be an empty tuple.
-\end{memberdesc}
-
-\begin{memberdesc}[class]{__name__}
-The name of the class or type.
-\end{memberdesc}
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
deleted file mode 100644
index 9948cb7..0000000
--- a/Doc/lib/libstring.tex
+++ /dev/null
@@ -1,425 +0,0 @@
-\section{\module{string} ---
- Common string operations}
-
-\declaremodule{standard}{string}
-\modulesynopsis{Common string operations.}
-
-The \module{string} module contains a number of useful constants and classes,
-as well as some deprecated legacy functions that are also available as methods
-on strings. See the module \refmodule{re}\refstmodindex{re} for string
-functions based on regular expressions.
-
-\subsection{String constants}
-
-The constants defined in this module are:
-
-\begin{datadesc}{ascii\_letters}
- The concatenation of the \constant{ascii_lowercase} and
- \constant{ascii_uppercase} constants described below. This value is
- not locale-dependent.
-\end{datadesc}
-
-\begin{datadesc}{ascii\_lowercase}
- The lowercase letters \code{'abcdefghijklmnopqrstuvwxyz'}. This
- value is not locale-dependent and will not change.
-\end{datadesc}
-
-\begin{datadesc}{ascii\_uppercase}
- The uppercase letters \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. This
- value is not locale-dependent and will not change.
-\end{datadesc}
-
-\begin{datadesc}{digits}
- The string \code{'0123456789'}.
-\end{datadesc}
-
-\begin{datadesc}{hexdigits}
- The string \code{'0123456789abcdefABCDEF'}.
-\end{datadesc}
-
-\begin{datadesc}{octdigits}
- The string \code{'01234567'}.
-\end{datadesc}
-
-\begin{datadesc}{punctuation}
- String of \ASCII{} characters which are considered punctuation
- characters in the \samp{C} locale.
-\end{datadesc}
-
-\begin{datadesc}{printable}
- String of characters which are considered printable. This is a
- combination of \constant{digits}, \constant{letters},
- \constant{punctuation}, and \constant{whitespace}.
-\end{datadesc}
-
-\begin{datadesc}{whitespace}
- A string containing all characters that are considered whitespace.
- On most systems this includes the characters space, tab, linefeed,
- return, formfeed, and vertical tab. Do not change its definition ---
- the effect on the routines \function{strip()} and \function{split()}
- is undefined.
-\end{datadesc}
-
-\subsection{Template strings}
-
-Templates provide simpler string substitutions as described in \pep{292}.
-Instead of the normal \samp{\%}-based substitutions, Templates support
-\samp{\$}-based substitutions, using the following rules:
-
-\begin{itemize}
-\item \samp{\$\$} is an escape; it is replaced with a single \samp{\$}.
-
-\item \samp{\$identifier} names a substitution placeholder matching a mapping
- key of "identifier". By default, "identifier" must spell a Python
- identifier. The first non-identifier character after the \samp{\$}
- character terminates this placeholder specification.
-
-\item \samp{\$\{identifier\}} is equivalent to \samp{\$identifier}. It is
- required when valid identifier characters follow the placeholder but are
- not part of the placeholder, such as "\$\{noun\}ification".
-\end{itemize}
-
-Any other appearance of \samp{\$} in the string will result in a
-\exception{ValueError} being raised.
-
-\versionadded{2.4}
-
-The \module{string} module provides a \class{Template} class that implements
-these rules. The methods of \class{Template} are:
-
-\begin{classdesc}{Template}{template}
-The constructor takes a single argument which is the template string.
-\end{classdesc}
-
-\begin{methoddesc}[Template]{substitute}{mapping\optional{, **kws}}
-Performs the template substitution, returning a new string. \var{mapping} is
-any dictionary-like object with keys that match the placeholders in the
-template. Alternatively, you can provide keyword arguments, where the
-keywords are the placeholders. When both \var{mapping} and \var{kws} are
-given and there are duplicates, the placeholders from \var{kws} take
-precedence.
-\end{methoddesc}
-
-\begin{methoddesc}[Template]{safe_substitute}{mapping\optional{, **kws}}
-Like \method{substitute()}, except that if placeholders are missing from
-\var{mapping} and \var{kws}, instead of raising a \exception{KeyError}
-exception, the original placeholder will appear in the resulting string
-intact. Also, unlike with \method{substitute()}, any other appearances of the
-\samp{\$} will simply return \samp{\$} instead of raising
-\exception{ValueError}.
-
-While other exceptions may still occur, this method is called ``safe'' because
-substitutions always tries to return a usable string instead of raising an
-exception. In another sense, \method{safe_substitute()} may be anything other
-than safe, since it will silently ignore malformed templates containing
-dangling delimiters, unmatched braces, or placeholders that are not valid
-Python identifiers.
-\end{methoddesc}
-
-\class{Template} instances also provide one public data attribute:
-
-\begin{memberdesc}[string]{template}
-This is the object passed to the constructor's \var{template} argument. In
-general, you shouldn't change it, but read-only access is not enforced.
-\end{memberdesc}
-
-Here is an example of how to use a Template:
-
-\begin{verbatim}
->>> from string import Template
->>> s = Template('$who likes $what')
->>> s.substitute(who='tim', what='kung pao')
-'tim likes kung pao'
->>> d = dict(who='tim')
->>> Template('Give $who $100').substitute(d)
-Traceback (most recent call last):
-[...]
-ValueError: Invalid placeholder in string: line 1, col 10
->>> Template('$who likes $what').substitute(d)
-Traceback (most recent call last):
-[...]
-KeyError: 'what'
->>> Template('$who likes $what').safe_substitute(d)
-'tim likes $what'
-\end{verbatim}
-
-Advanced usage: you can derive subclasses of \class{Template} to customize the
-placeholder syntax, delimiter character, or the entire regular expression used
-to parse template strings. To do this, you can override these class
-attributes:
-
-\begin{itemize}
-\item \var{delimiter} -- This is the literal string describing a placeholder
- introducing delimiter. The default value \samp{\$}. Note that this
- should \emph{not} be a regular expression, as the implementation will
- call \method{re.escape()} on this string as needed.
-\item \var{idpattern} -- This is the regular expression describing the pattern
- for non-braced placeholders (the braces will be added automatically as
- appropriate). The default value is the regular expression
- \samp{[_a-z][_a-z0-9]*}.
-\end{itemize}
-
-Alternatively, you can provide the entire regular expression pattern by
-overriding the class attribute \var{pattern}. If you do this, the value must
-be a regular expression object with four named capturing groups. The
-capturing groups correspond to the rules given above, along with the invalid
-placeholder rule:
-
-\begin{itemize}
-\item \var{escaped} -- This group matches the escape sequence,
- e.g. \samp{\$\$}, in the default pattern.
-\item \var{named} -- This group matches the unbraced placeholder name; it
- should not include the delimiter in capturing group.
-\item \var{braced} -- This group matches the brace enclosed placeholder name;
- it should not include either the delimiter or braces in the capturing
- group.
-\item \var{invalid} -- This group matches any other delimiter pattern (usually
- a single delimiter), and it should appear last in the regular
- expression.
-\end{itemize}
-
-\subsection{String functions}
-
-The following functions are available to operate on string and Unicode
-objects. They are not available as string methods.
-
-\begin{funcdesc}{capwords}{s}
- Split the argument into words using \function{split()}, capitalize
- each word using \function{capitalize()}, and join the capitalized
- words using \function{join()}. Note that this replaces runs of
- whitespace characters by a single space, and removes leading and
- trailing whitespace.
-\end{funcdesc}
-
-\begin{funcdesc}{maketrans}{from, to}
- Return a translation table suitable for passing to
- \function{translate()}, that will map
- each character in \var{from} into the character at the same position
- in \var{to}; \var{from} and \var{to} must have the same length.
-
- \warning{Don't use strings derived from \constant{lowercase}
- and \constant{uppercase} as arguments; in some locales, these don't have
- the same length. For case conversions, always use
- \function{lower()} and \function{upper()}.}
-\end{funcdesc}
-
-\subsection{Deprecated string functions}
-
-The following list of functions are also defined as methods of string and
-Unicode objects; see ``String Methods'' (section
-\ref{string-methods}) for more information on those. You should consider
-these functions as deprecated, although they will not be removed until Python
-3.0. The functions defined in this module are:
-
-\begin{funcdesc}{atof}{s}
- \deprecated{2.0}{Use the \function{float()} built-in function.}
- Convert a string to a floating point number. The string must have
- the standard syntax for a floating point literal in Python,
- optionally preceded by a sign (\samp{+} or \samp{-}). Note that
- this behaves identical to the built-in function
- \function{float()}\bifuncindex{float} when passed a string.
-
- \note{When passing in a string, values for NaN\index{NaN}
- and Infinity\index{Infinity} may be returned, depending on the
- underlying C library. The specific set of strings accepted which
- cause these values to be returned depends entirely on the C library
- and is known to vary.}
-\end{funcdesc}
-
-\begin{funcdesc}{atoi}{s\optional{, base}}
- \deprecated{2.0}{Use the \function{int()} built-in function.}
- Convert string \var{s} to an integer in the given \var{base}. The
- string must consist of one or more digits, optionally preceded by a
- sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it
- is 0, a default base is chosen depending on the leading characters
- of the string (after stripping the sign): \samp{0x} or \samp{0X}
- means 16, \samp{0} means 8, anything else means 10. If \var{base}
- is 16, a leading \samp{0x} or \samp{0X} is always accepted, though
- not required. This behaves identically to the built-in function
- \function{int()} when passed a string. (Also note: for a more
- flexible interpretation of numeric literals, use the built-in
- function \function{eval()}\bifuncindex{eval}.)
-\end{funcdesc}
-
-\begin{funcdesc}{atol}{s\optional{, base}}
- \deprecated{2.0}{Use the \function{long()} built-in function.}
- Convert string \var{s} to a long integer in the given \var{base}.
- The string must consist of one or more digits, optionally preceded
- by a sign (\samp{+} or \samp{-}). The \var{base} argument has the
- same meaning as for \function{atoi()}. A trailing \samp{l} or
- \samp{L} is not allowed, except if the base is 0. Note that when
- invoked without \var{base} or with \var{base} set to 10, this
- behaves identical to the built-in function
- \function{long()}\bifuncindex{long} when passed a string.
-\end{funcdesc}
-
-\begin{funcdesc}{capitalize}{word}
- Return a copy of \var{word} with only its first character capitalized.
-\end{funcdesc}
-
-\begin{funcdesc}{expandtabs}{s\optional{, tabsize}}
- Expand tabs in a string replacing them by one or more spaces,
- depending on the current column and the given tab size. The column
- number is reset to zero after each newline occurring in the string.
- This doesn't understand other non-printing characters or escape
- sequences. The tab size defaults to 8.
-\end{funcdesc}
-
-\begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}}
- Return the lowest index in \var{s} where the substring \var{sub} is
- found such that \var{sub} is wholly contained in
- \code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure.
- Defaults for \var{start} and \var{end} and interpretation of
- negative values is the same as for slices.
-\end{funcdesc}
-
-\begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}}
- Like \function{find()} but find the highest index.
-\end{funcdesc}
-
-\begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}}
- Like \function{find()} but raise \exception{ValueError} when the
- substring is not found.
-\end{funcdesc}
-
-\begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}}
- Like \function{rfind()} but raise \exception{ValueError} when the
- substring is not found.
-\end{funcdesc}
-
-\begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}}
- Return the number of (non-overlapping) occurrences of substring
- \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}.
- Defaults for \var{start} and \var{end} and interpretation of
- negative values are the same as for slices.
-\end{funcdesc}
-
-\begin{funcdesc}{lower}{s}
- Return a copy of \var{s}, but with upper case letters converted to
- lower case.
-\end{funcdesc}
-
-\begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}}
- Return a list of the words of the string \var{s}. If the optional
- second argument \var{sep} is absent or \code{None}, the words are
- separated by arbitrary strings of whitespace characters (space, tab,
- newline, return, formfeed). If the second argument \var{sep} is
- present and not \code{None}, it specifies a string to be used as the
- word separator. The returned list will then have one more item
- than the number of non-overlapping occurrences of the separator in
- the string. The optional third argument \var{maxsplit} defaults to
- 0. If it is nonzero, at most \var{maxsplit} number of splits occur,
- and the remainder of the string is returned as the final element of
- the list (thus, the list will have at most \code{\var{maxsplit}+1}
- elements).
-
- The behavior of split on an empty string depends on the value of \var{sep}.
- If \var{sep} is not specified, or specified as \code{None}, the result will
- be an empty list. If \var{sep} is specified as any string, the result will
- be a list containing one element which is an empty string.
-\end{funcdesc}
-
-\begin{funcdesc}{rsplit}{s\optional{, sep\optional{, maxsplit}}}
- Return a list of the words of the string \var{s}, scanning \var{s}
- from the end. To all intents and purposes, the resulting list of
- words is the same as returned by \function{split()}, except when the
- optional third argument \var{maxsplit} is explicitly specified and
- nonzero. When \var{maxsplit} is nonzero, at most \var{maxsplit}
- number of splits -- the \emph{rightmost} ones -- occur, and the remainder
- of the string is returned as the first element of the list (thus, the
- list will have at most \code{\var{maxsplit}+1} elements).
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}}
- This function behaves identically to \function{split()}. (In the
- past, \function{split()} was only used with one argument, while
- \function{splitfields()} was only used with two arguments.)
-\end{funcdesc}
-
-\begin{funcdesc}{join}{words\optional{, sep}}
- Concatenate a list or tuple of words with intervening occurrences of
- \var{sep}. The default value for \var{sep} is a single space
- character. It is always true that
- \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})}
- equals \var{s}.
-\end{funcdesc}
-
-\begin{funcdesc}{joinfields}{words\optional{, sep}}
- This function behaves identically to \function{join()}. (In the past,
- \function{join()} was only used with one argument, while
- \function{joinfields()} was only used with two arguments.)
- Note that there is no \method{joinfields()} method on string
- objects; use the \method{join()} method instead.
-\end{funcdesc}
-
-\begin{funcdesc}{lstrip}{s\optional{, chars}}
-Return a copy of the string with leading characters removed. If
-\var{chars} is omitted or \code{None}, whitespace characters are
-removed. If given and not \code{None}, \var{chars} must be a string;
-the characters in the string will be stripped from the beginning of
-the string this method is called on.
-\versionchanged[The \var{chars} parameter was added. The \var{chars}
-parameter cannot be passed in earlier 2.2 versions]{2.2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{rstrip}{s\optional{, chars}}
-Return a copy of the string with trailing characters removed. If
-\var{chars} is omitted or \code{None}, whitespace characters are
-removed. If given and not \code{None}, \var{chars} must be a string;
-the characters in the string will be stripped from the end of the
-string this method is called on.
-\versionchanged[The \var{chars} parameter was added. The \var{chars}
-parameter cannot be passed in earlier 2.2 versions]{2.2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{strip}{s\optional{, chars}}
-Return a copy of the string with leading and trailing characters
-removed. If \var{chars} is omitted or \code{None}, whitespace
-characters are removed. If given and not \code{None}, \var{chars}
-must be a string; the characters in the string will be stripped from
-the both ends of the string this method is called on.
-\versionchanged[The \var{chars} parameter was added. The \var{chars}
-parameter cannot be passed in earlier 2.2 versions]{2.2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{swapcase}{s}
- Return a copy of \var{s}, but with lower case letters
- converted to upper case and vice versa.
-\end{funcdesc}
-
-\begin{funcdesc}{translate}{s, table\optional{, deletechars}}
- Delete all characters from \var{s} that are in \var{deletechars} (if
- present), and then translate the characters using \var{table}, which
- must be a 256-character string giving the translation for each
- character value, indexed by its ordinal. If \var{table} is \code{None},
- then only the character deletion step is performed.
-\end{funcdesc}
-
-\begin{funcdesc}{upper}{s}
- Return a copy of \var{s}, but with lower case letters converted to
- upper case.
-\end{funcdesc}
-
-\begin{funcdesc}{ljust}{s, width}
-\funcline{rjust}{s, width}
-\funcline{center}{s, width}
- These functions respectively left-justify, right-justify and center
- a string in a field of given width. They return a string that is at
- least \var{width} characters wide, created by padding the string
- \var{s} with spaces until the given width on the right, left or both
- sides. The string is never truncated.
-\end{funcdesc}
-
-\begin{funcdesc}{zfill}{s, width}
- Pad a numeric string on the left with zero digits until the given
- width is reached. Strings starting with a sign are handled
- correctly.
-\end{funcdesc}
-
-\begin{funcdesc}{replace}{str, old, new\optional{, maxreplace}}
- Return a copy of string \var{str} with all occurrences of substring
- \var{old} replaced by \var{new}. If the optional argument
- \var{maxreplace} is given, the first \var{maxreplace} occurrences are
- replaced.
-\end{funcdesc}
diff --git a/Doc/lib/libstringio.tex b/Doc/lib/libstringio.tex
deleted file mode 100644
index 73ff0e4..0000000
--- a/Doc/lib/libstringio.tex
+++ /dev/null
@@ -1,125 +0,0 @@
-\section{\module{StringIO} ---
- Read and write strings as files}
-
-\declaremodule{standard}{StringIO}
-\modulesynopsis{Read and write strings as if they were files.}
-
-
-This module implements a file-like class, \class{StringIO},
-that reads and writes a string buffer (also known as \emph{memory
-files}). See the description of file objects for operations (section
-\ref{bltin-file-objects}).
-
-\begin{classdesc}{StringIO}{\optional{buffer}}
-When a \class{StringIO} object is created, it can be initialized
-to an existing string by passing the string to the constructor.
-If no string is given, the \class{StringIO} will start empty.
-In both cases, the initial file position starts at zero.
-
-The \class{StringIO} object can accept either Unicode or 8-bit
-strings, but mixing the two may take some care. If both are used,
-8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that
-use the 8th bit) will cause a \exception{UnicodeError} to be raised
-when \method{getvalue()} is called.
-\end{classdesc}
-
-The following methods of \class{StringIO} objects require special
-mention:
-
-\begin{methoddesc}{getvalue}{}
-Retrieve the entire contents of the ``file'' at any time before the
-\class{StringIO} object's \method{close()} method is called. See the
-note above for information about mixing Unicode and 8-bit strings;
-such mixing can cause this method to raise \exception{UnicodeError}.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
-Free the memory buffer.
-\end{methoddesc}
-
-Example usage:
-
-\begin{verbatim}
-import StringIO
-
-output = StringIO.StringIO()
-output.write('First line.\n')
-print >>output, 'Second line.'
-
-# Retrieve file contents -- this will be
-# 'First line.\nSecond line.\n'
-contents = output.getvalue()
-
-# Close object and discard memory buffer --
-# .getvalue() will now raise an exception.
-output.close()
-\end{verbatim}
-
-
-\section{\module{cStringIO} ---
- Faster version of \module{StringIO}}
-
-\declaremodule{builtin}{cStringIO}
-\modulesynopsis{Faster version of \module{StringIO}, but not
- subclassable.}
-\moduleauthor{Jim Fulton}{jim@zope.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The module \module{cStringIO} provides an interface similar to that of
-the \refmodule{StringIO} module. Heavy use of \class{StringIO.StringIO}
-objects can be made more efficient by using the function
-\function{StringIO()} from this module instead.
-
-Since this module provides a factory function which returns objects of
-built-in types, there's no way to build your own version using
-subclassing. Use the original \refmodule{StringIO} module in that case.
-
-Unlike the memory files implemented by the \refmodule{StringIO}
-module, those provided by this module are not able to accept Unicode
-strings that cannot be encoded as plain \ASCII{} strings.
-
-Calling \function{StringIO()} with a Unicode string parameter populates
-the object with the buffer representation of the Unicode string, instead of
-encoding the string.
-
-Another difference from the \refmodule{StringIO} module is that calling
-\function{StringIO()} with a string parameter creates a read-only object.
-Unlike an object created without a string parameter, it does not have
-write methods. These objects are not generally visible. They turn up in
-tracebacks as \class{StringI} and \class{StringO}.
-
-The following data objects are provided as well:
-
-
-\begin{datadesc}{InputType}
- The type object of the objects created by calling
- \function{StringIO} with a string parameter.
-\end{datadesc}
-
-\begin{datadesc}{OutputType}
- The type object of the objects returned by calling
- \function{StringIO} with no parameters.
-\end{datadesc}
-
-
-There is a C API to the module as well; refer to the module source for
-more information.
-
-Example usage:
-
-\begin{verbatim}
-import cStringIO
-
-output = cStringIO.StringIO()
-output.write('First line.\n')
-print >>output, 'Second line.'
-
-# Retrieve file contents -- this will be
-# 'First line.\nSecond line.\n'
-contents = output.getvalue()
-
-# Close object and discard memory buffer --
-# .getvalue() will now raise an exception.
-output.close()
-\end{verbatim}
-
diff --git a/Doc/lib/libstringprep.tex b/Doc/lib/libstringprep.tex
deleted file mode 100644
index 2614314..0000000
--- a/Doc/lib/libstringprep.tex
+++ /dev/null
@@ -1,136 +0,0 @@
-\section{\module{stringprep} ---
- Internet String Preparation}
-
-\declaremodule{standard}{stringprep}
-\modulesynopsis{String preparation, as per RFC 3453}
-\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.3}
-
-When identifying things (such as host names) in the internet, it is
-often necessary to compare such identifications for
-``equality''. Exactly how this comparison is executed may depend on
-the application domain, e.g. whether it should be case-insensitive or
-not. It may be also necessary to restrict the possible
-identifications, to allow only identifications consisting of
-``printable'' characters.
-
-\rfc{3454} defines a procedure for ``preparing'' Unicode strings in
-internet protocols. Before passing strings onto the wire, they are
-processed with the preparation procedure, after which they have a
-certain normalized form. The RFC defines a set of tables, which can be
-combined into profiles. Each profile must define which tables it uses,
-and what other optional parts of the \code{stringprep} procedure are
-part of the profile. One example of a \code{stringprep} profile is
-\code{nameprep}, which is used for internationalized domain names.
-
-The module \module{stringprep} only exposes the tables from RFC
-3454. As these tables would be very large to represent them as
-dictionaries or lists, the module uses the Unicode character database
-internally. The module source code itself was generated using the
-\code{mkstringprep.py} utility.
-
-As a result, these tables are exposed as functions, not as data
-structures. There are two kinds of tables in the RFC: sets and
-mappings. For a set, \module{stringprep} provides the ``characteristic
-function'', i.e. a function that returns true if the parameter is part
-of the set. For mappings, it provides the mapping function: given the
-key, it returns the associated value. Below is a list of all functions
-available in the module.
-
-\begin{funcdesc}{in_table_a1}{code}
-Determine whether \var{code} is in table{A.1} (Unassigned code points
-in Unicode 3.2).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_b1}{code}
-Determine whether \var{code} is in table{B.1} (Commonly mapped to
-nothing).
-\end{funcdesc}
-
-\begin{funcdesc}{map_table_b2}{code}
-Return the mapped value for \var{code} according to table{B.2}
-(Mapping for case-folding used with NFKC).
-\end{funcdesc}
-
-\begin{funcdesc}{map_table_b3}{code}
-Return the mapped value for \var{code} according to table{B.3}
-(Mapping for case-folding used with no normalization).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c11}{code}
-Determine whether \var{code} is in table{C.1.1}
-(ASCII space characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c12}{code}
-Determine whether \var{code} is in table{C.1.2}
-(Non-ASCII space characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c11_c12}{code}
-Determine whether \var{code} is in table{C.1}
-(Space characters, union of C.1.1 and C.1.2).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c21}{code}
-Determine whether \var{code} is in table{C.2.1}
-(ASCII control characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c22}{code}
-Determine whether \var{code} is in table{C.2.2}
-(Non-ASCII control characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c21_c22}{code}
-Determine whether \var{code} is in table{C.2}
-(Control characters, union of C.2.1 and C.2.2).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c3}{code}
-Determine whether \var{code} is in table{C.3}
-(Private use).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c4}{code}
-Determine whether \var{code} is in table{C.4}
-(Non-character code points).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c5}{code}
-Determine whether \var{code} is in table{C.5}
-(Surrogate codes).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c6}{code}
-Determine whether \var{code} is in table{C.6}
-(Inappropriate for plain text).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c7}{code}
-Determine whether \var{code} is in table{C.7}
-(Inappropriate for canonical representation).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c8}{code}
-Determine whether \var{code} is in table{C.8}
-(Change display properties or are deprecated).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_c9}{code}
-Determine whether \var{code} is in table{C.9}
-(Tagging characters).
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_d1}{code}
-Determine whether \var{code} is in table{D.1}
-(Characters with bidirectional property ``R'' or ``AL'').
-\end{funcdesc}
-
-\begin{funcdesc}{in_table_d2}{code}
-Determine whether \var{code} is in table{D.2}
-(Characters with bidirectional property ``L'').
-\end{funcdesc}
-
diff --git a/Doc/lib/libstrings.tex b/Doc/lib/libstrings.tex
deleted file mode 100644
index f3a31f4..0000000
--- a/Doc/lib/libstrings.tex
+++ /dev/null
@@ -1,10 +0,0 @@
-\chapter{String Services}
-\label{strings}
-
-The modules described in this chapter provide a wide range of string
-manipulation operations. Here's an overview:
-
-\localmoduletable
-
-Information on the methods of string objects can be found in
-section~\ref{string-methods}, ``String Methods.''
diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
deleted file mode 100644
index 68c5c9a..0000000
--- a/Doc/lib/libstruct.tex
+++ /dev/null
@@ -1,269 +0,0 @@
-\section{\module{struct} ---
- Interpret strings as packed binary data}
-\declaremodule{builtin}{struct}
-
-\modulesynopsis{Interpret strings as packed binary data.}
-
-\indexii{C}{structures}
-\indexiii{packing}{binary}{data}
-
-This module performs conversions between Python values and C
-structs represented as Python strings. It uses \dfn{format strings}
-(explained below) as compact descriptions of the lay-out of the C
-structs and the intended conversion to/from Python values. This can
-be used in handling binary data stored in files or from network
-connections, among other sources.
-
-The module defines the following exception and functions:
-
-
-\begin{excdesc}{error}
- Exception raised on various occasions; argument is a string
- describing what is wrong.
-\end{excdesc}
-
-\begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
- Return a string containing the values
- \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given
- format. The arguments must match the values required by the format
- exactly.
-\end{funcdesc}
-
-\begin{funcdesc}{pack_into}{fmt, buffer, offset, v1, v2, \moreargs}
- Pack the values \code{\var{v1}, \var{v2}, \textrm{\ldots}} according to the given
- format, write the packed bytes into the writable \var{buffer} starting at
- \var{offset}.
- Note that the offset is not an optional argument.
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{unpack}{fmt, string}
- Unpack the string (presumably packed by \code{pack(\var{fmt},
- \textrm{\ldots})}) according to the given format. The result is a
- tuple even if it contains exactly one item. The string must contain
- exactly the amount of data required by the format
- (\code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
-\end{funcdesc}
-
-\begin{funcdesc}{unpack_from}{fmt, buffer\optional{,offset \code{= 0}}}
- Unpack the \var{buffer} according to tthe given format.
- The result is a tuple even if it contains exactly one item. The
- \var{buffer} must contain at least the amount of data required by the
- format (\code{len(buffer[offset:])} must be at least
- \code{calcsize(\var{fmt})}).
-
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{calcsize}{fmt}
- Return the size of the struct (and hence of the string)
- corresponding to the given format.
-\end{funcdesc}
-
-Format characters have the following meaning; the conversion between
-C and Python values should be obvious given their types:
-
-\begin{tableiv}{c|l|l|c}{samp}{Format}{C Type}{Python}{Notes}
- \lineiv{x}{pad byte}{no value}{}
- \lineiv{c}{\ctype{char}}{string of length 1}{}
- \lineiv{b}{\ctype{signed char}}{integer}{}
- \lineiv{B}{\ctype{unsigned char}}{integer}{}
- \lineiv{t}{\ctype{_Bool}}{bool}{(1)}
- \lineiv{h}{\ctype{short}}{integer}{}
- \lineiv{H}{\ctype{unsigned short}}{integer}{}
- \lineiv{i}{\ctype{int}}{integer}{}
- \lineiv{I}{\ctype{unsigned int}}{long}{}
- \lineiv{l}{\ctype{long}}{integer}{}
- \lineiv{L}{\ctype{unsigned long}}{long}{}
- \lineiv{q}{\ctype{long long}}{long}{(2)}
- \lineiv{Q}{\ctype{unsigned long long}}{long}{(2)}
- \lineiv{f}{\ctype{float}}{float}{}
- \lineiv{d}{\ctype{double}}{float}{}
- \lineiv{s}{\ctype{char[]}}{string}{}
- \lineiv{p}{\ctype{char[]}}{string}{}
- \lineiv{P}{\ctype{void *}}{integer}{}
-\end{tableiv}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)]
- The \character{t} conversion code corresponds to the \ctype{_Bool} type
- defined by C99. If this type is not available, it is simulated using a
- \ctype{char}. In standard mode, it is always represented by one byte.
- \versionadded{2.6}
-\item[(2)]
- The \character{q} and \character{Q} conversion codes are available in
- native mode only if the platform C compiler supports C \ctype{long long},
- or, on Windows, \ctype{__int64}. They are always available in standard
- modes.
- \versionadded{2.2}
-\end{description}
-
-
-A format character may be preceded by an integral repeat count. For
-example, the format string \code{'4h'} means exactly the same as
-\code{'hhhh'}.
-
-Whitespace characters between formats are ignored; a count and its
-format must not contain whitespace though.
-
-For the \character{s} format character, the count is interpreted as the
-size of the string, not a repeat count like for the other format
-characters; for example, \code{'10s'} means a single 10-byte string, while
-\code{'10c'} means 10 characters. For packing, the string is
-truncated or padded with null bytes as appropriate to make it fit.
-For unpacking, the resulting string always has exactly the specified
-number of bytes. As a special case, \code{'0s'} means a single, empty
-string (while \code{'0c'} means 0 characters).
-
-The \character{p} format character encodes a "Pascal string", meaning
-a short variable-length string stored in a fixed number of bytes.
-The count is the total number of bytes stored. The first byte stored is
-the length of the string, or 255, whichever is smaller. The bytes
-of the string follow. If the string passed in to \function{pack()} is too
-long (longer than the count minus 1), only the leading count-1 bytes of the
-string are stored. If the string is shorter than count-1, it is padded
-with null bytes so that exactly count bytes in all are used. Note that
-for \function{unpack()}, the \character{p} format character consumes count
-bytes, but that the string returned can never contain more than 255
-characters.
-
-For the \character{I}, \character{L}, \character{q} and \character{Q}
-format characters, the return value is a Python long integer.
-
-For the \character{P} format character, the return value is a Python
-integer or long integer, depending on the size needed to hold a
-pointer when it has been cast to an integer type. A \NULL{} pointer will
-always be returned as the Python integer \code{0}. When packing pointer-sized
-values, Python integer or long integer objects may be used. For
-example, the Alpha and Merced processors use 64-bit pointer values,
-meaning a Python long integer will be used to hold the pointer; other
-platforms use 32-bit pointers and will use a Python integer.
-
-For the \character{t} format character, the return value is either
-\constant{True} or \constant{False}. When packing, the truth value
-of the argument object is used. Either 0 or 1 in the native or standard
-bool representation will be packed, and any non-zero value will be True
-when unpacking.
-
-By default, C numbers are represented in the machine's native format
-and byte order, and properly aligned by skipping pad bytes if
-necessary (according to the rules used by the C compiler).
-
-Alternatively, the first character of the format string can be used to
-indicate the byte order, size and alignment of the packed data,
-according to the following table:
-
-\begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment}
- \lineiii{@}{native}{native}
- \lineiii{=}{native}{standard}
- \lineiii{<}{little-endian}{standard}
- \lineiii{>}{big-endian}{standard}
- \lineiii{!}{network (= big-endian)}{standard}
-\end{tableiii}
-
-If the first character is not one of these, \character{@} is assumed.
-
-Native byte order is big-endian or little-endian, depending on the
-host system. For example, Motorola and Sun processors are big-endian;
-Intel and DEC processors are little-endian.
-
-Native size and alignment are determined using the C compiler's
-\keyword{sizeof} expression. This is always combined with native byte
-order.
-
-Standard size and alignment are as follows: no alignment is required
-for any type (so you have to use pad bytes);
-\ctype{short} is 2 bytes;
-\ctype{int} and \ctype{long} are 4 bytes;
-\ctype{long long} (\ctype{__int64} on Windows) is 8 bytes;
-\ctype{float} and \ctype{double} are 32-bit and 64-bit
-IEEE floating point numbers, respectively.
-\ctype{_Bool} is 1 byte.
-
-Note the difference between \character{@} and \character{=}: both use
-native byte order, but the size and alignment of the latter is
-standardized.
-
-The form \character{!} is available for those poor souls who claim they
-can't remember whether network byte order is big-endian or
-little-endian.
-
-There is no way to indicate non-native byte order (force
-byte-swapping); use the appropriate choice of \character{<} or
-\character{>}.
-
-The \character{P} format character is only available for the native
-byte ordering (selected as the default or with the \character{@} byte
-order character). The byte order character \character{=} chooses to
-use little- or big-endian ordering based on the host system. The
-struct module does not interpret this as native ordering, so the
-\character{P} format is not available.
-
-Examples (all using native byte order, size and alignment, on a
-big-endian machine):
-
-\begin{verbatim}
->>> from struct import *
->>> pack('hhl', 1, 2, 3)
-'\x00\x01\x00\x02\x00\x00\x00\x03'
->>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
-(1, 2, 3)
->>> calcsize('hhl')
-8
-\end{verbatim}
-
-Hint: to align the end of a structure to the alignment requirement of
-a particular type, end the format with the code for that type with a
-repeat count of zero. For example, the format \code{'llh0l'}
-specifies two pad bytes at the end, assuming longs are aligned on
-4-byte boundaries. This only works when native size and alignment are
-in effect; standard size and alignment does not enforce any alignment.
-
-\begin{seealso}
- \seemodule{array}{Packed binary storage of homogeneous data.}
- \seemodule{xdrlib}{Packing and unpacking of XDR data.}
-\end{seealso}
-
-\subsection{Struct Objects \label{struct-objects}}
-
-The \module{struct} module also defines the following type:
-
-\begin{classdesc}{Struct}{format}
- Return a new Struct object which writes and reads binary data according to
- the format string \var{format}. Creating a Struct object once and calling
- its methods is more efficient than calling the \module{struct} functions
- with the same format since the format string only needs to be compiled once.
-
- \versionadded{2.5}
-\end{classdesc}
-
-Compiled Struct objects support the following methods and attributes:
-
-\begin{methoddesc}[Struct]{pack}{v1, v2, \moreargs}
- Identical to the \function{pack()} function, using the compiled format.
- (\code{len(result)} will equal \member{self.size}.)
-\end{methoddesc}
-
-\begin{methoddesc}[Struct]{pack_into}{buffer, offset, v1, v2, \moreargs}
- Identical to the \function{pack_into()} function, using the compiled format.
-\end{methoddesc}
-
-\begin{methoddesc}[Struct]{unpack}{string}
- Identical to the \function{unpack()} function, using the compiled format.
- (\code{len(string)} must equal \member{self.size}).
-\end{methoddesc}
-
-\begin{methoddesc}[Struct]{unpack_from}{buffer\optional{,offset
- \code{= 0}}}
- Identical to the \function{unpack_from()} function, using the compiled format.
- (\code{len(buffer[offset:])} must be at least \member{self.size}).
-\end{methoddesc}
-
-\begin{memberdesc}[Struct]{format}
- The format string used to construct this Struct object.
-\end{memberdesc}
-
diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex
deleted file mode 100644
index e2a9bb6..0000000
--- a/Doc/lib/libsubprocess.tex
+++ /dev/null
@@ -1,340 +0,0 @@
-\section{\module{subprocess} --- Subprocess management}
-
-\declaremodule{standard}{subprocess}
-\modulesynopsis{Subprocess management.}
-\moduleauthor{Peter \AA strand}{astrand@lysator.liu.se}
-\sectionauthor{Peter \AA strand}{astrand@lysator.liu.se}
-
-\versionadded{2.4}
-
-The \module{subprocess} module allows you to spawn new processes,
-connect to their input/output/error pipes, and obtain their return
-codes. This module intends to replace several other, older modules
-and functions, such as:
-
-\begin{verbatim}
-os.system
-os.spawn*
-commands.*
-\end{verbatim}
-
-Information about how the \module{subprocess} module can be used to
-replace these modules and functions can be found in the following
-sections.
-
-\subsection{Using the subprocess Module}
-
-This module defines one class called \class{Popen}:
-
-\begin{classdesc}{Popen}{args, bufsize=0, executable=None,
- stdin=None, stdout=None, stderr=None,
- preexec_fn=None, close_fds=False, shell=False,
- cwd=None, env=None, universal_newlines=False,
- startupinfo=None, creationflags=0}
-
-Arguments are:
-
-\var{args} should be a string, or a sequence of program arguments. The
-program to execute is normally the first item in the args sequence or
-string, but can be explicitly set by using the executable argument.
-
-On \UNIX{}, with \var{shell=False} (default): In this case, the Popen
-class uses \method{os.execvp()} to execute the child program.
-\var{args} should normally be a sequence. A string will be treated as a
-sequence with the string as the only item (the program to execute).
-
-On \UNIX{}, with \var{shell=True}: If args is a string, it specifies the
-command string to execute through the shell. If \var{args} is a
-sequence, the first item specifies the command string, and any
-additional items will be treated as additional shell arguments.
-
-On Windows: the \class{Popen} class uses CreateProcess() to execute
-the child program, which operates on strings. If \var{args} is a
-sequence, it will be converted to a string using the
-\method{list2cmdline} method. Please note that not all MS Windows
-applications interpret the command line the same way:
-\method{list2cmdline} is designed for applications using the same
-rules as the MS C runtime.
-
-\var{bufsize}, if given, has the same meaning as the corresponding
-argument to the built-in open() function: \constant{0} means unbuffered,
-\constant{1} means line buffered, any other positive value means use a
-buffer of (approximately) that size. A negative \var{bufsize} means to
-use the system default, which usually means fully buffered. The default
-value for \var{bufsize} is \constant{0} (unbuffered).
-
-The \var{executable} argument specifies the program to execute. It is
-very seldom needed: Usually, the program to execute is defined by the
-\var{args} argument. If \code{shell=True}, the \var{executable}
-argument specifies which shell to use. On \UNIX{}, the default shell
-is \file{/bin/sh}. On Windows, the default shell is specified by the
-\envvar{COMSPEC} environment variable.
-
-\var{stdin}, \var{stdout} and \var{stderr} specify the executed
-programs' standard input, standard output and standard error file
-handles, respectively. Valid values are \code{PIPE}, an existing file
-descriptor (a positive integer), an existing file object, and
-\code{None}. \code{PIPE} indicates that a new pipe to the child
-should be created. With \code{None}, no redirection will occur; the
-child's file handles will be inherited from the parent. Additionally,
-\var{stderr} can be \code{STDOUT}, which indicates that the stderr
-data from the applications should be captured into the same file
-handle as for stdout.
-
-If \var{preexec_fn} is set to a callable object, this object will be
-called in the child process just before the child is executed.
-(\UNIX{} only)
-
-If \var{close_fds} is true, all file descriptors except \constant{0},
-\constant{1} and \constant{2} will be closed before the child process is
-executed. (\UNIX{} only). Or, on Windows, if \var{close_fds} is true
-then no handles will be inherited by the child process. Note that on
-Windows, you cannot set \var{close_fds} to true and also redirect the
-standard handles by setting \var{stdin}, \var{stdout} or \var{stderr}.
-
-If \var{shell} is \constant{True}, the specified command will be
-executed through the shell.
-
-If \var{cwd} is not \code{None}, the child's current directory will be
-changed to \var{cwd} before it is executed. Note that this directory
-is not considered when searching the executable, so you can't specify
-the program's path relative to \var{cwd}.
-
-If \var{env} is not \code{None}, it defines the environment variables
-for the new process.
-
-If \var{universal_newlines} is \constant{True}, the file objects stdout
-and stderr are opened as text files, but lines may be terminated by
-any of \code{'\e n'}, the \UNIX{} end-of-line convention, \code{'\e r'},
-the Macintosh convention or \code{'\e r\e n'}, the Windows convention.
-All of these external representations are seen as \code{'\e n'} by the
-Python program. \note{This feature is only available if Python is built
-with universal newline support (the default). Also, the newlines
-attribute of the file objects \member{stdout}, \member{stdin} and
-\member{stderr} are not updated by the communicate() method.}
-
-The \var{startupinfo} and \var{creationflags}, if given, will be
-passed to the underlying CreateProcess() function. They can specify
-things such as appearance of the main window and priority for the new
-process. (Windows only)
-\end{classdesc}
-
-\subsubsection{Convenience Functions}
-
-This module also defines two shortcut functions:
-
-\begin{funcdesc}{call}{*popenargs, **kwargs}
-Run command with arguments. Wait for command to complete, then
-return the \member{returncode} attribute.
-
-The arguments are the same as for the Popen constructor. Example:
-
-\begin{verbatim}
- retcode = call(["ls", "-l"])
-\end{verbatim}
-\end{funcdesc}
-
-\begin{funcdesc}{check_call}{*popenargs, **kwargs}
-Run command with arguments. Wait for command to complete. If the exit
-code was zero then return, otherwise raise \exception{CalledProcessError.}
-The \exception{CalledProcessError} object will have the return code in the
-\member{returncode} attribute.
-
-The arguments are the same as for the Popen constructor. Example:
-
-\begin{verbatim}
- check_call(["ls", "-l"])
-\end{verbatim}
-
-\versionadded{2.5}
-\end{funcdesc}
-
-\subsubsection{Exceptions}
-
-Exceptions raised in the child process, before the new program has
-started to execute, will be re-raised in the parent. Additionally,
-the exception object will have one extra attribute called
-\member{child_traceback}, which is a string containing traceback
-information from the childs point of view.
-
-The most common exception raised is \exception{OSError}. This occurs,
-for example, when trying to execute a non-existent file. Applications
-should prepare for \exception{OSError} exceptions.
-
-A \exception{ValueError} will be raised if \class{Popen} is called
-with invalid arguments.
-
-check_call() will raise \exception{CalledProcessError}, if the called
-process returns a non-zero return code.
-
-
-\subsubsection{Security}
-
-Unlike some other popen functions, this implementation will never call
-/bin/sh implicitly. This means that all characters, including shell
-metacharacters, can safely be passed to child processes.
-
-
-\subsection{Popen Objects}
-
-Instances of the \class{Popen} class have the following methods:
-
-\begin{methoddesc}[Popen]{poll}{}
-Check if child process has terminated. Returns returncode
-attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Popen]{wait}{}
-Wait for child process to terminate. Returns returncode attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Popen]{communicate}{input=None}
-Interact with process: Send data to stdin. Read data from stdout and
-stderr, until end-of-file is reached. Wait for process to terminate.
-The optional \var{input} argument should be a string to be sent to the
-child process, or \code{None}, if no data should be sent to the child.
-
-communicate() returns a tuple (stdout, stderr).
-
-\note{The data read is buffered in memory, so do not use this method
-if the data size is large or unlimited.}
-\end{methoddesc}
-
-The following attributes are also available:
-
-\begin{memberdesc}[Popen]{stdin}
-If the \var{stdin} argument is \code{PIPE}, this attribute is a file
-object that provides input to the child process. Otherwise, it is
-\code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{stdout}
-If the \var{stdout} argument is \code{PIPE}, this attribute is a file
-object that provides output from the child process. Otherwise, it is
-\code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{stderr}
-If the \var{stderr} argument is \code{PIPE}, this attribute is file
-object that provides error output from the child process. Otherwise,
-it is \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{pid}
-The process ID of the child process.
-\end{memberdesc}
-
-\begin{memberdesc}[Popen]{returncode}
-The child return code. A \code{None} value indicates that the process
-hasn't terminated yet. A negative value -N indicates that the child
-was terminated by signal N (\UNIX{} only).
-\end{memberdesc}
-
-
-\subsection{Replacing Older Functions with the subprocess Module}
-
-In this section, "a ==> b" means that b can be used as a replacement
-for a.
-
-\note{All functions in this section fail (more or less) silently if
-the executed program cannot be found; this module raises an
-\exception{OSError} exception.}
-
-In the following examples, we assume that the subprocess module is
-imported with "from subprocess import *".
-
-\subsubsection{Replacing /bin/sh shell backquote}
-
-\begin{verbatim}
-output=`mycmd myarg`
-==>
-output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
-\end{verbatim}
-
-\subsubsection{Replacing shell pipe line}
-
-\begin{verbatim}
-output=`dmesg | grep hda`
-==>
-p1 = Popen(["dmesg"], stdout=PIPE)
-p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
-output = p2.communicate()[0]
-\end{verbatim}
-
-\subsubsection{Replacing os.system()}
-
-\begin{verbatim}
-sts = os.system("mycmd" + " myarg")
-==>
-p = Popen("mycmd" + " myarg", shell=True)
-sts = os.waitpid(p.pid, 0)
-\end{verbatim}
-
-Notes:
-
-\begin{itemize}
-\item Calling the program through the shell is usually not required.
-\item It's easier to look at the \member{returncode} attribute than
- the exit status.
-\end{itemize}
-
-A more realistic example would look like this:
-
-\begin{verbatim}
-try:
- retcode = call("mycmd" + " myarg", shell=True)
- if retcode < 0:
- print >>sys.stderr, "Child was terminated by signal", -retcode
- else:
- print >>sys.stderr, "Child returned", retcode
-except OSError as e:
- print >>sys.stderr, "Execution failed:", e
-\end{verbatim}
-
-\subsubsection{Replacing os.spawn*}
-
-P_NOWAIT example:
-
-\begin{verbatim}
-pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
-==>
-pid = Popen(["/bin/mycmd", "myarg"]).pid
-\end{verbatim}
-
-P_WAIT example:
-
-\begin{verbatim}
-retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
-==>
-retcode = call(["/bin/mycmd", "myarg"])
-\end{verbatim}
-
-Vector example:
-
-\begin{verbatim}
-os.spawnvp(os.P_NOWAIT, path, args)
-==>
-Popen([path] + args[1:])
-\end{verbatim}
-
-Environment example:
-
-\begin{verbatim}
-os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
-==>
-Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
-\end{verbatim}
-
-\subsubsection{Replacing os.popen*}
-
-\begin{verbatim}
-pipe = os.popen(cmd, mode='r', bufsize)
-==>
-pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
-\end{verbatim}
-
-\begin{verbatim}
-pipe = os.popen(cmd, mode='w', bufsize)
-==>
-pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
-\end{verbatim}
diff --git a/Doc/lib/libsunau.tex b/Doc/lib/libsunau.tex
deleted file mode 100644
index 235bc3b..0000000
--- a/Doc/lib/libsunau.tex
+++ /dev/null
@@ -1,218 +0,0 @@
-\section{\module{sunau} ---
- Read and write Sun AU files}
-
-\declaremodule{standard}{sunau}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Provide an interface to the Sun AU sound format.}
-
-The \module{sunau} module provides a convenient interface to the Sun
-AU sound format. Note that this module is interface-compatible with
-the modules \refmodule{aifc} and \refmodule{wave}.
-
-An audio file consists of a header followed by the data. The fields
-of the header are:
-
-\begin{tableii}{l|l}{textrm}{Field}{Contents}
- \lineii{magic word}{The four bytes \samp{.snd}.}
- \lineii{header size}{Size of the header, including info, in bytes.}
- \lineii{data size}{Physical size of the data, in bytes.}
- \lineii{encoding}{Indicates how the audio samples are encoded.}
- \lineii{sample rate}{The sampling rate.}
- \lineii{\# of channels}{The number of channels in the samples.}
- \lineii{info}{\ASCII{} string giving a description of the audio
- file (padded with null bytes).}
-\end{tableii}
-
-Apart from the info field, all header fields are 4 bytes in size.
-They are all 32-bit unsigned integers encoded in big-endian byte
-order.
-
-
-The \module{sunau} module defines the following functions:
-
-\begin{funcdesc}{open}{file, mode}
-If \var{file} is a string, open the file by that name, otherwise treat it
-as a seekable file-like object. \var{mode} can be any of
-\begin{description}
- \item[\code{'r'}] Read only mode.
- \item[\code{'w'}] Write only mode.
-\end{description}
-Note that it does not allow read/write files.
-
-A \var{mode} of \code{'r'} returns a \class{AU_read}
-object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
-a \class{AU_write} object.
-\end{funcdesc}
-
-\begin{funcdesc}{openfp}{file, mode}
-A synonym for \function{open}, maintained for backwards compatibility.
-\end{funcdesc}
-
-The \module{sunau} module defines the following exception:
-
-\begin{excdesc}{Error}
-An error raised when something is impossible because of Sun AU specs or
-implementation deficiency.
-\end{excdesc}
-
-The \module{sunau} module defines the following data items:
-
-\begin{datadesc}{AUDIO_FILE_MAGIC}
-An integer every valid Sun AU file begins with, stored in big-endian
-form. This is the string \samp{.snd} interpreted as an integer.
-\end{datadesc}
-
-\begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_8}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_16}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_24}
-\dataline{AUDIO_FILE_ENCODING_LINEAR_32}
-\dataline{AUDIO_FILE_ENCODING_ALAW_8}
-Values of the encoding field from the AU header which are supported by
-this module.
-\end{datadesc}
-
-\begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT}
-\dataline{AUDIO_FILE_ENCODING_DOUBLE}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G721}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G722}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3}
-\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5}
-Additional known values of the encoding field from the AU header, but
-which are not supported by this module.
-\end{datadesc}
-
-
-\subsection{AU_read Objects \label{au-read-objects}}
-
-AU_read objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[AU_read]{close}{}
-Close the stream, and make the instance unusable. (This is
-called automatically on deletion.)
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getnchannels}{}
-Returns number of audio channels (1 for mone, 2 for stereo).
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getsampwidth}{}
-Returns sample width in bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getframerate}{}
-Returns sampling frequency.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getnframes}{}
-Returns number of audio frames.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getcomptype}{}
-Returns compression type.
-Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getcompname}{}
-Human-readable version of \method{getcomptype()}.
-The supported types have the respective names \code{'CCITT G.711
-u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getparams}{}
-Returns a tuple \code{(\var{nchannels}, \var{sampwidth},
-\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})},
-equivalent to output of the \method{get*()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{readframes}{n}
-Reads and returns at most \var{n} frames of audio, as a string of
-bytes. The data will be returned in linear format. If the original
-data is in u-LAW format, it will be converted.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{rewind}{}
-Rewind the file pointer to the beginning of the audio stream.
-\end{methoddesc}
-
-The following two methods define a term ``position'' which is compatible
-between them, and is otherwise implementation dependent.
-
-\begin{methoddesc}[AU_read]{setpos}{pos}
-Set the file pointer to the specified position. Only values returned
-from \method{tell()} should be used for \var{pos}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{tell}{}
-Return current file pointer position. Note that the returned value
-has nothing to do with the actual position in the file.
-\end{methoddesc}
-
-The following two functions are defined for compatibility with the
-\refmodule{aifc}, and don't do anything interesting.
-
-\begin{methoddesc}[AU_read]{getmarkers}{}
-Returns \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_read]{getmark}{id}
-Raise an error.
-\end{methoddesc}
-
-
-\subsection{AU_write Objects \label{au-write-objects}}
-
-AU_write objects, as returned by \function{open()} above, have the
-following methods:
-
-\begin{methoddesc}[AU_write]{setnchannels}{n}
-Set the number of channels.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setsampwidth}{n}
-Set the sample width (in bytes.)
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setframerate}{n}
-Set the frame rate.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setnframes}{n}
-Set the number of frames. This can be later changed, when and if more
-frames are written.
-\end{methoddesc}
-
-
-\begin{methoddesc}[AU_write]{setcomptype}{type, name}
-Set the compression type and description.
-Only \code{'NONE'} and \code{'ULAW'} are supported on output.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{setparams}{tuple}
-The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
-\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
-values valid for the \method{set*()} methods. Set all parameters.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{tell}{}
-Return current position in the file, with the same disclaimer for
-the \method{AU_read.tell()} and \method{AU_read.setpos()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{writeframesraw}{data}
-Write audio frames, without correcting \var{nframes}.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{writeframes}{data}
-Write audio frames and make sure \var{nframes} is correct.
-\end{methoddesc}
-
-\begin{methoddesc}[AU_write]{close}{}
-Make sure \var{nframes} is correct, and close the file.
-
-This method is called upon deletion.
-\end{methoddesc}
-
-Note that it is invalid to set any parameters after calling
-\method{writeframes()} or \method{writeframesraw()}.
diff --git a/Doc/lib/libsymbol.tex b/Doc/lib/libsymbol.tex
deleted file mode 100644
index 54cabeb..0000000
--- a/Doc/lib/libsymbol.tex
+++ /dev/null
@@ -1,30 +0,0 @@
-\section{\module{symbol} ---
- Constants used with Python parse trees}
-
-\declaremodule{standard}{symbol}
-\modulesynopsis{Constants representing internal nodes of the parse tree.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-This module provides constants which represent the numeric values of
-internal nodes of the parse tree. Unlike most Python constants, these
-use lower-case names. Refer to the file \file{Grammar/Grammar} in the
-Python distribution for the definitions of the names in the context of
-the language grammar. The specific numeric values which the names map
-to may change between Python versions.
-
-This module also provides one additional data object:
-
-
-\begin{datadesc}{sym_name}
- Dictionary mapping the numeric values of the constants defined in
- this module back to name strings, allowing more human-readable
- representation of parse trees to be generated.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{parser}{The second example for the \refmodule{parser}
- module shows how to use the \module{symbol}
- module.}
-\end{seealso}
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
deleted file mode 100644
index 4ab3247..0000000
--- a/Doc/lib/libsys.tex
+++ /dev/null
@@ -1,582 +0,0 @@
-\section{\module{sys} ---
- System-specific parameters and functions}
-
-\declaremodule{builtin}{sys}
-\modulesynopsis{Access system-specific parameters and functions.}
-
-This module provides access to some variables used or maintained by the
-interpreter and to functions that interact strongly with the interpreter.
-It is always available.
-
-
-\begin{datadesc}{argv}
- The list of command line arguments passed to a Python script.
- \code{argv[0]} is the script name (it is operating system dependent
- whether this is a full pathname or not). If the command was
- executed using the \programopt{-c} command line option to the
- interpreter, \code{argv[0]} is set to the string \code{'-c'}. If no
- script name was passed to the Python interpreter, \code{argv[0]} is
- the empty string.
-\end{datadesc}
-
-\begin{datadesc}{byteorder}
- An indicator of the native byte order. This will have the value
- \code{'big'} on big-endian (most-significant byte first) platforms,
- and \code{'little'} on little-endian (least-significant byte first)
- platforms.
- \versionadded{2.0}
-\end{datadesc}
-
-\begin{datadesc}{subversion}
- A triple (repo, branch, version) representing the Subversion
- information of the Python interpreter.
- \var{repo} is the name of the repository, \code{'CPython'}.
- \var{branch} is a string of one of the forms \code{'trunk'},
- \code{'branches/name'} or \code{'tags/name'}.
- \var{version} is the output of \code{svnversion}, if the
- interpreter was built from a Subversion checkout; it contains
- the revision number (range) and possibly a trailing 'M' if
- there were local modifications. If the tree was exported
- (or svnversion was not available), it is the revision of
- \code{Include/patchlevel.h} if the branch is a tag. Otherwise,
- it is \code{None}.
- \versionadded{2.5}
-\end{datadesc}
-
-\begin{datadesc}{builtin_module_names}
- A tuple of strings giving the names of all modules that are compiled
- into this Python interpreter. (This information is not available in
- any other way --- \code{modules.keys()} only lists the imported
- modules.)
-\end{datadesc}
-
-\begin{datadesc}{copyright}
- A string containing the copyright pertaining to the Python
- interpreter.
-\end{datadesc}
-
-\begin{funcdesc}{_current_frames}{}
- Return a dictionary mapping each thread's identifier to the topmost stack
- frame currently active in that thread at the time the function is called.
- Note that functions in the \refmodule{traceback} module can build the
- call stack given such a frame.
-
- This is most useful for debugging deadlock: this function does not
- require the deadlocked threads' cooperation, and such threads' call stacks
- are frozen for as long as they remain deadlocked. The frame returned
- for a non-deadlocked thread may bear no relationship to that thread's
- current activity by the time calling code examines the frame.
-
- This function should be used for internal and specialized purposes
- only.
- \versionadded{2.5}
-\end{funcdesc}
-
-\begin{datadesc}{dllhandle}
- Integer specifying the handle of the Python DLL.
- Availability: Windows.
-\end{datadesc}
-
-\begin{funcdesc}{displayhook}{\var{value}}
- If \var{value} is not \code{None}, this function prints it to
- \code{sys.stdout}, and saves it in \code{__builtin__._}.
-
- \code{sys.displayhook} is called on the result of evaluating an
- expression entered in an interactive Python session. The display of
- these values can be customized by assigning another one-argument
- function to \code{sys.displayhook}.
-\end{funcdesc}
-
-\begin{funcdesc}{excepthook}{\var{type}, \var{value}, \var{traceback}}
- This function prints out a given traceback and exception to
- \code{sys.stderr}.
-
- When an exception is raised and uncaught, the interpreter calls
- \code{sys.excepthook} with three arguments, the exception class,
- exception instance, and a traceback object. In an interactive
- session this happens just before control is returned to the prompt;
- in a Python program this happens just before the program exits. The
- handling of such top-level exceptions can be customized by assigning
- another three-argument function to \code{sys.excepthook}.
-\end{funcdesc}
-
-\begin{datadesc}{__displayhook__}
-\dataline{__excepthook__}
- These objects contain the original values of \code{displayhook} and
- \code{excepthook} at the start of the program. They are saved so
- that \code{displayhook} and \code{excepthook} can be restored in
- case they happen to get replaced with broken objects.
-\end{datadesc}
-
-\begin{funcdesc}{exc_info}{}
- This function returns a tuple of three values that give information
- about the exception that is currently being handled. The
- information returned is specific both to the current thread and to
- the current stack frame. If the current stack frame is not handling
- an exception, the information is taken from the calling stack frame,
- or its caller, and so on until a stack frame is found that is
- handling an exception. Here, ``handling an exception'' is defined
- as ``executing or having executed an except clause.'' For any stack
- frame, only information about the most recently handled exception is
- accessible.
-
- If no exception is being handled anywhere on the stack, a tuple
- containing three \code{None} values is returned. Otherwise, the
- values returned are \code{(\var{type}, \var{value},
- \var{traceback})}. Their meaning is: \var{type} gets the exception
- type of the exception being handled (a class object);
- \var{value} gets the exception parameter (its \dfn{associated value}
- or the second argument to \keyword{raise}, which is always a class
- instance if the exception type is a class object); \var{traceback}
- gets a traceback object (see the Reference Manual) which
- encapsulates the call stack at the point where the exception
- originally occurred. \obindex{traceback}
-
- \warning{Assigning the \var{traceback} return value to a
- local variable in a function that is handling an exception will
- cause a circular reference. This will prevent anything referenced
- by a local variable in the same function or by the traceback from
- being garbage collected. Since most functions don't need access to
- the traceback, the best solution is to use something like
- \code{exctype, value = sys.exc_info()[:2]} to extract only the
- exception type and value. If you do need the traceback, make sure
- to delete it after use (best done with a \keyword{try}
- ... \keyword{finally} statement) or to call \function{exc_info()} in
- a function that does not itself handle an exception.} \note{Beginning
- with Python 2.2, such cycles are automatically reclaimed when garbage
- collection is enabled and they become unreachable, but it remains more
- efficient to avoid creating cycles.}
-\end{funcdesc}
-
-\begin{datadesc}{exec_prefix}
- A string giving the site-specific directory prefix where the
- platform-dependent Python files are installed; by default, this is
- also \code{'/usr/local'}. This can be set at build time with the
- \longprogramopt{exec-prefix} argument to the \program{configure}
- script. Specifically, all configuration files (e.g. the
- \file{pyconfig.h} header file) are installed in the directory
- \code{exec_prefix + '/lib/python\var{version}/config'}, and shared
- library modules are installed in \code{exec_prefix +
- '/lib/python\var{version}/lib-dynload'}, where \var{version} is
- equal to \code{version[:3]}.
-\end{datadesc}
-
-\begin{datadesc}{executable}
- A string giving the name of the executable binary for the Python
- interpreter, on systems where this makes sense.
-\end{datadesc}
-
-\begin{funcdesc}{exit}{\optional{arg}}
- Exit from Python. This is implemented by raising the
- \exception{SystemExit} exception, so cleanup actions specified by
- finally clauses of \keyword{try} statements are honored, and it is
- possible to intercept the exit attempt at an outer level. The
- optional argument \var{arg} can be an integer giving the exit status
- (defaulting to zero), or another type of object. If it is an
- integer, zero is considered ``successful termination'' and any
- nonzero value is considered ``abnormal termination'' by shells and
- the like. Most systems require it to be in the range 0-127, and
- produce undefined results otherwise. Some systems have a convention
- for assigning specific meanings to specific exit codes, but these
- are generally underdeveloped; \UNIX{} programs generally use 2 for
- command line syntax errors and 1 for all other kind of errors. If
- another type of object is passed, \code{None} is equivalent to
- passing zero, and any other object is printed to \code{sys.stderr}
- and results in an exit code of 1. In particular,
- \code{sys.exit("some error message")} is a quick way to exit a
- program when an error occurs.
-\end{funcdesc}
-
-\begin{funcdesc}{getcheckinterval}{}
- Return the interpreter's ``check interval'';
- see \function{setcheckinterval()}.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getdefaultencoding}{}
- Return the name of the current default string encoding used by the
- Unicode implementation.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{getdlopenflags}{}
- Return the current value of the flags that are used for
- \cfunction{dlopen()} calls. The flag constants are defined in the
- \refmodule{dl} and \module{DLFCN} modules.
- Availability: \UNIX.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{getfilesystemencoding}{}
- Return the name of the encoding used to convert Unicode filenames
- into system file names, or \code{None} if the system default encoding
- is used. The result value depends on the operating system:
-\begin{itemize}
-\item On Windows 9x, the encoding is ``mbcs''.
-\item On Mac OS X, the encoding is ``utf-8''.
-\item On \UNIX, the encoding is the user's preference
- according to the result of nl_langinfo(CODESET), or \constant{None}
- if the \code{nl_langinfo(CODESET)} failed.
-\item On Windows NT+, file names are Unicode natively, so no conversion
- is performed. \function{getfilesystemencoding()} still returns
- \code{'mbcs'}, as this is the encoding that applications should use
- when they explicitly want to convert Unicode strings to byte strings
- that are equivalent when used as file names.
-\end{itemize}
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{getrefcount}{object}
- Return the reference count of the \var{object}. The count returned
- is generally one higher than you might expect, because it includes
- the (temporary) reference as an argument to
- \function{getrefcount()}.
-\end{funcdesc}
-
-\begin{funcdesc}{getrecursionlimit}{}
- Return the current value of the recursion limit, the maximum depth
- of the Python interpreter stack. This limit prevents infinite
- recursion from causing an overflow of the C stack and crashing
- Python. It can be set by \function{setrecursionlimit()}.
-\end{funcdesc}
-
-\begin{funcdesc}{_getframe}{\optional{depth}}
- Return a frame object from the call stack. If optional integer
- \var{depth} is given, return the frame object that many calls below
- the top of the stack. If that is deeper than the call stack,
- \exception{ValueError} is raised. The default for \var{depth} is
- zero, returning the frame at the top of the call stack.
-
- This function should be used for internal and specialized purposes
- only.
-\end{funcdesc}
-
-\begin{funcdesc}{getwindowsversion}{}
- Return a tuple containing five components, describing the Windows
- version currently running. The elements are \var{major}, \var{minor},
- \var{build}, \var{platform}, and \var{text}. \var{text} contains
- a string while all other values are integers.
-
- \var{platform} may be one of the following values:
-
- \begin{tableii}{l|l}{constant}{Constant}{Platform}
- \lineii{0 (VER_PLATFORM_WIN32s)} {Win32s on Windows 3.1}
- \lineii{1 (VER_PLATFORM_WIN32_WINDOWS)}{Windows 95/98/ME}
- \lineii{2 (VER_PLATFORM_WIN32_NT)} {Windows NT/2000/XP}
- \lineii{3 (VER_PLATFORM_WIN32_CE)} {Windows CE}
- \end{tableii}
-
- This function wraps the Win32 \cfunction{GetVersionEx()} function;
- see the Microsoft documentation for more information about these
- fields.
-
- Availability: Windows.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{hexversion}
- The version number encoded as a single integer. This is guaranteed
- to increase with each version, including proper support for
- non-production releases. For example, to test that the Python
- interpreter is at least version 1.5.2, use:
-
-\begin{verbatim}
-if sys.hexversion >= 0x010502F0:
- # use some advanced feature
- ...
-else:
- # use an alternative implementation or warn the user
- ...
-\end{verbatim}
-
- This is called \samp{hexversion} since it only really looks
- meaningful when viewed as the result of passing it to the built-in
- \function{hex()} function. The \code{version_info} value may be
- used for a more human-friendly encoding of the same information.
- \versionadded{1.5.2}
-\end{datadesc}
-
-\begin{funcdesc}{intern}{string}
- Enter \var{string} in the table of ``interned'' strings and return
- the interned string -- which is \var{string} itself or a copy.
- Interning strings is useful to gain a little performance on
- dictionary lookup -- if the keys in a dictionary are interned, and
- the lookup key is interned, the key comparisons (after hashing) can
- be done by a pointer compare instead of a string compare. Normally,
- the names used in Python programs are automatically interned, and
- the dictionaries used to hold module, class or instance attributes
- have interned keys. \versionchanged[Interned strings are not
- immortal (like they used to be in Python 2.2 and before);
- you must keep a reference to the return value of \function{intern()}
- around to benefit from it]{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{last_type}
-\dataline{last_value}
-\dataline{last_traceback}
- These three variables are not always defined; they are set when an
- exception is not handled and the interpreter prints an error message
- and a stack traceback. Their intended use is to allow an
- interactive user to import a debugger module and engage in
- post-mortem debugging without having to re-execute the command that
- caused the error. (Typical use is \samp{import pdb; pdb.pm()} to
- enter the post-mortem debugger; see chapter~\ref{debugger}, ``The
- Python Debugger,'' for more information.)
-
- The meaning of the variables is the same as that of the return
- values from \function{exc_info()} above. (Since there is only one
- interactive thread, thread-safety is not a concern for these
- variables, unlike for \code{exc_type} etc.)
-\end{datadesc}
-
-\begin{datadesc}{maxint}
- The largest positive integer supported by Python's regular integer
- type. This is at least 2**31-1. The largest negative integer is
- \code{-maxint-1} --- the asymmetry results from the use of 2's
- complement binary arithmetic.
-\end{datadesc}
-
-\begin{datadesc}{maxunicode}
- An integer giving the largest supported code point for a Unicode
- character. The value of this depends on the configuration option
- that specifies whether Unicode characters are stored as UCS-2 or
- UCS-4.
-\end{datadesc}
-
-\begin{datadesc}{modules}
- This is a dictionary that maps module names to modules which have
- already been loaded. This can be manipulated to force reloading of
- modules and other tricks.
-\end{datadesc}
-
-\begin{datadesc}{path}
-\indexiii{module}{search}{path}
- A list of strings that specifies the search path for modules.
- Initialized from the environment variable \envvar{PYTHONPATH}, plus an
- installation-dependent default.
-
- As initialized upon program startup,
- the first item of this list, \code{path[0]}, is the directory
- containing the script that was used to invoke the Python
- interpreter. If the script directory is not available (e.g. if the
- interpreter is invoked interactively or if the script is read from
- standard input), \code{path[0]} is the empty string, which directs
- Python to search modules in the current directory first. Notice
- that the script directory is inserted \emph{before} the entries
- inserted as a result of \envvar{PYTHONPATH}.
-
- A program is free to modify this list for its own purposes.
-
- \versionchanged[Unicode strings are no longer ignored]{2.3}
-\end{datadesc}
-
-\begin{datadesc}{platform}
- This string contains a platform identifier, e.g. \code{'sunos5'} or
- \code{'linux1'}. This can be used to append platform-specific
- components to \code{path}, for instance.
-\end{datadesc}
-
-\begin{datadesc}{prefix}
- A string giving the site-specific directory prefix where the
- platform independent Python files are installed; by default, this is
- the string \code{'/usr/local'}. This can be set at build time with
- the \longprogramopt{prefix} argument to the \program{configure}
- script. The main collection of Python library modules is installed
- in the directory \code{prefix + '/lib/python\var{version}'} while
- the platform independent header files (all except \file{pyconfig.h})
- are stored in \code{prefix + '/include/python\var{version}'}, where
- \var{version} is equal to \code{version[:3]}.
-\end{datadesc}
-
-\begin{datadesc}{ps1}
-\dataline{ps2}
-\index{interpreter prompts}
-\index{prompts, interpreter}
- Strings specifying the primary and secondary prompt of the
- interpreter. These are only defined if the interpreter is in
- interactive mode. Their initial values in this case are
- \code{'>>>~'} and \code{'...~'}. If a non-string object is
- assigned to either variable, its \function{str()} is re-evaluated
- each time the interpreter prepares to read a new interactive
- command; this can be used to implement a dynamic prompt.
-\end{datadesc}
-
-\begin{funcdesc}{setcheckinterval}{interval}
- Set the interpreter's ``check interval''. This integer value
- determines how often the interpreter checks for periodic things such
- as thread switches and signal handlers. The default is \code{100},
- meaning the check is performed every 100 Python virtual instructions.
- Setting it to a larger value may increase performance for programs
- using threads. Setting it to a value \code{<=} 0 checks every
- virtual instruction, maximizing responsiveness as well as overhead.
-\end{funcdesc}
-
-\begin{funcdesc}{setdefaultencoding}{name}
- Set the current default string encoding used by the Unicode
- implementation. If \var{name} does not match any available
- encoding, \exception{LookupError} is raised. This function is only
- intended to be used by the \refmodule{site} module implementation
- and, where needed, by \module{sitecustomize}. Once used by the
- \refmodule{site} module, it is removed from the \module{sys}
- module's namespace.
-% Note that \refmodule{site} is not imported if
-% the \programopt{-S} option is passed to the interpreter, in which
-% case this function will remain available.
- \versionadded{2.0}
-\end{funcdesc}
-
-\begin{funcdesc}{setdlopenflags}{n}
- Set the flags used by the interpreter for \cfunction{dlopen()}
- calls, such as when the interpreter loads extension modules. Among
- other things, this will enable a lazy resolving of symbols when
- importing a module, if called as \code{sys.setdlopenflags(0)}. To
- share symbols across extension modules, call as
- \code{sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)}. Symbolic
- names for the flag modules can be either found in the \refmodule{dl}
- module, or in the \module{DLFCN} module. If \module{DLFCN} is not
- available, it can be generated from \file{/usr/include/dlfcn.h}
- using the \program{h2py} script.
- Availability: \UNIX.
- \versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{setprofile}{profilefunc}
- Set the system's profile function,\index{profile function} which
- allows you to implement a Python source code profiler in
- Python.\index{profiler} See chapter~\ref{profile} for more
- information on the Python profiler. The system's profile function
- is called similarly to the system's trace function (see
- \function{settrace()}), but it isn't called for each executed line
- of code (only on call and return, but the return event is reported
- even when an exception has been set). The function is
- thread-specific, but there is no way for the profiler to know about
- context switches between threads, so it does not make sense to use
- this in the presence of multiple threads.
- Also, its return value is not used, so it can simply return
- \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{setrecursionlimit}{limit}
- Set the maximum depth of the Python interpreter stack to
- \var{limit}. This limit prevents infinite recursion from causing an
- overflow of the C stack and crashing Python.
-
- The highest possible limit is platform-dependent. A user may need
- to set the limit higher when she has a program that requires deep
- recursion and a platform that supports a higher limit. This should
- be done with care, because a too-high limit can lead to a crash.
-\end{funcdesc}
-
-\begin{funcdesc}{settrace}{tracefunc}
- Set the system's trace function,\index{trace function} which allows
- you to implement a Python source code debugger in Python. See
- section \ref{debugger-hooks}, ``How It Works,'' in the chapter on
- the Python debugger.\index{debugger} The function is
- thread-specific; for a debugger to support multiple threads, it must
- be registered using \function{settrace()} for each thread being
- debugged. \note{The \function{settrace()} function is intended only
- for implementing debuggers, profilers, coverage tools and the like.
- Its behavior is part of the implementation platform, rather than
- part of the language definition, and thus may not be available in
- all Python implementations.}
-\end{funcdesc}
-
-\begin{funcdesc}{settscdump}{on_flag}
- Activate dumping of VM measurements using the Pentium timestamp
- counter, if \var{on_flag} is true. Deactivate these dumps if
- \var{on_flag} is off. The function is available only if Python
- was compiled with \longprogramopt{with-tsc}. To understand the
- output of this dump, read \file{Python/ceval.c} in the Python
- sources.
- \versionadded{2.4}
-\end{funcdesc}
-
-\begin{datadesc}{stdin}
-\dataline{stdout}
-\dataline{stderr}
- File objects corresponding to the interpreter's standard input,
- output and error streams. \code{stdin} is used for all interpreter
- input except for scripts. \code{stdout} is
- used for the output of \keyword{print} and expression statements.
- The interpreter's own prompts and (almost all of) its error messages
- go to \code{stderr}. \code{stdout} and \code{stderr} needn't be
- built-in file objects: any object is acceptable as long as it has a
- \method{write()} method that takes a string argument. (Changing
- these objects doesn't affect the standard I/O streams of processes
- executed by \function{os.popen()}, \function{os.system()} or the
- \function{exec*()} family of functions in the \refmodule{os}
- module.)
-\end{datadesc}
-
-\begin{datadesc}{__stdin__}
-\dataline{__stdout__}
-\dataline{__stderr__}
- These objects contain the original values of \code{stdin},
- \code{stderr} and \code{stdout} at the start of the program. They
- are used during finalization, and could be useful to restore the
- actual files to known working file objects in case they have been
- overwritten with a broken object.
-\end{datadesc}
-
-\begin{datadesc}{tracebacklimit}
- When this variable is set to an integer value, it determines the
- maximum number of levels of traceback information printed when an
- unhandled exception occurs. The default is \code{1000}. When set
- to \code{0} or less, all traceback information is suppressed and
- only the exception type and value are printed.
-\end{datadesc}
-
-\begin{datadesc}{version}
- A string containing the version number of the Python interpreter
- plus additional information on the build number and compiler used.
- It has a value of the form \code{'\var{version}
- (\#\var{build_number}, \var{build_date}, \var{build_time})
- [\var{compiler}]'}. The first three characters are used to identify
- the version in the installation directories (where appropriate on
- each platform). An example:
-
-\begin{verbatim}
->>> import sys
->>> sys.version
-'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
-\end{verbatim}
-\end{datadesc}
-
-\begin{datadesc}{api_version}
- The C API version for this interpreter. Programmers may find this useful
- when debugging version conflicts between Python and extension
- modules. \versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{version_info}
- A tuple containing the five components of the version number:
- \var{major}, \var{minor}, \var{micro}, \var{releaselevel}, and
- \var{serial}. All values except \var{releaselevel} are integers;
- the release level is \code{'alpha'}, \code{'beta'},
- \code{'candidate'}, or \code{'final'}. The \code{version_info}
- value corresponding to the Python version 2.0 is \code{(2, 0, 0,
- 'final', 0)}.
- \versionadded{2.0}
-\end{datadesc}
-
-\begin{datadesc}{warnoptions}
- This is an implementation detail of the warnings framework; do not
- modify this value. Refer to the \refmodule{warnings} module for
- more information on the warnings framework.
-\end{datadesc}
-
-\begin{datadesc}{winver}
- The version number used to form registry keys on Windows platforms.
- This is stored as string resource 1000 in the Python DLL. The value
- is normally the first three characters of \constant{version}. It is
- provided in the \module{sys} module for informational purposes;
- modifying this value has no effect on the registry keys used by
- Python.
- Availability: Windows.
-\end{datadesc}
-
-
-\begin{seealso}
- \seemodule{site}
- {This describes how to use .pth files to extend \code{sys.path}.}
-\end{seealso}
diff --git a/Doc/lib/libsyslog.tex b/Doc/lib/libsyslog.tex
deleted file mode 100644
index fc59776..0000000
--- a/Doc/lib/libsyslog.tex
+++ /dev/null
@@ -1,76 +0,0 @@
-\section{\module{syslog} ---
- \UNIX{} syslog library routines}
-
-\declaremodule{builtin}{syslog}
- \platform{Unix}
-\modulesynopsis{An interface to the \UNIX\ syslog library routines.}
-
-
-This module provides an interface to the \UNIX{} \code{syslog} library
-routines. Refer to the \UNIX{} manual pages for a detailed description
-of the \code{syslog} facility.
-
-The module defines the following functions:
-
-
-\begin{funcdesc}{syslog}{\optional{priority,} message}
-Send the string \var{message} to the system logger. A trailing
-newline is added if necessary. Each message is tagged with a priority
-composed of a \var{facility} and a \var{level}. The optional
-\var{priority} argument, which defaults to \constant{LOG_INFO},
-determines the message priority. If the facility is not encoded in
-\var{priority} using logical-or (\code{LOG_INFO | LOG_USER}), the
-value given in the \function{openlog()} call is used.
-\end{funcdesc}
-
-\begin{funcdesc}{openlog}{ident\optional{, logopt\optional{, facility}}}
-Logging options other than the defaults can be set by explicitly
-opening the log file with \function{openlog()} prior to calling
-\function{syslog()}. The defaults are (usually) \var{ident} =
-\code{'syslog'}, \var{logopt} = \code{0}, \var{facility} =
-\constant{LOG_USER}. The \var{ident} argument is a string which is
-prepended to every message. The optional \var{logopt} argument is a
-bit field - see below for possible values to combine. The optional
-\var{facility} argument sets the default facility for messages which
-do not have a facility explicitly encoded.
-\end{funcdesc}
-
-\begin{funcdesc}{closelog}{}
-Close the log file.
-\end{funcdesc}
-
-\begin{funcdesc}{setlogmask}{maskpri}
-Set the priority mask to \var{maskpri} and return the
-previous mask value. Calls to \function{syslog()} with a priority
-level not set in \var{maskpri} are ignored. The default is to log all
-priorities. The function \code{LOG_MASK(\var{pri})} calculates the
-mask for the individual priority \var{pri}. The function
-\code{LOG_UPTO(\var{pri})} calculates the mask for all priorities up
-to and including \var{pri}.
-\end{funcdesc}
-
-
-The module defines the following constants:
-
-\begin{description}
-
-\item[Priority levels (high to low):]
-
-\constant{LOG_EMERG}, \constant{LOG_ALERT}, \constant{LOG_CRIT},
-\constant{LOG_ERR}, \constant{LOG_WARNING}, \constant{LOG_NOTICE},
-\constant{LOG_INFO}, \constant{LOG_DEBUG}.
-
-\item[Facilities:]
-
-\constant{LOG_KERN}, \constant{LOG_USER}, \constant{LOG_MAIL},
-\constant{LOG_DAEMON}, \constant{LOG_AUTH}, \constant{LOG_LPR},
-\constant{LOG_NEWS}, \constant{LOG_UUCP}, \constant{LOG_CRON} and
-\constant{LOG_LOCAL0} to \constant{LOG_LOCAL7}.
-
-\item[Log options:]
-
-\constant{LOG_PID}, \constant{LOG_CONS}, \constant{LOG_NDELAY},
-\constant{LOG_NOWAIT} and \constant{LOG_PERROR} if defined in
-\code{<syslog.h>}.
-
-\end{description}
diff --git a/Doc/lib/libtabnanny.tex b/Doc/lib/libtabnanny.tex
deleted file mode 100644
index 12b9385..0000000
--- a/Doc/lib/libtabnanny.tex
+++ /dev/null
@@ -1,62 +0,0 @@
-\section{\module{tabnanny} ---
- Detection of ambiguous indentation}
-
-% rudimentary documentation based on module comments, by Peter Funk
-% <pf@artcom-gmbh.de>
-
-\declaremodule{standard}{tabnanny}
-\modulesynopsis{Tool for detecting white space related problems
- in Python source files in a directory tree.}
-\moduleauthor{Tim Peters}{tim_one@users.sourceforge.net}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-For the time being this module is intended to be called as a script.
-However it is possible to import it into an IDE and use the function
-\function{check()} described below.
-
-\warning{The API provided by this module is likely to change
-in future releases; such changes may not be backward compatible.}
-
-\begin{funcdesc}{check}{file_or_dir}
- If \var{file_or_dir} is a directory and not a symbolic link, then
- recursively descend the directory tree named by \var{file_or_dir},
- checking all \file{.py} files along the way. If \var{file_or_dir}
- is an ordinary Python source file, it is checked for whitespace
- related problems. The diagnostic messages are written to standard
- output using the print statement.
-\end{funcdesc}
-
-
-\begin{datadesc}{verbose}
- Flag indicating whether to print verbose messages.
- This is incremented by the \code{-v} option if called as a script.
-\end{datadesc}
-
-
-\begin{datadesc}{filename_only}
- Flag indicating whether to print only the filenames of files
- containing whitespace related problems. This is set to true by the
- \code{-q} option if called as a script.
-\end{datadesc}
-
-
-\begin{excdesc}{NannyNag}
- Raised by \function{tokeneater()} if detecting an ambiguous indent.
- Captured and handled in \function{check()}.
-\end{excdesc}
-
-
-\begin{funcdesc}{tokeneater}{type, token, start, end, line}
- This function is used by \function{check()} as a callback parameter to
- the function \function{tokenize.tokenize()}.
-\end{funcdesc}
-
-% XXX FIXME: Document \function{errprint},
-% \function{format_witnesses} \class{Whitespace}
-% check_equal, indents
-% \function{reset_globals}
-
-\begin{seealso}
- \seemodule{tokenize}{Lexical scanner for Python source code.}
- % XXX may be add a reference to IDLE?
-\end{seealso}
diff --git a/Doc/lib/libtarfile.tex b/Doc/lib/libtarfile.tex
deleted file mode 100644
index 95ea051..0000000
--- a/Doc/lib/libtarfile.tex
+++ /dev/null
@@ -1,664 +0,0 @@
-\section{\module{tarfile} --- Read and write tar archive files}
-
-\declaremodule{standard}{tarfile}
-\modulesynopsis{Read and write tar-format archive files.}
-\versionadded{2.3}
-
-\moduleauthor{Lars Gust\"abel}{lars@gustaebel.de}
-\sectionauthor{Lars Gust\"abel}{lars@gustaebel.de}
-
-The \module{tarfile} module makes it possible to read and create tar archives.
-Some facts and figures:
-
-\begin{itemize}
-\item reads and writes \module{gzip} and \module{bzip2} compressed archives.
-\item read/write support for the \POSIX{}.1-1988 (ustar) format.
-\item read/write support for the GNU tar format including \emph{longname} and
- \emph{longlink} extensions, read-only support for the \emph{sparse}
- extension.
-\item read/write support for the \POSIX{}.1-2001 (pax) format.
- \versionadded{2.6}
-\item handles directories, regular files, hardlinks, symbolic links, fifos,
- character devices and block devices and is able to acquire and
- restore file information like timestamp, access permissions and owner.
-\item can handle tape devices.
-\end{itemize}
-
-\begin{funcdesc}{open}{name\optional{, mode\optional{,
- fileobj\optional{, bufsize}}}, **kwargs}
- Return a \class{TarFile} object for the pathname \var{name}.
- For detailed information on \class{TarFile} objects and the keyword
- arguments that are allowed, see \citetitle{TarFile Objects}
- (section \ref{tarfile-objects}).
-
- \var{mode} has to be a string of the form \code{'filemode[:compression]'},
- it defaults to \code{'r'}. Here is a full list of mode combinations:
-
- \begin{tableii}{c|l}{code}{mode}{action}
- \lineii{'r' or 'r:*'}{Open for reading with transparent compression (recommended).}
- \lineii{'r:'}{Open for reading exclusively without compression.}
- \lineii{'r:gz'}{Open for reading with gzip compression.}
- \lineii{'r:bz2'}{Open for reading with bzip2 compression.}
- \lineii{'a' or 'a:'}{Open for appending with no compression. The file
- is created if it does not exist.}
- \lineii{'w' or 'w:'}{Open for uncompressed writing.}
- \lineii{'w:gz'}{Open for gzip compressed writing.}
- \lineii{'w:bz2'}{Open for bzip2 compressed writing.}
- \end{tableii}
-
- Note that \code{'a:gz'} or \code{'a:bz2'} is not possible.
- If \var{mode} is not suitable to open a certain (compressed) file for
- reading, \exception{ReadError} is raised. Use \var{mode} \code{'r'} to
- avoid this. If a compression method is not supported,
- \exception{CompressionError} is raised.
-
- If \var{fileobj} is specified, it is used as an alternative to a file
- object opened for \var{name}. It is supposed to be at position 0.
-
- For special purposes, there is a second format for \var{mode}:
- \code{'filemode|[compression]'}. \function{open()} will return a
- \class{TarFile} object that processes its data as a stream of
- blocks. No random seeking will be done on the file. If given,
- \var{fileobj} may be any object that has a \method{read()} or
- \method{write()} method (depending on the \var{mode}).
- \var{bufsize} specifies the blocksize and defaults to \code{20 *
- 512} bytes. Use this variant in combination with
- e.g. \code{sys.stdin}, a socket file object or a tape device.
- However, such a \class{TarFile} object is limited in that it does
- not allow to be accessed randomly, see ``Examples''
- (section~\ref{tar-examples}). The currently possible modes:
-
- \begin{tableii}{c|l}{code}{Mode}{Action}
- \lineii{'r|*'}{Open a \emph{stream} of tar blocks for reading with transparent compression.}
- \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.}
- \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.}
- \lineii{'r|bz2'}{Open a bzip2 compressed \emph{stream} for reading.}
- \lineii{'w|'}{Open an uncompressed \emph{stream} for writing.}
- \lineii{'w|gz'}{Open an gzip compressed \emph{stream} for writing.}
- \lineii{'w|bz2'}{Open an bzip2 compressed \emph{stream} for writing.}
- \end{tableii}
-\end{funcdesc}
-
-\begin{classdesc*}{TarFile}
- Class for reading and writing tar archives. Do not use this
- class directly, better use \function{open()} instead.
- See ``TarFile Objects'' (section~\ref{tarfile-objects}).
-\end{classdesc*}
-
-\begin{funcdesc}{is_tarfile}{name}
- Return \constant{True} if \var{name} is a tar archive file, that
- the \module{tarfile} module can read.
-\end{funcdesc}
-
-\begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{,
- compression}}}
- Class for limited access to tar archives with a
- \refmodule{zipfile}-like interface. Please consult the
- documentation of the \refmodule{zipfile} module for more details.
- \var{compression} must be one of the following constants:
- \begin{datadesc}{TAR_PLAIN}
- Constant for an uncompressed tar archive.
- \end{datadesc}
- \begin{datadesc}{TAR_GZIPPED}
- Constant for a \refmodule{gzip} compressed tar archive.
- \end{datadesc}
-\end{classdesc}
-
-\begin{excdesc}{TarError}
- Base class for all \module{tarfile} exceptions.
-\end{excdesc}
-
-\begin{excdesc}{ReadError}
- Is raised when a tar archive is opened, that either cannot be handled by
- the \module{tarfile} module or is somehow invalid.
-\end{excdesc}
-
-\begin{excdesc}{CompressionError}
- Is raised when a compression method is not supported or when the data
- cannot be decoded properly.
-\end{excdesc}
-
-\begin{excdesc}{StreamError}
- Is raised for the limitations that are typical for stream-like
- \class{TarFile} objects.
-\end{excdesc}
-
-\begin{excdesc}{ExtractError}
- Is raised for \emph{non-fatal} errors when using \method{extract()}, but
- only if \member{TarFile.errorlevel}\code{ == 2}.
-\end{excdesc}
-
-\begin{excdesc}{HeaderError}
- Is raised by \method{frombuf()} if the buffer it gets is invalid.
- \versionadded{2.6}
-\end{excdesc}
-
-Each of the following constants defines a tar archive format that the
-\module{tarfile} module is able to create. See section \ref{tar-formats} for
-details.
-
-\begin{datadesc}{USTAR_FORMAT}
- \POSIX{}.1-1988 (ustar) format.
-\end{datadesc}
-
-\begin{datadesc}{GNU_FORMAT}
- GNU tar format.
-\end{datadesc}
-
-\begin{datadesc}{PAX_FORMAT}
- \POSIX{}.1-2001 (pax) format.
-\end{datadesc}
-
-\begin{datadesc}{DEFAULT_FORMAT}
- The default format for creating archives. This is currently
- \constant{GNU_FORMAT}.
-\end{datadesc}
-
-\begin{seealso}
- \seemodule{zipfile}{Documentation of the \refmodule{zipfile}
- standard module.}
-
- \seetitle[http://www.gnu.org/software/tar/manual/html_node/tar_134.html\#SEC134]
- {GNU tar manual, Basic Tar Format}{Documentation for tar archive files,
- including GNU tar extensions.}
-\end{seealso}
-
-%-----------------
-% TarFile Objects
-%-----------------
-
-\subsection{TarFile Objects \label{tarfile-objects}}
-
-The \class{TarFile} object provides an interface to a tar archive. A tar
-archive is a sequence of blocks. An archive member (a stored file) is made up
-of a header block followed by data blocks. It is possible to store a file in a
-tar archive several times. Each archive member is represented by a
-\class{TarInfo} object, see \citetitle{TarInfo Objects} (section
-\ref{tarinfo-objects}) for details.
-
-\begin{classdesc}{TarFile}{name=None, mode='r', fileobj=None,
- format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False,
- ignore_zeros=False, encoding=None, errors=None, pax_headers=None,
- debug=0, errorlevel=0}
-
- All following arguments are optional and can be accessed as instance
- attributes as well.
-
- \var{name} is the pathname of the archive. It can be omitted if
- \var{fileobj} is given. In this case, the file object's \member{name}
- attribute is used if it exists.
-
- \var{mode} is either \code{'r'} to read from an existing archive,
- \code{'a'} to append data to an existing file or \code{'w'} to create a new
- file overwriting an existing one.
-
- If \var{fileobj} is given, it is used for reading or writing data.
- If it can be determined, \var{mode} is overridden by \var{fileobj}'s mode.
- \var{fileobj} will be used from position 0.
- \begin{notice}
- \var{fileobj} is not closed, when \class{TarFile} is closed.
- \end{notice}
-
- \var{format} controls the archive format. It must be one of the constants
- \constant{USTAR_FORMAT}, \constant{GNU_FORMAT} or \constant{PAX_FORMAT}
- that are defined at module level.
- \versionadded{2.6}
-
- The \var{tarinfo} argument can be used to replace the default
- \class{TarInfo} class with a different one.
- \versionadded{2.6}
-
- If \var{dereference} is \code{False}, add symbolic and hard links to the
- archive. If it is \code{True}, add the content of the target files to the
- archive. This has no effect on systems that do not support symbolic links.
-
- If \var{ignore_zeros} is \code{False}, treat an empty block as the end of
- the archive. If it is \var{True}, skip empty (and invalid) blocks and try
- to get as many members as possible. This is only useful for reading
- concatenated or damaged archives.
-
- \var{debug} can be set from \code{0} (no debug messages) up to \code{3}
- (all debug messages). The messages are written to \code{sys.stderr}.
-
- If \var{errorlevel} is \code{0}, all errors are ignored when using
- \method{extract()}. Nevertheless, they appear as error messages in the
- debug output, when debugging is enabled. If \code{1}, all \emph{fatal}
- errors are raised as \exception{OSError} or \exception{IOError} exceptions.
- If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError}
- exceptions as well.
-
- The \var{encoding} and \var{errors} arguments control the way strings are
- converted to unicode objects and vice versa. The default settings will work
- for most users. See section \ref{tar-unicode} for in-depth information.
- \versionadded{2.6}
-
- The \var{pax_headers} argument is an optional dictionary of unicode strings
- which will be added as a pax global header if \var{format} is
- \constant{PAX_FORMAT}.
- \versionadded{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{open}{...}
- Alternative constructor. The \function{open()} function on module level is
- actually a shortcut to this classmethod. See section~\ref{module-tarfile}
- for details.
-\end{methoddesc}
-
-\begin{methoddesc}{getmember}{name}
- Return a \class{TarInfo} object for member \var{name}. If \var{name} can
- not be found in the archive, \exception{KeyError} is raised.
- \begin{notice}
- If a member occurs more than once in the archive, its last
- occurrence is assumed to be the most up-to-date version.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{getmembers}{}
- Return the members of the archive as a list of \class{TarInfo} objects.
- The list has the same order as the members in the archive.
-\end{methoddesc}
-
-\begin{methoddesc}{getnames}{}
- Return the members as a list of their names. It has the same order as
- the list returned by \method{getmembers()}.
-\end{methoddesc}
-
-\begin{methoddesc}{list}{verbose=True}
- Print a table of contents to \code{sys.stdout}. If \var{verbose} is
- \constant{False}, only the names of the members are printed. If it is
- \constant{True}, output similar to that of \program{ls -l} is produced.
-\end{methoddesc}
-
-\begin{methoddesc}{next}{}
- Return the next member of the archive as a \class{TarInfo} object, when
- \class{TarFile} is opened for reading. Return \code{None} if there is no
- more available.
-\end{methoddesc}
-
-\begin{methoddesc}{extractall}{\optional{path\optional{, members}}}
- Extract all members from the archive to the current working directory
- or directory \var{path}. If optional \var{members} is given, it must be
- a subset of the list returned by \method{getmembers()}.
- Directory information like owner, modification time and permissions are
- set after all members have been extracted. This is done to work around two
- problems: A directory's modification time is reset each time a file is
- created in it. And, if a directory's permissions do not allow writing,
- extracting files to it will fail.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{extract}{member\optional{, path}}
- Extract a member from the archive to the current working directory,
- using its full name. Its file information is extracted as accurately as
- possible.
- \var{member} may be a filename or a \class{TarInfo} object.
- You can specify a different directory using \var{path}.
- \begin{notice}
- Because the \method{extract()} method allows random access to a tar
- archive there are some issues you must take care of yourself. See the
- description for \method{extractall()} above.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{extractfile}{member}
- Extract a member from the archive as a file object.
- \var{member} may be a filename or a \class{TarInfo} object.
- If \var{member} is a regular file, a file-like object is returned.
- If \var{member} is a link, a file-like object is constructed from the
- link's target.
- If \var{member} is none of the above, \code{None} is returned.
- \begin{notice}
- The file-like object is read-only and provides the following methods:
- \method{read()}, \method{readline()}, \method{readlines()},
- \method{seek()}, \method{tell()}.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive\optional{, exclude}}}}
- Add the file \var{name} to the archive. \var{name} may be any type
- of file (directory, fifo, symbolic link, etc.).
- If given, \var{arcname} specifies an alternative name for the file in the
- archive. Directories are added recursively by default.
- This can be avoided by setting \var{recursive} to \constant{False}.
- If \var{exclude} is given it must be a function that takes one filename
- argument and returns a boolean value. Depending on this value the
- respective file is either excluded (\constant{True}) or added
- (\constant{False}).
- \versionchanged[Added the \var{exclude} parameter]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}}
- Add the \class{TarInfo} object \var{tarinfo} to the archive.
- If \var{fileobj} is given, \code{\var{tarinfo}.size} bytes are read
- from it and added to the archive. You can create \class{TarInfo} objects
- using \method{gettarinfo()}.
- \begin{notice}
- On Windows platforms, \var{fileobj} should always be opened with mode
- \code{'rb'} to avoid irritation about the file size.
- \end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{gettarinfo}{\optional{name\optional{,
- arcname\optional{, fileobj}}}}
- Create a \class{TarInfo} object for either the file \var{name} or
- the file object \var{fileobj} (using \function{os.fstat()} on its
- file descriptor). You can modify some of the \class{TarInfo}'s
- attributes before you add it using \method{addfile()}. If given,
- \var{arcname} specifies an alternative name for the file in the
- archive.
-\end{methoddesc}
-
-\begin{methoddesc}{close}{}
- Close the \class{TarFile}. In write mode, two finishing zero
- blocks are appended to the archive.
-\end{methoddesc}
-
-\begin{memberdesc}{posix}
- Setting this to \constant{True} is equivalent to setting the
- \member{format} attribute to \constant{USTAR_FORMAT},
- \constant{False} is equivalent to \constant{GNU_FORMAT}.
- \versionchanged[\var{posix} defaults to \constant{False}]{2.4}
- \deprecated{2.6}{Use the \member{format} attribute instead.}
-\end{memberdesc}
-
-\begin{memberdesc}{pax_headers}
- A dictionary containing key-value pairs of pax global headers.
- \versionadded{2.6}
-\end{memberdesc}
-
-%-----------------
-% TarInfo Objects
-%-----------------
-
-\subsection{TarInfo Objects \label{tarinfo-objects}}
-
-A \class{TarInfo} object represents one member in a
-\class{TarFile}. Aside from storing all required attributes of a file
-(like file type, size, time, permissions, owner etc.), it provides
-some useful methods to determine its type. It does \emph{not} contain
-the file's data itself.
-
-\class{TarInfo} objects are returned by \class{TarFile}'s methods
-\method{getmember()}, \method{getmembers()} and \method{gettarinfo()}.
-
-\begin{classdesc}{TarInfo}{\optional{name}}
- Create a \class{TarInfo} object.
-\end{classdesc}
-
-\begin{methoddesc}{frombuf}{buf}
- Create and return a \class{TarInfo} object from string buffer \var{buf}.
- \versionadded[Raises \exception{HeaderError} if the buffer is
- invalid.]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{fromtarfile}{tarfile}
- Read the next member from the \class{TarFile} object \var{tarfile} and
- return it as a \class{TarInfo} object.
- \versionadded{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{tobuf}{\optional{format\optional{, encoding
- \optional{, errors}}}}
- Create a string buffer from a \class{TarInfo} object. For information
- on the arguments see the constructor of the \class{TarFile} class.
- \versionchanged[The arguments were added]{2.6}
-\end{methoddesc}
-
-A \code{TarInfo} object has the following public data attributes:
-
-\begin{memberdesc}{name}
- Name of the archive member.
-\end{memberdesc}
-
-\begin{memberdesc}{size}
- Size in bytes.
-\end{memberdesc}
-
-\begin{memberdesc}{mtime}
- Time of last modification.
-\end{memberdesc}
-
-\begin{memberdesc}{mode}
- Permission bits.
-\end{memberdesc}
-
-\begin{memberdesc}{type}
- File type. \var{type} is usually one of these constants:
- \constant{REGTYPE}, \constant{AREGTYPE}, \constant{LNKTYPE},
- \constant{SYMTYPE}, \constant{DIRTYPE}, \constant{FIFOTYPE},
- \constant{CONTTYPE}, \constant{CHRTYPE}, \constant{BLKTYPE},
- \constant{GNUTYPE_SPARSE}. To determine the type of a
- \class{TarInfo} object more conveniently, use the \code{is_*()}
- methods below.
-\end{memberdesc}
-
-\begin{memberdesc}{linkname}
- Name of the target file name, which is only present in
- \class{TarInfo} objects of type \constant{LNKTYPE} and
- \constant{SYMTYPE}.
-\end{memberdesc}
-
-\begin{memberdesc}{uid}
- User ID of the user who originally stored this member.
-\end{memberdesc}
-
-\begin{memberdesc}{gid}
- Group ID of the user who originally stored this member.
-\end{memberdesc}
-
-\begin{memberdesc}{uname}
- User name.
-\end{memberdesc}
-
-\begin{memberdesc}{gname}
- Group name.
-\end{memberdesc}
-
-\begin{memberdesc}{pax_headers}
- A dictionary containing key-value pairs of an associated pax
- extended header.
- \versionadded{2.6}
-\end{memberdesc}
-
-A \class{TarInfo} object also provides some convenient query methods:
-
-\begin{methoddesc}{isfile}{}
- Return \constant{True} if the \class{Tarinfo} object is a regular
- file.
-\end{methoddesc}
-
-\begin{methoddesc}{isreg}{}
- Same as \method{isfile()}.
-\end{methoddesc}
-
-\begin{methoddesc}{isdir}{}
- Return \constant{True} if it is a directory.
-\end{methoddesc}
-
-\begin{methoddesc}{issym}{}
- Return \constant{True} if it is a symbolic link.
-\end{methoddesc}
-
-\begin{methoddesc}{islnk}{}
- Return \constant{True} if it is a hard link.
-\end{methoddesc}
-
-\begin{methoddesc}{ischr}{}
- Return \constant{True} if it is a character device.
-\end{methoddesc}
-
-\begin{methoddesc}{isblk}{}
- Return \constant{True} if it is a block device.
-\end{methoddesc}
-
-\begin{methoddesc}{isfifo}{}
- Return \constant{True} if it is a FIFO.
-\end{methoddesc}
-
-\begin{methoddesc}{isdev}{}
- Return \constant{True} if it is one of character device, block
- device or FIFO.
-\end{methoddesc}
-
-%------------------------
-% Examples
-%------------------------
-
-\subsection{Examples \label{tar-examples}}
-
-How to extract an entire tar archive to the current working directory:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar.gz")
-tar.extractall()
-tar.close()
-\end{verbatim}
-
-How to create an uncompressed tar archive from a list of filenames:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar", "w")
-for name in ["foo", "bar", "quux"]:
- tar.add(name)
-tar.close()
-\end{verbatim}
-
-How to read a gzip compressed tar archive and display some member information:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar.gz", "r:gz")
-for tarinfo in tar:
- print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
- if tarinfo.isreg():
- print "a regular file."
- elif tarinfo.isdir():
- print "a directory."
- else:
- print "something else."
-tar.close()
-\end{verbatim}
-
-How to create a tar archive with faked information:
-\begin{verbatim}
-import tarfile
-tar = tarfile.open("sample.tar.gz", "w:gz")
-for name in namelist:
- tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name)
- tarinfo.uid = 123
- tarinfo.gid = 456
- tarinfo.uname = "johndoe"
- tarinfo.gname = "fake"
- tar.addfile(tarinfo, file(name))
-tar.close()
-\end{verbatim}
-
-The \emph{only} way to extract an uncompressed tar stream from
-\code{sys.stdin}:
-\begin{verbatim}
-import sys
-import tarfile
-tar = tarfile.open(mode="r|", fileobj=sys.stdin)
-for tarinfo in tar:
- tar.extract(tarinfo)
-tar.close()
-\end{verbatim}
-
-%------------
-% Tar format
-%------------
-
-\subsection{Supported tar formats \label{tar-formats}}
-
-There are three tar formats that can be created with the \module{tarfile}
-module:
-
-\begin{itemize}
-
-\item
-The \POSIX{}.1-1988 ustar format (\constant{USTAR_FORMAT}). It supports
-filenames up to a length of at best 256 characters and linknames up to 100
-characters. The maximum file size is 8 gigabytes. This is an old and limited
-but widely supported format.
-
-\item
-The GNU tar format (\constant{GNU_FORMAT}). It supports long filenames and
-linknames, files bigger than 8 gigabytes and sparse files. It is the de facto
-standard on GNU/Linux systems. \module{tarfile} fully supports the GNU tar
-extensions for long names, sparse file support is read-only.
-
-\item
-The \POSIX{}.1-2001 pax format (\constant{PAX_FORMAT}). It is the most
-flexible format with virtually no limits. It supports long filenames and
-linknames, large files and stores pathnames in a portable way. However, not
-all tar implementations today are able to handle pax archives properly.
-
-The \emph{pax} format is an extension to the existing \emph{ustar} format. It
-uses extra headers for information that cannot be stored otherwise. There are
-two flavours of pax headers: Extended headers only affect the subsequent file
-header, global headers are valid for the complete archive and affect all
-following files. All the data in a pax header is encoded in \emph{UTF-8} for
-portability reasons.
-
-\end{itemize}
-
-There are some more variants of the tar format which can be read, but not
-created:
-
-\begin{itemize}
-
-\item
-The ancient V7 format. This is the first tar format from \UNIX{} Seventh
-Edition, storing only regular files and directories. Names must not be longer
-than 100 characters, there is no user/group name information. Some archives
-have miscalculated header checksums in case of fields with non-\ASCII{}
-characters.
-
-\item
-The SunOS tar extended format. This format is a variant of the \POSIX{}.1-2001
-pax format, but is not compatible.
-
-\end{itemize}
-
-%----------------
-% Unicode issues
-%----------------
-
-\subsection{Unicode issues \label{tar-unicode}}
-
-The tar format was originally conceived to make backups on tape drives with the
-main focus on preserving file system information. Nowadays tar archives are
-commonly used for file distribution and exchanging archives over networks. One
-problem of the original format (that all other formats are merely variants of)
-is that there is no concept of supporting different character encodings.
-For example, an ordinary tar archive created on a \emph{UTF-8} system cannot be
-read correctly on a \emph{Latin-1} system if it contains non-\ASCII{}
-characters. Names (i.e. filenames, linknames, user/group names) containing
-these characters will appear damaged. Unfortunately, there is no way to
-autodetect the encoding of an archive.
-
-The pax format was designed to solve this problem. It stores non-\ASCII{} names
-using the universal character encoding \emph{UTF-8}. When a pax archive is
-read, these \emph{UTF-8} names are converted to the encoding of the local
-file system.
-
-The details of unicode conversion are controlled by the \var{encoding} and
-\var{errors} keyword arguments of the \class{TarFile} class.
-
-The default value for \var{encoding} is the local character encoding. It is
-deduced from \function{sys.getfilesystemencoding()} and
-\function{sys.getdefaultencoding()}. In read mode, \var{encoding} is used
-exclusively to convert unicode names from a pax archive to strings in the local
-character encoding. In write mode, the use of \var{encoding} depends on the
-chosen archive format. In case of \constant{PAX_FORMAT}, input names that
-contain non-\ASCII{} characters need to be decoded before being stored as
-\emph{UTF-8} strings. The other formats do not make use of \var{encoding}
-unless unicode objects are used as input names. These are converted to
-8-bit character strings before they are added to the archive.
-
-The \var{errors} argument defines how characters are treated that cannot be
-converted to or from \var{encoding}. Possible values are listed in section
-\ref{codec-base-classes}. In read mode, there is an additional scheme
-\code{'utf-8'} which means that bad characters are replaced by their
-\emph{UTF-8} representation. This is the default scheme. In write mode the
-default value for \var{errors} is \code{'strict'} to ensure that name
-information is not altered unnoticed.
diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex
deleted file mode 100644
index 853788f..0000000
--- a/Doc/lib/libtelnetlib.tex
+++ /dev/null
@@ -1,228 +0,0 @@
-\section{\module{telnetlib} ---
- Telnet client}
-
-\declaremodule{standard}{telnetlib}
-\modulesynopsis{Telnet client class.}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\index{protocol!Telnet}
-
-The \module{telnetlib} module provides a \class{Telnet} class that
-implements the Telnet protocol. See \rfc{854} for details about the
-protocol. In addition, it provides symbolic constants for the protocol
-characters (see below), and for the telnet options. The
-symbolic names of the telnet options follow the definitions in
-\code{arpa/telnet.h}, with the leading \code{TELOPT_} removed. For
-symbolic names of options which are traditionally not included in
-\code{arpa/telnet.h}, see the module source itself.
-
-The symbolic constants for the telnet commands are: IAC, DONT, DO,
-WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data
-Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT
-(Are You There), EC (Erase Character), EL (Erase Line), GA (Go Ahead),
-SB (Subnegotiation Begin).
-
-
-\begin{classdesc}{Telnet}{\optional{host\optional{, port\optional{, timeout}}}}
-\class{Telnet} represents a connection to a Telnet server. The
-instance is initially not connected by default; the \method{open()}
-method must be used to establish a connection. Alternatively, the
-host name and optional port number can be passed to the constructor,
-to, in which case the connection to the server will be established
-before the constructor returns.
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used).
-
-Do not reopen an already connected instance.
-
-This class has many \method{read_*()} methods. Note that some of them
-raise \exception{EOFError} when the end of the connection is read,
-because they can return an empty string for other reasons. See the
-individual descriptions below.
-\versionchanged[\var{timeout} was added]{2.6}
-\end{classdesc}
-
-
-\begin{seealso}
- \seerfc{854}{Telnet Protocol Specification}{
- Definition of the Telnet protocol.}
-\end{seealso}
-
-
-
-\subsection{Telnet Objects \label{telnet-objects}}
-
-\class{Telnet} instances have the following methods:
-
-
-\begin{methoddesc}[Telnet]{read_until}{expected\optional{, timeout}}
-Read until a given string, \var{expected}, is encountered or until
-\var{timeout} seconds have passed.
-
-When no match is found, return whatever is available instead,
-possibly the empty string. Raise \exception{EOFError} if the connection
-is closed and no cooked data is available.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_all}{}
-Read all data until \EOF; block until connection closed.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_some}{}
-Read at least one byte of cooked data unless \EOF{} is hit.
-Return \code{''} if \EOF{} is hit. Block if no data is immediately
-available.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_very_eager}{}
-Read everything that can be without blocking in I/O (eager).
-
-Raise \exception{EOFError} if connection closed and no cooked data
-available. Return \code{''} if no cooked data available otherwise.
-Do not block unless in the midst of an IAC sequence.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_eager}{}
-Read readily available data.
-
-Raise \exception{EOFError} if connection closed and no cooked data
-available. Return \code{''} if no cooked data available otherwise.
-Do not block unless in the midst of an IAC sequence.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_lazy}{}
-Process and return data already in the queues (lazy).
-
-Raise \exception{EOFError} if connection closed and no data available.
-Return \code{''} if no cooked data available otherwise. Do not block
-unless in the midst of an IAC sequence.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_very_lazy}{}
-Return any data available in the cooked queue (very lazy).
-
-Raise \exception{EOFError} if connection closed and no data available.
-Return \code{''} if no cooked data available otherwise. This method
-never blocks.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{read_sb_data}{}
-Return the data collected between a SB/SE pair (suboption begin/end).
-The callback should access these data when it was invoked with a
-\code{SE} command. This method never blocks.
-
-\versionadded{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{open}{host\optional{, port\optional{, timeout}}}
-Connect to a host.
-The optional second argument is the port number, which
-defaults to the standard Telnet port (23).
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used).
-
-Do not try to reopen an already connected instance.
-\versionchanged[\var{timeout} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}}
-Print a debug message when the debug level is \code{>} 0.
-If extra arguments are present, they are substituted in the
-message using the standard string formatting operator.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{set_debuglevel}{debuglevel}
-Set the debug level. The higher the value of \var{debuglevel}, the
-more debug output you get (on \code{sys.stdout}).
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{close}{}
-Close the connection.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{get_socket}{}
-Return the socket object used internally.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{fileno}{}
-Return the file descriptor of the socket object used internally.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{write}{buffer}
-Write a string to the socket, doubling any IAC characters.
-This can block if the connection is blocked. May raise
-\exception{socket.error} if the connection is closed.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{interact}{}
-Interaction function, emulates a very dumb Telnet client.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{mt_interact}{}
-Multithreaded version of \method{interact()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{expect}{list\optional{, timeout}}
-Read until one from a list of a regular expressions matches.
-
-The first argument is a list of regular expressions, either
-compiled (\class{re.RegexObject} instances) or uncompiled (strings).
-The optional second argument is a timeout, in seconds; the default
-is to block indefinitely.
-
-Return a tuple of three items: the index in the list of the
-first regular expression that matches; the match object
-returned; and the text read up till and including the match.
-
-If end of file is found and no text was read, raise
-\exception{EOFError}. Otherwise, when nothing matches, return
-\code{(-1, None, \var{text})} where \var{text} is the text received so
-far (may be the empty string if a timeout happened).
-
-If a regular expression ends with a greedy match (such as \regexp{.*})
-or if more than one expression can match the same input, the
-results are indeterministic, and may depend on the I/O timing.
-\end{methoddesc}
-
-\begin{methoddesc}[Telnet]{set_option_negotiation_callback}{callback}
-Each time a telnet option is read on the input flow, this
-\var{callback} (if set) is called with the following parameters :
-callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other
-action is done afterwards by telnetlib.
-\end{methoddesc}
-
-
-\subsection{Telnet Example \label{telnet-example}}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-A simple example illustrating typical use:
-
-\begin{verbatim}
-import getpass
-import sys
-import telnetlib
-
-def raw_input(prompt):
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-HOST = "localhost"
-user = raw_input("Enter your remote account: ")
-password = getpass.getpass()
-
-tn = telnetlib.Telnet(HOST)
-
-tn.read_until("login: ")
-tn.write(user + "\n")
-if password:
- tn.read_until("Password: ")
- tn.write(password + "\n")
-
-tn.write("ls\n")
-tn.write("exit\n")
-
-print tn.read_all()
-\end{verbatim}
diff --git a/Doc/lib/libtempfile.tex b/Doc/lib/libtempfile.tex
deleted file mode 100644
index 8bc559e..0000000
--- a/Doc/lib/libtempfile.tex
+++ /dev/null
@@ -1,214 +0,0 @@
-\section{\module{tempfile} ---
- Generate temporary files and directories}
-\sectionauthor{Zack Weinberg}{zack@codesourcery.com}
-
-\declaremodule{standard}{tempfile}
-\modulesynopsis{Generate temporary files and directories.}
-
-\indexii{temporary}{file name}
-\indexii{temporary}{file}
-
-This module generates temporary files and directories. It works on
-all supported platforms.
-
-In version 2.3 of Python, this module was overhauled for enhanced
-security. It now provides three new functions,
-\function{NamedTemporaryFile()}, \function{mkstemp()}, and
-\function{mkdtemp()}, which should eliminate all remaining need to use
-the insecure \function{mktemp()} function. Temporary file names created
-by this module no longer contain the process ID; instead a string of
-six random characters is used.
-
-Also, all the user-callable functions now take additional arguments
-which allow direct control over the location and name of temporary
-files. It is no longer necessary to use the global \var{tempdir} and
-\var{template} variables. To maintain backward compatibility, the
-argument order is somewhat odd; it is recommended to use keyword
-arguments for clarity.
-
-The module defines the following user-callable functions:
-
-\begin{funcdesc}{TemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
- bufsize=\code{-1}\optional{,
- suffix\optional{, prefix\optional{, dir}}}}}}
-Return a file (or file-like) object that can be used as a temporary
-storage area. The file is created using \function{mkstemp}. It will
-be destroyed as soon as it is closed (including an implicit close when
-the object is garbage collected). Under \UNIX, the directory entry
-for the file is removed immediately after the file is created. Other
-platforms do not support this; your code should not rely on a
-temporary file created using this function having or not having a
-visible name in the file system.
-
-The \var{mode} parameter defaults to \code{'w+b'} so that the file
-created can be read and written without being closed. Binary mode is
-used so that it behaves consistently on all platforms without regard
-for the data that is stored. \var{bufsize} defaults to \code{-1},
-meaning that the operating system default is used.
-
-The \var{dir}, \var{prefix} and \var{suffix} parameters are passed to
-\function{mkstemp()}.
-\end{funcdesc}
-
-\begin{funcdesc}{NamedTemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
- bufsize=\code{-1}\optional{,
- suffix\optional{, prefix\optional{,
- dir\optional{, delete}}}}}}}
-This function operates exactly as \function{TemporaryFile()} does,
-except that the file is guaranteed to have a visible name in the file
-system (on \UNIX, the directory entry is not unlinked). That name can
-be retrieved from the \member{name} member of the file object. Whether
-the name can be used to open the file a second time, while the
-named temporary file is still open, varies across platforms (it can
-be so used on \UNIX; it cannot on Windows NT or later).
-If \var{delete} is true (the default), the file is deleted as soon as
-it is closed.
-\versionadded{2.3}
-\versionadded[The \var{delete} parameter]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{SpooledTemporaryFile}{\optional{max\_size=\code{0},
- \optional{mode=\code{'w+b'}\optional{,
- bufsize=\code{-1}\optional{,
- suffix\optional{, prefix\optional{,
- dir}}}}}}}
-This function operates exactly as \function{TemporaryFile()} does,
-except that data is spooled in memory until the file size exceeds
-\var{max_size}, or until the file's \function{fileno()} method is
-called, at which point the contents are written to disk and operation
-proceeds as with \function{TemporaryFile()}.
-
-The resulting file has one additional method, \function{rollover()},
-which causes the file to roll over to an on-disk file regardless of
-its size.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{mkstemp}{\optional{suffix\optional{,
- prefix\optional{, dir\optional{, text}}}}}
-Creates a temporary file in the most secure manner possible. There
-are no race conditions in the file's creation, assuming that the
-platform properly implements the \constant{O_EXCL} flag for
-\function{os.open()}. The file is readable and writable only by the
-creating user ID. If the platform uses permission bits to indicate
-whether a file is executable, the file is executable by no one. The
-file descriptor is not inherited by child processes.
-
-Unlike \function{TemporaryFile()}, the user of \function{mkstemp()} is
-responsible for deleting the temporary file when done with it.
-
-If \var{suffix} is specified, the file name will end with that suffix,
-otherwise there will be no suffix. \function{mkstemp()} does not put a
-dot between the file name and the suffix; if you need one, put it at
-the beginning of \var{suffix}.
-
-If \var{prefix} is specified, the file name will begin with that
-prefix; otherwise, a default prefix is used.
-
-If \var{dir} is specified, the file will be created in that directory;
-otherwise, a default directory is used. The default directory is chosen
-from a platform-dependent list, but the user of the application can control
-the directory location by setting the \var{TMPDIR}, \var{TEMP} or \var{TMP}
-environment variables. There is thus no guarantee that the generated
-filename will have any nice properties, such as not requiring quoting when
-passed to external commands via \code{os.popen()}.
-
-If \var{text} is specified, it indicates whether to open the file in
-binary mode (the default) or text mode. On some platforms, this makes
-no difference.
-
-\function{mkstemp()} returns a tuple containing an OS-level handle to
-an open file (as would be returned by \function{os.open()}) and the
-absolute pathname of that file, in that order.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
-Creates a temporary directory in the most secure manner possible.
-There are no race conditions in the directory's creation. The
-directory is readable, writable, and searchable only by the
-creating user ID.
-
-The user of \function{mkdtemp()} is responsible for deleting the
-temporary directory and its contents when done with it.
-
-The \var{prefix}, \var{suffix}, and \var{dir} arguments are the same
-as for \function{mkstemp()}.
-
-\function{mkdtemp()} returns the absolute pathname of the new directory.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{mktemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
-\deprecated{2.3}{Use \function{mkstemp()} instead.}
-Return an absolute pathname of a file that did not exist at the time
-the call is made. The \var{prefix}, \var{suffix}, and \var{dir}
-arguments are the same as for \function{mkstemp()}.
-
-\warning{Use of this function may introduce a security hole in your
-program. By the time you get around to doing anything with the file
-name it returns, someone else may have beaten you to the punch.}
-\end{funcdesc}
-
-The module uses two global variables that tell it how to construct a
-temporary name. They are initialized at the first call to any of the
-functions above. The caller may change them, but this is discouraged;
-use the appropriate function arguments, instead.
-
-\begin{datadesc}{tempdir}
-When set to a value other than \code{None}, this variable defines the
-default value for the \var{dir} argument to all the functions defined
-in this module.
-
-If \code{tempdir} is unset or \code{None} at any call to any of the
-above functions, Python searches a standard list of directories and
-sets \var{tempdir} to the first one which the calling user can create
-files in. The list is:
-
-\begin{enumerate}
-\item The directory named by the \envvar{TMPDIR} environment variable.
-\item The directory named by the \envvar{TEMP} environment variable.
-\item The directory named by the \envvar{TMP} environment variable.
-\item A platform-specific location:
- \begin{itemize}
- \item On RiscOS, the directory named by the
- \envvar{Wimp\$ScrapDir} environment variable.
- \item On Windows, the directories
- \file{C:$\backslash$TEMP},
- \file{C:$\backslash$TMP},
- \file{$\backslash$TEMP}, and
- \file{$\backslash$TMP}, in that order.
- \item On all other platforms, the directories
- \file{/tmp}, \file{/var/tmp}, and \file{/usr/tmp}, in that order.
- \end{itemize}
-\item As a last resort, the current working directory.
-\end{enumerate}
-\end{datadesc}
-
-\begin{funcdesc}{gettempdir}{}
-Return the directory currently selected to create temporary files in.
-If \code{tempdir} is not \code{None}, this simply returns its contents;
-otherwise, the search described above is performed, and the result
-returned.
-\end{funcdesc}
-
-\begin{datadesc}{template}
-\deprecated{2.0}{Use \function{gettempprefix()} instead.}
-When set to a value other than \code{None}, this variable defines the
-prefix of the final component of the filenames returned by
-\function{mktemp()}. A string of six random letters and digits is
-appended to the prefix to make the filename unique. On Windows,
-the default prefix is \file{\textasciitilde{}T}; on all other systems
-it is \file{tmp}.
-
-Older versions of this module used to require that \code{template} be
-set to \code{None} after a call to \function{os.fork()}; this has not
-been necessary since version 1.5.2.
-\end{datadesc}
-
-\begin{funcdesc}{gettempprefix}{}
-Return the filename prefix used to create temporary files. This does
-not contain the directory component. Using this function is preferred
-over reading the \var{template} variable directly.
-\versionadded{1.5.2}
-\end{funcdesc}
diff --git a/Doc/lib/libtermios.tex b/Doc/lib/libtermios.tex
deleted file mode 100644
index 64f3438..0000000
--- a/Doc/lib/libtermios.tex
+++ /dev/null
@@ -1,112 +0,0 @@
-\section{\module{termios} ---
- \POSIX{} style tty control}
-
-\declaremodule{builtin}{termios}
- \platform{Unix}
-\modulesynopsis{\POSIX\ style tty control.}
-
-\indexii{\POSIX}{I/O control}
-\indexii{tty}{I/O control}
-
-
-This module provides an interface to the \POSIX{} calls for tty I/O
-control. For a complete description of these calls, see the \POSIX{} or
-\UNIX{} manual pages. It is only available for those \UNIX{} versions
-that support \POSIX{} \emph{termios} style tty I/O control (and then
-only if configured at installation time).
-
-All functions in this module take a file descriptor \var{fd} as their
-first argument. This can be an integer file descriptor, such as
-returned by \code{sys.stdin.fileno()}, or a file object, such as
-\code{sys.stdin} itself.
-
-This module also defines all the constants needed to work with the
-functions provided here; these have the same name as their
-counterparts in C. Please refer to your system documentation for more
-information on using these terminal control interfaces.
-
-The module defines the following functions:
-
-\begin{funcdesc}{tcgetattr}{fd}
-Return a list containing the tty attributes for file descriptor
-\var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
-\var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
-\var{cc} is a list of the tty special characters (each a string of
-length 1, except the items with indices \constant{VMIN} and
-\constant{VTIME}, which are integers when these fields are
-defined). The interpretation of the flags and the speeds as well as
-the indexing in the \var{cc} array must be done using the symbolic
-constants defined in the \module{termios}
-module.
-\end{funcdesc}
-
-\begin{funcdesc}{tcsetattr}{fd, when, attributes}
-Set the tty attributes for file descriptor \var{fd} from the
-\var{attributes}, which is a list like the one returned by
-\function{tcgetattr()}. The \var{when} argument determines when the
-attributes are changed: \constant{TCSANOW} to change immediately,
-\constant{TCSADRAIN} to change after transmitting all queued output,
-or \constant{TCSAFLUSH} to change after transmitting all queued
-output and discarding all queued input.
-\end{funcdesc}
-
-\begin{funcdesc}{tcsendbreak}{fd, duration}
-Send a break on file descriptor \var{fd}. A zero \var{duration} sends
-a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
-dependent meaning.
-\end{funcdesc}
-
-\begin{funcdesc}{tcdrain}{fd}
-Wait until all output written to file descriptor \var{fd} has been
-transmitted.
-\end{funcdesc}
-
-\begin{funcdesc}{tcflush}{fd, queue}
-Discard queued data on file descriptor \var{fd}. The \var{queue}
-selector specifies which queue: \constant{TCIFLUSH} for the input
-queue, \constant{TCOFLUSH} for the output queue, or
-\constant{TCIOFLUSH} for both queues.
-\end{funcdesc}
-
-\begin{funcdesc}{tcflow}{fd, action}
-Suspend or resume input or output on file descriptor \var{fd}. The
-\var{action} argument can be \constant{TCOOFF} to suspend output,
-\constant{TCOON} to restart output, \constant{TCIOFF} to suspend
-input, or \constant{TCION} to restart input.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{tty}{Convenience functions for common terminal control
- operations.}
-\end{seealso}
-
-
-\subsection{Example}
-\nodename{termios Example}
-
-Here's a function that prompts for a password with echoing turned
-off. Note the technique using a separate \function{tcgetattr()} call
-and a \keyword{try} ... \keyword{finally} statement to ensure that the
-old tty attributes are restored exactly no matter what happens:
-
-\begin{verbatim}
-def raw_input(prompt):
- import sys
- sys.stdout.write(prompt)
- sys.stdout.flush()
- return sys.stdin.readline()
-
-def getpass(prompt = "Password: "):
- import termios, sys
- fd = sys.stdin.fileno()
- old = termios.tcgetattr(fd)
- new = termios.tcgetattr(fd)
- new[3] = new[3] & ~termios.ECHO # lflags
- try:
- termios.tcsetattr(fd, termios.TCSADRAIN, new)
- passwd = raw_input(prompt)
- finally:
- termios.tcsetattr(fd, termios.TCSADRAIN, old)
- return passwd
-\end{verbatim}
diff --git a/Doc/lib/libtest.tex b/Doc/lib/libtest.tex
deleted file mode 100644
index d258089..0000000
--- a/Doc/lib/libtest.tex
+++ /dev/null
@@ -1,316 +0,0 @@
-\section{\module{test} ---
- Regression tests package for Python}
-
-\declaremodule{standard}{test}
-\sectionauthor{Brett Cannon}{brett@python.org}
-\modulesynopsis{Regression tests package containing the testing suite
- for Python.}
-
-
-The \module{test} package contains all regression tests for Python as
-well as the modules \module{test.test_support} and
-\module{test.regrtest}. \module{test.test_support} is used to enhance
-your tests while \module{test.regrtest} drives the testing suite.
-
-Each module in the \module{test} package whose name starts with
-\samp{test_} is a testing suite for a specific module or feature.
-All new tests should be written using the \refmodule{unittest} or
-\refmodule{doctest} module. Some older tests are
-written using a ``traditional'' testing style that compares output
-printed to \code{sys.stdout}; this style of test is considered
-deprecated.
-
-\begin{seealso}
-\seemodule{unittest}{Writing PyUnit regression tests.}
-\seemodule{doctest}{Tests embedded in documentation strings.}
-\end{seealso}
-
-
-\subsection{Writing Unit Tests for the \module{test} package%
- \label{writing-tests}}
-
-It is preferred that tests that use the \refmodule{unittest} module
-follow a few guidelines.
-One is to name the test module by starting it with \samp{test_} and end it with
-the name of the module being tested.
-The test methods in the test module should start with \samp{test_} and end with
-a description of what the method is testing.
-This is needed so that the methods are recognized by the test driver as
-test methods.
-Also, no documentation string for the method should be included.
-A comment (such as
-\samp{\# Tests function returns only True or False}) should be used to provide
-documentation for test methods.
-This is done because documentation strings get printed out if they exist and
-thus what test is being run is not stated.
-
-A basic boilerplate is often used:
-
-\begin{verbatim}
-import unittest
-from test import test_support
-
-class MyTestCase1(unittest.TestCase):
-
- # Only use setUp() and tearDown() if necessary
-
- def setUp(self):
- ... code to execute in preparation for tests ...
-
- def tearDown(self):
- ... code to execute to clean up after tests ...
-
- def test_feature_one(self):
- # Test feature one.
- ... testing code ...
-
- def test_feature_two(self):
- # Test feature two.
- ... testing code ...
-
- ... more test methods ...
-
-class MyTestCase2(unittest.TestCase):
- ... same structure as MyTestCase1 ...
-
-... more test classes ...
-
-def test_main():
- test_support.run_unittest(MyTestCase1,
- MyTestCase2,
- ... list other tests ...
- )
-
-if __name__ == '__main__':
- test_main()
-\end{verbatim}
-
-This boilerplate code allows the testing suite to be run by
-\module{test.regrtest} as well as on its own as a script.
-
-The goal for regression testing is to try to break code.
-This leads to a few guidelines to be followed:
-
-\begin{itemize}
-\item The testing suite should exercise all classes, functions, and
- constants.
- This includes not just the external API that is to be presented to the
- outside world but also "private" code.
-\item Whitebox testing (examining the code being tested when the tests are
- being written) is preferred.
- Blackbox testing (testing only the published user interface) is not
- complete enough to make sure all boundary and edge cases are tested.
-\item Make sure all possible values are tested including invalid ones.
- This makes sure that not only all valid values are acceptable but also
- that improper values are handled correctly.
-\item Exhaust as many code paths as possible.
- Test where branching occurs and thus tailor input to make sure as many
- different paths through the code are taken.
-\item Add an explicit test for any bugs discovered for the tested code.
- This will make sure that the error does not crop up again if the code is
- changed in the future.
-\item Make sure to clean up after your tests (such as close and remove all
- temporary files).
-\item If a test is dependent on a specific condition of the operating system
- then verify the condition already exists before attempting the test.
-\item Import as few modules as possible and do it as soon as possible.
- This minimizes external dependencies of tests and also minimizes possible
- anomalous behavior from side-effects of importing a module.
-\item Try to maximize code reuse.
- On occasion, tests will vary by something as small as what type
- of input is used.
- Minimize code duplication by subclassing a basic test class with a class
- that specifies the input:
-\begin{verbatim}
-class TestFuncAcceptsSequences(unittest.TestCase):
-
- func = mySuperWhammyFunction
-
- def test_func(self):
- self.func(self.arg)
-
-class AcceptLists(TestFuncAcceptsSequences):
- arg = [1,2,3]
-
-class AcceptStrings(TestFuncAcceptsSequences):
- arg = 'abc'
-
-class AcceptTuples(TestFuncAcceptsSequences):
- arg = (1,2,3)
-\end{verbatim}
-\end{itemize}
-
-\begin{seealso}
-\seetitle{Test Driven Development}
- {A book by Kent Beck on writing tests before code.}
-\end{seealso}
-
-
-\subsection{Running tests using \module{test.regrtest} \label{regrtest}}
-
-\module{test.regrtest} can be used as a script to drive Python's
-regression test suite.
-Running the script by itself automatically starts running all
-regression tests in the \module{test} package.
-It does this by finding all modules in the package whose name starts with
-\samp{test_}, importing them, and executing the function
-\function{test_main()} if present.
-The names of tests to execute may also be passed to the script.
-Specifying a single regression test (\program{python regrtest.py}
-\programopt{test_spam.py}) will minimize output and only print whether
-the test passed or failed and thus minimize output.
-
-Running \module{test.regrtest} directly allows what resources are
-available for tests to use to be set.
-You do this by using the \programopt{-u} command-line option.
-Run \program{python regrtest.py} \programopt{-uall} to turn on all
-resources; specifying \programopt{all} as an option for
-\programopt{-u} enables all possible resources.
-If all but one resource is desired (a more common case), a
-comma-separated list of resources that are not desired may be listed after
-\programopt{all}.
-The command \program{python regrtest.py}
-\programopt{-uall,-audio,-largefile} will run \module{test.regrtest}
-with all resources except the \programopt{audio} and
-\programopt{largefile} resources.
-For a list of all resources and more command-line options, run
-\program{python regrtest.py} \programopt{-h}.
-
-Some other ways to execute the regression tests depend on what platform the
-tests are being executed on.
-On \UNIX{}, you can run \program{make} \programopt{test} at the
-top-level directory where Python was built.
-On Windows, executing \program{rt.bat} from your \file{PCBuild}
-directory will run all regression tests.
-
-
-\section{\module{test.test_support} ---
- Utility functions for tests}
-
-\declaremodule[test.testsupport]{standard}{test.test_support}
-\modulesynopsis{Support for Python regression tests.}
-
-The \module{test.test_support} module provides support for Python's
-regression tests.
-
-This module defines the following exceptions:
-
-\begin{excdesc}{TestFailed}
-Exception to be raised when a test fails. This is deprecated in favor
-of \module{unittest}-based tests and \class{unittest.TestCase}'s
-assertion methods.
-\end{excdesc}
-
-\begin{excdesc}{TestSkipped}
-Subclass of \exception{TestFailed}.
-Raised when a test is skipped.
-This occurs when a needed resource (such as a network connection) is not
-available at the time of testing.
-\end{excdesc}
-
-\begin{excdesc}{ResourceDenied}
-Subclass of \exception{TestSkipped}.
-Raised when a resource (such as a network connection) is not available.
-Raised by the \function{requires()} function.
-\end{excdesc}
-
-
-The \module{test.test_support} module defines the following constants:
-
-\begin{datadesc}{verbose}
-\constant{True} when verbose output is enabled.
-Should be checked when more detailed information is desired about a running
-test.
-\var{verbose} is set by \module{test.regrtest}.
-\end{datadesc}
-
-\begin{datadesc}{have_unicode}
-\constant{True} when Unicode support is available.
-\end{datadesc}
-
-\begin{datadesc}{is_jython}
-\constant{True} if the running interpreter is Jython.
-\end{datadesc}
-
-\begin{datadesc}{TESTFN}
-Set to the path that a temporary file may be created at.
-Any temporary that is created should be closed and unlinked (removed).
-\end{datadesc}
-
-
-The \module{test.test_support} module defines the following functions:
-
-\begin{funcdesc}{forget}{module_name}
-Removes the module named \var{module_name} from \code{sys.modules} and deletes
-any byte-compiled files of the module.
-\end{funcdesc}
-
-\begin{funcdesc}{is_resource_enabled}{resource}
-Returns \constant{True} if \var{resource} is enabled and available.
-The list of available resources is only set when \module{test.regrtest}
-is executing the tests.
-\end{funcdesc}
-
-\begin{funcdesc}{requires}{resource\optional{, msg}}
-Raises \exception{ResourceDenied} if \var{resource} is not available.
-\var{msg} is the argument to \exception{ResourceDenied} if it is raised.
-Always returns true if called by a function whose \code{__name__} is
-\code{'__main__'}.
-Used when tests are executed by \module{test.regrtest}.
-\end{funcdesc}
-
-\begin{funcdesc}{findfile}{filename}
-Return the path to the file named \var{filename}.
-If no match is found \var{filename} is returned.
-This does not equal a failure since it could be the path to the file.
-\end{funcdesc}
-
-\begin{funcdesc}{guard_warnings_filter}{}
-Returns a context manager that guards the \module{warnings} module's
-filter settings.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{run_unittest}{*classes}
-Execute \class{unittest.TestCase} subclasses passed to the function.
-The function scans the classes for methods starting with the prefix
-\samp{test_} and executes the tests individually.
-
-It is also legal to pass strings as parameters; these should be keys in
-\code{sys.modules}. Each associated module will be scanned by
-\code{unittest.TestLoader.loadTestsFromModule()}. This is usually seen in
-the following \function{test_main()} function:
-
-\begin{verbatim}
-def test_main():
- test_support.run_unittest(__name__)
-\end{verbatim}
-
-This will run all tests defined in the named module.
-\end{funcdesc}
-
-The \module{test.test_support} module defines the following classes:
-
-\begin{classdesc}{TransientResource}{exc\optional{, **kwargs}}
-Create a context manager that raises \class{ResourceDenied} if the specified
-exception type is raised. Any keyword arguments are treated as name/value
-pairs to be compared against any exception raised with the \code{with}
-statement. Only if all pairs match is \class{ResourceDenied} raised.
-\versionadded{2.6}
-\end{classdesc}
-
-\begin{classdesc}{EnvironmentVarGuard}{}
-Class used to temporarily set or unset environment variables. Instances can be
-used as a context manager.
-\versionadded{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{set}{envvar, value}
-Temporarily set the environment variable \code{envvar} to the value of
-\code{value}.
-\end{methoddesc}
-
-\begin{methoddesc}{unset}{envvar}
-Temporarily unset the environment variable \code{envvar}.
-\end{methoddesc}
-
diff --git a/Doc/lib/libtextwrap.tex b/Doc/lib/libtextwrap.tex
deleted file mode 100644
index 8ea25a8..0000000
--- a/Doc/lib/libtextwrap.tex
+++ /dev/null
@@ -1,188 +0,0 @@
-\section{\module{textwrap} ---
- Text wrapping and filling}
-
-\declaremodule{standard}{textwrap}
-\modulesynopsis{Text wrapping and filling}
-\moduleauthor{Greg Ward}{gward@python.net}
-\sectionauthor{Greg Ward}{gward@python.net}
-
-\versionadded{2.3}
-
-The \module{textwrap} module provides two convenience functions,
-\function{wrap()} and \function{fill()}, as well as
-\class{TextWrapper}, the class that does all the work, and a utility function
-\function{dedent()}. If you're just wrapping or filling one or two
-text strings, the convenience functions should be good enough; otherwise,
-you should use an instance of \class{TextWrapper} for efficiency.
-
-\begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}}
-Wraps the single paragraph in \var{text} (a string) so every line is at
-most \var{width} characters long. Returns a list of output lines,
-without final newlines.
-
-Optional keyword arguments correspond to the instance attributes of
-\class{TextWrapper}, documented below. \var{width} defaults to
-\code{70}.
-\end{funcdesc}
-
-\begin{funcdesc}{fill}{text\optional{, width\optional{, \moreargs}}}
-Wraps the single paragraph in \var{text}, and returns a single string
-containing the wrapped paragraph. \function{fill()} is shorthand for
-\begin{verbatim}
-"\n".join(wrap(text, ...))
-\end{verbatim}
-
-In particular, \function{fill()} accepts exactly the same keyword
-arguments as \function{wrap()}.
-\end{funcdesc}
-
-Both \function{wrap()} and \function{fill()} work by creating a
-\class{TextWrapper} instance and calling a single method on it. That
-instance is not reused, so for applications that wrap/fill many text
-strings, it will be more efficient for you to create your own
-\class{TextWrapper} object.
-
-An additional utility function, \function{dedent()}, is provided to
-remove indentation from strings that have unwanted whitespace to the
-left of the text.
-
-\begin{funcdesc}{dedent}{text}
-Remove any common leading whitespace from every line in \var{text}.
-
-This can be used to make triple-quoted strings line up with the left
-edge of the display, while still presenting them in the source code
-in indented form.
-
-Note that tabs and spaces are both treated as whitespace, but they are
-not equal: the lines \code{" {} hello"} and \code{"\e thello"}
-are considered to have no common leading whitespace. (This behaviour is
-new in Python 2.5; older versions of this module incorrectly expanded
-tabs before searching for common leading whitespace.)
-
-For example:
-\begin{verbatim}
-def test():
- # end first line with \ to avoid the empty line!
- s = '''\
- hello
- world
- '''
- print repr(s) # prints ' hello\n world\n '
- print repr(dedent(s)) # prints 'hello\n world\n'
-\end{verbatim}
-\end{funcdesc}
-
-\begin{classdesc}{TextWrapper}{...}
-The \class{TextWrapper} constructor accepts a number of optional
-keyword arguments. Each argument corresponds to one instance attribute,
-so for example
-\begin{verbatim}
-wrapper = TextWrapper(initial_indent="* ")
-\end{verbatim}
-is the same as
-\begin{verbatim}
-wrapper = TextWrapper()
-wrapper.initial_indent = "* "
-\end{verbatim}
-
-You can re-use the same \class{TextWrapper} object many times, and you
-can change any of its options through direct assignment to instance
-attributes between uses.
-\end{classdesc}
-
-The \class{TextWrapper} instance attributes (and keyword arguments to
-the constructor) are as follows:
-
-\begin{memberdesc}{width}
-(default: \code{70}) The maximum length of wrapped lines. As long as
-there are no individual words in the input text longer than
-\member{width}, \class{TextWrapper} guarantees that no output line
-will be longer than \member{width} characters.
-\end{memberdesc}
-
-\begin{memberdesc}{expand_tabs}
-(default: \code{True}) If true, then all tab characters in \var{text}
-will be expanded to spaces using the \method{expandtabs()} method of
-\var{text}.
-\end{memberdesc}
-
-\begin{memberdesc}{replace_whitespace}
-(default: \code{True}) If true, each whitespace character (as defined
-by \code{string.whitespace}) remaining after tab expansion will be
-replaced by a single space. \note{If \member{expand_tabs} is false
-and \member{replace_whitespace} is true, each tab character will be
-replaced by a single space, which is \emph{not} the same as tab
-expansion.}
-\end{memberdesc}
-
-\begin{memberdesc}{drop_whitespace}
-(default: \code{True}) If true, whitespace that, after wrapping, happens
-to end up at the beginning or end of a line is dropped (leading whitespace
-in the first line is always preserved, though).
-\versionadded[Whitespace was always dropped in earlier versions]{2.6}
-\end{memberdesc}
-
-\begin{memberdesc}{initial_indent}
-(default: \code{''}) String that will be prepended to the first line
-of wrapped output. Counts towards the length of the first line.
-\end{memberdesc}
-
-\begin{memberdesc}{subsequent_indent}
-(default: \code{''}) String that will be prepended to all lines of
-wrapped output except the first. Counts towards the length of each
-line except the first.
-\end{memberdesc}
-
-\begin{memberdesc}{fix_sentence_endings}
-(default: \code{False}) If true, \class{TextWrapper} attempts to detect
-sentence endings and ensure that sentences are always separated by
-exactly two spaces. This is generally desired for text in a monospaced
-font. However, the sentence detection algorithm is imperfect: it
-assumes that a sentence ending consists of a lowercase letter followed
-by one of \character{.},
-\character{!}, or \character{?}, possibly followed by one of
-\character{"} or \character{'}, followed by a space. One problem
-with this is algorithm is that it is unable to detect the difference
-between ``Dr.'' in
-
-\begin{verbatim}
-[...] Dr. Frankenstein's monster [...]
-\end{verbatim}
-
-and ``Spot.'' in
-
-\begin{verbatim}
-[...] See Spot. See Spot run [...]
-\end{verbatim}
-
-\member{fix_sentence_endings} is false by default.
-
-Since the sentence detection algorithm relies on
-\code{string.lowercase} for the definition of ``lowercase letter,''
-and a convention of using two spaces after a period to separate
-sentences on the same line, it is specific to English-language texts.
-\end{memberdesc}
-
-\begin{memberdesc}{break_long_words}
-(default: \code{True}) If true, then words longer than
-\member{width} will be broken in order to ensure that no lines are
-longer than \member{width}. If it is false, long words will not be
-broken, and some lines may be longer than \member{width}. (Long words
-will be put on a line by themselves, in order to minimize the amount
-by which \member{width} is exceeded.)
-\end{memberdesc}
-
-\class{TextWrapper} also provides two public methods, analogous to the
-module-level convenience functions:
-
-\begin{methoddesc}{wrap}{text}
-Wraps the single paragraph in \var{text} (a string) so every line is
-at most \member{width} characters long. All wrapping options are
-taken from instance attributes of the \class{TextWrapper} instance.
-Returns a list of output lines, without final newlines.
-\end{methoddesc}
-
-\begin{methoddesc}{fill}{text}
-Wraps the single paragraph in \var{text}, and returns a single string
-containing the wrapped paragraph.
-\end{methoddesc}
diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex
deleted file mode 100644
index d007eec..0000000
--- a/Doc/lib/libthread.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{thread} ---
- Multiple threads of control}
-
-\declaremodule{builtin}{thread}
-\modulesynopsis{Create multiple threads of control within one interpreter.}
-
-
-This module provides low-level primitives for working with multiple
-threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple
-threads of control sharing their global data space. For
-synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary
-semaphores}) are provided.
-\index{light-weight processes}
-\index{processes, light-weight}
-\index{binary semaphores}
-\index{semaphores, binary}
-
-The module is optional. It is supported on Windows, Linux, SGI
-IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread
-(a.k.a. ``pthread'') implementation. For systems lacking the \module{thread}
-module, the \refmodule[dummythread]{dummy_thread} module is available.
-It duplicates this module's interface and can be
-used as a drop-in replacement.
-\index{pthreads}
-\indexii{threads}{\POSIX}
-
-It defines the following constant and functions:
-
-\begin{excdesc}{error}
-Raised on thread-specific errors.
-\end{excdesc}
-
-\begin{datadesc}{LockType}
-This is the type of lock objects.
-\end{datadesc}
-
-\begin{funcdesc}{start_new_thread}{function, args\optional{, kwargs}}
-Start a new thread and return its identifier. The thread executes the function
-\var{function} with the argument list \var{args} (which must be a tuple). The
-optional \var{kwargs} argument specifies a dictionary of keyword arguments.
-When the function returns, the thread silently exits. When the function
-terminates with an unhandled exception, a stack trace is printed and
-then the thread exits (but other threads continue to run).
-\end{funcdesc}
-
-\begin{funcdesc}{interrupt_main}{}
-Raise a \exception{KeyboardInterrupt} exception in the main thread. A subthread
-can use this function to interrupt the main thread.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{exit}{}
-Raise the \exception{SystemExit} exception. When not caught, this
-will cause the thread to exit silently.
-\end{funcdesc}
-
-%\begin{funcdesc}{exit_prog}{status}
-%Exit all threads and report the value of the integer argument
-%\var{status} as the exit status of the entire program.
-%\strong{Caveat:} code in pending \keyword{finally} clauses, in this thread
-%or in other threads, is not executed.
-%\end{funcdesc}
-
-\begin{funcdesc}{allocate_lock}{}
-Return a new lock object. Methods of locks are described below. The
-lock is initially unlocked.
-\end{funcdesc}
-
-\begin{funcdesc}{get_ident}{}
-Return the `thread identifier' of the current thread. This is a
-nonzero integer. Its value has no direct meaning; it is intended as a
-magic cookie to be used e.g. to index a dictionary of thread-specific
-data. Thread identifiers may be recycled when a thread exits and
-another thread is created.
-\end{funcdesc}
-
-\begin{funcdesc}{stack_size}{\optional{size}}
-Return the thread stack size used when creating new threads. The
-optional \var{size} argument specifies the stack size to be used for
-subsequently created threads, and must be 0 (use platform or
-configured default) or a positive integer value of at least 32,768 (32kB).
-If changing the thread stack size is unsupported, a \exception{ThreadError}
-is raised. If the specified stack size is invalid, a \exception{ValueError}
-is raised and the stack size is unmodified. 32kB is currently the minimum
-supported stack size value to guarantee sufficient stack space for the
-interpreter itself. Note that some platforms may have particular
-restrictions on values for the stack size, such as requiring a minimum
-stack size > 32kB or requiring allocation in multiples of the system
-memory page size - platform documentation should be referred to for
-more information (4kB pages are common; using multiples of 4096 for
-the stack size is the suggested approach in the absence of more
-specific information).
-Availability: Windows, systems with \POSIX{} threads.
-\versionadded{2.5}
-\end{funcdesc}
-
-
-Lock objects have the following methods:
-
-\begin{methoddesc}[lock]{acquire}{\optional{waitflag}}
-Without the optional argument, this method acquires the lock
-unconditionally, if necessary waiting until it is released by another
-thread (only one thread at a time can acquire a lock --- that's their
-reason for existence). If the integer
-\var{waitflag} argument is present, the action depends on its
-value: if it is zero, the lock is only acquired if it can be acquired
-immediately without waiting, while if it is nonzero, the lock is
-acquired unconditionally as before. The
-return value is \code{True} if the lock is acquired successfully,
-\code{False} if not.
-\end{methoddesc}
-
-\begin{methoddesc}[lock]{release}{}
-Releases the lock. The lock must have been acquired earlier, but not
-necessarily by the same thread.
-\end{methoddesc}
-
-\begin{methoddesc}[lock]{locked}{}
-Return the status of the lock:\ \code{True} if it has been acquired by
-some thread, \code{False} if not.
-\end{methoddesc}
-
-In addition to these methods, lock objects can also be used via the
-\keyword{with} statement, e.g.:
-
-\begin{verbatim}
-from __future__ import with_statement
-import thread
-
-a_lock = thread.allocate_lock()
-
-with a_lock:
- print "a_lock is locked while this executes"
-\end{verbatim}
-
-\strong{Caveats:}
-
-\begin{itemize}
-\item
-Threads interact strangely with interrupts: the
-\exception{KeyboardInterrupt} exception will be received by an
-arbitrary thread. (When the \refmodule{signal}\refbimodindex{signal}
-module is available, interrupts always go to the main thread.)
-
-\item
-Calling \function{sys.exit()} or raising the \exception{SystemExit}
-exception is equivalent to calling \function{exit()}.
-
-\item
-Not all built-in functions that may block waiting for I/O allow other
-threads to run. (The most popular ones (\function{time.sleep()},
-\method{\var{file}.read()}, \function{select.select()}) work as
-expected.)
-
-\item
-It is not possible to interrupt the \method{acquire()} method on a lock
---- the \exception{KeyboardInterrupt} exception will happen after the
-lock has been acquired.
-
-\item
-When the main thread exits, it is system defined whether the other
-threads survive. On SGI IRIX using the native thread implementation,
-they survive. On most other systems, they are killed without
-executing \keyword{try} ... \keyword{finally} clauses or executing
-object destructors.
-\indexii{threads}{IRIX}
-
-\item
-When the main thread exits, it does not do any of its usual cleanup
-(except that \keyword{try} ... \keyword{finally} clauses are honored),
-and the standard I/O files are not flushed.
-
-\end{itemize}
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex
deleted file mode 100644
index 19c496e..0000000
--- a/Doc/lib/libthreading.tex
+++ /dev/null
@@ -1,728 +0,0 @@
-\section{\module{threading} ---
- Higher-level threading interface}
-
-\declaremodule{standard}{threading}
-\modulesynopsis{Higher-level threading interface.}
-
-
-This module constructs higher-level threading interfaces on top of the
-lower level \refmodule{thread} module.
-
-The \refmodule[dummythreading]{dummy_threading} module is provided for
-situations where \module{threading} cannot be used because
-\refmodule{thread} is missing.
-
-This module defines the following functions and objects:
-
-\begin{funcdesc}{activeCount}{}
-Return the number of \class{Thread} objects currently alive. The
-returned count is equal to the length of the list returned by
-\function{enumerate()}.
-\end{funcdesc}
-
-\begin{funcdescni}{Condition}{}
-A factory function that returns a new condition variable object.
-A condition variable allows one or more threads to wait until they
-are notified by another thread.
-\end{funcdescni}
-
-\begin{funcdesc}{currentThread}{}
-Return the current \class{Thread} object, corresponding to the
-caller's thread of control. If the caller's thread of control was not
-created through the
-\module{threading} module, a dummy thread object with limited functionality
-is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{enumerate}{}
-Return a list of all \class{Thread} objects currently alive. The list
-includes daemonic threads, dummy thread objects created by
-\function{currentThread()}, and the main thread. It excludes
-terminated threads and threads that have not yet been started.
-\end{funcdesc}
-
-\begin{funcdescni}{Event}{}
-A factory function that returns a new event object. An event manages
-a flag that can be set to true with the \method{set()} method and
-reset to false with the \method{clear()} method. The \method{wait()}
-method blocks until the flag is true.
-\end{funcdescni}
-
-\begin{classdesc*}{local}{}
-A class that represents thread-local data. Thread-local data are data
-whose values are thread specific. To manage thread-local data, just
-create an instance of \class{local} (or a subclass) and store
-attributes on it:
-
-\begin{verbatim}
-mydata = threading.local()
-mydata.x = 1
-\end{verbatim}
-
-The instance's values will be different for separate threads.
-
-For more details and extensive examples, see the documentation string
-of the \module{_threading_local} module.
-
-\versionadded{2.4}
-\end{classdesc*}
-
-\begin{funcdesc}{Lock}{}
-A factory function that returns a new primitive lock object. Once
-a thread has acquired it, subsequent attempts to acquire it block,
-until it is released; any thread may release it.
-\end{funcdesc}
-
-\begin{funcdesc}{RLock}{}
-A factory function that returns a new reentrant lock object.
-A reentrant lock must be released by the thread that acquired it.
-Once a thread has acquired a reentrant lock, the same thread may
-acquire it again without blocking; the thread must release it once
-for each time it has acquired it.
-\end{funcdesc}
-
-\begin{funcdescni}{Semaphore}{\optional{value}}
-A factory function that returns a new semaphore object. A
-semaphore manages a counter representing the number of \method{release()}
-calls minus the number of \method{acquire()} calls, plus an initial value.
-The \method{acquire()} method blocks if necessary until it can return
-without making the counter negative. If not given, \var{value} defaults to
-1.
-\end{funcdescni}
-
-\begin{funcdesc}{BoundedSemaphore}{\optional{value}}
-A factory function that returns a new bounded semaphore object. A bounded
-semaphore checks to make sure its current value doesn't exceed its initial
-value. If it does, \exception{ValueError} is raised. In most situations
-semaphores are used to guard resources with limited capacity. If the
-semaphore is released too many times it's a sign of a bug. If not given,
-\var{value} defaults to 1.
-\end{funcdesc}
-
-\begin{classdesc*}{Thread}
-A class that represents a thread of control. This class can be safely
-subclassed in a limited fashion.
-\end{classdesc*}
-
-\begin{classdesc*}{Timer}
-A thread that executes a function after a specified interval has passed.
-\end{classdesc*}
-
-\begin{funcdesc}{settrace}{func}
-Set a trace function\index{trace function} for all threads started
-from the \module{threading} module. The \var{func} will be passed to
-\function{sys.settrace()} for each thread, before its \method{run()}
-method is called.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setprofile}{func}
-Set a profile function\index{profile function} for all threads started
-from the \module{threading} module. The \var{func} will be passed to
-\function{sys.setprofile()} for each thread, before its \method{run()}
-method is called.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{stack_size}{\optional{size}}
-Return the thread stack size used when creating new threads. The
-optional \var{size} argument specifies the stack size to be used for
-subsequently created threads, and must be 0 (use platform or
-configured default) or a positive integer value of at least 32,768 (32kB).
-If changing the thread stack size is unsupported, a \exception{ThreadError}
-is raised. If the specified stack size is invalid, a \exception{ValueError}
-is raised and the stack size is unmodified. 32kB is currently the minimum
-supported stack size value to guarantee sufficient stack space for the
-interpreter itself. Note that some platforms may have particular
-restrictions on values for the stack size, such as requiring a minimum
-stack size > 32kB or requiring allocation in multiples of the system
-memory page size - platform documentation should be referred to for
-more information (4kB pages are common; using multiples of 4096 for
-the stack size is the suggested approach in the absence of more
-specific information).
-Availability: Windows, systems with \POSIX{} threads.
-\versionadded{2.5}
-\end{funcdesc}
-
-Detailed interfaces for the objects are documented below.
-
-The design of this module is loosely based on Java's threading model.
-However, where Java makes locks and condition variables basic behavior
-of every object, they are separate objects in Python. Python's \class{Thread}
-class supports a subset of the behavior of Java's Thread class;
-currently, there are no priorities, no thread groups, and threads
-cannot be destroyed, stopped, suspended, resumed, or interrupted. The
-static methods of Java's Thread class, when implemented, are mapped to
-module-level functions.
-
-All of the methods described below are executed atomically.
-
-
-\subsection{Lock Objects \label{lock-objects}}
-
-A primitive lock is a synchronization primitive that is not owned
-by a particular thread when locked. In Python, it is currently
-the lowest level synchronization primitive available, implemented
-directly by the \refmodule{thread} extension module.
-
-A primitive lock is in one of two states, ``locked'' or ``unlocked''.
-It is created in the unlocked state. It has two basic methods,
-\method{acquire()} and \method{release()}. When the state is
-unlocked, \method{acquire()} changes the state to locked and returns
-immediately. When the state is locked, \method{acquire()} blocks
-until a call to \method{release()} in another thread changes it to
-unlocked, then the \method{acquire()} call resets it to locked and
-returns. The \method{release()} method should only be called in the
-locked state; it changes the state to unlocked and returns
-immediately. If an attempt is made to release an unlocked lock, a
-\exception{RuntimeError} will be raised.
-
-When more than one thread is blocked in \method{acquire()} waiting for
-the state to turn to unlocked, only one thread proceeds when a
-\method{release()} call resets the state to unlocked; which one of the
-waiting threads proceeds is not defined, and may vary across
-implementations.
-
-All methods are executed atomically.
-
-\begin{methoddesc}[Lock]{acquire}{\optional{blocking\code{ = 1}}}
-Acquire a lock, blocking or non-blocking.
-
-When invoked without arguments, block until the lock is
-unlocked, then set it to locked, and return true.
-
-When invoked with the \var{blocking} argument set to true, do the
-same thing as when called without arguments, and return true.
-
-When invoked with the \var{blocking} argument set to false, do not
-block. If a call without an argument would block, return false
-immediately; otherwise, do the same thing as when called
-without arguments, and return true.
-\end{methoddesc}
-
-\begin{methoddesc}[Lock]{release}{}
-Release a lock.
-
-When the lock is locked, reset it to unlocked, and return. If
-any other threads are blocked waiting for the lock to become
-unlocked, allow exactly one of them to proceed.
-
-Do not call this method when the lock is unlocked.
-
-There is no return value.
-\end{methoddesc}
-
-
-\subsection{RLock Objects \label{rlock-objects}}
-
-A reentrant lock is a synchronization primitive that may be
-acquired multiple times by the same thread. Internally, it uses
-the concepts of ``owning thread'' and ``recursion level'' in
-addition to the locked/unlocked state used by primitive locks. In
-the locked state, some thread owns the lock; in the unlocked
-state, no thread owns it.
-
-To lock the lock, a thread calls its \method{acquire()} method; this
-returns once the thread owns the lock. To unlock the lock, a
-thread calls its \method{release()} method.
-\method{acquire()}/\method{release()} call pairs may be nested; only
-the final \method{release()} (the \method{release()} of the outermost
-pair) resets the lock to unlocked and allows another thread blocked in
-\method{acquire()} to proceed.
-
-\begin{methoddesc}[RLock]{acquire}{\optional{blocking\code{ = 1}}}
-Acquire a lock, blocking or non-blocking.
-
-When invoked without arguments: if this thread already owns
-the lock, increment the recursion level by one, and return
-immediately. Otherwise, if another thread owns the lock,
-block until the lock is unlocked. Once the lock is unlocked
-(not owned by any thread), then grab ownership, set the
-recursion level to one, and return. If more than one thread
-is blocked waiting until the lock is unlocked, only one at a
-time will be able to grab ownership of the lock. There is no
-return value in this case.
-
-When invoked with the \var{blocking} argument set to true, do the
-same thing as when called without arguments, and return true.
-
-When invoked with the \var{blocking} argument set to false, do not
-block. If a call without an argument would block, return false
-immediately; otherwise, do the same thing as when called
-without arguments, and return true.
-\end{methoddesc}
-
-\begin{methoddesc}[RLock]{release}{}
-Release a lock, decrementing the recursion level. If after the
-decrement it is zero, reset the lock to unlocked (not owned by any
-thread), and if any other threads are blocked waiting for the lock to
-become unlocked, allow exactly one of them to proceed. If after the
-decrement the recursion level is still nonzero, the lock remains
-locked and owned by the calling thread.
-
-Only call this method when the calling thread owns the lock. A
-\exception{RuntimeError} is raised if this method is called when the
-lock is unlocked.
-
-There is no return value.
-\end{methoddesc}
-
-
-\subsection{Condition Objects \label{condition-objects}}
-
-A condition variable is always associated with some kind of lock;
-this can be passed in or one will be created by default. (Passing
-one in is useful when several condition variables must share the
-same lock.)
-
-A condition variable has \method{acquire()} and \method{release()}
-methods that call the corresponding methods of the associated lock.
-It also has a \method{wait()} method, and \method{notify()} and
-\method{notifyAll()} methods. These three must only be called when
-the calling thread has acquired the lock, otherwise a
-\exception{RuntimeError} is raised.
-
-The \method{wait()} method releases the lock, and then blocks until it
-is awakened by a \method{notify()} or \method{notifyAll()} call for
-the same condition variable in another thread. Once awakened, it
-re-acquires the lock and returns. It is also possible to specify a
-timeout.
-
-The \method{notify()} method wakes up one of the threads waiting for
-the condition variable, if any are waiting. The \method{notifyAll()}
-method wakes up all threads waiting for the condition variable.
-
-Note: the \method{notify()} and \method{notifyAll()} methods don't
-release the lock; this means that the thread or threads awakened will
-not return from their \method{wait()} call immediately, but only when
-the thread that called \method{notify()} or \method{notifyAll()}
-finally relinquishes ownership of the lock.
-
-Tip: the typical programming style using condition variables uses the
-lock to synchronize access to some shared state; threads that are
-interested in a particular change of state call \method{wait()}
-repeatedly until they see the desired state, while threads that modify
-the state call \method{notify()} or \method{notifyAll()} when they
-change the state in such a way that it could possibly be a desired
-state for one of the waiters. For example, the following code is a
-generic producer-consumer situation with unlimited buffer capacity:
-
-\begin{verbatim}
-# Consume one item
-cv.acquire()
-while not an_item_is_available():
- cv.wait()
-get_an_available_item()
-cv.release()
-
-# Produce one item
-cv.acquire()
-make_an_item_available()
-cv.notify()
-cv.release()
-\end{verbatim}
-
-To choose between \method{notify()} and \method{notifyAll()}, consider
-whether one state change can be interesting for only one or several
-waiting threads. E.g. in a typical producer-consumer situation,
-adding one item to the buffer only needs to wake up one consumer
-thread.
-
-\begin{classdesc}{Condition}{\optional{lock}}
-If the \var{lock} argument is given and not \code{None}, it must be a
-\class{Lock} or \class{RLock} object, and it is used as the underlying
-lock. Otherwise, a new \class{RLock} object is created and used as
-the underlying lock.
-\end{classdesc}
-
-\begin{methoddesc}{acquire}{*args}
-Acquire the underlying lock.
-This method calls the corresponding method on the underlying
-lock; the return value is whatever that method returns.
-\end{methoddesc}
-
-\begin{methoddesc}{release}{}
-Release the underlying lock.
-This method calls the corresponding method on the underlying
-lock; there is no return value.
-\end{methoddesc}
-
-\begin{methoddesc}{wait}{\optional{timeout}}
-Wait until notified or until a timeout occurs. If the calling thread
-has not acquired the lock when this method is called, a
-\exception{RuntimeError} is raised.
-
-This method releases the underlying lock, and then blocks until it is
-awakened by a \method{notify()} or \method{notifyAll()} call for the
-same condition variable in another thread, or until the optional
-timeout occurs. Once awakened or timed out, it re-acquires the lock
-and returns.
-
-When the \var{timeout} argument is present and not \code{None}, it
-should be a floating point number specifying a timeout for the
-operation in seconds (or fractions thereof).
-
-When the underlying lock is an \class{RLock}, it is not released using
-its \method{release()} method, since this may not actually unlock the
-lock when it was acquired multiple times recursively. Instead, an
-internal interface of the \class{RLock} class is used, which really
-unlocks it even when it has been recursively acquired several times.
-Another internal interface is then used to restore the recursion level
-when the lock is reacquired.
-\end{methoddesc}
-
-\begin{methoddesc}{notify}{}
-Wake up a thread waiting on this condition, if any. Wait until
-notified or until a timeout occurs. If the calling thread has not
-acquired the lock when this method is called, a
-\exception{RuntimeError} is raised.
-
-This method wakes up one of the threads waiting for the condition
-variable, if any are waiting; it is a no-op if no threads are waiting.
-
-The current implementation wakes up exactly one thread, if any are
-waiting. However, it's not safe to rely on this behavior. A future,
-optimized implementation may occasionally wake up more than one
-thread.
-
-Note: the awakened thread does not actually return from its
-\method{wait()} call until it can reacquire the lock. Since
-\method{notify()} does not release the lock, its caller should.
-\end{methoddesc}
-
-\begin{methoddesc}{notifyAll}{}
-Wake up all threads waiting on this condition. This method acts like
-\method{notify()}, but wakes up all waiting threads instead of one. If
-the calling thread has not acquired the lock when this method is
-called, a \exception{RuntimeError} is raised.
-\end{methoddesc}
-
-
-\subsection{Semaphore Objects \label{semaphore-objects}}
-
-This is one of the oldest synchronization primitives in the history of
-computer science, invented by the early Dutch computer scientist
-Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
-\method{acquire()} and \method{release()}).
-
-A semaphore manages an internal counter which is decremented by each
-\method{acquire()} call and incremented by each \method{release()}
-call. The counter can never go below zero; when \method{acquire()}
-finds that it is zero, it blocks, waiting until some other thread
-calls \method{release()}.
-
-\begin{classdesc}{Semaphore}{\optional{value}}
-The optional argument gives the initial \var{value} for the internal
-counter; it defaults to \code{1}. If the \var{value} given is less
-than 0, \exception{ValueError} is raised.
-\end{classdesc}
-
-\begin{methoddesc}{acquire}{\optional{blocking}}
-Acquire a semaphore.
-
-When invoked without arguments: if the internal counter is larger than
-zero on entry, decrement it by one and return immediately. If it is
-zero on entry, block, waiting until some other thread has called
-\method{release()} to make it larger than zero. This is done with
-proper interlocking so that if multiple \method{acquire()} calls are
-blocked, \method{release()} will wake exactly one of them up. The
-implementation may pick one at random, so the order in which blocked
-threads are awakened should not be relied on. There is no return
-value in this case.
-
-When invoked with \var{blocking} set to true, do the same thing as
-when called without arguments, and return true.
-
-When invoked with \var{blocking} set to false, do not block. If a
-call without an argument would block, return false immediately;
-otherwise, do the same thing as when called without arguments, and
-return true.
-\end{methoddesc}
-
-\begin{methoddesc}{release}{}
-Release a semaphore,
-incrementing the internal counter by one. When it was zero on
-entry and another thread is waiting for it to become larger
-than zero again, wake up that thread.
-\end{methoddesc}
-
-
-\subsubsection{\class{Semaphore} Example \label{semaphore-examples}}
-
-Semaphores are often used to guard resources with limited capacity, for
-example, a database server. In any situation where the size of the resource
-size is fixed, you should use a bounded semaphore. Before spawning any
-worker threads, your main thread would initialize the semaphore:
-
-\begin{verbatim}
-maxconnections = 5
-...
-pool_sema = BoundedSemaphore(value=maxconnections)
-\end{verbatim}
-
-Once spawned, worker threads call the semaphore's acquire and release
-methods when they need to connect to the server:
-
-\begin{verbatim}
-pool_sema.acquire()
-conn = connectdb()
-... use connection ...
-conn.close()
-pool_sema.release()
-\end{verbatim}
-
-The use of a bounded semaphore reduces the chance that a programming error
-which causes the semaphore to be released more than it's acquired will go
-undetected.
-
-
-\subsection{Event Objects \label{event-objects}}
-
-This is one of the simplest mechanisms for communication between
-threads: one thread signals an event and other threads wait for it.
-
-An event object manages an internal flag that can be set to true with
-the \method{set()} method and reset to false with the \method{clear()}
-method. The \method{wait()} method blocks until the flag is true.
-
-
-\begin{classdesc}{Event}{}
-The internal flag is initially false.
-\end{classdesc}
-
-\begin{methoddesc}{isSet}{}
-Return true if and only if the internal flag is true.
-\end{methoddesc}
-
-\begin{methoddesc}{set}{}
-Set the internal flag to true.
-All threads waiting for it to become true are awakened.
-Threads that call \method{wait()} once the flag is true will not block
-at all.
-\end{methoddesc}
-
-\begin{methoddesc}{clear}{}
-Reset the internal flag to false.
-Subsequently, threads calling \method{wait()} will block until
-\method{set()} is called to set the internal flag to true again.
-\end{methoddesc}
-
-\begin{methoddesc}{wait}{\optional{timeout}}
-Block until the internal flag is true.
-If the internal flag is true on entry, return immediately. Otherwise,
-block until another thread calls \method{set()} to set the flag to
-true, or until the optional timeout occurs.
-
-When the timeout argument is present and not \code{None}, it should be a
-floating point number specifying a timeout for the operation in
-seconds (or fractions thereof).
-\end{methoddesc}
-
-
-\subsection{Thread Objects \label{thread-objects}}
-
-This class represents an activity that is run in a separate thread
-of control. There are two ways to specify the activity: by
-passing a callable object to the constructor, or by overriding the
-\method{run()} method in a subclass. No other methods (except for the
-constructor) should be overridden in a subclass. In other words,
-\emph{only} override the \method{__init__()} and \method{run()}
-methods of this class.
-
-Once a thread object is created, its activity must be started by
-calling the thread's \method{start()} method. This invokes the
-\method{run()} method in a separate thread of control.
-
-Once the thread's activity is started, the thread is considered
-'alive'. It stops being alive when its \method{run()} method terminates
--- either normally, or by raising an unhandled exception. The
-\method{isAlive()} method tests whether the thread is alive.
-
-Other threads can call a thread's \method{join()} method. This blocks
-the calling thread until the thread whose \method{join()} method is
-called is terminated.
-
-A thread has a name. The name can be passed to the constructor,
-set with the \method{setName()} method, and retrieved with the
-\method{getName()} method.
-
-A thread can be flagged as a ``daemon thread''. The significance
-of this flag is that the entire Python program exits when only
-daemon threads are left. The initial value is inherited from the
-creating thread. The flag can be set with the \method{setDaemon()}
-method and retrieved with the \method{isDaemon()} method.
-
-There is a ``main thread'' object; this corresponds to the
-initial thread of control in the Python program. It is not a
-daemon thread.
-
-There is the possibility that ``dummy thread objects'' are created.
-These are thread objects corresponding to ``alien threads'', which
-are threads of control started outside the threading module, such as
-directly from C code. Dummy thread objects have limited
-functionality; they are always considered alive and daemonic, and
-cannot be \method{join()}ed. They are never deleted, since it is
-impossible to detect the termination of alien threads.
-
-
-\begin{classdesc}{Thread}{group=None, target=None, name=None,
- args=(), kwargs=\{\}}
-This constructor should always be called with keyword
-arguments. Arguments are:
-
-\var{group} should be \code{None}; reserved for future extension when
-a \class{ThreadGroup} class is implemented.
-
-\var{target} is the callable object to be invoked by the
-\method{run()} method. Defaults to \code{None}, meaning nothing is
-called.
-
-\var{name} is the thread name. By default, a unique name is
-constructed of the form ``Thread-\var{N}'' where \var{N} is a small
-decimal number.
-
-\var{args} is the argument tuple for the target invocation. Defaults
-to \code{()}.
-
-\var{kwargs} is a dictionary of keyword arguments for the target
-invocation. Defaults to \code{\{\}}.
-
-If the subclass overrides the constructor, it must make sure
-to invoke the base class constructor (\code{Thread.__init__()})
-before doing anything else to the thread.
-\end{classdesc}
-
-\begin{methoddesc}{start}{}
-Start the thread's activity.
-
-It must be called at most once per thread object. It arranges for the
-object's \method{run()} method to be invoked in a separate thread of
-control.
-
-This method will raise a \exception{RuntimeException} if called more
-than once on the same thread object.
-\end{methoddesc}
-
-\begin{methoddesc}{run}{}
-Method representing the thread's activity.
-
-You may override this method in a subclass. The standard
-\method{run()} method invokes the callable object passed to the
-object's constructor as the \var{target} argument, if any, with
-sequential and keyword arguments taken from the \var{args} and
-\var{kwargs} arguments, respectively.
-\end{methoddesc}
-
-\begin{methoddesc}{join}{\optional{timeout}}
-Wait until the thread terminates.
-This blocks the calling thread until the thread whose \method{join()}
-method is called terminates -- either normally or through an
-unhandled exception -- or until the optional timeout occurs.
-
-When the \var{timeout} argument is present and not \code{None}, it
-should be a floating point number specifying a timeout for the
-operation in seconds (or fractions thereof). As \method{join()} always
-returns \code{None}, you must call \method{isAlive()} to decide whether
-a timeout happened.
-
-When the \var{timeout} argument is not present or \code{None}, the
-operation will block until the thread terminates.
-
-A thread can be \method{join()}ed many times.
-
-\method{join()} may throw a \exception{RuntimeError}, if an attempt is
-made to join the current thread as that would cause a deadlock. It is
-also an error to \method{join()} a thread before it has been started
-and attempts to do so raises same exception.
-\end{methoddesc}
-
-\begin{methoddesc}{getName}{}
-Return the thread's name.
-\end{methoddesc}
-
-\begin{methoddesc}{setName}{name}
-Set the thread's name.
-
-The name is a string used for identification purposes only.
-It has no semantics. Multiple threads may be given the same
-name. The initial name is set by the constructor.
-\end{methoddesc}
-
-\begin{methoddesc}{isAlive}{}
-Return whether the thread is alive.
-
-Roughly, a thread is alive from the moment the \method{start()} method
-returns until its \method{run()} method terminates. The module
-function \function{enumerate()} returns a list of all alive threads.
-\end{methoddesc}
-
-\begin{methoddesc}{isDaemon}{}
-Return the thread's daemon flag.
-\end{methoddesc}
-
-\begin{methoddesc}{setDaemon}{daemonic}
-Set the thread's daemon flag to the Boolean value \var{daemonic}.
-This must be called before \method{start()} is called, otherwise
-\exception{RuntimeError} is raised.
-
-The initial value is inherited from the creating thread.
-
-The entire Python program exits when no alive non-daemon threads are
-left.
-\end{methoddesc}
-
-
-\subsection{Timer Objects \label{timer-objects}}
-
-This class represents an action that should be run only after a
-certain amount of time has passed --- a timer. \class{Timer} is a
-subclass of \class{Thread} and as such also functions as an example of
-creating custom threads.
-
-Timers are started, as with threads, by calling their \method{start()}
-method. The timer can be stopped (before its action has begun) by
-calling the \method{cancel()} method. The interval the timer will
-wait before executing its action may not be exactly the same as the
-interval specified by the user.
-
-For example:
-\begin{verbatim}
-def hello():
- print "hello, world"
-
-t = Timer(30.0, hello)
-t.start() # after 30 seconds, "hello, world" will be printed
-\end{verbatim}
-
-\begin{classdesc}{Timer}{interval, function, args=[], kwargs=\{\}}
-Create a timer that will run \var{function} with arguments \var{args} and
-keyword arguments \var{kwargs}, after \var{interval} seconds have passed.
-\end{classdesc}
-
-\begin{methoddesc}{cancel}{}
-Stop the timer, and cancel the execution of the timer's action. This
-will only work if the timer is still in its waiting stage.
-\end{methoddesc}
-
-\subsection{Using locks, conditions, and semaphores in the \keyword{with}
-statement \label{with-locks}}
-
-All of the objects provided by this module that have \method{acquire()} and
-\method{release()} methods can be used as context managers for a \keyword{with}
-statement. The \method{acquire()} method will be called when the block is
-entered, and \method{release()} will be called when the block is exited.
-
-Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore},
-and \class{BoundedSemaphore} objects may be used as \keyword{with}
-statement context managers. For example:
-
-\begin{verbatim}
-from __future__ import with_statement
-import threading
-
-some_rlock = threading.RLock()
-
-with some_rlock:
- print "some_rlock is locked while this executes"
-\end{verbatim}
-
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
deleted file mode 100644
index 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 968728f..0000000
--- a/Doc/lib/libtimeit.tex
+++ /dev/null
@@ -1,249 +0,0 @@
-\section{\module{timeit} ---
- Measure execution time of small code snippets}
-
-\declaremodule{standard}{timeit}
-\modulesynopsis{Measure the execution time of small code snippets.}
-
-\versionadded{2.3}
-\index{Benchmarking}
-\index{Performance}
-
-This module provides a simple way to time small bits of Python code.
-It has both command line as well as callable interfaces. It avoids a
-number of common traps for measuring execution times. See also Tim
-Peters' introduction to the ``Algorithms'' chapter in the
-\citetitle{Python Cookbook}, published by O'Reilly.
-
-The module defines the following public class:
-
-\begin{classdesc}{Timer}{\optional{stmt=\code{'pass'}
- \optional{, setup=\code{'pass'}
- \optional{, timer=<timer function>}}}}
-Class for timing execution speed of small code snippets.
-
-The constructor takes a statement to be timed, an additional statement
-used for setup, and a timer function. Both statements default to
-\code{'pass'}; the timer function is platform-dependent (see the
-module doc string). The statements may contain newlines, as long as
-they don't contain multi-line string literals.
-
-To measure the execution time of the first statement, use the
-\method{timeit()} method. The \method{repeat()} method is a
-convenience to call \method{timeit()} multiple times and return a list
-of results.
-
-\versionchanged[The \var{stmt} and \var{setup} parameters can now also
- take objects that are callable without arguments. This
- will embed calls to them in a timer function that will
- then be executed by \method{timeit()}. Note that the timing
- overhead is a little larger in this case because of the
- extra function calls]{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{print_exc}{\optional{file=\constant{None}}}
-Helper to print a traceback from the timed code.
-
-Typical use:
-
-\begin{verbatim}
- t = Timer(...) # outside the try/except
- try:
- t.timeit(...) # or t.repeat(...)
- except:
- t.print_exc()
-\end{verbatim}
-
-The advantage over the standard traceback is that source lines in the
-compiled template will be displayed.
-The optional \var{file} argument directs where the traceback is sent;
-it defaults to \code{sys.stderr}.
-\end{methoddesc}
-
-\begin{methoddesc}{repeat}{\optional{repeat\code{=3} \optional{,
- number\code{=1000000}}}}
-Call \method{timeit()} a few times.
-
-This is a convenience function that calls the \method{timeit()}
-repeatedly, returning a list of results. The first argument specifies
-how many times to call \method{timeit()}. The second argument
-specifies the \var{number} argument for \function{timeit()}.
-
-\begin{notice}
-It's tempting to calculate mean and standard deviation from the result
-vector and report these. However, this is not very useful. In a typical
-case, the lowest value gives a lower bound for how fast your machine can run
-the given code snippet; higher values in the result vector are typically not
-caused by variability in Python's speed, but by other processes interfering
-with your timing accuracy. So the \function{min()} of the result is
-probably the only number you should be interested in. After that, you
-should look at the entire vector and apply common sense rather than
-statistics.
-\end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}{timeit}{\optional{number\code{=1000000}}}
-Time \var{number} executions of the main statement.
-This executes the setup statement once, and then
-returns the time it takes to execute the main statement a number of
-times, measured in seconds as a float. The argument is the number of
-times through the loop, defaulting to one million. The main
-statement, the setup statement and the timer function to be used are
-passed to the constructor.
-
-\begin{notice}
-By default, \method{timeit()} temporarily turns off garbage collection
-during the timing. The advantage of this approach is that it makes
-independent timings more comparable. This disadvantage is that GC
-may be an important component of the performance of the function being
-measured. If so, GC can be re-enabled as the first statement in the
-\var{setup} string. For example:
-\begin{verbatim}
- timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
-\end{verbatim}
-\end{notice}
-\end{methoddesc}
-
-
-Starting with version 2.6, the module also defines two convenience functions:
-
-\begin{funcdesc}{repeat}{stmt\optional{, setup\optional{, timer\optional{,
- repeat\code{=3} \optional{, number\code{=1000000}}}}}}
-Create a \class{Timer} instance with the given statement, setup code and timer
-function and run its \method{repeat} method with the given repeat count and
-\var{number} executions.
-\versionadded{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{timeit}{stmt\optional{, setup\optional{, timer\optional{,
- number\code{=1000000}}}}}
-Create a \class{Timer} instance with the given statement, setup code and timer
-function and run its \method{timeit} method with \var{number} executions.
-\versionadded{2.6}
-\end{funcdesc}
-
-
-\subsection{Command Line Interface}
-
-When called as a program from the command line, the following form is used:
-
-\begin{verbatim}
-python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
-\end{verbatim}
-
-where the following options are understood:
-
-\begin{description}
-\item[-n N/\longprogramopt{number=N}] how many times to execute 'statement'
-\item[-r N/\longprogramopt{repeat=N}] how many times to repeat the timer (default 3)
-\item[-s S/\longprogramopt{setup=S}] statement to be executed once initially (default
-\code{'pass'})
-\item[-t/\longprogramopt{time}] use \function{time.time()}
-(default on all platforms but Windows)
-\item[-c/\longprogramopt{clock}] use \function{time.clock()} (default on Windows)
-\item[-v/\longprogramopt{verbose}] print raw timing results; repeat for more digits
-precision
-\item[-h/\longprogramopt{help}] print a short usage message and exit
-\end{description}
-
-A multi-line statement may be given by specifying each line as a
-separate statement argument; indented lines are possible by enclosing
-an argument in quotes and using leading spaces. Multiple
-\programopt{-s} options are treated similarly.
-
-If \programopt{-n} is not given, a suitable number of loops is
-calculated by trying successive powers of 10 until the total time is
-at least 0.2 seconds.
-
-The default timer function is platform dependent. On Windows,
-\function{time.clock()} has microsecond granularity but
-\function{time.time()}'s granularity is 1/60th of a second; on \UNIX,
-\function{time.clock()} has 1/100th of a second granularity and
-\function{time.time()} is much more precise. On either platform, the
-default timer functions measure wall clock time, not the CPU time.
-This means that other processes running on the same computer may
-interfere with the timing. The best thing to do when accurate timing
-is necessary is to repeat the timing a few times and use the best
-time. The \programopt{-r} option is good for this; the default of 3
-repetitions is probably enough in most cases. On \UNIX, you can use
-\function{time.clock()} to measure CPU time.
-
-\begin{notice}
- There is a certain baseline overhead associated with executing a
- pass statement. The code here doesn't try to hide it, but you
- should be aware of it. The baseline overhead can be measured by
- invoking the program without arguments.
-\end{notice}
-
-The baseline overhead differs between Python versions! Also, to
-fairly compare older Python versions to Python 2.3, you may want to
-use Python's \programopt{-O} option for the older versions to avoid
-timing \code{SET_LINENO} instructions.
-
-\subsection{Examples}
-
-Here are two example sessions (one using the command line, one using
-the module interface) that compare the cost of using
-\function{hasattr()} vs. \keyword{try}/\keyword{except} to test for
-missing and present object attributes.
-
-\begin{verbatim}
-% timeit.py 'try:' ' str.__bool__' 'except AttributeError:' ' pass'
-100000 loops, best of 3: 15.7 usec per loop
-% timeit.py 'if hasattr(str, "__bool__"): pass'
-100000 loops, best of 3: 4.26 usec per loop
-% timeit.py 'try:' ' int.__bool__' 'except AttributeError:' ' pass'
-1000000 loops, best of 3: 1.43 usec per loop
-% timeit.py 'if hasattr(int, "__bool__"): pass'
-100000 loops, best of 3: 2.23 usec per loop
-\end{verbatim}
-
-\begin{verbatim}
->>> import timeit
->>> s = """\
-... try:
-... str.__bool__
-... except AttributeError:
-... pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-17.09 usec/pass
->>> s = """\
-... if hasattr(str, '__bool__'): pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-4.85 usec/pass
->>> s = """\
-... try:
-... int.__bool__
-... except AttributeError:
-... pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-1.97 usec/pass
->>> s = """\
-... if hasattr(int, '__bool__'): pass
-... """
->>> t = timeit.Timer(stmt=s)
->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
-3.15 usec/pass
-\end{verbatim}
-
-To give the \module{timeit} module access to functions you
-define, you can pass a \code{setup} parameter which contains an import
-statement:
-
-\begin{verbatim}
-def test():
- "Stupid test function"
- L = []
- for i in range(100):
- L.append(i)
-
-if __name__=='__main__':
- from timeit import Timer
- t = Timer("test()", "from __main__ import test")
- print t.timeit()
-\end{verbatim}
diff --git a/Doc/lib/libtoken.tex b/Doc/lib/libtoken.tex
deleted file mode 100644
index 47f4750..0000000
--- a/Doc/lib/libtoken.tex
+++ /dev/null
@@ -1,44 +0,0 @@
-\section{\module{token} ---
- Constants used with Python parse trees}
-
-\declaremodule{standard}{token}
-\modulesynopsis{Constants representing terminal nodes of the parse tree.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-This module provides constants which represent the numeric values of
-leaf nodes of the parse tree (terminal tokens). Refer to the file
-\file{Grammar/Grammar} in the Python distribution for the definitions
-of the names in the context of the language grammar. The specific
-numeric values which the names map to may change between Python
-versions.
-
-This module also provides one data object and some functions. The
-functions mirror definitions in the Python C header files.
-
-
-
-\begin{datadesc}{tok_name}
-Dictionary mapping the numeric values of the constants defined in this
-module back to name strings, allowing more human-readable
-representation of parse trees to be generated.
-\end{datadesc}
-
-\begin{funcdesc}{ISTERMINAL}{x}
-Return true for terminal token values.
-\end{funcdesc}
-
-\begin{funcdesc}{ISNONTERMINAL}{x}
-Return true for non-terminal token values.
-\end{funcdesc}
-
-\begin{funcdesc}{ISEOF}{x}
-Return true if \var{x} is the marker indicating the end of input.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{parser}{The second example for the \refmodule{parser}
- module shows how to use the \module{symbol}
- module.}
-\end{seealso}
diff --git a/Doc/lib/libtokenize.tex b/Doc/lib/libtokenize.tex
deleted file mode 100644
index 8c9ad3e..0000000
--- a/Doc/lib/libtokenize.tex
+++ /dev/null
@@ -1,119 +0,0 @@
-\section{\module{tokenize} ---
- Tokenizer for Python source}
-
-\declaremodule{standard}{tokenize}
-\modulesynopsis{Lexical scanner for Python source code.}
-\moduleauthor{Ka Ping Yee}{}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-
-The \module{tokenize} module provides a lexical scanner for Python
-source code, implemented in Python. The scanner in this module
-returns comments as tokens as well, making it useful for implementing
-``pretty-printers,'' including colorizers for on-screen displays.
-
-The primary entry point is a generator:
-
-\begin{funcdesc}{generate_tokens}{readline}
- The \function{generate_tokens()} generator requires one argment,
- \var{readline}, which must be a callable object which
- provides the same interface as the \method{readline()} method of
- built-in file objects (see section~\ref{bltin-file-objects}). Each
- call to the function should return one line of input as a string.
-
- The generator produces 5-tuples with these members:
- the token type;
- the token string;
- a 2-tuple \code{(\var{srow}, \var{scol})} of ints specifying the
- row and column where the token begins in the source;
- a 2-tuple \code{(\var{erow}, \var{ecol})} of ints specifying the
- row and column where the token ends in the source;
- and the line on which the token was found.
- The line passed is the \emph{logical} line;
- continuation lines are included.
- \versionadded{2.2}
-\end{funcdesc}
-
-An older entry point is retained for backward compatibility:
-
-\begin{funcdesc}{tokenize}{readline\optional{, tokeneater}}
- The \function{tokenize()} function accepts two parameters: one
- representing the input stream, and one providing an output mechanism
- for \function{tokenize()}.
-
- The first parameter, \var{readline}, must be a callable object which
- provides the same interface as the \method{readline()} method of
- built-in file objects (see section~\ref{bltin-file-objects}). Each
- call to the function should return one line of input as a string.
- Alternately, \var{readline} may be a callable object that signals
- completion by raising \exception{StopIteration}.
- \versionchanged[Added \exception{StopIteration} support]{2.5}
-
- The second parameter, \var{tokeneater}, must also be a callable
- object. It is called once for each token, with five arguments,
- corresponding to the tuples generated by \function{generate_tokens()}.
-\end{funcdesc}
-
-
-All constants from the \refmodule{token} module are also exported from
-\module{tokenize}, as are two additional token type values that might be
-passed to the \var{tokeneater} function by \function{tokenize()}:
-
-\begin{datadesc}{COMMENT}
- Token value used to indicate a comment.
-\end{datadesc}
-\begin{datadesc}{NL}
- Token value used to indicate a non-terminating newline. The NEWLINE
- token indicates the end of a logical line of Python code; NL tokens
- are generated when a logical line of code is continued over multiple
- physical lines.
-\end{datadesc}
-
-Another function is provided to reverse the tokenization process.
-This is useful for creating tools that tokenize a script, modify
-the token stream, and write back the modified script.
-
-\begin{funcdesc}{untokenize}{iterable}
- Converts tokens back into Python source code. The \var{iterable}
- must return sequences with at least two elements, the token type and
- the token string. Any additional sequence elements are ignored.
-
- The reconstructed script is returned as a single string. The
- result is guaranteed to tokenize back to match the input so that
- the conversion is lossless and round-trips are assured. The
- guarantee applies only to the token type and token string as
- the spacing between tokens (column positions) may change.
- \versionadded{2.5}
-\end{funcdesc}
-
-Example of a script re-writer that transforms float literals into
-Decimal objects:
-\begin{verbatim}
-def decistmt(s):
- """Substitute Decimals for floats in a string of statements.
-
- >>> from decimal import Decimal
- >>> s = 'print +21.3e-5*-.1234/81.7'
- >>> decistmt(s)
- "print +Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7')"
-
- >>> exec(s)
- -3.21716034272e-007
- >>> exec(decistmt(s))
- -3.217160342717258261933904529E-7
-
- """
- result = []
- g = generate_tokens(StringIO(s).readline) # tokenize the string
- for toknum, tokval, _, _, _ in g:
- if toknum == NUMBER and '.' in tokval: # replace NUMBER tokens
- result.extend([
- (NAME, 'Decimal'),
- (OP, '('),
- (STRING, repr(tokval)),
- (OP, ')')
- ])
- else:
- result.append((toknum, tokval))
- return untokenize(result)
-\end{verbatim}
diff --git a/Doc/lib/libtrace.tex b/Doc/lib/libtrace.tex
deleted file mode 100644
index 2465aac..0000000
--- a/Doc/lib/libtrace.tex
+++ /dev/null
@@ -1,125 +0,0 @@
-\section{\module{trace} ---
- Trace or track Python statement execution}
-
-\declaremodule{standard}{trace}
-\modulesynopsis{Trace or track Python statement execution.}
-
-The \module{trace} module allows you to trace program execution, generate
-annotated statement coverage listings, print caller/callee relationships and
-list functions executed during a program run. It can be used in another
-program or from the command line.
-
-\subsection{Command Line Usage\label{trace-cli}}
-
-The \module{trace} module can be invoked from the command line. It can be
-as simple as
-
-\begin{verbatim}
-python -m trace --count somefile.py ...
-\end{verbatim}
-
-The above will generate annotated listings of all Python modules imported
-during the execution of \file{somefile.py}.
-
-The following command-line arguments are supported:
-
-\begin{description}
-\item[\longprogramopt{trace}, \programopt{-t}]
-Display lines as they are executed.
-
-\item[\longprogramopt{count}, \programopt{-c}]
-Produce a set of annotated listing files upon program
-completion that shows how many times each statement was executed.
-
-\item[\longprogramopt{report}, \programopt{-r}]
-Produce an annotated list from an earlier program run that
-used the \longprogramopt{count} and \longprogramopt{file} arguments.
-
-\item[\longprogramopt{no-report}, \programopt{-R}]
-Do not generate annotated listings. This is useful if you intend to make
-several runs with \longprogramopt{count} then produce a single set
-of annotated listings at the end.
-
-\item[\longprogramopt{listfuncs}, \programopt{-l}]
-List the functions executed by running the program.
-
-\item[\longprogramopt{trackcalls}, \programopt{-T}]
-Generate calling relationships exposed by running the program.
-
-\item[\longprogramopt{file}, \programopt{-f}]
-Name a file containing (or to contain) counts.
-
-\item[\longprogramopt{coverdir}, \programopt{-C}]
-Name a directory in which to save annotated listing files.
-
-\item[\longprogramopt{missing}, \programopt{-m}]
-When generating annotated listings, mark lines which
-were not executed with `\code{>>>>>>}'.
-
-\item[\longprogramopt{summary}, \programopt{-s}]
-When using \longprogramopt{count} or \longprogramopt{report}, write a
-brief summary to stdout for each file processed.
-
-\item[\longprogramopt{ignore-module}]
-Ignore the named module and its submodules (if it is
-a package). May be given multiple times.
-
-\item[\longprogramopt{ignore-dir}]
-Ignore all modules and packages in the named directory
-and subdirectories. May be given multiple times.
-\end{description}
-
-\subsection{Programming Interface\label{trace-api}}
-
-\begin{classdesc}{Trace}{\optional{count=1\optional{, trace=1\optional{,
- countfuncs=0\optional{, countcallers=0\optional{,
- ignoremods=()\optional{, ignoredirs=()\optional{,
- infile=None\optional{, outfile=None}}}}}}}}}
-Create an object to trace execution of a single statement or expression.
-All parameters are optional. \var{count} enables counting of line numbers.
-\var{trace} enables line execution tracing. \var{countfuncs} enables
-listing of the functions called during the run. \var{countcallers} enables
-call relationship tracking. \var{ignoremods} is a list of modules or
-packages to ignore. \var{ignoredirs} is a list of directories whose modules
-or packages should be ignored. \var{infile} is the file from which to read
-stored count information. \var{outfile} is a file in which to write updated
-count information.
-\end{classdesc}
-
-\begin{methoddesc}[Trace]{run}{cmd}
-Run \var{cmd} under control of the Trace object with the current tracing
-parameters.
-\end{methoddesc}
-
-\begin{methoddesc}[Trace]{runctx}{cmd\optional{, globals=None\optional{,
- locals=None}}}
-Run \var{cmd} under control of the Trace object with the current tracing
-parameters in the defined global and local environments. If not defined,
-\var{globals} and \var{locals} default to empty dictionaries.
-\end{methoddesc}
-
-\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds}
-Call \var{func} with the given arguments under control of the
-\class{Trace} object with the current tracing parameters.
-\end{methoddesc}
-
-This is a simple example showing the use of this module:
-
-\begin{verbatim}
-import sys
-import trace
-
-# create a Trace object, telling it what to ignore, and whether to
-# do tracing or line-counting or both.
-tracer = trace.Trace(
- ignoredirs=[sys.prefix, sys.exec_prefix],
- trace=0,
- count=1)
-
-# run the new command using the given tracer
-tracer.run('main()')
-
-# make a report, placing output in /tmp
-r = tracer.results()
-r.write_results(show_missing=True, coverdir="/tmp")
-\end{verbatim}
diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex
deleted file mode 100644
index a87b1ef..0000000
--- a/Doc/lib/libtraceback.tex
+++ /dev/null
@@ -1,152 +0,0 @@
-\section{\module{traceback} ---
- Print or retrieve a stack traceback}
-
-\declaremodule{standard}{traceback}
-\modulesynopsis{Print or retrieve a stack traceback.}
-
-
-This module provides a standard interface to extract, format and print
-stack traces of Python programs. It exactly mimics the behavior of
-the Python interpreter when it prints a stack trace. This is useful
-when you want to print stack traces under program control, such as in a
-``wrapper'' around the interpreter.
-
-The module uses traceback objects --- this is the object type that is
-stored in the \code{sys.last_traceback} variable and returned
-as the third item from \function{sys.exc_info()}.
-\obindex{traceback}
-
-The module defines the following functions:
-
-\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}}
-Print up to \var{limit} stack trace entries from \var{traceback}. If
-\var{limit} is omitted or \code{None}, all entries are printed.
-If \var{file} is omitted or \code{None}, the output goes to
-\code{sys.stderr}; otherwise it should be an open file or file-like
-object to receive the output.
-\end{funcdesc}
-
-\begin{funcdesc}{print_exception}{type, value, traceback\optional{,
- limit\optional{, file}}}
-Print exception information and up to \var{limit} stack trace entries
-from \var{traceback} to \var{file}.
-This differs from \function{print_tb()} in the
-following ways: (1) if \var{traceback} is not \code{None}, it prints a
-header \samp{Traceback (most recent call last):}; (2) it prints the
-exception \var{type} and \var{value} after the stack trace; (3) if
-\var{type} is \exception{SyntaxError} and \var{value} has the
-appropriate format, it prints the line where the syntax error occurred
-with a caret indicating the approximate position of the error.
-\end{funcdesc}
-
-\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}}
-This is a shorthand for \code{print_exception(*\function{sys.exc_info()}}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_exc}{\optional{limit}}
-This is like \code{print_exc(\var{limit})} but returns a string
-instead of printing to a file.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
-This is a shorthand for \code{print_exception(sys.last_type,
-sys.last_value, sys.last_traceback, \var{limit}, \var{file})}.
-\end{funcdesc}
-
-\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
-This function prints a stack trace from its invocation point. The
-optional \var{f} argument can be used to specify an alternate stack
-frame to start. The optional \var{limit} and \var{file} arguments have the
-same meaning as for \function{print_exception()}.
-\end{funcdesc}
-
-\begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
-Return a list of up to \var{limit} ``pre-processed'' stack trace
-entries extracted from the traceback object \var{traceback}. It is
-useful for alternate formatting of stack traces. If \var{limit} is
-omitted or \code{None}, all entries are extracted. A
-``pre-processed'' stack trace entry is a quadruple (\var{filename},
-\var{line number}, \var{function name}, \var{text}) representing
-the information that is usually printed for a stack trace. The
-\var{text} is a string with leading and trailing whitespace
-stripped; if the source is not available it is \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
-Extract the raw traceback from the current stack frame. The return
-value has the same format as for \function{extract_tb()}. The
-optional \var{f} and \var{limit} arguments have the same meaning as
-for \function{print_stack()}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_list}{list}
-Given a list of tuples as returned by \function{extract_tb()} or
-\function{extract_stack()}, return a list of strings ready for
-printing. Each string in the resulting list corresponds to the item
-with the same index in the argument list. Each string ends in a
-newline; the strings may contain internal newlines as well, for those
-items whose source text line is not \code{None}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_exception_only}{type, value}
-Format the exception part of a traceback. The arguments are the
-exception type and value such as given by \code{sys.last_type} and
-\code{sys.last_value}. The return value is a list of strings, each
-ending in a newline. Normally, the list contains a single string;
-however, for \exception{SyntaxError} exceptions, it contains several
-lines that (when printed) display detailed information about where the
-syntax error occurred. The message indicating which exception
-occurred is the always last string in the list.
-\end{funcdesc}
-
-\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
-Format a stack trace and the exception information. The arguments
-have the same meaning as the corresponding arguments to
-\function{print_exception()}. The return value is a list of strings,
-each ending in a newline and some containing internal newlines. When
-these lines are concatenated and printed, exactly the same text is
-printed as does \function{print_exception()}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_tb}{tb\optional{, limit}}
-A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
-\end{funcdesc}
-
-\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
-A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
-\end{funcdesc}
-
-\begin{funcdesc}{tb_lineno}{tb}
-This function returns the current line number set in the traceback
-object. This function was necessary because in versions of Python
-prior to 2.3 when the \programopt{-O} flag was passed to Python the
-\code{\var{tb}.tb_lineno} was not updated correctly. This function
-has no use in versions past 2.3.
-\end{funcdesc}
-
-
-\subsection{Traceback Example \label{traceback-example}}
-
-This simple example implements a basic read-eval-print loop, similar
-to (but less useful than) the standard Python interactive interpreter
-loop. For a more complete implementation of the interpreter loop,
-refer to the \refmodule{code} module.
-
-\begin{verbatim}
-import sys, traceback
-
-def run_user_code(envdir):
- source = raw_input(">>> ")
- try:
- exec(source, envdir)
- except:
- print "Exception in user code:"
- print '-'*60
- traceback.print_exc(file=sys.stdout)
- print '-'*60
-
-envdir = {}
-while 1:
- run_user_code(envdir)
-\end{verbatim}
diff --git a/Doc/lib/libtty.tex b/Doc/lib/libtty.tex
deleted file mode 100644
index d42771a..0000000
--- a/Doc/lib/libtty.tex
+++ /dev/null
@@ -1,34 +0,0 @@
-\section{\module{tty} ---
- Terminal control functions}
-
-\declaremodule{standard}{tty}
- \platform{Unix}
-\moduleauthor{Steen Lumholt}{}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Utility functions that perform common terminal control
- operations.}
-
-The \module{tty} module defines functions for putting the tty into
-cbreak and raw modes.
-
-Because it requires the \refmodule{termios} module, it will work
-only on \UNIX.
-
-The \module{tty} module defines the following functions:
-
-\begin{funcdesc}{setraw}{fd\optional{, when}}
-Change the mode of the file descriptor \var{fd} to raw. If \var{when}
-is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed
-to \function{termios.tcsetattr()}.
-\end{funcdesc}
-
-\begin{funcdesc}{setcbreak}{fd\optional{, when}}
-Change the mode of file descriptor \var{fd} to cbreak. If \var{when}
-is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed
-to \function{termios.tcsetattr()}.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seemodule{termios}{Low-level terminal control interface.}
-\end{seealso}
diff --git a/Doc/lib/libturtle.tex b/Doc/lib/libturtle.tex
deleted file mode 100644
index fa8f0dd..0000000
--- a/Doc/lib/libturtle.tex
+++ /dev/null
@@ -1,268 +0,0 @@
-\section{\module{turtle} ---
- Turtle graphics for Tk}
-
-\declaremodule{standard}{turtle}
- \platform{Tk}
-\moduleauthor{Guido van Rossum}{guido@python.org}
-\modulesynopsis{An environment for turtle graphics.}
-
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-
-
-The \module{turtle} module provides turtle graphics primitives, in both an
-object-oriented and procedure-oriented ways. Because it uses \module{Tkinter}
-for the underlying graphics, it needs a version of python installed with
-Tk support.
-
-The procedural interface uses a pen and a canvas which are automagically
-created when any of the functions are called.
-
-The \module{turtle} module defines the following functions:
-
-\begin{funcdesc}{degrees}{}
-Set angle measurement units to degrees.
-\end{funcdesc}
-
-\begin{funcdesc}{radians}{}
-Set angle measurement units to radians.
-\end{funcdesc}
-
-\begin{funcdesc}{setup}{**kwargs}
-Sets the size and position of the main window. Keywords are:
-\begin{itemize}
- \item \code{width}: either a size in pixels or a fraction of the screen.
- The default is 50\% of the screen.
- \item \code{height}: either a size in pixels or a fraction of the screen.
- The default is 50\% of the screen.
- \item \code{startx}: starting position in pixels from the left edge
- of the screen. \code{None} is the default value and
- centers the window horizontally on screen.
- \item \code{starty}: starting position in pixels from the top edge
- of the screen. \code{None} is the default value and
- centers the window vertically on screen.
-\end{itemize}
-
- Examples:
-
-\begin{verbatim}
-# Uses default geometry: 50% x 50% of screen, centered.
-setup()
-
-# Sets window to 200x200 pixels, in upper left of screen
-setup (width=200, height=200, startx=0, starty=0)
-
-# Sets window to 75% of screen by 50% of screen, and centers it.
-setup(width=.75, height=0.5, startx=None, starty=None)
-\end{verbatim}
-
-\end{funcdesc}
-
-\begin{funcdesc}{title}{title_str}
-Set the window's title to \var{title}.
-\end{funcdesc}
-
-\begin{funcdesc}{done}{}
-Enters the Tk main loop. The window will continue to
-be displayed until the user closes it or the process is killed.
-\end{funcdesc}
-
-\begin{funcdesc}{reset}{}
-Clear the screen, re-center the pen, and set variables to the default
-values.
-\end{funcdesc}
-
-\begin{funcdesc}{clear}{}
-Clear the screen.
-\end{funcdesc}
-
-\begin{funcdesc}{tracer}{flag}
-Set tracing on/off (according to whether flag is true or not). Tracing
-means line are drawn more slowly, with an animation of an arrow along the
-line.
-\end{funcdesc}
-
-\begin{funcdesc}{speed}{speed}
-Set the speed of the turtle. Valid values for the parameter
-\var{speed} are \code{'fastest'} (no delay), \code{'fast'},
-(delay 5ms), \code{'normal'} (delay 10ms), \code{'slow'}
-(delay 15ms), and \code{'slowest'} (delay 20ms).
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{delay}{delay}
-Set the speed of the turtle to \var{delay}, which is given
-in ms. \versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{forward}{distance}
-Go forward \var{distance} steps.
-\end{funcdesc}
-
-\begin{funcdesc}{backward}{distance}
-Go backward \var{distance} steps.
-\end{funcdesc}
-
-\begin{funcdesc}{left}{angle}
-Turn left \var{angle} units. Units are by default degrees, but can be
-set via the \function{degrees()} and \function{radians()} functions.
-\end{funcdesc}
-
-\begin{funcdesc}{right}{angle}
-Turn right \var{angle} units. Units are by default degrees, but can be
-set via the \function{degrees()} and \function{radians()} functions.
-\end{funcdesc}
-
-\begin{funcdesc}{up}{}
-Move the pen up --- stop drawing.
-\end{funcdesc}
-
-\begin{funcdesc}{down}{}
-Move the pen down --- draw when moving.
-\end{funcdesc}
-
-\begin{funcdesc}{width}{width}
-Set the line width to \var{width}.
-\end{funcdesc}
-
-\begin{funcdesc}{color}{s}
-\funclineni{color}{(r, g, b)}
-\funclineni{color}{r, g, b}
-Set the pen color. In the first form, the color is specified as a
-Tk color specification as a string. The second form specifies the
-color as a tuple of the RGB values, each in the range [0..1]. For the
-third form, the color is specified giving the RGB values as three
-separate parameters (each in the range [0..1]).
-\end{funcdesc}
-
-\begin{funcdesc}{write}{text\optional{, move}}
-Write \var{text} at the current pen position. If \var{move} is true,
-the pen is moved to the bottom-right corner of the text. By default,
-\var{move} is false.
-\end{funcdesc}
-
-\begin{funcdesc}{fill}{flag}
-The complete specifications are rather complex, but the recommended
-usage is: call \code{fill(1)} before drawing a path you want to fill,
-and call \code{fill(0)} when you finish to draw the path.
-\end{funcdesc}
-
-\begin{funcdesc}{begin\_fill}{}
-Switch turtle into filling mode;
-Must eventually be followed by a corresponding end_fill() call.
-Otherwise it will be ignored.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{end\_fill}{}
-End filling mode, and fill the shape; equivalent to \code{fill(0)}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{circle}{radius\optional{, extent}}
-Draw a circle with radius \var{radius} whose center-point is
-\var{radius} units left of the turtle.
-\var{extent} determines which part of a circle is drawn: if
-not given it defaults to a full circle.
-
-If \var{extent} is not a full circle, one endpoint of the arc is the
-current pen position. The arc is drawn in a counter clockwise
-direction if \var{radius} is positive, otherwise in a clockwise
-direction. In the process, the direction of the turtle is changed
-by the amount of the \var{extent}.
-\end{funcdesc}
-
-\begin{funcdesc}{goto}{x, y}
-\funclineni{goto}{(x, y)}
-Go to co-ordinates \var{x}, \var{y}. The co-ordinates may be
-specified either as two separate arguments or as a 2-tuple.
-\end{funcdesc}
-
-\begin{funcdesc}{towards}{x, y}
-Return the angle of the line from the turtle's position
-to the point \var{x}, \var{y}. The co-ordinates may be
-specified either as two separate arguments, as a 2-tuple,
-or as another pen object.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{heading}{}
-Return the current orientation of the turtle.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setheading}{angle}
-Set the orientation of the turtle to \var{angle}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{position}{}
-Return the current location of the turtle as an \code{(x,y)} pair.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{setx}{x}
-Set the x coordinate of the turtle to \var{x}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{sety}{y}
-Set the y coordinate of the turtle to \var{y}.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{window\_width}{}
-Return the width of the canvas window.
-\versionadded{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{window\_height}{}
-Return the height of the canvas window.
-\versionadded{2.3}
-\end{funcdesc}
-
-This module also does \code{from math import *}, so see the
-documentation for the \refmodule{math} module for additional constants
-and functions useful for turtle graphics.
-
-\begin{funcdesc}{demo}{}
-Exercise the module a bit.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-Exception raised on any error caught by this module.
-\end{excdesc}
-
-For examples, see the code of the \function{demo()} function.
-
-This module defines the following classes:
-
-\begin{classdesc}{Pen}{}
-Define a pen. All above functions can be called as a methods on the given
-pen. The constructor automatically creates a canvas do be drawn on.
-\end{classdesc}
-
-\begin{classdesc}{Turtle}{}
-Define a pen. This is essentially a synonym for \code{Pen()};
-\class{Turtle} is an empty subclass of \class{Pen}.
-\end{classdesc}
-
-\begin{classdesc}{RawPen}{canvas}
-Define a pen which draws on a canvas \var{canvas}. This is useful if
-you want to use the module to create graphics in a ``real'' program.
-\end{classdesc}
-
-\subsection{Turtle, Pen and RawPen Objects \label{pen-rawpen-objects}}
-
-Most of the global functions available in the module are also
-available as methods of the \class{Turtle}, \class{Pen} and
-\class{RawPen} classes, affecting only the state of the given pen.
-
-The only method which is more powerful as a method is
-\function{degrees()}, which takes an optional argument letting
-you specify the number of units corresponding to a full circle:
-
-\begin{methoddesc}[Turtle]{degrees}{\optional{fullcircle}}
-\var{fullcircle} is by default 360. This can cause the pen to have any
-angular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or
-400 for gradians.
-\end{methoddesc}
diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex
deleted file mode 100644
index 2b143b9..0000000
--- a/Doc/lib/libtypes.tex
+++ /dev/null
@@ -1,211 +0,0 @@
-\section{\module{types} ---
- Names for built-in types}
-
-\declaremodule{standard}{types}
-\modulesynopsis{Names for built-in types.}
-
-
-This module defines names for some object types that are used by
-the standard Python interpreter, but not for the types defined by various
-extension modules. Also, it does not include some of the types that
-arise during processing such as the \code{listiterator} type.
-It is safe to use \samp{from types import *} ---
-the module does not export any names besides the ones listed here.
-New names exported by future versions of this module will all end in
-\samp{Type}.
-
-Typical use is for functions that do different things depending on
-their argument types, like the following:
-
-\begin{verbatim}
-from types import *
-def delete(mylist, item):
- if type(item) is IntType:
- del mylist[item]
- else:
- mylist.remove(item)
-\end{verbatim}
-
-Starting in Python 2.2, built-in factory functions such as
-\function{int()} and \function{str()} are also names for the
-corresponding types. This is now the preferred way to access
-the type instead of using the \module{types} module. Accordingly,
-the example above should be written as follows:
-
-\begin{verbatim}
-def delete(mylist, item):
- if isinstance(item, int):
- del mylist[item]
- else:
- mylist.remove(item)
-\end{verbatim}
-
-The module defines the following names:
-
-\begin{datadesc}{NoneType}
-The type of \code{None}.
-\end{datadesc}
-
-\begin{datadesc}{TypeType}
-The type of type objects (such as returned by
-\function{type()}\bifuncindex{type}).
-\end{datadesc}
-
-\begin{datadesc}{BooleanType}
-The type of the \class{bool} values \code{True} and \code{False}; this
-is an alias of the built-in \function{bool()} function.
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{IntType}
-The type of integers (e.g. \code{1}).
-\end{datadesc}
-
-\begin{datadesc}{LongType}
-The type of long integers (e.g. \code{1L}).
-\end{datadesc}
-
-\begin{datadesc}{FloatType}
-The type of floating point numbers (e.g. \code{1.0}).
-\end{datadesc}
-
-\begin{datadesc}{ComplexType}
-The type of complex numbers (e.g. \code{1.0j}). This is not defined
-if Python was built without complex number support.
-\end{datadesc}
-
-\begin{datadesc}{StringType}
-The type of character strings (e.g. \code{'Spam'}).
-\end{datadesc}
-
-\begin{datadesc}{UnicodeType}
-The type of Unicode character strings (e.g. \code{u'Spam'}). This is
-not defined if Python was built without Unicode support.
-\end{datadesc}
-
-\begin{datadesc}{TupleType}
-The type of tuples (e.g. \code{(1, 2, 3, 'Spam')}).
-\end{datadesc}
-
-\begin{datadesc}{ListType}
-The type of lists (e.g. \code{[0, 1, 2, 3]}).
-\end{datadesc}
-
-\begin{datadesc}{DictType}
-The type of dictionaries (e.g. \code{\{'Bacon': 1, 'Ham': 0\}}).
-\end{datadesc}
-
-\begin{datadesc}{DictionaryType}
-An alternate name for \code{DictType}.
-\end{datadesc}
-
-\begin{datadesc}{FunctionType}
-The type of user-defined functions and lambdas.
-\end{datadesc}
-
-\begin{datadesc}{LambdaType}
-An alternate name for \code{FunctionType}.
-\end{datadesc}
-
-\begin{datadesc}{GeneratorType}
-The type of generator-iterator objects, produced by calling a
-generator function.
-\versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{CodeType}
-The type for code objects such as returned by
-\function{compile()}\bifuncindex{compile}.
-\end{datadesc}
-
-\begin{datadesc}{ClassType}
-The type of user-defined classes.
-\end{datadesc}
-
-\begin{datadesc}{MethodType}
-The type of methods of user-defined class instances.
-\end{datadesc}
-
-\begin{datadesc}{UnboundMethodType}
-An alternate name for \code{MethodType}.
-\end{datadesc}
-
-\begin{datadesc}{BuiltinFunctionType}
-The type of built-in functions like \function{len()} or
-\function{sys.exit()}.
-\end{datadesc}
-
-\begin{datadesc}{BuiltinMethodType}
-An alternate name for \code{BuiltinFunction}.
-\end{datadesc}
-
-\begin{datadesc}{ModuleType}
-The type of modules.
-\end{datadesc}
-
-\begin{datadesc}{FileType}
-The type of open file objects such as \code{sys.stdout}.
-\end{datadesc}
-
-\begin{datadesc}{RangeType}
-The type of range objects returned by
-\function{range()}\bifuncindex{range}.
-\end{datadesc}
-
-\begin{datadesc}{SliceType}
-The type of objects returned by
-\function{slice()}\bifuncindex{slice}.
-\end{datadesc}
-
-\begin{datadesc}{EllipsisType}
-The type of \code{Ellipsis}.
-\end{datadesc}
-
-\begin{datadesc}{TracebackType}
-The type of traceback objects such as found in
-\code{sys.exc_info()[2]}.
-\end{datadesc}
-
-\begin{datadesc}{FrameType}
-The type of frame objects such as found in \code{tb.tb_frame} if
-\code{tb} is a traceback object.
-\end{datadesc}
-
-\begin{datadesc}{BufferType}
-The type of buffer objects created by the
-\function{buffer()}\bifuncindex{buffer} function.
-\end{datadesc}
-
-\begin{datadesc}{DictProxyType}
-The type of dict proxies, such as \code{TypeType.__dict__}.
-\end{datadesc}
-
-\begin{datadesc}{NotImplementedType}
-The type of \code{NotImplemented}
-\end{datadesc}
-
-\begin{datadesc}{GetSetDescriptorType}
-The type of objects defined in extension modules with \code{PyGetSetDef}, such
-as \code{FrameType.f_locals} or \code{array.array.typecode}. This constant is
-not defined in implementations of Python that do not have such extension
-types, so for portable code use \code{hasattr(types, 'GetSetDescriptorType')}.
-\versionadded{2.5}
-\end{datadesc}
-
-\begin{datadesc}{MemberDescriptorType}
-The type of objects defined in extension modules with \code{PyMemberDef}, such
-as \code {datetime.timedelta.days}. This constant is not defined in
-implementations of Python that do not have such extension types, so for
-portable code use \code{hasattr(types, 'MemberDescriptorType')}.
-\versionadded{2.5}
-\end{datadesc}
-
-\begin{datadesc}{StringTypes}
-A sequence containing \code{StringType} and \code{UnicodeType} used to
-facilitate easier checking for any string object. Using this is more
-portable than using a sequence of the two string types constructed
-elsewhere since it only contains \code{UnicodeType} if it has been
-built in the running version of Python. For example:
-\code{isinstance(s, types.StringTypes)}.
-\versionadded{2.2}
-\end{datadesc}
diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex
deleted file mode 100644
index 6f51eee..0000000
--- a/Doc/lib/libundoc.tex
+++ /dev/null
@@ -1,82 +0,0 @@
-\chapter{Undocumented Modules \label{undoc}}
-
-Here's a quick listing of modules that are currently undocumented, but
-that should be documented. Feel free to contribute documentation for
-them! (Send via email to \email{docs@python.org}.)
-
-The idea and original contents for this chapter were taken
-from a posting by Fredrik Lundh; the specific contents of this chapter
-have been substantially revised.
-
-
-\section{Frameworks}
-
-Frameworks tend to be harder to document, but are well worth the
-effort spent.
-
-\begin{description}
-\item None at this time.
-\end{description}
-
-
-\section{Miscellaneous useful utilities}
-
-Some of these are very old and/or not very robust; marked with ``hmm.''
-
-\begin{description}
-\item[\module{bdb}]
---- A generic Python debugger base class (used by pdb).
-
-\item[\module{ihooks}]
---- Import hook support (for \refmodule{rexec}; may become obsolete).
-\end{description}
-
-
-
-\section{Platform specific modules}
-
-These modules are used to implement the \refmodule{os.path} module,
-and are not documented beyond this mention. There's little need to
-document these.
-
-\begin{description}
-\item[\module{ntpath}]
---- Implementation of \module{os.path} on Win32, Win64, WinCE, and
- OS/2 platforms.
-
-\item[\module{posixpath}]
---- Implementation of \module{os.path} on \POSIX.
-\end{description}
-
-
-\section{Multimedia}
-
-\begin{description}
-\item[\module{sunaudio}]
---- Interpret Sun audio headers (may become obsolete or a tool/demo).
-\end{description}
-
-
-\section{Obsolete \label{obsolete-modules}}
-
-These modules are not normally available for import; additional work
-must be done to make them available.
-
-%%% lib-old is empty as of Python 2.5
-% Those which are written in Python will be installed into the directory
-% \file{lib-old/} installed as part of the standard library. To use
-% these, the directory must be added to \code{sys.path}, possibly using
-% \envvar{PYTHONPATH}.
-
-These extension modules written in C are not built by default.
-Under \UNIX, these must be enabled by uncommenting the appropriate
-lines in \file{Modules/Setup} in the build tree and either rebuilding
-Python if the modules are statically linked, or building and
-installing the shared object if using dynamically-loaded extensions.
-
-% XXX need Windows instructions!
-
-\begin{description}
-\item
---- This section should be empty for Python 3.0.
-\end{description}
diff --git a/Doc/lib/libunicodedata.tex b/Doc/lib/libunicodedata.tex
deleted file mode 100644
index 435466a..0000000
--- a/Doc/lib/libunicodedata.tex
+++ /dev/null
@@ -1,160 +0,0 @@
-\section{\module{unicodedata} ---
- Unicode Database}
-
-\declaremodule{standard}{unicodedata}
-\modulesynopsis{Access the Unicode Database.}
-\moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\index{Unicode}
-\index{character}
-\indexii{Unicode}{database}
-
-This module provides access to the Unicode Character Database which
-defines character properties for all Unicode characters. The data in
-this database is based on the \file{UnicodeData.txt} file version
-4.1.0 which is publicly available from \url{ftp://ftp.unicode.org/}.
-
-The module uses the same names and symbols as defined by the
-UnicodeData File Format 4.1.0 (see
-\url{http://www.unicode.org/Public/4.1.0/ucd/UCD.html}). It
-defines the following functions:
-
-\begin{funcdesc}{lookup}{name}
- Look up character by name. If a character with the
- given name is found, return the corresponding Unicode
- character. If not found, \exception{KeyError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{name}{unichr\optional{, default}}
- Returns the name assigned to the Unicode character
- \var{unichr} as a string. If no name is defined,
- \var{default} is returned, or, if not given,
- \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{decimal}{unichr\optional{, default}}
- Returns the decimal value assigned to the Unicode character
- \var{unichr} as integer. If no such value is defined,
- \var{default} is returned, or, if not given,
- \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{digit}{unichr\optional{, default}}
- Returns the digit value assigned to the Unicode character
- \var{unichr} as integer. If no such value is defined,
- \var{default} is returned, or, if not given,
- \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{numeric}{unichr\optional{, default}}
- Returns the numeric value assigned to the Unicode character
- \var{unichr} as float. If no such value is defined, \var{default} is
- returned, or, if not given, \exception{ValueError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{category}{unichr}
- Returns the general category assigned to the Unicode character
- \var{unichr} as string.
-\end{funcdesc}
-
-\begin{funcdesc}{bidirectional}{unichr}
- Returns the bidirectional category assigned to the Unicode character
- \var{unichr} as string. If no such value is defined, an empty string
- is returned.
-\end{funcdesc}
-
-\begin{funcdesc}{combining}{unichr}
- Returns the canonical combining class assigned to the Unicode
- character \var{unichr} as integer. Returns \code{0} if no combining
- class is defined.
-\end{funcdesc}
-
-\begin{funcdesc}{east_asian_width}{unichr}
- Returns the east asian width assigned to the Unicode character
- \var{unichr} as string.
-\versionadded{2.4}
-\end{funcdesc}
-
-\begin{funcdesc}{mirrored}{unichr}
- Returns the mirrored property assigned to the Unicode character
- \var{unichr} as integer. Returns \code{1} if the character has been
- identified as a ``mirrored'' character in bidirectional text,
- \code{0} otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{decomposition}{unichr}
- Returns the character decomposition mapping assigned to the Unicode
- character \var{unichr} as string. An empty string is returned in case
- no such mapping is defined.
-\end{funcdesc}
-
-\begin{funcdesc}{normalize}{form, unistr}
-
-Return the normal form \var{form} for the Unicode string \var{unistr}.
-Valid values for \var{form} are 'NFC', 'NFKC', 'NFD', and 'NFKD'.
-
-The Unicode standard defines various normalization forms of a Unicode
-string, based on the definition of canonical equivalence and
-compatibility equivalence. In Unicode, several characters can be
-expressed in various way. For example, the character U+00C7 (LATIN
-CAPITAL LETTER C WITH CEDILLA) can also be expressed as the sequence
-U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
-
-For each character, there are two normal forms: normal form C and
-normal form D. Normal form D (NFD) is also known as canonical
-decomposition, and translates each character into its decomposed form.
-Normal form C (NFC) first applies a canonical decomposition, then
-composes pre-combined characters again.
-
-In addition to these two forms, there are two additional normal forms
-based on compatibility equivalence. In Unicode, certain characters are
-supported which normally would be unified with other characters. For
-example, U+2160 (ROMAN NUMERAL ONE) is really the same thing as U+0049
-(LATIN CAPITAL LETTER I). However, it is supported in Unicode for
-compatibility with existing character sets (e.g. gb2312).
-
-The normal form KD (NFKD) will apply the compatibility decomposition,
-i.e. replace all compatibility characters with their equivalents. The
-normal form KC (NFKC) first applies the compatibility decomposition,
-followed by the canonical composition.
-
-\versionadded{2.3}
-\end{funcdesc}
-
-In addition, the module exposes the following constant:
-
-\begin{datadesc}{unidata_version}
-The version of the Unicode database used in this module.
-
-\versionadded{2.3}
-\end{datadesc}
-
-\begin{datadesc}{ucd_3_2_0}
-This is an object that has the same methods as the entire
-module, but uses the Unicode database version 3.2 instead,
-for applications that require this specific version of
-the Unicode database (such as IDNA).
-
-\versionadded{2.5}
-\end{datadesc}
-
-Examples:
-
-\begin{verbatim}
->>> unicodedata.lookup('LEFT CURLY BRACKET')
-u'{'
->>> unicodedata.name(u'/')
-'SOLIDUS'
->>> unicodedata.decimal(u'9')
-9
->>> unicodedata.decimal(u'a')
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-ValueError: not a decimal
->>> unicodedata.category(u'A') # 'L'etter, 'u'ppercase
-'Lu'
->>> unicodedata.bidirectional(u'\u0660') # 'A'rabic, 'N'umber
-'AN'
-\end{verbatim}
diff --git a/Doc/lib/libunittest.tex b/Doc/lib/libunittest.tex
deleted file mode 100644
index fa198c7..0000000
--- a/Doc/lib/libunittest.tex
+++ /dev/null
@@ -1,978 +0,0 @@
-\section{\module{unittest} ---
- Unit testing framework}
-
-\declaremodule{standard}{unittest}
-\modulesynopsis{Unit testing framework for Python.}
-\moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
-\sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Raymond Hettinger}{python@rcn.com}
-
-\versionadded{2.1}
-
-The Python unit testing framework, sometimes referred to as ``PyUnit,'' is
-a Python language version of JUnit, by Kent Beck and Erich Gamma.
-JUnit is, in turn, a Java version of Kent's Smalltalk testing
-framework. Each is the de facto standard unit testing framework for
-its respective language.
-
-\module{unittest} supports test automation, sharing of setup and shutdown
-code for tests, aggregation of tests into collections, and independence of
-the tests from the reporting framework. The \module{unittest} module
-provides classes that make it easy to support these qualities for a
-set of tests.
-
-To achieve this, \module{unittest} supports some important concepts:
-
-\begin{definitions}
-\term{test fixture}
-A \dfn{test fixture} represents the preparation needed to perform one
-or more tests, and any associate cleanup actions. This may involve,
-for example, creating temporary or proxy databases, directories, or
-starting a server process.
-
-\term{test case}
-A \dfn{test case} is the smallest unit of testing. It checks for a
-specific response to a particular set of inputs. \module{unittest}
-provides a base class, \class{TestCase}, which may be used to create
-new test cases.
-
-\term{test suite}
-A \dfn{test suite} is a collection of test cases, test suites, or
-both. It is used to aggregate tests that should be executed
-together.
-
-\term{test runner}
-A \dfn{test runner} is a component which orchestrates the execution of
-tests and provides the outcome to the user. The runner may use a
-graphical interface, a textual interface, or return a special value to
-indicate the results of executing the tests.
-\end{definitions}
-
-
-The test case and test fixture concepts are supported through the
-\class{TestCase} and \class{FunctionTestCase} classes; the former
-should be used when creating new tests, and the latter can be used when
-integrating existing test code with a \module{unittest}-driven framework.
-When building test fixtures using \class{TestCase}, the \method{setUp()}
-and \method{tearDown()} methods can be overridden to provide
-initialization and cleanup for the fixture. With
-\class{FunctionTestCase}, existing functions can be passed to the
-constructor for these purposes. When the test is run, the
-fixture initialization is run first; if it succeeds, the cleanup
-method is run after the test has been executed, regardless of the
-outcome of the test. Each instance of the \class{TestCase} will only
-be used to run a single test method, so a new fixture is created for
-each test.
-
-Test suites are implemented by the \class{TestSuite} class. This
-class allows individual tests and test suites to be aggregated; when
-the suite is executed, all tests added directly to the suite and in
-``child'' test suites are run.
-
-A test runner is an object that provides a single method,
-\method{run()}, which accepts a \class{TestCase} or \class{TestSuite}
-object as a parameter, and returns a result object. The class
-\class{TestResult} is provided for use as the result object.
-\module{unittest} provides the \class{TextTestRunner} as an example
-test runner which reports test results on the standard error stream by
-default. Alternate runners can be implemented for other environments
-(such as graphical environments) without any need to derive from a
-specific class.
-
-
-\begin{seealso}
- \seemodule{doctest}{Another test-support module with a very
- different flavor.}
- \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk
- Testing: With Patterns}{Kent Beck's original paper on
- testing frameworks using the pattern shared by
- \module{unittest}.}
-\end{seealso}
-
-
-\subsection{Basic example \label{unittest-minimal-example}}
-
-The \module{unittest} module provides a rich set of tools for
-constructing and running tests. This section demonstrates that a
-small subset of the tools suffice to meet the needs of most users.
-
-Here is a short script to test three functions from the
-\refmodule{random} module:
-
-\begin{verbatim}
-import random
-import unittest
-
-class TestSequenceFunctions(unittest.TestCase):
-
- def setUp(self):
- self.seq = range(10)
-
- def testshuffle(self):
- # make sure the shuffled sequence does not lose any elements
- random.shuffle(self.seq)
- self.seq.sort()
- self.assertEqual(self.seq, range(10))
-
- def testchoice(self):
- element = random.choice(self.seq)
- self.assert_(element in self.seq)
-
- def testsample(self):
- self.assertRaises(ValueError, random.sample, self.seq, 20)
- for element in random.sample(self.seq, 5):
- self.assert_(element in self.seq)
-
-if __name__ == '__main__':
- unittest.main()
-\end{verbatim}
-
-A testcase is created by subclassing \class{unittest.TestCase}.
-The three individual tests are defined with methods whose names start with
-the letters \samp{test}. This naming convention informs the test runner
-about which methods represent tests.
-
-The crux of each test is a call to \method{assertEqual()} to
-check for an expected result; \method{assert_()} to verify a condition;
-or \method{assertRaises()} to verify that an expected exception gets
-raised. These methods are used instead of the \keyword{assert} statement
-so the test runner can accumulate all test results and produce a report.
-
-When a \method{setUp()} method is defined, the test runner will run that
-method prior to each test. Likewise, if a \method{tearDown()} method is
-defined, the test runner will invoke that method after each test. In the
-example, \method{setUp()} was used to create a fresh sequence for each test.
-
-The final block shows a simple way to run the tests.
-\function{unittest.main()} provides a command line interface to the
-test script. When run from the command line, the above script
-produces an output that looks like this:
-
-\begin{verbatim}
-...
-----------------------------------------------------------------------
-Ran 3 tests in 0.000s
-
-OK
-\end{verbatim}
-
-Instead of \function{unittest.main()}, there are other ways to run the tests
-with a finer level of control, less terse output, and no requirement to be
-run from the command line. For example, the last two lines may be replaced
-with:
-
-\begin{verbatim}
-suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
-unittest.TextTestRunner(verbosity=2).run(suite)
-\end{verbatim}
-
-Running the revised script from the interpreter or another script
-produces the following output:
-
-\begin{verbatim}
-testchoice (__main__.TestSequenceFunctions) ... ok
-testsample (__main__.TestSequenceFunctions) ... ok
-testshuffle (__main__.TestSequenceFunctions) ... ok
-
-----------------------------------------------------------------------
-Ran 3 tests in 0.110s
-
-OK
-\end{verbatim}
-
-The above examples show the most commonly used \module{unittest} features
-which are sufficient to meet many everyday testing needs. The remainder
-of the documentation explores the full feature set from first principles.
-
-
-\subsection{Organizing test code
- \label{organizing-tests}}
-
-The basic building blocks of unit testing are \dfn{test cases} ---
-single scenarios that must be set up and checked for correctness. In
-\module{unittest}, test cases are represented by instances of
-\module{unittest}'s \class{TestCase} class. To make
-your own test cases you must write subclasses of \class{TestCase}, or
-use \class{FunctionTestCase}.
-
-An instance of a \class{TestCase}-derived class is an object that can
-completely run a single test method, together with optional set-up
-and tidy-up code.
-
-The testing code of a \class{TestCase} instance should be entirely
-self contained, such that it can be run either in isolation or in
-arbitrary combination with any number of other test cases.
-
-The simplest \class{TestCase} subclass will simply override the
-\method{runTest()} method in order to perform specific testing code:
-
-\begin{verbatim}
-import unittest
-
-class DefaultWidgetSizeTestCase(unittest.TestCase):
- def runTest(self):
- widget = Widget('The widget')
- self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
-\end{verbatim}
-
-Note that in order to test something, we use the one of the
-\method{assert*()} or \method{fail*()} methods provided by the
-\class{TestCase} base class. If the test fails, an exception will be
-raised, and \module{unittest} will identify the test case as a
-\dfn{failure}. Any other exceptions will be treated as \dfn{errors}.
-This helps you identify where the problem is: \dfn{failures} are caused by
-incorrect results - a 5 where you expected a 6. \dfn{Errors} are caused by
-incorrect code - e.g., a \exception{TypeError} caused by an incorrect
-function call.
-
-The way to run a test case will be described later. For now, note
-that to construct an instance of such a test case, we call its
-constructor without arguments:
-
-\begin{verbatim}
-testCase = DefaultWidgetSizeTestCase()
-\end{verbatim}
-
-Now, such test cases can be numerous, and their set-up can be
-repetitive. In the above case, constructing a \class{Widget} in each of
-100 Widget test case subclasses would mean unsightly duplication.
-
-Luckily, we can factor out such set-up code by implementing a method
-called \method{setUp()}, which the testing framework will
-automatically call for us when we run the test:
-
-\begin{verbatim}
-import unittest
-
-class SimpleWidgetTestCase(unittest.TestCase):
- def setUp(self):
- self.widget = Widget('The widget')
-
-class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
- def runTest(self):
- self.failUnless(self.widget.size() == (50,50),
- 'incorrect default size')
-
-class WidgetResizeTestCase(SimpleWidgetTestCase):
- def runTest(self):
- self.widget.resize(100,150)
- self.failUnless(self.widget.size() == (100,150),
- 'wrong size after resize')
-\end{verbatim}
-
-If the \method{setUp()} method raises an exception while the test is
-running, the framework will consider the test to have suffered an
-error, and the \method{runTest()} method will not be executed.
-
-Similarly, we can provide a \method{tearDown()} method that tidies up
-after the \method{runTest()} method has been run:
-
-\begin{verbatim}
-import unittest
-
-class SimpleWidgetTestCase(unittest.TestCase):
- def setUp(self):
- self.widget = Widget('The widget')
-
- def tearDown(self):
- self.widget.dispose()
- self.widget = None
-\end{verbatim}
-
-If \method{setUp()} succeeded, the \method{tearDown()} method will be
-run whether \method{runTest()} succeeded or not.
-
-Such a working environment for the testing code is called a
-\dfn{fixture}.
-
-Often, many small test cases will use the same fixture. In this case,
-we would end up subclassing \class{SimpleWidgetTestCase} into many
-small one-method classes such as
-\class{DefaultWidgetSizeTestCase}. This is time-consuming and
-
-discouraging, so in the same vein as JUnit, \module{unittest} provides
-a simpler mechanism:
-
-\begin{verbatim}
-import unittest
-
-class WidgetTestCase(unittest.TestCase):
- def setUp(self):
- self.widget = Widget('The widget')
-
- def tearDown(self):
- self.widget.dispose()
- self.widget = None
-
- def testDefaultSize(self):
- self.failUnless(self.widget.size() == (50,50),
- 'incorrect default size')
-
- def testResize(self):
- self.widget.resize(100,150)
- self.failUnless(self.widget.size() == (100,150),
- 'wrong size after resize')
-\end{verbatim}
-
-Here we have not provided a \method{runTest()} method, but have
-instead provided two different test methods. Class instances will now
-each run one of the \method{test*()} methods, with \code{self.widget}
-created and destroyed separately for each instance. When creating an
-instance we must specify the test method it is to run. We do this by
-passing the method name in the constructor:
-
-\begin{verbatim}
-defaultSizeTestCase = WidgetTestCase('testDefaultSize')
-resizeTestCase = WidgetTestCase('testResize')
-\end{verbatim}
-
-Test case instances are grouped together according to the features
-they test. \module{unittest} provides a mechanism for this: the
-\dfn{test suite}, represented by \module{unittest}'s \class{TestSuite}
-class:
-
-\begin{verbatim}
-widgetTestSuite = unittest.TestSuite()
-widgetTestSuite.addTest(WidgetTestCase('testDefaultSize'))
-widgetTestSuite.addTest(WidgetTestCase('testResize'))
-\end{verbatim}
-
-For the ease of running tests, as we will see later, it is a good
-idea to provide in each test module a callable object that returns a
-pre-built test suite:
-
-\begin{verbatim}
-def suite():
- suite = unittest.TestSuite()
- suite.addTest(WidgetTestCase('testDefaultSize'))
- suite.addTest(WidgetTestCase('testResize'))
- return suite
-\end{verbatim}
-
-or even:
-
-\begin{verbatim}
-def suite():
- tests = ['testDefaultSize', 'testResize']
-
- return unittest.TestSuite(map(WidgetTestCase, tests))
-\end{verbatim}
-
-Since it is a common pattern to create a \class{TestCase} subclass
-with many similarly named test functions, \module{unittest} provides a
-\class{TestLoader} class that can be used to automate the process of
-creating a test suite and populating it with individual tests.
-For example,
-
-\begin{verbatim}
-suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
-\end{verbatim}
-
-will create a test suite that will run
-\code{WidgetTestCase.testDefaultSize()} and \code{WidgetTestCase.testResize}.
-\class{TestLoader} uses the \code{'test'} method name prefix to identify
-test methods automatically.
-
-Note that the order in which the various test cases will be run is
-determined by sorting the test function names with the built-in
-\function{cmp()} function.
-
-Often it is desirable to group suites of test cases together, so as to
-run tests for the whole system at once. This is easy, since
-\class{TestSuite} instances can be added to a \class{TestSuite} just
-as \class{TestCase} instances can be added to a \class{TestSuite}:
-
-\begin{verbatim}
-suite1 = module1.TheTestSuite()
-suite2 = module2.TheTestSuite()
-alltests = unittest.TestSuite([suite1, suite2])
-\end{verbatim}
-
-You can place the definitions of test cases and test suites in the
-same modules as the code they are to test (such as \file{widget.py}),
-but there are several advantages to placing the test code in a
-separate module, such as \file{test_widget.py}:
-
-\begin{itemize}
- \item The test module can be run standalone from the command line.
- \item The test code can more easily be separated from shipped code.
- \item There is less temptation to change test code to fit the code
- it tests without a good reason.
- \item Test code should be modified much less frequently than the
- code it tests.
- \item Tested code can be refactored more easily.
- \item Tests for modules written in C must be in separate modules
- anyway, so why not be consistent?
- \item If the testing strategy changes, there is no need to change
- the source code.
-\end{itemize}
-
-
-\subsection{Re-using old test code
- \label{legacy-unit-tests}}
-
-Some users will find that they have existing test code that they would
-like to run from \module{unittest}, without converting every old test
-function to a \class{TestCase} subclass.
-
-For this reason, \module{unittest} provides a \class{FunctionTestCase}
-class. This subclass of \class{TestCase} can be used to wrap an existing
-test function. Set-up and tear-down functions can also be provided.
-
-Given the following test function:
-
-\begin{verbatim}
-def testSomething():
- something = makeSomething()
- assert something.name is not None
- # ...
-\end{verbatim}
-
-one can create an equivalent test case instance as follows:
-
-\begin{verbatim}
-testcase = unittest.FunctionTestCase(testSomething)
-\end{verbatim}
-
-If there are additional set-up and tear-down methods that should be
-called as part of the test case's operation, they can also be provided
-like so:
-
-\begin{verbatim}
-testcase = unittest.FunctionTestCase(testSomething,
- setUp=makeSomethingDB,
- tearDown=deleteSomethingDB)
-\end{verbatim}
-
-To make migrating existing test suites easier, \module{unittest}
-supports tests raising \exception{AssertionError} to indicate test failure.
-However, it is recommended that you use the explicit
-\method{TestCase.fail*()} and \method{TestCase.assert*()} methods instead,
-as future versions of \module{unittest} may treat \exception{AssertionError}
-differently.
-
-\note{Even though \class{FunctionTestCase} can be used to quickly convert
-an existing test base over to a \module{unittest}-based system, this
-approach is not recommended. Taking the time to set up proper
-\class{TestCase} subclasses will make future test refactorings infinitely
-easier.}
-
-
-
-\subsection{Classes and functions
- \label{unittest-contents}}
-
-\begin{classdesc}{TestCase}{\optional{methodName}}
- Instances of the \class{TestCase} class represent the smallest
- testable units in the \module{unittest} universe. This class is
- intended to be used as a base class, with specific tests being
- implemented by concrete subclasses. This class implements the
- interface needed by the test runner to allow it to drive the
- test, and methods that the test code can use to check for and
- report various kinds of failure.
-
- Each instance of \class{TestCase} will run a single test method:
- the method named \var{methodName}. If you remember, we had an
- earlier example that went something like this:
-
- \begin{verbatim}
- def suite():
- suite = unittest.TestSuite()
- suite.addTest(WidgetTestCase('testDefaultSize'))
- suite.addTest(WidgetTestCase('testResize'))
- return suite
- \end{verbatim}
-
- Here, we create two instances of \class{WidgetTestCase}, each of
- which runs a single test.
-
- \var{methodName} defaults to \code{'runTest'}.
-\end{classdesc}
-
-\begin{classdesc}{FunctionTestCase}{testFunc\optional{,
- setUp\optional{, tearDown\optional{, description}}}}
- This class implements the portion of the \class{TestCase} interface
- which allows the test runner to drive the test, but does not provide
- the methods which test code can use to check and report errors.
- This is used to create test cases using legacy test code, allowing
- it to be integrated into a \refmodule{unittest}-based test
- framework.
-\end{classdesc}
-
-\begin{classdesc}{TestSuite}{\optional{tests}}
- This class represents an aggregation of individual tests cases and
- test suites. The class presents the interface needed by the test
- runner to allow it to be run as any other test case. Running a
- \class{TestSuite} instance is the same as iterating over the suite,
- running each test individually.
-
- If \var{tests} is given, it must be an iterable of individual test cases or
- other test suites that will be used to build the suite initially.
- Additional methods are provided to add test cases and suites to the
- collection later on.
-\end{classdesc}
-
-\begin{classdesc}{TestLoader}{}
- This class is responsible for loading tests according to various
- criteria and returning them wrapped in a \class{TestSuite}.
- It can load all tests within a given module or \class{TestCase}
- subclass.
-\end{classdesc}
-
-\begin{classdesc}{TestResult}{}
- This class is used to compile information about which tests have succeeded
- and which have failed.
-\end{classdesc}
-
-\begin{datadesc}{defaultTestLoader}
- Instance of the \class{TestLoader} class intended to be shared. If no
- customization of the \class{TestLoader} is needed, this instance can
- be used instead of repeatedly creating new instances.
-\end{datadesc}
-
-\begin{classdesc}{TextTestRunner}{\optional{stream\optional{,
- descriptions\optional{, verbosity}}}}
- A basic test runner implementation which prints results on standard
- error. It has a few configurable parameters, but is essentially
- very simple. Graphical applications which run test suites should
- provide alternate implementations.
-\end{classdesc}
-
-\begin{funcdesc}{main}{\optional{module\optional{,
- defaultTest\optional{, argv\optional{,
- testRunner\optional{, testLoader}}}}}}
- A command-line program that runs a set of tests; this is primarily
- for making test modules conveniently executable. The simplest use
- for this function is to include the following line at the end of a
- test script:
-
-\begin{verbatim}
-if __name__ == '__main__':
- unittest.main()
-\end{verbatim}
-
- The \var{testRunner} argument can either be a test runner class or
- an already created instance of it.
-\end{funcdesc}
-
-In some cases, the existing tests may have been written using the
-\refmodule{doctest} module. If so, that module provides a
-\class{DocTestSuite} class that can automatically build
-\class{unittest.TestSuite} instances from the existing
-\module{doctest}-based tests.
-\versionadded{2.3}
-
-
-\subsection{TestCase Objects
- \label{testcase-objects}}
-
-Each \class{TestCase} instance represents a single test, but each
-concrete subclass may be used to define multiple tests --- the
-concrete class represents a single test fixture. The fixture is
-created and cleaned up for each test case.
-
-\class{TestCase} instances provide three groups of methods: one group
-used to run the test, another used by the test implementation to
-check conditions and report failures, and some inquiry methods
-allowing information about the test itself to be gathered.
-
-Methods in the first group (running the test) are:
-
-\begin{methoddesc}[TestCase]{setUp}{}
- Method called to prepare the test fixture. This is called
- immediately before calling the test method; any exception raised by
- this method will be considered an error rather than a test failure.
- The default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{tearDown}{}
- Method called immediately after the test method has been called and
- the result recorded. This is called even if the test method raised
- an exception, so the implementation in subclasses may need to be
- particularly careful about checking internal state. Any exception
- raised by this method will be considered an error rather than a test
- failure. This method will only be called if the \method{setUp()}
- succeeds, regardless of the outcome of the test method.
- The default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{run}{\optional{result}}
- Run the test, collecting the result into the test result object
- passed as \var{result}. If \var{result} is omitted or \constant{None},
- a temporary result object is created (by calling the
- \method{defaultTestCase()} method) and used; this result object is not
- returned to \method{run()}'s caller.
-
- The same effect may be had by simply calling the \class{TestCase}
- instance.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{debug}{}
- Run the test without collecting the result. This allows exceptions
- raised by the test to be propagated to the caller, and can be used
- to support running tests under a debugger.
-\end{methoddesc}
-
-
-The test code can use any of the following methods to check for and
-report failures.
-
-\begin{methoddesc}[TestCase]{assert_}{expr\optional{, msg}}
-\methodline[TestCase]{failUnless}{expr\optional{, msg}}
- Signal a test failure if \var{expr} is false; the explanation for
- the error will be \var{msg} if given, otherwise it will be
- \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertEqual}{first, second\optional{, msg}}
-\methodline[TestCase]{failUnlessEqual}{first, second\optional{, msg}}
- Test that \var{first} and \var{second} are equal. If the values do
- not compare equal, the test will fail with the explanation given by
- \var{msg}, or \constant{None}. Note that using \method{failUnlessEqual()}
- improves upon doing the comparison as the first parameter to
- \method{failUnless()}: the default value for \var{msg} can be
- computed to include representations of both \var{first} and
- \var{second}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertNotEqual}{first, second\optional{, msg}}
-\methodline[TestCase]{failIfEqual}{first, second\optional{, msg}}
- Test that \var{first} and \var{second} are not equal. If the values
- do compare equal, the test will fail with the explanation given by
- \var{msg}, or \constant{None}. Note that using \method{failIfEqual()}
- improves upon doing the comparison as the first parameter to
- \method{failUnless()} is that the default value for \var{msg} can be
- computed to include representations of both \var{first} and
- \var{second}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
-\methodline[TestCase]{failUnlessAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
- Test that \var{first} and \var{second} are approximately equal
- by computing the difference, rounding to the given number of \var{places},
- and comparing to zero. Note that comparing a given number of decimal places
- is not the same as comparing a given number of significant digits.
- If the values do not compare equal, the test will fail with the explanation
- given by \var{msg}, or \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertNotAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
-\methodline[TestCase]{failIfAlmostEqual}{first, second\optional{,
- places\optional{, msg}}}
- Test that \var{first} and \var{second} are not approximately equal
- by computing the difference, rounding to the given number of \var{places},
- and comparing to zero. Note that comparing a given number of decimal places
- is not the same as comparing a given number of significant digits.
- If the values do not compare equal, the test will fail with the explanation
- given by \var{msg}, or \constant{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{assertRaises}{exception, callable, \moreargs}
-\methodline[TestCase]{failUnlessRaises}{exception, callable, \moreargs}
- Test that an exception is raised when \var{callable} is called with
- any positional or keyword arguments that are also passed to
- \method{assertRaises()}. The test passes if \var{exception} is
- raised, is an error if another exception is raised, or fails if no
- exception is raised. To catch any of a group of exceptions, a tuple
- containing the exception classes may be passed as \var{exception}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}}
- The inverse of the \method{failUnless()} method is the
- \method{failIf()} method. This signals a test failure if \var{expr}
- is true, with \var{msg} or \constant{None} for the error message.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{fail}{\optional{msg}}
- Signals a test failure unconditionally, with \var{msg} or
- \constant{None} for the error message.
-\end{methoddesc}
-
-\begin{memberdesc}[TestCase]{failureException}
- This class attribute gives the exception raised by the
- \method{test()} method. If a test framework needs to use a
- specialized exception, possibly to carry additional information, it
- must subclass this exception in order to ``play fair'' with the
- framework. The initial value of this attribute is
- \exception{AssertionError}.
-\end{memberdesc}
-
-
-Testing frameworks can use the following methods to collect
-information on the test:
-
-\begin{methoddesc}[TestCase]{countTestCases}{}
- Return the number of tests represented by this test object. For
- \class{TestCase} instances, this will always be \code{1}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{defaultTestResult}{}
- Return an instance of the test result class that should be used
- for this test case class (if no other result instance is provided
- to the \method{run()} method).
-
- For \class{TestCase} instances, this will always be an instance of
- \class{TestResult}; subclasses of \class{TestCase} should
- override this as necessary.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{id}{}
- Return a string identifying the specific test case. This is usually
- the full name of the test method, including the module and class
- name.
-\end{methoddesc}
-
-\begin{methoddesc}[TestCase]{shortDescription}{}
- Returns a one-line description of the test, or \constant{None} if no
- description has been provided. The default implementation of this
- method returns the first line of the test method's docstring, if
- available, or \constant{None}.
-\end{methoddesc}
-
-
-\subsection{TestSuite Objects
- \label{testsuite-objects}}
-
-\class{TestSuite} objects behave much like \class{TestCase} objects,
-except they do not actually implement a test. Instead, they are used
-to aggregate tests into groups of tests that should be run together.
-Some additional methods are available to add tests to \class{TestSuite}
-instances:
-
-\begin{methoddesc}[TestSuite]{addTest}{test}
- Add a \class{TestCase} or \class{TestSuite} to the suite.
-\end{methoddesc}
-
-\begin{methoddesc}[TestSuite]{addTests}{tests}
- Add all the tests from an iterable of \class{TestCase} and
- \class{TestSuite} instances to this test suite.
-
- This is equivalent to iterating over \var{tests}, calling
- \method{addTest()} for each element.
-\end{methoddesc}
-
-\class{TestSuite} shares the following methods with \class{TestCase}:
-
-\begin{methoddesc}[TestSuite]{run}{result}
- Run the tests associated with this suite, collecting the result into
- the test result object passed as \var{result}. Note that unlike
- \method{TestCase.run()}, \method{TestSuite.run()} requires the
- result object to be passed in.
-\end{methoddesc}
-
-\begin{methoddesc}[TestSuite]{debug}{}
- Run the tests associated with this suite without collecting the result.
- This allows exceptions raised by the test to be propagated to the caller
- and can be used to support running tests under a debugger.
-\end{methoddesc}
-
-\begin{methoddesc}[TestSuite]{countTestCases}{}
- Return the number of tests represented by this test object, including
- all individual tests and sub-suites.
-\end{methoddesc}
-
-In the typical usage of a \class{TestSuite} object, the \method{run()}
-method is invoked by a \class{TestRunner} rather than by the end-user
-test harness.
-
-
-\subsection{TestResult Objects
- \label{testresult-objects}}
-
-A \class{TestResult} object stores the results of a set of tests. The
-\class{TestCase} and \class{TestSuite} classes ensure that results are
-properly recorded; test authors do not need to worry about recording the
-outcome of tests.
-
-Testing frameworks built on top of \refmodule{unittest} may want
-access to the \class{TestResult} object generated by running a set of
-tests for reporting purposes; a \class{TestResult} instance is
-returned by the \method{TestRunner.run()} method for this purpose.
-
-\class{TestResult} instances have the following attributes that will
-be of interest when inspecting the results of running a set of tests:
-
-\begin{memberdesc}[TestResult]{errors}
- A list containing 2-tuples of \class{TestCase} instances and
- strings holding formatted tracebacks. Each tuple represents a test which
- raised an unexpected exception.
- \versionchanged[Contains formatted tracebacks instead of
- \function{sys.exc_info()} results]{2.2}
-\end{memberdesc}
-
-\begin{memberdesc}[TestResult]{failures}
- A list containing 2-tuples of \class{TestCase} instances and strings
- holding formatted tracebacks. Each tuple represents a test where a failure
- was explicitly signalled using the \method{TestCase.fail*()} or
- \method{TestCase.assert*()} methods.
- \versionchanged[Contains formatted tracebacks instead of
- \function{sys.exc_info()} results]{2.2}
-\end{memberdesc}
-
-\begin{memberdesc}[TestResult]{testsRun}
- The total number of tests run so far.
-\end{memberdesc}
-
-\begin{methoddesc}[TestResult]{wasSuccessful}{}
- Returns \constant{True} if all tests run so far have passed,
- otherwise returns \constant{False}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{stop}{}
- This method can be called to signal that the set of tests being run
- should be aborted by setting the \class{TestResult}'s \code{shouldStop}
- attribute to \constant{True}. \class{TestRunner} objects should respect
- this flag and return without running any additional tests.
-
- For example, this feature is used by the \class{TextTestRunner} class
- to stop the test framework when the user signals an interrupt from
- the keyboard. Interactive tools which provide \class{TestRunner}
- implementations can use this in a similar manner.
-\end{methoddesc}
-
-
-The following methods of the \class{TestResult} class are used to
-maintain the internal data structures, and may be extended in
-subclasses to support additional reporting requirements. This is
-particularly useful in building tools which support interactive
-reporting while tests are being run.
-
-\begin{methoddesc}[TestResult]{startTest}{test}
- Called when the test case \var{test} is about to be run.
-
- The default implementation simply increments the instance's
- \code{testsRun} counter.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{stopTest}{test}
- Called after the test case \var{test} has been executed, regardless
- of the outcome.
-
- The default implementation does nothing.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{addError}{test, err}
- Called when the test case \var{test} raises an unexpected exception
- \var{err} is a tuple of the form returned by \function{sys.exc_info()}:
- \code{(\var{type}, \var{value}, \var{traceback})}.
-
- The default implementation appends \code{(\var{test}, \var{err})} to
- the instance's \code{errors} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{addFailure}{test, err}
- Called when the test case \var{test} signals a failure.
- \var{err} is a tuple of the form returned by
- \function{sys.exc_info()}: \code{(\var{type}, \var{value},
- \var{traceback})}.
-
- The default implementation appends \code{(\var{test}, \var{err})} to
- the instance's \code{failures} attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[TestResult]{addSuccess}{test}
- Called when the test case \var{test} succeeds.
-
- The default implementation does nothing.
-\end{methoddesc}
-
-
-
-\subsection{TestLoader Objects
- \label{testloader-objects}}
-
-The \class{TestLoader} class is used to create test suites from
-classes and modules. Normally, there is no need to create an instance
-of this class; the \refmodule{unittest} module provides an instance
-that can be shared as \code{unittest.defaultTestLoader}.
-Using a subclass or instance, however, allows customization of some
-configurable properties.
-
-\class{TestLoader} objects have the following methods:
-
-\begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass}
- Return a suite of all tests cases contained in the
- \class{TestCase}-derived \class{testCaseClass}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{loadTestsFromModule}{module}
- Return a suite of all tests cases contained in the given module.
- This method searches \var{module} for classes derived from
- \class{TestCase} and creates an instance of the class for each test
- method defined for the class.
-
- \warning{While using a hierarchy of
- \class{TestCase}-derived classes can be convenient in sharing
- fixtures and helper functions, defining test methods on base classes
- that are not intended to be instantiated directly does not play well
- with this method. Doing so, however, can be useful when the
- fixtures are different and defined in subclasses.}
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{loadTestsFromName}{name\optional{, module}}
- Return a suite of all tests cases given a string specifier.
-
- The specifier \var{name} is a ``dotted name'' that may resolve
- either to a module, a test case class, a test method within a test
- case class, a \class{TestSuite} instance, or a callable object which
- returns a \class{TestCase} or \class{TestSuite} instance. These checks
- are applied in the order listed here; that is, a method on a possible
- test case class will be picked up as ``a test method within a test
- case class'', rather than ``a callable object''.
-
- For example, if you have a module \module{SampleTests} containing a
- \class{TestCase}-derived class \class{SampleTestCase} with three test
- methods (\method{test_one()}, \method{test_two()}, and
- \method{test_three()}), the specifier \code{'SampleTests.SampleTestCase'}
- would cause this method to return a suite which will run all three test
- methods. Using the specifier \code{'SampleTests.SampleTestCase.test_two'}
- would cause it to return a test suite which will run only the
- \method{test_two()} test method. The specifier can refer to modules
- and packages which have not been imported; they will be imported as
- a side-effect.
-
- The method optionally resolves \var{name} relative to the given
- \var{module}.
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}}
- Similar to \method{loadTestsFromName()}, but takes a sequence of
- names rather than a single name. The return value is a test suite
- which supports all the tests defined for each name.
-\end{methoddesc}
-
-\begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass}
- Return a sorted sequence of method names found within
- \var{testCaseClass}; this should be a subclass of \class{TestCase}.
-\end{methoddesc}
-
-
-The following attributes of a \class{TestLoader} can be configured
-either by subclassing or assignment on an instance:
-
-\begin{memberdesc}[TestLoader]{testMethodPrefix}
- String giving the prefix of method names which will be interpreted
- as test methods. The default value is \code{'test'}.
-
- This affects \method{getTestCaseNames()} and all the
- \method{loadTestsFrom*()} methods.
-\end{memberdesc}
-
-\begin{memberdesc}[TestLoader]{sortTestMethodsUsing}
- Function to be used to compare method names when sorting them in
- \method{getTestCaseNames()} and all the \method{loadTestsFrom*()} methods.
- The default value is the built-in \function{cmp()} function; the attribute
- can also be set to \constant{None} to disable the sort.
-\end{memberdesc}
-
-\begin{memberdesc}[TestLoader]{suiteClass}
- Callable object that constructs a test suite from a list of tests.
- No methods on the resulting object are needed. The default value is
- the \class{TestSuite} class.
-
- This affects all the \method{loadTestsFrom*()} methods.
-\end{memberdesc}
diff --git a/Doc/lib/libunix.tex b/Doc/lib/libunix.tex
deleted file mode 100644
index 686df01..0000000
--- a/Doc/lib/libunix.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{Unix Specific Services}
-\label{unix}
-
-The modules described in this chapter provide interfaces to features
-that are unique to the \UNIX{} operating system, or in some cases to
-some or many variants of it. Here's an overview:
-
-\localmoduletable
diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
deleted file mode 100644
index 77dfb8f..0000000
--- a/Doc/lib/liburllib.tex
+++ /dev/null
@@ -1,494 +0,0 @@
-\section{\module{urllib} ---
- Open arbitrary resources by URL}
-
-\declaremodule{standard}{urllib}
-\modulesynopsis{Open an arbitrary network resource by URL (requires sockets).}
-
-\index{WWW}
-\index{World Wide Web}
-\index{URL}
-
-
-This module provides a high-level interface for fetching data across
-the World Wide Web. In particular, the \function{urlopen()} function
-is similar to the built-in function \function{open()}, but accepts
-Universal Resource Locators (URLs) instead of filenames. Some
-restrictions apply --- it can only open URLs for reading, and no seek
-operations are available.
-
-It defines the following public functions:
-
-\begin{funcdesc}{urlopen}{url\optional{, data\optional{, proxies}}}
-Open a network object denoted by a URL for reading. If the URL does
-not have a scheme identifier, or if it has \file{file:} as its scheme
-identifier, this opens a local file (without universal newlines);
-otherwise it opens a socket to a server somewhere on the network. If
-the connection cannot be made
-the \exception{IOError} exception is raised. If all went well, a
-file-like object is returned. This supports the following methods:
-\method{read()}, \method{readline()}, \method{readlines()}, \method{fileno()},
-\method{close()}, \method{info()} and \method{geturl()}. It also has
-proper support for the iterator protocol.
-One caveat: the \method{read()} method, if the size argument is
-omitted or negative, may not read until the end of the data stream;
-there is no good way to determine that the entire stream from a socket
-has been read in the general case.
-
-Except for the \method{info()} and \method{geturl()} methods,
-these methods have the same interface as for
-file objects --- see section \ref{bltin-file-objects} in this
-manual. (It is not a built-in file object, however, so it can't be
-used at those few places where a true built-in file object is
-required.)
-
-The \method{info()} method returns an instance of the class
-\class{mimetools.Message} containing meta-information associated
-with the URL. When the method is HTTP, these headers are those
-returned by the server at the head of the retrieved HTML page
-(including Content-Length and Content-Type). When the method is FTP,
-a Content-Length header will be present if (as is now usual) the
-server passed back a file length in response to the FTP retrieval
-request. A Content-Type header will be present if the MIME type can
-be guessed. When the method is local-file, returned headers will include
-a Date representing the file's last-modified time, a Content-Length
-giving file size, and a Content-Type containing a guess at the file's
-type. See also the description of the
-\refmodule{mimetools}\refstmodindex{mimetools} module.
-
-The \method{geturl()} method returns the real URL of the page. In
-some cases, the HTTP server redirects a client to another URL. The
-\function{urlopen()} function handles this transparently, but in some
-cases the caller needs to know which URL the client was redirected
-to. The \method{geturl()} method can be used to get at this
-redirected URL.
-
-If the \var{url} uses the \file{http:} scheme identifier, the optional
-\var{data} argument may be given to specify a \code{POST} request
-(normally the request type is \code{GET}). The \var{data} argument
-must be in standard \mimetype{application/x-www-form-urlencoded} format;
-see the \function{urlencode()} function below.
-
-The \function{urlopen()} function works transparently with proxies
-which do not require authentication. In a \UNIX{} or Windows
-environment, set the \envvar{http_proxy}, or \envvar{ftp_proxy}
-environment variables to a URL that identifies
-the proxy server before starting the Python interpreter. For example
-(the \character{\%} is the command prompt):
-
-\begin{verbatim}
-% http_proxy="http://www.someproxy.com:3128"
-% export http_proxy
-% python
-...
-\end{verbatim}
-
-In a Windows environment, if no proxy environment variables are set,
-proxy settings are obtained from the registry's Internet Settings
-section.
-
-In a Macintosh environment, \function{urlopen()} will retrieve proxy
-information from Internet\index{Internet Config} Config.
-
-Alternatively, the optional \var{proxies} argument may be used to
-explicitly specify proxies. It must be a dictionary mapping scheme
-names to proxy URLs, where an empty dictionary causes no proxies to be
-used, and \code{None} (the default value) causes environmental proxy
-settings to be used as discussed above. For example:
-
-\begin{verbatim}
-# Use http://www.someproxy.com:3128 for http proxying
-proxies = {'http': 'http://www.someproxy.com:3128'}
-filehandle = urllib.urlopen(some_url, proxies=proxies)
-# Don't use any proxies
-filehandle = urllib.urlopen(some_url, proxies={})
-# Use proxies from environment - both versions are equivalent
-filehandle = urllib.urlopen(some_url, proxies=None)
-filehandle = urllib.urlopen(some_url)
-\end{verbatim}
-
-The \function{urlopen()} function does not support explicit proxy
-specification. If you need to override environmental proxy settings,
-use \class{URLopener}, or a subclass such as \class{FancyURLopener}.
-
-Proxies which require authentication for use are not currently
-supported; this is considered an implementation limitation.
-
-\versionchanged[Added the \var{proxies} support]{2.3}
-\end{funcdesc}
-
-\begin{funcdesc}{urlretrieve}{url\optional{, filename\optional{,
- reporthook\optional{, data}}}}
-Copy a network object denoted by a URL to a local file, if necessary.
-If the URL points to a local file, or a valid cached copy of the
-object exists, the object is not copied. Return a tuple
-\code{(\var{filename}, \var{headers})} where \var{filename} is the
-local file name under which the object can be found, and \var{headers}
-is whatever the \method{info()} method of the object returned by
-\function{urlopen()} returned (for a remote object, possibly cached).
-Exceptions are the same as for \function{urlopen()}.
-
-The second argument, if present, specifies the file location to copy
-to (if absent, the location will be a tempfile with a generated name).
-The third argument, if present, is a hook function that will be called
-once on establishment of the network connection and once after each
-block read thereafter. The hook will be passed three arguments; a
-count of blocks transferred so far, a block size in bytes, and the
-total size of the file. The third argument may be \code{-1} on older
-FTP servers which do not return a file size in response to a retrieval
-request.
-
-If the \var{url} uses the \file{http:} scheme identifier, the optional
-\var{data} argument may be given to specify a \code{POST} request
-(normally the request type is \code{GET}). The \var{data} argument
-must in standard \mimetype{application/x-www-form-urlencoded} format;
-see the \function{urlencode()} function below.
-
-\versionchanged[
-\function{urlretrieve()} will raise \exception{ContentTooShortError}
-when it detects that the amount of data available
-was less than the expected amount (which is the size reported by a
-\var{Content-Length} header). This can occur, for example, when the
-download is interrupted.
-
-The \var{Content-Length} is treated as a lower bound: if there's more data
-to read, urlretrieve reads more data, but if less data is available,
-it raises the exception.
-
-You can still retrieve the downloaded data in this case, it is stored
-in the \member{content} attribute of the exception instance.
-
-If no \var{Content-Length} header was supplied, urlretrieve can
-not check the size of the data it has downloaded, and just returns it.
-In this case you just have to assume that the download was successful]{2.5}
-
-\end{funcdesc}
-
-\begin{datadesc}{_urlopener}
-The public functions \function{urlopen()} and
-\function{urlretrieve()} create an instance of the
-\class{FancyURLopener} class and use it to perform their requested
-actions. To override this functionality, programmers can create a
-subclass of \class{URLopener} or \class{FancyURLopener}, then assign
-an instance of that class to the
-\code{urllib._urlopener} variable before calling the desired function.
-For example, applications may want to specify a different
-\mailheader{User-Agent} header than \class{URLopener} defines. This
-can be accomplished with the following code:
-
-\begin{verbatim}
-import urllib
-
-class AppURLopener(urllib.FancyURLopener):
- version = "App/1.7"
-
-urllib._urlopener = AppURLopener()
-\end{verbatim}
-\end{datadesc}
-
-\begin{funcdesc}{urlcleanup}{}
-Clear the cache that may have been built up by previous calls to
-\function{urlretrieve()}.
-\end{funcdesc}
-
-\begin{funcdesc}{quote}{string\optional{, safe}}
-Replace special characters in \var{string} using the \samp{\%xx} escape.
-Letters, digits, and the characters \character{_.-} are never quoted.
-The optional \var{safe} parameter specifies additional characters
-that should not be quoted --- its default value is \code{'/'}.
-
-Example: \code{quote('/\~{}connolly/')} yields \code{'/\%7econnolly/'}.
-\end{funcdesc}
-
-\begin{funcdesc}{quote_plus}{string\optional{, safe}}
-Like \function{quote()}, but also replaces spaces by plus signs, as
-required for quoting HTML form values. Plus signs in the original
-string are escaped unless they are included in \var{safe}. It also
-does not have \var{safe} default to \code{'/'}.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote}{string}
-Replace \samp{\%xx} escapes by their single-character equivalent.
-
-Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~{}connolly/'}.
-\end{funcdesc}
-
-\begin{funcdesc}{unquote_plus}{string}
-Like \function{unquote()}, but also replaces plus signs by spaces, as
-required for unquoting HTML form values.
-\end{funcdesc}
-
-\begin{funcdesc}{urlencode}{query\optional{, doseq}}
-Convert a mapping object or a sequence of two-element tuples to a
-``url-encoded'' string, suitable to pass to
-\function{urlopen()} above as the optional \var{data} argument. This
-is useful to pass a dictionary of form fields to a \code{POST}
-request. The resulting string is a series of
-\code{\var{key}=\var{value}} pairs separated by \character{\&}
-characters, where both \var{key} and \var{value} are quoted using
-\function{quote_plus()} above. If the optional parameter \var{doseq} is
-present and evaluates to true, individual \code{\var{key}=\var{value}} pairs
-are generated for each element of the sequence.
-When a sequence of two-element tuples is used as the \var{query} argument,
-the first element of each tuple is a key and the second is a value. The
-order of parameters in the encoded string will match the order of parameter
-tuples in the sequence.
-The \refmodule{cgi} module provides the functions
-\function{parse_qs()} and \function{parse_qsl()} which are used to
-parse query strings into Python data structures.
-\end{funcdesc}
-
-\begin{funcdesc}{pathname2url}{path}
-Convert the pathname \var{path} from the local syntax for a path to
-the form used in the path component of a URL. This does not produce a
-complete URL. The return value will already be quoted using the
-\function{quote()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{url2pathname}{path}
-Convert the path component \var{path} from an encoded URL to the local
-syntax for a path. This does not accept a complete URL. This
-function uses \function{unquote()} to decode \var{path}.
-\end{funcdesc}
-
-\begin{classdesc}{URLopener}{\optional{proxies\optional{, **x509}}}
-Base class for opening and reading URLs. Unless you need to support
-opening objects using schemes other than \file{http:}, \file{ftp:},
-or \file{file:}, you probably want to use
-\class{FancyURLopener}.
-
-By default, the \class{URLopener} class sends a
-\mailheader{User-Agent} header of \samp{urllib/\var{VVV}}, where
-\var{VVV} is the \module{urllib} version number. Applications can
-define their own \mailheader{User-Agent} header by subclassing
-\class{URLopener} or \class{FancyURLopener} and setting the class
-attribute \member{version} to an appropriate string value in the
-subclass definition.
-
-The optional \var{proxies} parameter should be a dictionary mapping
-scheme names to proxy URLs, where an empty dictionary turns proxies
-off completely. Its default value is \code{None}, in which case
-environmental proxy settings will be used if present, as discussed in
-the definition of \function{urlopen()}, above.
-
-Additional keyword parameters, collected in \var{x509}, may be used for
-authentication of the client when using the \file{https:} scheme. The keywords
-\var{key_file} and \var{cert_file} are supported to provide an
-SSL key and certificate; both are needed to support client authentication.
-
-\class{URLopener} objects will raise an \exception{IOError} exception
-if the server returns an error code.
-\end{classdesc}
-
-\begin{classdesc}{FancyURLopener}{...}
-\class{FancyURLopener} subclasses \class{URLopener} providing default
-handling for the following HTTP response codes: 301, 302, 303, 307 and
-401. For the 30x response codes listed above, the
-\mailheader{Location} header is used to fetch the actual URL. For 401
-response codes (authentication required), basic HTTP authentication is
-performed. For the 30x response codes, recursion is bounded by the
-value of the \var{maxtries} attribute, which defaults to 10.
-
-For all other response codes, the method \method{http_error_default()}
-is called which you can override in subclasses to handle the error
-appropriately.
-
-\note{According to the letter of \rfc{2616}, 301 and 302 responses to
- POST requests must not be automatically redirected without
- confirmation by the user. In reality, browsers do allow automatic
- redirection of these responses, changing the POST to a GET, and
- \module{urllib} reproduces this behaviour.}
-
-The parameters to the constructor are the same as those for
-\class{URLopener}.
-
-\note{When performing basic authentication, a
-\class{FancyURLopener} instance calls its
-\method{prompt_user_passwd()} method. The default implementation asks
-the users for the required information on the controlling terminal. A
-subclass may override this method to support more appropriate behavior
-if needed.}
-\end{classdesc}
-
-\begin{excclassdesc}{ContentTooShortError}{msg\optional{, content}}
-This exception is raised when the \function{urlretrieve()} function
-detects that the amount of the downloaded data is less than the
-expected amount (given by the \var{Content-Length} header). The
-\member{content} attribute stores the downloaded (and supposedly
-truncated) data.
-\versionadded{2.5}
-\end{excclassdesc}
-
-Restrictions:
-
-\begin{itemize}
-
-\item
-Currently, only the following protocols are supported: HTTP, (versions
-0.9 and 1.0), FTP, and local files.
-\indexii{HTTP}{protocol}
-\indexii{FTP}{protocol}
-
-\item
-The caching feature of \function{urlretrieve()} has been disabled
-until I find the time to hack proper processing of Expiration time
-headers.
-
-\item
-There should be a function to query whether a particular URL is in
-the cache.
-
-\item
-For backward compatibility, if a URL appears to point to a local file
-but the file can't be opened, the URL is re-interpreted using the FTP
-protocol. This can sometimes cause confusing error messages.
-
-\item
-The \function{urlopen()} and \function{urlretrieve()} functions can
-cause arbitrarily long delays while waiting for a network connection
-to be set up. This means that it is difficult to build an interactive
-Web client using these functions without using threads.
-
-\item
-The data returned by \function{urlopen()} or \function{urlretrieve()}
-is the raw data returned by the server. This may be binary data
-(such as an image), plain text or (for example) HTML\index{HTML}. The
-HTTP\indexii{HTTP}{protocol} protocol provides type information in the
-reply header, which can be inspected by looking at the
-\mailheader{Content-Type} header. If the
-returned data is HTML, you can use the module
-\refmodule{htmllib}\refstmodindex{htmllib} to parse it.
-
-\item
-The code handling the FTP\index{FTP} protocol cannot differentiate
-between a file and a directory. This can lead to unexpected behavior
-when attempting to read a URL that points to a file that is not
-accessible. If the URL ends in a \code{/}, it is assumed to refer to
-a directory and will be handled accordingly. But if an attempt to
-read a file leads to a 550 error (meaning the URL cannot be found or
-is not accessible, often for permission reasons), then the path is
-treated as a directory in order to handle the case when a directory is
-specified by a URL but the trailing \code{/} has been left off. This can
-cause misleading results when you try to fetch a file whose read
-permissions make it inaccessible; the FTP code will try to read it,
-fail with a 550 error, and then perform a directory listing for the
-unreadable file. If fine-grained control is needed, consider using the
-\module{ftplib} module, subclassing \class{FancyURLOpener}, or changing
-\var{_urlopener} to meet your needs.
-
-\item
-This module does not support the use of proxies which require
-authentication. This may be implemented in the future.
-
-\item
-Although the \module{urllib} module contains (undocumented) routines
-to parse and unparse URL strings, the recommended interface for URL
-manipulation is in module \refmodule{urlparse}\refstmodindex{urlparse}.
-
-\end{itemize}
-
-
-\subsection{URLopener Objects \label{urlopener-objs}}
-\sectionauthor{Skip Montanaro}{skip@mojam.com}
-
-\class{URLopener} and \class{FancyURLopener} objects have the
-following attributes.
-
-\begin{methoddesc}[URLopener]{open}{fullurl\optional{, data}}
-Open \var{fullurl} using the appropriate protocol. This method sets
-up cache and proxy information, then calls the appropriate open method with
-its input arguments. If the scheme is not recognized,
-\method{open_unknown()} is called. The \var{data} argument
-has the same meaning as the \var{data} argument of \function{urlopen()}.
-\end{methoddesc}
-
-\begin{methoddesc}[URLopener]{open_unknown}{fullurl\optional{, data}}
-Overridable interface to open unknown URL types.
-\end{methoddesc}
-
-\begin{methoddesc}[URLopener]{retrieve}{url\optional{,
- filename\optional{,
- reporthook\optional{, data}}}}
-Retrieves the contents of \var{url} and places it in \var{filename}. The
-return value is a tuple consisting of a local filename and either a
-\class{mimetools.Message} object containing the response headers (for remote
-URLs) or \code{None} (for local URLs). The caller must then open and read the
-contents of \var{filename}. If \var{filename} is not given and the URL
-refers to a local file, the input filename is returned. If the URL is
-non-local and \var{filename} is not given, the filename is the output of
-\function{tempfile.mktemp()} with a suffix that matches the suffix of the last
-path component of the input URL. If \var{reporthook} is given, it must be
-a function accepting three numeric parameters. It will be called after each
-chunk of data is read from the network. \var{reporthook} is ignored for
-local URLs.
-
-If the \var{url} uses the \file{http:} scheme identifier, the optional
-\var{data} argument may be given to specify a \code{POST} request
-(normally the request type is \code{GET}). The \var{data} argument
-must in standard \mimetype{application/x-www-form-urlencoded} format;
-see the \function{urlencode()} function below.
-\end{methoddesc}
-
-\begin{memberdesc}[URLopener]{version}
-Variable that specifies the user agent of the opener object. To get
-\refmodule{urllib} to tell servers that it is a particular user agent,
-set this in a subclass as a class variable or in the constructor
-before calling the base constructor.
-\end{memberdesc}
-
-The \class{FancyURLopener} class offers one additional method that
-should be overloaded to provide the appropriate behavior:
-
-\begin{methoddesc}[FancyURLopener]{prompt_user_passwd}{host, realm}
-Return information needed to authenticate the user at the given host
-in the specified security realm. The return value should be a tuple,
-\code{(\var{user}, \var{password})}, which can be used for basic
-authentication.
-
-The implementation prompts for this information on the terminal; an
-application should override this method to use an appropriate
-interaction model in the local environment.
-\end{methoddesc}
-
-
-\subsection{Examples}
-\nodename{Urllib Examples}
-
-Here is an example session that uses the \samp{GET} method to retrieve
-a URL containing parameters:
-
-\begin{verbatim}
->>> import urllib
->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
->>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
->>> print f.read()
-\end{verbatim}
-
-The following example uses the \samp{POST} method instead:
-
-\begin{verbatim}
->>> import urllib
->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
->>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
->>> print f.read()
-\end{verbatim}
-
-The following example uses an explicitly specified HTTP proxy,
-overriding environment settings:
-
-\begin{verbatim}
->>> import urllib
->>> proxies = {'http': 'http://proxy.example.com:8080/'}
->>> opener = urllib.FancyURLopener(proxies)
->>> f = opener.open("http://www.python.org")
->>> f.read()
-\end{verbatim}
-
-The following example uses no proxies at all, overriding environment
-settings:
-
-\begin{verbatim}
->>> import urllib
->>> opener = urllib.FancyURLopener({})
->>> f = opener.open("http://www.python.org/")
->>> f.read()
-\end{verbatim}
diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex
deleted file mode 100644
index 9d2c382..0000000
--- a/Doc/lib/liburllib2.tex
+++ /dev/null
@@ -1,872 +0,0 @@
-\section{\module{urllib2} ---
- extensible library for opening URLs}
-
-\declaremodule{standard}{urllib2}
-\moduleauthor{Jeremy Hylton}{jhylton@users.sourceforge.net}
-\sectionauthor{Moshe Zadka}{moshez@users.sourceforge.net}
-
-\modulesynopsis{An extensible library for opening URLs using a variety of
- protocols}
-
-The \module{urllib2} module defines functions and classes which help
-in opening URLs (mostly HTTP) in a complex world --- basic and digest
-authentication, redirections, cookies and more.
-
-The \module{urllib2} module defines the following functions:
-
-\begin{funcdesc}{urlopen}{url\optional{, data}\optional{, timeout}}
-Open the URL \var{url}, which can be either a string or a \class{Request}
-object.
-
-\var{data} may be a string specifying additional data to send to the
-server, or \code{None} if no such data is needed.
-Currently HTTP requests are the only ones that use \var{data};
-the HTTP request will be a POST instead of a GET when the \var{data}
-parameter is provided. \var{data} should be a buffer in the standard
-\mimetype{application/x-www-form-urlencoded} format. The
-\function{urllib.urlencode()} function takes a mapping or sequence of
-2-tuples and returns a string in this format.
-
-The optional \var{timeout} parameter specifies a timeout in seconds for the
-connection attempt (if not specified, or passed as None, the global default
-timeout setting will be used). This actually only work for HTTP, HTTPS, FTP
-and FTPS connections.
-
-This function returns a file-like object with two additional methods:
-
-\begin{itemize}
- \item \method{geturl()} --- return the URL of the resource retrieved
- \item \method{info()} --- return the meta-information of the page, as
- a dictionary-like object
-\end{itemize}
-
-Raises \exception{URLError} on errors.
-
-Note that \code{None} may be returned if no handler handles the
-request (though the default installed global \class{OpenerDirector}
-uses \class{UnknownHandler} to ensure this never happens).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{funcdesc}
-
-\begin{funcdesc}{install_opener}{opener}
-Install an \class{OpenerDirector} instance as the default global
-opener. Installing an opener is only necessary if you want urlopen to
-use that opener; otherwise, simply call \method{OpenerDirector.open()}
-instead of \function{urlopen()}. The code does not check for a real
-\class{OpenerDirector}, and any class with the appropriate interface
-will work.
-\end{funcdesc}
-
-\begin{funcdesc}{build_opener}{\optional{handler, \moreargs}}
-Return an \class{OpenerDirector} instance, which chains the
-handlers in the order given. \var{handler}s can be either instances
-of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in
-which case it must be possible to call the constructor without
-any parameters). Instances of the following classes will be in
-front of the \var{handler}s, unless the \var{handler}s contain
-them, instances of them or subclasses of them:
-\class{ProxyHandler}, \class{UnknownHandler}, \class{HTTPHandler},
-\class{HTTPDefaultErrorHandler}, \class{HTTPRedirectHandler},
-\class{FTPHandler}, \class{FileHandler}, \class{HTTPErrorProcessor}.
-
-If the Python installation has SSL support (\function{socket.ssl()}
-exists), \class{HTTPSHandler} will also be added.
-
-Beginning in Python 2.3, a \class{BaseHandler} subclass may also
-change its \member{handler_order} member variable to modify its
-position in the handlers list.
-\end{funcdesc}
-
-
-The following exceptions are raised as appropriate:
-
-\begin{excdesc}{URLError}
-The handlers raise this exception (or derived exceptions) when they
-run into a problem. It is a subclass of \exception{IOError}.
-\end{excdesc}
-
-\begin{excdesc}{HTTPError}
-A subclass of \exception{URLError}, it can also function as a
-non-exceptional file-like return value (the same thing that
-\function{urlopen()} returns). This is useful when handling exotic
-HTTP errors, such as requests for authentication.
-\end{excdesc}
-
-
-The following classes are provided:
-
-\begin{classdesc}{Request}{url\optional{, data}\optional{, headers}
- \optional{, origin_req_host}\optional{, unverifiable}}
-This class is an abstraction of a URL request.
-
-\var{url} should be a string containing a valid URL.
-
-\var{data} may be a string specifying additional data to send to the
-server, or \code{None} if no such data is needed.
-Currently HTTP requests are the only ones that use \var{data};
-the HTTP request will be a POST instead of a GET when the \var{data}
-parameter is provided. \var{data} should be a buffer in the standard
-\mimetype{application/x-www-form-urlencoded} format. The
-\function{urllib.urlencode()} function takes a mapping or sequence of
-2-tuples and returns a string in this format.
-
-\var{headers} should be a dictionary, and will be treated as if
-\method{add_header()} was called with each key and value as arguments.
-
-The final two arguments are only of interest for correct handling of
-third-party HTTP cookies:
-
-\var{origin_req_host} should be the request-host of the origin
-transaction, as defined by \rfc{2965}. It defaults to
-\code{cookielib.request_host(self)}. This is the host name or IP
-address of the original request that was initiated by the user. For
-example, if the request is for an image in an HTML document, this
-should be the request-host of the request for the page containing the
-image.
-
-\var{unverifiable} should indicate whether the request is
-unverifiable, as defined by RFC 2965. It defaults to False. An
-unverifiable request is one whose URL the user did not have the option
-to approve. For example, if the request is for an image in an HTML
-document, and the user had no option to approve the automatic fetching
-of the image, this should be true.
-\end{classdesc}
-
-\begin{classdesc}{OpenerDirector}{}
-The \class{OpenerDirector} class opens URLs via \class{BaseHandler}s
-chained together. It manages the chaining of handlers, and recovery
-from errors.
-\end{classdesc}
-
-\begin{classdesc}{BaseHandler}{}
-This is the base class for all registered handlers --- and handles only
-the simple mechanics of registration.
-\end{classdesc}
-
-\begin{classdesc}{HTTPDefaultErrorHandler}{}
-A class which defines a default handler for HTTP error responses; all
-responses are turned into \exception{HTTPError} exceptions.
-\end{classdesc}
-
-\begin{classdesc}{HTTPRedirectHandler}{}
-A class to handle redirections.
-\end{classdesc}
-
-\begin{classdesc}{HTTPCookieProcessor}{\optional{cookiejar}}
-A class to handle HTTP Cookies.
-\end{classdesc}
-
-\begin{classdesc}{ProxyHandler}{\optional{proxies}}
-Cause requests to go through a proxy.
-If \var{proxies} is given, it must be a dictionary mapping
-protocol names to URLs of proxies.
-The default is to read the list of proxies from the environment
-variables \envvar{<protocol>_proxy}.
-\end{classdesc}
-
-\begin{classdesc}{HTTPPasswordMgr}{}
-Keep a database of
-\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})}
-mappings.
-\end{classdesc}
-
-\begin{classdesc}{HTTPPasswordMgrWithDefaultRealm}{}
-Keep a database of
-\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})} mappings.
-A realm of \code{None} is considered a catch-all realm, which is searched
-if no other realm fits.
-\end{classdesc}
-
-\begin{classdesc}{AbstractBasicAuthHandler}{\optional{password_mgr}}
-This is a mixin class that helps with HTTP authentication, both
-to the remote host and to a proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}}
-Handle authentication with the remote host.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}}
-Handle authentication with the proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}}
-This is a mixin class that helps with HTTP authentication, both
-to the remote host and to a proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}}
-Handle authentication with the remote host.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}}
-Handle authentication with the proxy.
-\var{password_mgr}, if given, should be something that is compatible
-with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
-for information on the interface that must be supported.
-\end{classdesc}
-
-\begin{classdesc}{HTTPHandler}{}
-A class to handle opening of HTTP URLs.
-\end{classdesc}
-
-\begin{classdesc}{HTTPSHandler}{}
-A class to handle opening of HTTPS URLs.
-\end{classdesc}
-
-\begin{classdesc}{FileHandler}{}
-Open local files.
-\end{classdesc}
-
-\begin{classdesc}{FTPHandler}{}
-Open FTP URLs.
-\end{classdesc}
-
-\begin{classdesc}{CacheFTPHandler}{}
-Open FTP URLs, keeping a cache of open FTP connections to minimize
-delays.
-\end{classdesc}
-
-\begin{classdesc}{UnknownHandler}{}
-A catch-all class to handle unknown URLs.
-\end{classdesc}
-
-
-\subsection{Request Objects \label{request-objects}}
-
-The following methods describe all of \class{Request}'s public interface,
-and so all must be overridden in subclasses.
-
-\begin{methoddesc}[Request]{add_data}{data}
-Set the \class{Request} data to \var{data}. This is ignored by all
-handlers except HTTP handlers --- and there it should be a byte
-string, and will change the request to be \code{POST} rather than
-\code{GET}.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_method}{}
-Return a string indicating the HTTP request method. This is only
-meaningful for HTTP requests, and currently always returns
-\code{'GET'} or \code{'POST'}.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{has_data}{}
-Return whether the instance has a non-\code{None} data.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_data}{}
-Return the instance's data.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{add_header}{key, val}
-Add another header to the request. Headers are currently ignored by
-all handlers except HTTP handlers, where they are added to the list
-of headers sent to the server. Note that there cannot be more than
-one header with the same name, and later calls will overwrite
-previous calls in case the \var{key} collides. Currently, this is
-no loss of HTTP functionality, since all headers which have meaning
-when used more than once have a (header-specific) way of gaining the
-same functionality using only one header.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{add_unredirected_header}{key, header}
-Add a header that will not be added to a redirected request.
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{has_header}{header}
-Return whether the instance has the named header (checks both regular
-and unredirected).
-\versionadded{2.4}
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_full_url}{}
-Return the URL given in the constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_type}{}
-Return the type of the URL --- also known as the scheme.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_host}{}
-Return the host to which a connection will be made.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_selector}{}
-Return the selector --- the part of the URL that is sent to
-the server.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{set_proxy}{host, type}
-Prepare the request by connecting to a proxy server. The \var{host}
-and \var{type} will replace those of the instance, and the instance's
-selector will be the original URL given in the constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{get_origin_req_host}{}
-Return the request-host of the origin transaction, as defined by
-\rfc{2965}. See the documentation for the \class{Request}
-constructor.
-\end{methoddesc}
-
-\begin{methoddesc}[Request]{is_unverifiable}{}
-Return whether the request is unverifiable, as defined by RFC 2965.
-See the documentation for the \class{Request} constructor.
-\end{methoddesc}
-
-
-\subsection{OpenerDirector Objects \label{opener-director-objects}}
-
-\class{OpenerDirector} instances have the following methods:
-
-\begin{methoddesc}[OpenerDirector]{add_handler}{handler}
-\var{handler} should be an instance of \class{BaseHandler}. The
-following methods are searched, and added to the possible chains (note
-that HTTP errors are a special case).
-
-\begin{itemize}
- \item \method{\var{protocol}_open()} ---
- signal that the handler knows how to open \var{protocol} URLs.
- \item \method{http_error_\var{type}()} ---
- signal that the handler knows how to handle HTTP errors with HTTP
- error code \var{type}.
- \item \method{\var{protocol}_error()} ---
- signal that the handler knows how to handle errors from
- (non-\code{http}) \var{protocol}.
- \item \method{\var{protocol}_request()} ---
- signal that the handler knows how to pre-process \var{protocol}
- requests.
- \item \method{\var{protocol}_response()} ---
- signal that the handler knows how to post-process \var{protocol}
- responses.
-\end{itemize}
-\end{methoddesc}
-
-\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}{\optional{, timeout}}}
-Open the given \var{url} (which can be a request object or a string),
-optionally passing the given \var{data}.
-Arguments, return values and exceptions raised are the same as those
-of \function{urlopen()} (which simply calls the \method{open()} method
-on the currently installed global \class{OpenerDirector}). The optional
-\var{timeout} parameter specifies a timeout in seconds for the connection
-attempt (if not specified, or passed as None, the global default timeout
-setting will be used; this actually only work for HTTP, HTTPS, FTP
-and FTPS connections).
-
-\versionchanged[\var{timeout} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
- arg\optional{, \moreargs}}}
-Handle an error of the given protocol. This will call the registered
-error handlers for the given protocol with the given arguments (which
-are protocol specific). The HTTP protocol is a special case which
-uses the HTTP response code to determine the specific error handler;
-refer to the \method{http_error_*()} methods of the handler classes.
-
-Return values and exceptions raised are the same as those
-of \function{urlopen()}.
-\end{methoddesc}
-
-OpenerDirector objects open URLs in three stages:
-
-The order in which these methods are called within each stage is
-determined by sorting the handler instances.
-
-\begin{enumerate}
- \item Every handler with a method named like
- \method{\var{protocol}_request()} has that method called to
- pre-process the request.
-
- \item Handlers with a method named like
- \method{\var{protocol}_open()} are called to handle the request.
- This stage ends when a handler either returns a
- non-\constant{None} value (ie. a response), or raises an exception
- (usually \exception{URLError}). Exceptions are allowed to propagate.
-
- In fact, the above algorithm is first tried for methods named
- \method{default_open}. If all such methods return
- \constant{None}, the algorithm is repeated for methods named like
- \method{\var{protocol}_open()}. If all such methods return
- \constant{None}, the algorithm is repeated for methods named
- \method{unknown_open()}.
-
- Note that the implementation of these methods may involve calls of
- the parent \class{OpenerDirector} instance's \method{.open()} and
- \method{.error()} methods.
-
- \item Every handler with a method named like
- \method{\var{protocol}_response()} has that method called to
- post-process the response.
-
-\end{enumerate}
-
-\subsection{BaseHandler Objects \label{base-handler-objects}}
-
-\class{BaseHandler} objects provide a couple of methods that are
-directly useful, and others that are meant to be used by derived
-classes. These are intended for direct use:
-
-\begin{methoddesc}[BaseHandler]{add_parent}{director}
-Add a director as parent.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseHandler]{close}{}
-Remove any parents.
-\end{methoddesc}
-
-The following members and methods should only be used by classes
-derived from \class{BaseHandler}. \note{The convention has been
-adopted that subclasses defining \method{\var{protocol}_request()} or
-\method{\var{protocol}_response()} methods are named
-\class{*Processor}; all others are named \class{*Handler}.}
-
-
-\begin{memberdesc}[BaseHandler]{parent}
-A valid \class{OpenerDirector}, which can be used to open using a
-different protocol, or handle errors.
-\end{memberdesc}
-
-\begin{methoddesc}[BaseHandler]{default_open}{req}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to catch all URLs.
-
-This method, if implemented, will be called by the parent
-\class{OpenerDirector}. It should return a file-like object as
-described in the return value of the \method{open()} of
-\class{OpenerDirector}, or \code{None}. It should raise
-\exception{URLError}, unless a truly exceptional thing happens (for
-example, \exception{MemoryError} should not be mapped to
-\exception{URLError}).
-
-This method will be called before any protocol-specific open method.
-\end{methoddesc}
-
-\begin{methoddescni}[BaseHandler]{\var{protocol}_open}{req}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to handle URLs with the given
-protocol.
-
-This method, if defined, will be called by the parent
-\class{OpenerDirector}. Return values should be the same as for
-\method{default_open()}.
-\end{methoddescni}
-
-\begin{methoddesc}[BaseHandler]{unknown_open}{req}
-This method is \var{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to catch all URLs with no
-specific registered handler to open it.
-
-This method, if implemented, will be called by the \member{parent}
-\class{OpenerDirector}. Return values should be the same as for
-\method{default_open()}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseHandler]{http_error_default}{req, fp, code, msg, hdrs}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should override it if they intend to provide a catch-all
-for otherwise unhandled HTTP errors. It will be called automatically
-by the \class{OpenerDirector} getting the error, and should not
-normally be called in other circumstances.
-
-\var{req} will be a \class{Request} object, \var{fp} will be a
-file-like object with the HTTP error body, \var{code} will be the
-three-digit code of the error, \var{msg} will be the user-visible
-explanation of the code and \var{hdrs} will be a mapping object with
-the headers of the error.
-
-Return values and exceptions raised should be the same as those
-of \function{urlopen()}.
-\end{methoddesc}
-
-\begin{methoddesc}[BaseHandler]{http_error_\var{nnn}}{req, fp, code, msg, hdrs}
-\var{nnn} should be a three-digit HTTP error code. This method is
-also not defined in \class{BaseHandler}, but will be called, if it
-exists, on an instance of a subclass, when an HTTP error with code
-\var{nnn} occurs.
-
-Subclasses should override this method to handle specific HTTP
-errors.
-
-Arguments, return values and exceptions raised should be the same as
-for \method{http_error_default()}.
-\end{methoddesc}
-
-\begin{methoddescni}[BaseHandler]{\var{protocol}_request}{req}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to pre-process requests of
-the given protocol.
-
-This method, if defined, will be called by the parent
-\class{OpenerDirector}. \var{req} will be a \class{Request} object.
-The return value should be a \class{Request} object.
-\end{methoddescni}
-
-\begin{methoddescni}[BaseHandler]{\var{protocol}_response}{req, response}
-This method is \emph{not} defined in \class{BaseHandler}, but
-subclasses should define it if they want to post-process responses of
-the given protocol.
-
-This method, if defined, will be called by the parent
-\class{OpenerDirector}. \var{req} will be a \class{Request} object.
-\var{response} will be an object implementing the same interface as
-the return value of \function{urlopen()}. The return value should
-implement the same interface as the return value of
-\function{urlopen()}.
-\end{methoddescni}
-
-\subsection{HTTPRedirectHandler Objects \label{http-redirect-handler}}
-
-\note{Some HTTP redirections require action from this module's client
- code. If this is the case, \exception{HTTPError} is raised. See
- \rfc{2616} for details of the precise meanings of the various
- redirection codes.}
-
-\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req,
- fp, code, msg, hdrs}
-Return a \class{Request} or \code{None} in response to a redirect.
-This is called by the default implementations of the
-\method{http_error_30*()} methods when a redirection is received from
-the server. If a redirection should take place, return a new
-\class{Request} to allow \method{http_error_30*()} to perform the
-redirect. Otherwise, raise \exception{HTTPError} if no other handler
-should try to handle this URL, or return \code{None} if you can't but
-another handler might.
-
-\begin{notice}
- The default implementation of this method does not strictly
- follow \rfc{2616}, which says that 301 and 302 responses to \code{POST}
- requests must not be automatically redirected without confirmation by
- the user. In reality, browsers do allow automatic redirection of
- these responses, changing the POST to a \code{GET}, and the default
- implementation reproduces this behavior.
-\end{notice}
-\end{methoddesc}
-
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_301}{req,
- fp, code, msg, hdrs}
-Redirect to the \code{Location:} URL. This method is called by
-the parent \class{OpenerDirector} when getting an HTTP
-`moved permanently' response.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_302}{req,
- fp, code, msg, hdrs}
-The same as \method{http_error_301()}, but called for the
-`found' response.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_303}{req,
- fp, code, msg, hdrs}
-The same as \method{http_error_301()}, but called for the
-`see other' response.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPRedirectHandler]{http_error_307}{req,
- fp, code, msg, hdrs}
-The same as \method{http_error_301()}, but called for the
-`temporary redirect' response.
-\end{methoddesc}
-
-
-\subsection{HTTPCookieProcessor Objects \label{http-cookie-processor}}
-
-\versionadded{2.4}
-
-\class{HTTPCookieProcessor} instances have one attribute:
-
-\begin{memberdesc}[HTTPCookieProcessor]{cookiejar}
-The \class{cookielib.CookieJar} in which cookies are stored.
-\end{memberdesc}
-
-
-\subsection{ProxyHandler Objects \label{proxy-handler}}
-
-\begin{methoddescni}[ProxyHandler]{\var{protocol}_open}{request}
-The \class{ProxyHandler} will have a method
-\method{\var{protocol}_open()} for every \var{protocol} which has a
-proxy in the \var{proxies} dictionary given in the constructor. The
-method will modify requests to go through the proxy, by calling
-\code{request.set_proxy()}, and call the next handler in the chain to
-actually execute the protocol.
-\end{methoddescni}
-
-
-\subsection{HTTPPasswordMgr Objects \label{http-password-mgr}}
-
-These methods are available on \class{HTTPPasswordMgr} and
-\class{HTTPPasswordMgrWithDefaultRealm} objects.
-
-\begin{methoddesc}[HTTPPasswordMgr]{add_password}{realm, uri, user, passwd}
-\var{uri} can be either a single URI, or a sequence of URIs. \var{realm},
-\var{user} and \var{passwd} must be strings. This causes
-\code{(\var{user}, \var{passwd})} to be used as authentication tokens
-when authentication for \var{realm} and a super-URI of any of the
-given URIs is given.
-\end{methoddesc}
-
-\begin{methoddesc}[HTTPPasswordMgr]{find_user_password}{realm, authuri}
-Get user/password for given realm and URI, if any. This method will
-return \code{(None, None)} if there is no matching user/password.
-
-For \class{HTTPPasswordMgrWithDefaultRealm} objects, the realm
-\code{None} will be searched if the given \var{realm} has no matching
-user/password.
-\end{methoddesc}
-
-
-\subsection{AbstractBasicAuthHandler Objects
- \label{abstract-basic-auth-handler}}
-
-\begin{methoddesc}[AbstractBasicAuthHandler]{http_error_auth_reqed}
- {authreq, host, req, headers}
-Handle an authentication request by getting a user/password pair, and
-re-trying the request. \var{authreq} should be the name of the header
-where the information about the realm is included in the request,
-\var{host} specifies the URL and path to authenticate for, \var{req}
-should be the (failed) \class{Request} object, and \var{headers}
-should be the error headers.
-
-\var{host} is either an authority (e.g. \code{"python.org"}) or a URL
-containing an authority component (e.g. \code{"http://python.org/"}).
-In either case, the authority must not contain a userinfo component
-(so, \code{"python.org"} and \code{"python.org:80"} are fine,
-\code{"joe:password@python.org"} is not).
-\end{methoddesc}
-
-
-\subsection{HTTPBasicAuthHandler Objects
- \label{http-basic-auth-handler}}
-
-\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{ProxyBasicAuthHandler Objects
- \label{proxy-basic-auth-handler}}
-
-\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{AbstractDigestAuthHandler Objects
- \label{abstract-digest-auth-handler}}
-
-\begin{methoddesc}[AbstractDigestAuthHandler]{http_error_auth_reqed}
- {authreq, host, req, headers}
-\var{authreq} should be the name of the header where the information about
-the realm is included in the request, \var{host} should be the host to
-authenticate to, \var{req} should be the (failed) \class{Request}
-object, and \var{headers} should be the error headers.
-\end{methoddesc}
-
-
-\subsection{HTTPDigestAuthHandler Objects
- \label{http-digest-auth-handler}}
-
-\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{ProxyDigestAuthHandler Objects
- \label{proxy-digest-auth-handler}}
-
-\begin{methoddesc}[ProxyDigestAuthHandler]{http_error_407}{req, fp, code,
- msg, hdrs}
-Retry the request with authentication information, if available.
-\end{methoddesc}
-
-
-\subsection{HTTPHandler Objects \label{http-handler-objects}}
-
-\begin{methoddesc}[HTTPHandler]{http_open}{req}
-Send an HTTP request, which can be either GET or POST, depending on
-\code{\var{req}.has_data()}.
-\end{methoddesc}
-
-
-\subsection{HTTPSHandler Objects \label{https-handler-objects}}
-
-\begin{methoddesc}[HTTPSHandler]{https_open}{req}
-Send an HTTPS request, which can be either GET or POST, depending on
-\code{\var{req}.has_data()}.
-\end{methoddesc}
-
-
-\subsection{FileHandler Objects \label{file-handler-objects}}
-
-\begin{methoddesc}[FileHandler]{file_open}{req}
-Open the file locally, if there is no host name, or
-the host name is \code{'localhost'}. Change the
-protocol to \code{ftp} otherwise, and retry opening
-it using \member{parent}.
-\end{methoddesc}
-
-
-\subsection{FTPHandler Objects \label{ftp-handler-objects}}
-
-\begin{methoddesc}[FTPHandler]{ftp_open}{req}
-Open the FTP file indicated by \var{req}.
-The login is always done with empty username and password.
-\end{methoddesc}
-
-
-\subsection{CacheFTPHandler Objects \label{cacheftp-handler-objects}}
-
-\class{CacheFTPHandler} objects are \class{FTPHandler} objects with
-the following additional methods:
-
-\begin{methoddesc}[CacheFTPHandler]{setTimeout}{t}
-Set timeout of connections to \var{t} seconds.
-\end{methoddesc}
-
-\begin{methoddesc}[CacheFTPHandler]{setMaxConns}{m}
-Set maximum number of cached connections to \var{m}.
-\end{methoddesc}
-
-
-\subsection{UnknownHandler Objects \label{unknown-handler-objects}}
-
-\begin{methoddesc}[UnknownHandler]{unknown_open}{}
-Raise a \exception{URLError} exception.
-\end{methoddesc}
-
-
-\subsection{HTTPErrorProcessor Objects \label{http-error-processor-objects}}
-
-\versionadded{2.4}
-
-\begin{methoddesc}[HTTPErrorProcessor]{unknown_open}{}
-Process HTTP error responses.
-
-For 200 error codes, the response object is returned immediately.
-
-For non-200 error codes, this simply passes the job on to the
-\method{\var{protocol}_error_\var{code}()} handler methods, via
-\method{OpenerDirector.error()}. Eventually,
-\class{urllib2.HTTPDefaultErrorHandler} will raise an
-\exception{HTTPError} if no other handler handles the error.
-\end{methoddesc}
-
-
-\subsection{Examples \label{urllib2-examples}}
-
-This example gets the python.org main page and displays the first 100
-bytes of it:
-
-\begin{verbatim}
->>> import urllib2
->>> f = urllib2.urlopen('http://www.python.org/')
->>> print f.read(100)
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<?xml-stylesheet href="./css/ht2html
-\end{verbatim}
-
-Here we are sending a data-stream to the stdin of a CGI and reading
-the data it returns to us. Note that this example will only work when the
-Python installation supports SSL.
-
-\begin{verbatim}
->>> import urllib2
->>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
-... data='This data is passed to stdin of the CGI')
->>> f = urllib2.urlopen(req)
->>> print f.read()
-Got Data: "This data is passed to stdin of the CGI"
-\end{verbatim}
-
-The code for the sample CGI used in the above example is:
-
-\begin{verbatim}
-#!/usr/bin/env python
-import sys
-data = sys.stdin.read()
-print 'Content-type: text-plain\n\nGot Data: "%s"' % data
-\end{verbatim}
-
-
-Use of Basic HTTP Authentication:
-
-\begin{verbatim}
-import urllib2
-# Create an OpenerDirector with support for Basic HTTP Authentication...
-auth_handler = urllib2.HTTPBasicAuthHandler()
-auth_handler.add_password(realm='PDQ Application',
- uri='https://mahler:8092/site-updates.py',
- user='klem',
- passwd='kadidd!ehopper')
-opener = urllib2.build_opener(auth_handler)
-# ...and install it globally so it can be used with urlopen.
-urllib2.install_opener(opener)
-urllib2.urlopen('http://www.example.com/login.html')
-\end{verbatim}
-
-\function{build_opener()} provides many handlers by default, including a
-\class{ProxyHandler}. By default, \class{ProxyHandler} uses the
-environment variables named \code{<scheme>_proxy}, where \code{<scheme>}
-is the URL scheme involved. For example, the \envvar{http_proxy}
-environment variable is read to obtain the HTTP proxy's URL.
-
-This example replaces the default \class{ProxyHandler} with one that uses
-programatically-supplied proxy URLs, and adds proxy authorization support
-with \class{ProxyBasicAuthHandler}.
-
-\begin{verbatim}
-proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'})
-proxy_auth_handler = urllib2.HTTPBasicAuthHandler()
-proxy_auth_handler.add_password('realm', 'host', 'username', 'password')
-
-opener = build_opener(proxy_handler, proxy_auth_handler)
-# This time, rather than install the OpenerDirector, we use it directly:
-opener.open('http://www.example.com/login.html')
-\end{verbatim}
-
-
-Adding HTTP headers:
-
-Use the \var{headers} argument to the \class{Request} constructor, or:
-
-\begin{verbatim}
-import urllib2
-req = urllib2.Request('http://www.example.com/')
-req.add_header('Referer', 'http://www.python.org/')
-r = urllib2.urlopen(req)
-\end{verbatim}
-
-\class{OpenerDirector} automatically adds a \mailheader{User-Agent}
-header to every \class{Request}. To change this:
-
-\begin{verbatim}
-import urllib2
-opener = urllib2.build_opener()
-opener.addheaders = [('User-agent', 'Mozilla/5.0')]
-opener.open('http://www.example.com/')
-\end{verbatim}
-
-Also, remember that a few standard headers
-(\mailheader{Content-Length}, \mailheader{Content-Type} and
-\mailheader{Host}) are added when the \class{Request} is passed to
-\function{urlopen()} (or \method{OpenerDirector.open()}).
diff --git a/Doc/lib/liburlparse.tex b/Doc/lib/liburlparse.tex
deleted file mode 100644
index 16f38a0..0000000
--- a/Doc/lib/liburlparse.tex
+++ /dev/null
@@ -1,253 +0,0 @@
-\section{\module{urlparse} ---
- Parse URLs into components}
-\declaremodule{standard}{urlparse}
-
-\modulesynopsis{Parse URLs into components.}
-
-\index{WWW}
-\index{World Wide Web}
-\index{URL}
-\indexii{URL}{parsing}
-\indexii{relative}{URL}
-
-
-This module defines a standard interface to break Uniform Resource
-Locator (URL) strings up in components (addressing scheme, network
-location, path etc.), to combine the components back into a URL
-string, and to convert a ``relative URL'' to an absolute URL given a
-``base URL.''
-
-The module has been designed to match the Internet RFC on Relative
-Uniform Resource Locators (and discovered a bug in an earlier
-draft!). It supports the following URL schemes:
-\code{file}, \code{ftp}, \code{gopher}, \code{hdl}, \code{http},
-\code{https}, \code{imap}, \code{mailto}, \code{mms}, \code{news},
-\code{nntp}, \code{prospero}, \code{rsync}, \code{rtsp}, \code{rtspu},
-\code{sftp}, \code{shttp}, \code{sip}, \code{sips}, \code{snews}, \code{svn},
-\code{svn+ssh}, \code{telnet}, \code{wais}.
-
-\versionadded[Support for the \code{sftp} and \code{sips} schemes]{2.5}
-
-The \module{urlparse} module defines the following functions:
-
-\begin{funcdesc}{urlparse}{urlstring\optional{,
- default_scheme\optional{, allow_fragments}}}
-Parse a URL into six components, returning a 6-tuple. This
-corresponds to the general structure of a URL:
-\code{\var{scheme}://\var{netloc}/\var{path};\var{parameters}?\var{query}\#\var{fragment}}.
-Each tuple item is a string, possibly empty.
-The components are not broken up in smaller parts (for example, the network
-location is a single string), and \% escapes are not expanded.
-The delimiters as shown above are not part of the result,
-except for a leading slash in the \var{path} component, which is
-retained if present. For example:
-
-\begin{verbatim}
->>> from urlparse import urlparse
->>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
->>> o
-('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
->>> o.scheme
-'http'
->>> o.port
-80
->>> o.geturl()
-'http://www.cwi.nl:80/%7Eguido/Python.html'
-\end{verbatim}
-
-If the \var{default_scheme} argument is specified, it gives the
-default addressing scheme, to be used only if the URL does not
-specify one. The default value for this argument is the empty string.
-
-If the \var{allow_fragments} argument is false, fragment identifiers
-are not allowed, even if the URL's addressing scheme normally does
-support them. The default value for this argument is \constant{True}.
-
-The return value is actually an instance of a subclass of
-\pytype{tuple}. This class has the following additional read-only
-convenience attributes:
-
-\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present}
- \lineiv{scheme} {0} {URL scheme specifier} {empty string}
- \lineiv{netloc} {1} {Network location part} {empty string}
- \lineiv{path} {2} {Hierarchical path} {empty string}
- \lineiv{params} {3} {Parameters for last path element} {empty string}
- \lineiv{query} {4} {Query component} {empty string}
- \lineiv{fragment}{5} {Fragment identifier} {empty string}
- \lineiv{username}{ } {User name} {\constant{None}}
- \lineiv{password}{ } {Password} {\constant{None}}
- \lineiv{hostname}{ } {Host name (lower case)} {\constant{None}}
- \lineiv{port} { } {Port number as integer, if present} {\constant{None}}
-\end{tableiv}
-
-See section~\ref{urlparse-result-object}, ``Results of
-\function{urlparse()} and \function{urlsplit()},'' for more
-information on the result object.
-
-\versionchanged[Added attributes to return value]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{urlunparse}{parts}
-Construct a URL from a tuple as returned by \code{urlparse()}.
-The \var{parts} argument can be any six-item iterable.
-This may result in a slightly different, but equivalent URL, if the
-URL that was parsed originally had unnecessary delimiters (for example,
-a ? with an empty query; the RFC states that these are equivalent).
-\end{funcdesc}
-
-\begin{funcdesc}{urlsplit}{urlstring\optional{,
- default_scheme\optional{, allow_fragments}}}
-This is similar to \function{urlparse()}, but does not split the
-params from the URL. This should generally be used instead of
-\function{urlparse()} if the more recent URL syntax allowing
-parameters to be applied to each segment of the \var{path} portion of
-the URL (see \rfc{2396}) is wanted. A separate function is needed to
-separate the path segments and parameters. This function returns a
-5-tuple: (addressing scheme, network location, path, query, fragment
-identifier).
-
-The return value is actually an instance of a subclass of
-\pytype{tuple}. This class has the following additional read-only
-convenience attributes:
-
-\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present}
- \lineiv{scheme} {0} {URL scheme specifier} {empty string}
- \lineiv{netloc} {1} {Network location part} {empty string}
- \lineiv{path} {2} {Hierarchical path} {empty string}
- \lineiv{query} {3} {Query component} {empty string}
- \lineiv{fragment} {4} {Fragment identifier} {empty string}
- \lineiv{username} { } {User name} {\constant{None}}
- \lineiv{password} { } {Password} {\constant{None}}
- \lineiv{hostname} { } {Host name (lower case)} {\constant{None}}
- \lineiv{port} { } {Port number as integer, if present} {\constant{None}}
-\end{tableiv}
-
-See section~\ref{urlparse-result-object}, ``Results of
-\function{urlparse()} and \function{urlsplit()},'' for more
-information on the result object.
-
-\versionadded{2.2}
-\versionchanged[Added attributes to return value]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{urlunsplit}{parts}
-Combine the elements of a tuple as returned by \function{urlsplit()}
-into a complete URL as a string.
-The \var{parts} argument can be any five-item iterable.
-This may result in a slightly different, but equivalent URL, if the
-URL that was parsed originally had unnecessary delimiters (for example,
-a ? with an empty query; the RFC states that these are equivalent).
-\versionadded{2.2}
-\end{funcdesc}
-
-\begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}}
-Construct a full (``absolute'') URL by combining a ``base URL''
-(\var{base}) with another URL (\var{url}). Informally, this
-uses components of the base URL, in particular the addressing scheme,
-the network location and (part of) the path, to provide missing
-components in the relative URL. For example:
-
-\begin{verbatim}
->>> from urlparse import urljoin
->>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
-'http://www.cwi.nl/%7Eguido/FAQ.html'
-\end{verbatim}
-
-The \var{allow_fragments} argument has the same meaning and default as
-for \function{urlparse()}.
-
-\note{If \var{url} is an absolute URL (that is, starting with \code{//}
- or \code{scheme://}), the \var{url}'s host name and/or scheme
- will be present in the result. For example:}
-
-\begin{verbatim}
->>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
-... '//www.python.org/%7Eguido')
-'http://www.python.org/%7Eguido'
-\end{verbatim}
-
-If you do not want that behavior, preprocess
-the \var{url} with \function{urlsplit()} and \function{urlunsplit()},
-removing possible \emph{scheme} and \emph{netloc} parts.
-\end{funcdesc}
-
-\begin{funcdesc}{urldefrag}{url}
-If \var{url} contains a fragment identifier, returns a modified
-version of \var{url} with no fragment identifier, and the fragment
-identifier as a separate string. If there is no fragment identifier
-in \var{url}, returns \var{url} unmodified and an empty string.
-\end{funcdesc}
-
-
-\begin{seealso}
- \seerfc{1738}{Uniform Resource Locators (URL)}{
- This specifies the formal syntax and semantics of absolute
- URLs.}
- \seerfc{1808}{Relative Uniform Resource Locators}{
- This Request For Comments includes the rules for joining an
- absolute and a relative URL, including a fair number of
- ``Abnormal Examples'' which govern the treatment of border
- cases.}
- \seerfc{2396}{Uniform Resource Identifiers (URI): Generic Syntax}{
- Document describing the generic syntactic requirements for
- both Uniform Resource Names (URNs) and Uniform Resource
- Locators (URLs).}
-\end{seealso}
-
-
-\subsection{Results of \function{urlparse()} and \function{urlsplit()}
- \label{urlparse-result-object}}
-
-The result objects from the \function{urlparse()} and
-\function{urlsplit()} functions are subclasses of the \pytype{tuple}
-type. These subclasses add the attributes described in those
-functions, as well as provide an additional method:
-
-\begin{methoddesc}[ParseResult]{geturl}{}
- Return the re-combined version of the original URL as a string.
- This may differ from the original URL in that the scheme will always
- be normalized to lower case and empty components may be dropped.
- Specifically, empty parameters, queries, and fragment identifiers
- will be removed.
-
- The result of this method is a fixpoint if passed back through the
- original parsing function:
-
-\begin{verbatim}
->>> import urlparse
->>> url = 'HTTP://www.Python.org/doc/#'
-
->>> r1 = urlparse.urlsplit(url)
->>> r1.geturl()
-'http://www.Python.org/doc/'
-
->>> r2 = urlparse.urlsplit(r1.geturl())
->>> r2.geturl()
-'http://www.Python.org/doc/'
-\end{verbatim}
-
-\versionadded{2.5}
-\end{methoddesc}
-
-The following classes provide the implementations of the parse results::
-
-\begin{classdesc*}{BaseResult}
- Base class for the concrete result classes. This provides most of
- the attribute definitions. It does not provide a \method{geturl()}
- method. It is derived from \class{tuple}, but does not override the
- \method{__init__()} or \method{__new__()} methods.
-\end{classdesc*}
-
-
-\begin{classdesc}{ParseResult}{scheme, netloc, path, params, query, fragment}
- Concrete class for \function{urlparse()} results. The
- \method{__new__()} method is overridden to support checking that the
- right number of arguments are passed.
-\end{classdesc}
-
-
-\begin{classdesc}{SplitResult}{scheme, netloc, path, query, fragment}
- Concrete class for \function{urlsplit()} results. The
- \method{__new__()} method is overridden to support checking that the
- right number of arguments are passed.
-\end{classdesc}
diff --git a/Doc/lib/libuser.tex b/Doc/lib/libuser.tex
deleted file mode 100644
index 6dd1546..0000000
--- a/Doc/lib/libuser.tex
+++ /dev/null
@@ -1,71 +0,0 @@
-\section{\module{user} ---
- User-specific configuration hook}
-
-\declaremodule{standard}{user}
-\modulesynopsis{A standard way to reference user-specific modules.}
-
-
-\indexii{.pythonrc.py}{file}
-\indexiii{user}{configuration}{file}
-
-As a policy, Python doesn't run user-specified code on startup of
-Python programs. (Only interactive sessions execute the script
-specified in the \envvar{PYTHONSTARTUP} environment variable if it
-exists).
-
-However, some programs or sites may find it convenient to allow users
-to have a standard customization file, which gets run when a program
-requests it. This module implements such a mechanism. A program
-that wishes to use the mechanism must execute the statement
-
-\begin{verbatim}
-import user
-\end{verbatim}
-
-The \module{user} module looks for a file \file{.pythonrc.py} in the user's
-home directory and if it can be opened, executes it (using
-\function{exec()}\bifuncindex{exec}) in its own (the
-module \module{user}'s) global namespace. Errors during this phase
-are not caught; that's up to the program that imports the
-\module{user} module, if it wishes. The home directory is assumed to
-be named by the \envvar{HOME} environment variable; if this is not set,
-the current directory is used.
-
-The user's \file{.pythonrc.py} could conceivably test for
-\code{sys.version} if it wishes to do different things depending on
-the Python version.
-
-A warning to users: be very conservative in what you place in your
-\file{.pythonrc.py} file. Since you don't know which programs will
-use it, changing the behavior of standard modules or functions is
-generally not a good idea.
-
-A suggestion for programmers who wish to use this mechanism: a simple
-way to let users specify options for your package is to have them
-define variables in their \file{.pythonrc.py} file that you test in
-your module. For example, a module \module{spam} that has a verbosity
-level can look for a variable \code{user.spam_verbose}, as follows:
-
-\begin{verbatim}
-import user
-
-verbose = bool(getattr(user, "spam_verbose", 0))
-\end{verbatim}
-
-(The three-argument form of \function{getattr()} is used in case
-the user has not defined \code{spam_verbose} in their
-\file{.pythonrc.py} file.)
-
-Programs with extensive customization needs are better off reading a
-program-specific customization file.
-
-Programs with security or privacy concerns should \emph{not} import
-this module; a user can easily break into a program by placing
-arbitrary code in the \file{.pythonrc.py} file.
-
-Modules for general use should \emph{not} import this module; it may
-interfere with the operation of the importing program.
-
-\begin{seealso}
- \seemodule{site}{Site-wide customization mechanism.}
-\end{seealso}
diff --git a/Doc/lib/libuserdict.tex b/Doc/lib/libuserdict.tex
deleted file mode 100644
index 0bb57c8..0000000
--- a/Doc/lib/libuserdict.tex
+++ /dev/null
@@ -1,181 +0,0 @@
-\section{\module{UserDict} ---
- Class wrapper for dictionary objects}
-
-\declaremodule{standard}{UserDict}
-\modulesynopsis{Class wrapper for dictionary objects.}
-
-
-The module defines a mixin, \class{DictMixin}, defining all dictionary
-methods for classes that already have a minimum mapping interface. This
-greatly simplifies writing classes that need to be substitutable for
-dictionaries (such as the shelve module).
-
-This also module defines a class, \class{UserDict}, that acts as a wrapper
-around dictionary objects. The need for this class has been largely
-supplanted by the ability to subclass directly from \class{dict} (a feature
-that became available starting with Python version 2.2). Prior to the
-introduction of \class{dict}, the \class{UserDict} class was used to
-create dictionary-like sub-classes that obtained new behaviors by overriding
-existing methods or adding new ones.
-
-The \module{UserDict} module defines the \class{UserDict} class
-and \class{DictMixin}:
-
-\begin{classdesc}{UserDict}{\optional{initialdata}}
-Class that simulates a dictionary. The instance's contents are kept
-in a regular dictionary, which is accessible via the \member{data}
-attribute of \class{UserDict} instances. If \var{initialdata} is
-provided, \member{data} is initialized with its contents; note that a
-reference to \var{initialdata} will not be kept, allowing it be used
-for other purposes. \note{For backward compatibility, instances of
-\class{UserDict} are not iterable.}
-\end{classdesc}
-
-\begin{classdesc}{IterableUserDict}{\optional{initialdata}}
-Subclass of \class{UserDict} that supports direct iteration (e.g.
-\code{for key in myDict}).
-\end{classdesc}
-
-In addition to supporting the methods and operations of mappings (see
-section \ref{typesmapping}), \class{UserDict} and
-\class{IterableUserDict} instances provide the following attribute:
-
-\begin{memberdesc}{data}
-A real dictionary used to store the contents of the \class{UserDict}
-class.
-\end{memberdesc}
-
-\begin{classdesc}{DictMixin}{}
-Mixin defining all dictionary methods for classes that already have
-a minimum dictionary interface including \method{__getitem__()},
-\method{__setitem__()}, \method{__delitem__()}, and \method{keys()}.
-
-This mixin should be used as a superclass. Adding each of the
-above methods adds progressively more functionality. For instance,
-defining all but \method{__delitem__} will preclude only \method{pop}
-and \method{popitem} from the full interface.
-
-In addition to the four base methods, progressively more efficiency
-comes with defining \method{__contains__()}, \method{__iter__()}, and
-\method{iteritems()}.
-
-Since the mixin has no knowledge of the subclass constructor, it
-does not define \method{__init__()} or \method{copy()}.
-\end{classdesc}
-
-
-\section{\module{UserList} ---
- Class wrapper for list objects}
-
-\declaremodule{standard}{UserList}
-\modulesynopsis{Class wrapper for list objects.}
-
-
-\note{This module is available for backward compatibility only. If
-you are writing code that does not need to work with versions of
-Python earlier than Python 2.2, please consider subclassing directly
-from the built-in \class{list} type.}
-
-This module defines a class that acts as a wrapper around
-list objects. It is a useful base class for
-your own list-like classes, which can inherit from
-them and override existing methods or add new ones. In this way one
-can add new behaviors to lists.
-
-The \module{UserList} module defines the \class{UserList} class:
-
-\begin{classdesc}{UserList}{\optional{list}}
-Class that simulates a list. The instance's
-contents are kept in a regular list, which is accessible via the
-\member{data} attribute of \class{UserList} instances. The instance's
-contents are initially set to a copy of \var{list}, defaulting to the
-empty list \code{[]}. \var{list} can be either a regular Python list,
-or an instance of \class{UserList} (or a subclass).
-\end{classdesc}
-
-In addition to supporting the methods and operations of mutable
-sequences (see section \ref{typesseq}), \class{UserList} instances
-provide the following attribute:
-
-\begin{memberdesc}{data}
-A real Python list object used to store the contents of the
-\class{UserList} class.
-\end{memberdesc}
-
-\strong{Subclassing requirements:}
-Subclasses of \class{UserList} are expect to offer a constructor which
-can be called with either no arguments or one argument. List
-operations which return a new sequence attempt to create an instance
-of the actual implementation class. To do so, it assumes that the
-constructor can be called with a single parameter, which is a sequence
-object used as a data source.
-
-If a derived class does not wish to comply with this requirement, all
-of the special methods supported by this class will need to be
-overridden; please consult the sources for information about the
-methods which need to be provided in that case.
-
-\versionchanged[Python versions 1.5.2 and 1.6 also required that the
- constructor be callable with no parameters, and offer
- a mutable \member{data} attribute. Earlier versions
- of Python did not attempt to create instances of the
- derived class]{2.0}
-
-
-\section{\module{UserString} ---
- Class wrapper for string objects}
-
-\declaremodule{standard}{UserString}
-\modulesynopsis{Class wrapper for string objects.}
-\moduleauthor{Peter Funk}{pf@artcom-gmbh.de}
-\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
-
-\note{This \class{UserString} class from this module is available for
-backward compatibility only. If you are writing code that does not
-need to work with versions of Python earlier than Python 2.2, please
-consider subclassing directly from the built-in \class{str} type
-instead of using \class{UserString} (there is no built-in equivalent
-to \class{MutableString}).}
-
-This module defines a class that acts as a wrapper around string
-objects. It is a useful base class for your own string-like classes,
-which can inherit from them and override existing methods or add new
-ones. In this way one can add new behaviors to strings.
-
-It should be noted that these classes are highly inefficient compared
-to real string or Unicode objects; this is especially the case for
-\class{MutableString}.
-
-The \module{UserString} module defines the following classes:
-
-\begin{classdesc}{UserString}{\optional{sequence}}
-Class that simulates a string or a Unicode string
-object. The instance's content is kept in a regular string or Unicode
-string object, which is accessible via the \member{data} attribute of
-\class{UserString} instances. The instance's contents are initially
-set to a copy of \var{sequence}. \var{sequence} can be either a
-regular Python string or Unicode string, an instance of
-\class{UserString} (or a subclass) or an arbitrary sequence which can
-be converted into a string using the built-in \function{str()} function.
-\end{classdesc}
-
-\begin{classdesc}{MutableString}{\optional{sequence}}
-This class is derived from the \class{UserString} above and redefines
-strings to be \emph{mutable}. Mutable strings can't be used as
-dictionary keys, because dictionaries require \emph{immutable} objects as
-keys. The main intention of this class is to serve as an educational
-example for inheritance and necessity to remove (override) the
-\method{__hash__()} method in order to trap attempts to use a
-mutable object as dictionary key, which would be otherwise very
-error prone and hard to track down.
-\end{classdesc}
-
-In addition to supporting the methods and operations of string and
-Unicode objects (see section \ref{string-methods}, ``String
-Methods''), \class{UserString} instances provide the following
-attribute:
-
-\begin{memberdesc}{data}
-A real Python string or Unicode object used to store the content of the
-\class{UserString} class.
-\end{memberdesc}
diff --git a/Doc/lib/libuu.tex b/Doc/lib/libuu.tex
deleted file mode 100644
index 7e546a0..0000000
--- a/Doc/lib/libuu.tex
+++ /dev/null
@@ -1,58 +0,0 @@
-\section{\module{uu} ---
- Encode and decode uuencode files}
-
-\declaremodule{standard}{uu}
-\modulesynopsis{Encode and decode files in uuencode format.}
-\moduleauthor{Lance Ellinghouse}{}
-
-
-This module encodes and decodes files in uuencode format, allowing
-arbitrary binary data to be transferred over ASCII-only connections.
-Wherever a file argument is expected, the methods accept a file-like
-object. For backwards compatibility, a string containing a pathname
-is also accepted, and the corresponding file will be opened for
-reading and writing; the pathname \code{'-'} is understood to mean the
-standard input or output. However, this interface is deprecated; it's
-better for the caller to open the file itself, and be sure that, when
-required, the mode is \code{'rb'} or \code{'wb'} on Windows.
-
-This code was contributed by Lance Ellinghouse, and modified by Jack
-Jansen.
-\index{Jansen, Jack}
-\index{Ellinghouse, Lance}
-
-The \module{uu} module defines the following functions:
-
-\begin{funcdesc}{encode}{in_file, out_file\optional{, name\optional{, mode}}}
- Uuencode file \var{in_file} into file \var{out_file}. The uuencoded
- file will have the header specifying \var{name} and \var{mode} as
- the defaults for the results of decoding the file. The default
- defaults are taken from \var{in_file}, or \code{'-'} and \code{0666}
- respectively.
-\end{funcdesc}
-
-\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode\optional{, quiet}}}}
- This call decodes uuencoded file \var{in_file} placing the result on
- file \var{out_file}. If \var{out_file} is a pathname, \var{mode} is
- used to set the permission bits if the file must be
- created. Defaults for \var{out_file} and \var{mode} are taken from
- the uuencode header. However, if the file specified in the header
- already exists, a \exception{uu.Error} is raised.
-
- \function{decode()} may print a warning to standard error if the
- input was produced by an incorrect uuencoder and Python could
- recover from that error. Setting \var{quiet} to a true value
- silences this warning.
-\end{funcdesc}
-
-\begin{excclassdesc}{Error}{}
- Subclass of \exception{Exception}, this can be raised by
- \function{uu.decode()} under various situations, such as described
- above, but also including a badly formatted header, or truncated
- input file.
-\end{excclassdesc}
-
-\begin{seealso}
- \seemodule{binascii}{Support module containing \ASCII-to-binary
- and binary-to-\ASCII{} conversions.}
-\end{seealso}
diff --git a/Doc/lib/libuuid.tex b/Doc/lib/libuuid.tex
deleted file mode 100644
index 5aa9d8c..0000000
--- a/Doc/lib/libuuid.tex
+++ /dev/null
@@ -1,233 +0,0 @@
-\section{\module{uuid} ---
- UUID objects according to RFC 4122}
-\declaremodule{builtin}{uuid}
-\modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122}
-\moduleauthor{Ka-Ping Yee}{ping@zesty.ca}
-\sectionauthor{George Yoshida}{quiver@users.sourceforge.net}
-
-\versionadded{2.5}
-
-This module provides immutable \class{UUID} objects (the \class{UUID} class)
-and the functions \function{uuid1()}, \function{uuid3()},
-\function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4,
-and 5 UUIDs as specified in \rfc{4122}.
-
-If all you want is a unique ID, you should probably call
-\function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()}
-may compromise privacy since it creates a UUID containing the computer's
-network address. \function{uuid4()} creates a random UUID.
-
-\begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{,
-bytes_le\optional{, fields\optional{, int\optional{, version}}}}}}}
-
-Create a UUID from either a string of 32 hexadecimal digits,
-a string of 16 bytes as the \var{bytes} argument, a string of 16 bytes
-in little-endian order as the \var{bytes_le} argument, a tuple of six
-integers (32-bit \var{time_low}, 16-bit \var{time_mid},
-16-bit \var{time_hi_version},
-8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node})
-as the \var{fields} argument, or a single 128-bit integer as the \var{int}
-argument. When a string of hex digits is given, curly braces,
-hyphens, and a URN prefix are all optional. For example, these
-expressions all yield the same UUID:
-
-\begin{verbatim}
-UUID('{12345678-1234-5678-1234-567812345678}')
-UUID('12345678123456781234567812345678')
-UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
-UUID(bytes='\x12\x34\x56\x78'*4)
-UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' +
- '\x12\x34\x56\x78\x12\x34\x56\x78')
-UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
-UUID(int=0x12345678123456781234567812345678)
-\end{verbatim}
-
-Exactly one of \var{hex}, \var{bytes}, \var{bytes_le}, \var{fields},
-or \var{int} must
-be given. The \var{version} argument is optional; if given, the
-resulting UUID will have its variant and version number set according to
-RFC 4122, overriding bits in the given \var{hex}, \var{bytes},
-\var{bytes_le}, \var{fields}, or \var{int}.
-
-\end{classdesc}
-
-\class{UUID} instances have these read-only attributes:
-
-\begin{memberdesc}{bytes}
-The UUID as a 16-byte string (containing the six
-integer fields in big-endian byte order).
-\end{memberdesc}
-
-\begin{memberdesc}{bytes_le}
-The UUID as a 16-byte string (with \var{time_low}, \var{time_mid},
-and \var{time_hi_version} in little-endian byte order).
-\end{memberdesc}
-
-\begin{memberdesc}{fields}
-A tuple of the six integer fields of the UUID, which are also available
-as six individual attributes and two derived attributes:
-
-\begin{tableii}{l|l}{member}{Field}{Meaning}
- \lineii{time_low}{the first 32 bits of the UUID}
- \lineii{time_mid}{the next 16 bits of the UUID}
- \lineii{time_hi_version}{the next 16 bits of the UUID}
- \lineii{clock_seq_hi_variant}{the next 8 bits of the UUID}
- \lineii{clock_seq_low}{the next 8 bits of the UUID}
- \lineii{node}{the last 48 bits of the UUID}
- \lineii{time}{the 60-bit timestamp}
- \lineii{clock_seq}{the 14-bit sequence number}
-\end{tableii}
-
-
-\end{memberdesc}
-
-\begin{memberdesc}{hex}
-The UUID as a 32-character hexadecimal string.
-\end{memberdesc}
-
-\begin{memberdesc}{int}
-The UUID as a 128-bit integer.
-\end{memberdesc}
-
-\begin{memberdesc}{urn}
-The UUID as a URN as specified in RFC 4122.
-\end{memberdesc}
-
-\begin{memberdesc}{variant}
-The UUID variant, which determines the internal layout of the UUID.
-This will be one of the integer constants
-\constant{RESERVED_NCS},
-\constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or
-\constant{RESERVED_FUTURE}.
-\end{memberdesc}
-
-\begin{memberdesc}{version}
-The UUID version number (1 through 5, meaningful only
-when the variant is \constant{RFC_4122}).
-\end{memberdesc}
-
-The \module{uuid} module defines the following functions:
-
-\begin{funcdesc}{getnode}{}
-Get the hardware address as a 48-bit positive integer. The first time this
-runs, it may launch a separate program, which could be quite slow. If all
-attempts to obtain the hardware address fail, we choose a random 48-bit
-number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware
-address" means the MAC address of a network interface, and on a machine
-with multiple network interfaces the MAC address of any one of them may
-be returned.
-\end{funcdesc}
-\index{getnode}
-
-\begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}}
-Generate a UUID from a host ID, sequence number, and the current time.
-If \var{node} is not given, \function{getnode()} is used to obtain the
-hardware address.
-If \var{clock_seq} is given, it is used as the sequence number;
-otherwise a random 14-bit sequence number is chosen.
-\end{funcdesc}
-\index{uuid1}
-
-\begin{funcdesc}{uuid3}{namespace, name}
-Generate a UUID based on the MD5 hash
-of a namespace identifier (which is a UUID) and a name (which is a string).
-\end{funcdesc}
-\index{uuid3}
-
-\begin{funcdesc}{uuid4}{}
-Generate a random UUID.
-\end{funcdesc}
-\index{uuid4}
-
-\begin{funcdesc}{uuid5}{namespace, name}
-Generate a UUID based on the SHA-1 hash
-of a namespace identifier (which is a UUID) and a name (which is a string).
-\end{funcdesc}
-\index{uuid5}
-
-The \module{uuid} module defines the following namespace identifiers
-for use with \function{uuid3()} or \function{uuid5()}.
-
-\begin{datadesc}{NAMESPACE_DNS}
-When this namespace is specified,
-the \var{name} string is a fully-qualified domain name.
-\end{datadesc}
-
-\begin{datadesc}{NAMESPACE_URL}
-When this namespace is specified,
-the \var{name} string is a URL.
-\end{datadesc}
-
-\begin{datadesc}{NAMESPACE_OID}
-When this namespace is specified,
-the \var{name} string is an ISO OID.
-\end{datadesc}
-
-\begin{datadesc}{NAMESPACE_X500}
-When this namespace is specified,
-the \var{name} string is an X.500 DN in DER or a text output format.
-\end{datadesc}
-
-The \module{uuid} module defines the following constants
-for the possible values of the \member{variant} attribute:
-
-\begin{datadesc}{RESERVED_NCS}
-Reserved for NCS compatibility.
-\end{datadesc}
-
-\begin{datadesc}{RFC_4122}
-Specifies the UUID layout given in \rfc{4122}.
-\end{datadesc}
-
-\begin{datadesc}{RESERVED_MICROSOFT}
-Reserved for Microsoft compatibility.
-\end{datadesc}
-
-\begin{datadesc}{RESERVED_FUTURE}
-Reserved for future definition.
-\end{datadesc}
-
-
-\begin{seealso}
- \seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{
-This specification defines a Uniform Resource Name namespace for UUIDs,
-the internal format of UUIDs, and methods of generating UUIDs.}
-\end{seealso}
-
-\subsection{Example \label{uuid-example}}
-
-Here are some examples of typical usage of the \module{uuid} module:
-\begin{verbatim}
->>> import uuid
-
-# make a UUID based on the host ID and current time
->>> uuid.uuid1()
-UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
-
-# make a UUID using an MD5 hash of a namespace UUID and a name
->>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
-UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
-
-# make a random UUID
->>> uuid.uuid4()
-UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
-
-# make a UUID using a SHA-1 hash of a namespace UUID and a name
->>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
-UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
-
-# make a UUID from a string of hex digits (braces and hyphens ignored)
->>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
-
-# convert a UUID to a string of hex digits in standard form
->>> str(x)
-'00010203-0405-0607-0809-0a0b0c0d0e0f'
-
-# get the raw 16 bytes of the UUID
->>> x.bytes
-'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
-
-# make a UUID from a 16-byte string
->>> uuid.UUID(bytes=x.bytes)
-UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
-\end{verbatim}
diff --git a/Doc/lib/libwarnings.tex b/Doc/lib/libwarnings.tex
deleted file mode 100644
index a37a9f5..0000000
--- a/Doc/lib/libwarnings.tex
+++ /dev/null
@@ -1,253 +0,0 @@
-\section{\module{warnings} ---
- Warning control}
-
-\declaremodule{standard}{warnings}
-\modulesynopsis{Issue warning messages and control their disposition.}
-\index{warnings}
-
-\versionadded{2.1}
-
-Warning messages are typically issued in situations where it is useful
-to alert the user of some condition in a program, where that condition
-(normally) doesn't warrant raising an exception and terminating the
-program. For example, one might want to issue a warning when a
-program uses an obsolete module.
-
-Python programmers issue warnings by calling the \function{warn()}
-function defined in this module. (C programmers use
-\cfunction{PyErr_Warn()}; see the
-\citetitle[../api/exceptionHandling.html]{Python/C API Reference
-Manual} for details).
-
-Warning messages are normally written to \code{sys.stderr}, but their
-disposition can be changed flexibly, from ignoring all warnings to
-turning them into exceptions. The disposition of warnings can vary
-based on the warning category (see below), the text of the warning
-message, and the source location where it is issued. Repetitions of a
-particular warning for the same source location are typically
-suppressed.
-
-There are two stages in warning control: first, each time a warning is
-issued, a determination is made whether a message should be issued or
-not; next, if a message is to be issued, it is formatted and printed
-using a user-settable hook.
-
-The determination whether to issue a warning message is controlled by
-the warning filter, which is a sequence of matching rules and actions.
-Rules can be added to the filter by calling
-\function{filterwarnings()} and reset to its default state by calling
-\function{resetwarnings()}.
-
-The printing of warning messages is done by calling
-\function{showwarning()}, which may be overridden; the default
-implementation of this function formats the message by calling
-\function{formatwarning()}, which is also available for use by custom
-implementations.
-
-
-\subsection{Warning Categories \label{warning-categories}}
-
-There are a number of built-in exceptions that represent warning
-categories. This categorization is useful to be able to filter out
-groups of warnings. The following warnings category classes are
-currently defined:
-
-\begin{tableii}{l|l}{exception}{Class}{Description}
-
-\lineii{Warning}{This is the base class of all warning category
-classes. It is a subclass of \exception{Exception}.}
-
-\lineii{UserWarning}{The default category for \function{warn()}.}
-
-\lineii{DeprecationWarning}{Base category for warnings about
-deprecated features.}
-
-\lineii{SyntaxWarning}{Base category for warnings about dubious
-syntactic features.}
-
-\lineii{RuntimeWarning}{Base category for warnings about dubious
-runtime features.}
-
-\lineii{FutureWarning}{Base category for warnings about constructs
-that will change semantically in the future.}
-
-\lineii{PendingDeprecationWarning}{Base category for warnings about
-features that will be deprecated in the future (ignored by default).}
-
-\lineii{ImportWarning}{Base category for warnings triggered during the
-process of importing a module (ignored by default).}
-
-\lineii{UnicodeWarning}{Base category for warnings related to Unicode.}
-
-\end{tableii}
-
-While these are technically built-in exceptions, they are documented
-here, because conceptually they belong to the warnings mechanism.
-
-User code can define additional warning categories by subclassing one
-of the standard warning categories. A warning category must always be
-a subclass of the \exception{Warning} class.
-
-
-\subsection{The Warnings Filter \label{warning-filter}}
-
-The warnings filter controls whether warnings are ignored, displayed,
-or turned into errors (raising an exception).
-
-Conceptually, the warnings filter maintains an ordered list of filter
-specifications; any specific warning is matched against each filter
-specification in the list in turn until a match is found; the match
-determines the disposition of the match. Each entry is a tuple of the
-form (\var{action}, \var{message}, \var{category}, \var{module},
-\var{lineno}), where:
-
-\begin{itemize}
-
-\item \var{action} is one of the following strings:
-
- \begin{tableii}{l|l}{code}{Value}{Disposition}
-
- \lineii{"error"}{turn matching warnings into exceptions}
-
- \lineii{"ignore"}{never print matching warnings}
-
- \lineii{"always"}{always print matching warnings}
-
- \lineii{"default"}{print the first occurrence of matching
- warnings for each location where the warning is issued}
-
- \lineii{"module"}{print the first occurrence of matching
- warnings for each module where the warning is issued}
-
- \lineii{"once"}{print only the first occurrence of matching
- warnings, regardless of location}
-
- \end{tableii}
-
-\item \var{message} is a string containing a regular expression that
-the warning message must match (the match is compiled to always be
-case-insensitive)
-
-\item \var{category} is a class (a subclass of \exception{Warning}) of
- which the warning category must be a subclass in order to match
-
-\item \var{module} is a string containing a regular expression that the module
- name must match (the match is compiled to be case-sensitive)
-
-\item \var{lineno} is an integer that the line number where the
- warning occurred must match, or \code{0} to match all line
- numbers
-
-\end{itemize}
-
-Since the \exception{Warning} class is derived from the built-in
-\exception{Exception} class, to turn a warning into an error we simply
-raise \code{category(message)}.
-
-The warnings filter is initialized by \programopt{-W} options passed
-to the Python interpreter command line. The interpreter saves the
-arguments for all \programopt{-W} options without interpretation in
-\code{sys.warnoptions}; the \module{warnings} module parses these when
-it is first imported (invalid options are ignored, after printing a
-message to \code{sys.stderr}).
-
-The warnings that are ignored by default may be enabled by passing
- \programopt{-Wd} to the interpreter. This enables default handling
-for all warnings, including those that are normally ignored by
-default. This is particular useful for enabling ImportWarning when
-debugging problems importing a developed package. ImportWarning can
-also be enabled explicitly in Python code using:
-
-\begin{verbatim}
- warnings.simplefilter('default', ImportWarning)
-\end{verbatim}
-
-
-\subsection{Available Functions \label{warning-functions}}
-
-\begin{funcdesc}{warn}{message\optional{, category\optional{, stacklevel}}}
-Issue a warning, or maybe ignore it or raise an exception. The
-\var{category} argument, if given, must be a warning category class
-(see above); it defaults to \exception{UserWarning}. Alternatively
-\var{message} can be a \exception{Warning} instance, in which case
-\var{category} will be ignored and \code{message.__class__} will be used.
-In this case the message text will be \code{str(message)}. This function
-raises an exception if the particular warning issued is changed
-into an error by the warnings filter see above. The \var{stacklevel}
-argument can be used by wrapper functions written in Python, like
-this:
-
-\begin{verbatim}
-def deprecation(message):
- warnings.warn(message, DeprecationWarning, stacklevel=2)
-\end{verbatim}
-
-This makes the warning refer to \function{deprecation()}'s caller,
-rather than to the source of \function{deprecation()} itself (since
-the latter would defeat the purpose of the warning message).
-\end{funcdesc}
-
-\begin{funcdesc}{warn_explicit}{message, category, filename,
- lineno\optional{, module\optional{, registry\optional{,
- module_globals}}}}
-This is a low-level interface to the functionality of
-\function{warn()}, passing in explicitly the message, category,
-filename and line number, and optionally the module name and the
-registry (which should be the \code{__warningregistry__} dictionary of
-the module). The module name defaults to the filename with \code{.py}
-stripped; if no registry is passed, the warning is never suppressed.
-\var{message} must be a string and \var{category} a subclass of
-\exception{Warning} or \var{message} may be a \exception{Warning} instance,
-in which case \var{category} will be ignored.
-
-\var{module_globals}, if supplied, should be the global namespace in use
-by the code for which the warning is issued. (This argument is used to
-support displaying source for modules found in zipfiles or other
-non-filesystem import sources, and was added in Python 2.5.)
-\end{funcdesc}
-
-\begin{funcdesc}{showwarning}{message, category, filename,
- lineno\optional{, file}}
-Write a warning to a file. The default implementation calls
-\code{formatwarning(\var{message}, \var{category}, \var{filename},
-\var{lineno})} and writes the resulting string to \var{file}, which
-defaults to \code{sys.stderr}. You may replace this function with an
-alternative implementation by assigning to
-\code{warnings.showwarning}.
-\end{funcdesc}
-
-\begin{funcdesc}{formatwarning}{message, category, filename, lineno}
-Format a warning the standard way. This returns a string which may
-contain embedded newlines and ends in a newline.
-\end{funcdesc}
-
-\begin{funcdesc}{filterwarnings}{action\optional{,
- message\optional{, category\optional{,
- module\optional{, lineno\optional{, append}}}}}}
-Insert an entry into the list of warnings filters. The entry is
-inserted at the front by default; if \var{append} is true, it is
-inserted at the end.
-This checks the types of the arguments, compiles the message and
-module regular expressions, and inserts them as a tuple in the
-list of warnings filters. Entries closer to the front of the list
-override entries later in the list, if both match a particular
-warning. Omitted arguments default to a value that matches
-everything.
-\end{funcdesc}
-
-\begin{funcdesc}{simplefilter}{action\optional{,
- category\optional{,
- lineno\optional{, append}}}}
-Insert a simple entry into the list of warnings filters. The meaning
-of the function parameters is as for \function{filterwarnings()}, but
-regular expressions are not needed as the filter inserted always
-matches any message in any module as long as the category and line
-number match.
-\end{funcdesc}
-
-\begin{funcdesc}{resetwarnings}{}
-Reset the warnings filter. This discards the effect of all previous
-calls to \function{filterwarnings()}, including that of the
-\programopt{-W} command line options and calls to
-\function{simplefilter()}.
-\end{funcdesc}
diff --git a/Doc/lib/libwave.tex b/Doc/lib/libwave.tex
deleted file mode 100644
index 936bbed..0000000
--- a/Doc/lib/libwave.tex
+++ /dev/null
@@ -1,171 +0,0 @@
-% Documentations stolen and LaTeX'ed from comments in file.
-\section{\module{wave} ---
- Read and write WAV files}
-
-\declaremodule{standard}{wave}
-\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
-\modulesynopsis{Provide an interface to the WAV sound format.}
-
-The \module{wave} module provides a convenient interface to the WAV sound
-format. It does not support compression/decompression, but it does support
-mono/stereo.
-
-The \module{wave} module defines the following function and exception:
-
-\begin{funcdesc}{open}{file\optional{, mode}}
-If \var{file} is a string, open the file by that name, other treat it
-as a seekable file-like object. \var{mode} can be any of
-\begin{description}
- \item[\code{'r'}, \code{'rb'}] Read only mode.
- \item[\code{'w'}, \code{'wb'}] Write only mode.
-\end{description}
-Note that it does not allow read/write WAV files.
-
-A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read}
-object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
-a \class{Wave_write} object. If \var{mode} is omitted and a file-like
-object is passed as \var{file}, \code{\var{file}.mode} is used as the
-default value for \var{mode} (the \character{b} flag is still added if
-necessary).
-\end{funcdesc}
-
-\begin{funcdesc}{openfp}{file, mode}
-A synonym for \function{open()}, maintained for backwards compatibility.
-\end{funcdesc}
-
-\begin{excdesc}{Error}
-An error raised when something is impossible because it violates the
-WAV specification or hits an implementation deficiency.
-\end{excdesc}
-
-
-\subsection{Wave_read Objects \label{Wave-read-objects}}
-
-Wave_read objects, as returned by \function{open()}, have the
-following methods:
-
-\begin{methoddesc}[Wave_read]{close}{}
-Close the stream, and make the instance unusable. This is
-called automatically on object collection.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getnchannels}{}
-Returns number of audio channels (\code{1} for mono, \code{2} for
-stereo).
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getsampwidth}{}
-Returns sample width in bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getframerate}{}
-Returns sampling frequency.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getnframes}{}
-Returns number of audio frames.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getcomptype}{}
-Returns compression type (\code{'NONE'} is the only supported type).
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getcompname}{}
-Human-readable version of \method{getcomptype()}.
-Usually \code{'not compressed'} parallels \code{'NONE'}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getparams}{}
-Returns a tuple
-\code{(\var{nchannels}, \var{sampwidth}, \var{framerate},
-\var{nframes}, \var{comptype}, \var{compname})}, equivalent to output
-of the \method{get*()} methods.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{readframes}{n}
-Reads and returns at most \var{n} frames of audio, as a string of bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{rewind}{}
-Rewind the file pointer to the beginning of the audio stream.
-\end{methoddesc}
-
-The following two methods are defined for compatibility with the
-\refmodule{aifc} module, and don't do anything interesting.
-
-\begin{methoddesc}[Wave_read]{getmarkers}{}
-Returns \code{None}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{getmark}{id}
-Raise an error.
-\end{methoddesc}
-
-The following two methods define a term ``position'' which is compatible
-between them, and is otherwise implementation dependent.
-
-\begin{methoddesc}[Wave_read]{setpos}{pos}
-Set the file pointer to the specified position.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_read]{tell}{}
-Return current file pointer position.
-\end{methoddesc}
-
-
-\subsection{Wave_write Objects \label{Wave-write-objects}}
-
-Wave_write objects, as returned by \function{open()}, have the
-following methods:
-
-\begin{methoddesc}[Wave_write]{close}{}
-Make sure \var{nframes} is correct, and close the file.
-This method is called upon deletion.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setnchannels}{n}
-Set the number of channels.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setsampwidth}{n}
-Set the sample width to \var{n} bytes.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setframerate}{n}
-Set the frame rate to \var{n}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setnframes}{n}
-Set the number of frames to \var{n}. This will be changed later if
-more frames are written.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setcomptype}{type, name}
-Set the compression type and description.
-At the moment, only compression type \samp{NONE} is supported,
-meaning no compression.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{setparams}{tuple}
-The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
-\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
-values valid for the \method{set*()} methods. Sets all parameters.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{tell}{}
-Return current position in the file, with the same disclaimer for
-the \method{Wave_read.tell()} and \method{Wave_read.setpos()}
-methods.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{writeframesraw}{data}
-Write audio frames, without correcting \var{nframes}.
-\end{methoddesc}
-
-\begin{methoddesc}[Wave_write]{writeframes}{data}
-Write audio frames and make sure \var{nframes} is correct.
-\end{methoddesc}
-
-Note that it is invalid to set any parameters after calling
-\method{writeframes()} or \method{writeframesraw()}, and any attempt
-to do so will raise \exception{wave.Error}.
diff --git a/Doc/lib/libweakref.tex b/Doc/lib/libweakref.tex
deleted file mode 100644
index 6f676a2..0000000
--- a/Doc/lib/libweakref.tex
+++ /dev/null
@@ -1,336 +0,0 @@
-\section{\module{weakref} ---
- Weak references}
-
-\declaremodule{extension}{weakref}
-\modulesynopsis{Support for weak references and weak dictionaries.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\moduleauthor{Neil Schemenauer}{nas@arctrix.com}
-\moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{2.1}
-
-% When making changes to the examples in this file, be sure to update
-% Lib/test/test_weakref.py::libreftest too!
-
-The \module{weakref} module allows the Python programmer to create
-\dfn{weak references} to objects.
-
-In the following, the term \dfn{referent} means the
-object which is referred to by a weak reference.
-
-A weak reference to an object is not enough to keep the object alive:
-when the only remaining references to a referent are weak references,
-garbage collection is free to destroy the referent and reuse its memory
-for something else. A primary use for weak references is to implement
-caches or mappings holding large objects, where it's desired that a
-large object not be kept alive solely because it appears in a cache or
-mapping. For example, if you have a number of large binary image objects,
-you may wish to associate a name with each. If you used a Python
-dictionary to map names to images, or images to names, the image objects
-would remain alive just because they appeared as values or keys in the
-dictionaries. The \class{WeakKeyDictionary} and
-\class{WeakValueDictionary} classes supplied by the \module{weakref}
-module are an alternative, using weak references to construct mappings
-that don't keep objects alive solely because they appear in the mapping
-objects. If, for example, an image object is a value in a
-\class{WeakValueDictionary}, then when the last remaining
-references to that image object are the weak references held by weak
-mappings, garbage collection can reclaim the object, and its corresponding
-entries in weak mappings are simply deleted.
-
-\class{WeakKeyDictionary} and \class{WeakValueDictionary} use weak
-references in their implementation, setting up callback functions on
-the weak references that notify the weak dictionaries when a key or value
-has been reclaimed by garbage collection. Most programs should find that
-using one of these weak dictionary types is all they need -- it's
-not usually necessary to create your own weak references directly. The
-low-level machinery used by the weak dictionary implementations is exposed
-by the \module{weakref} module for the benefit of advanced uses.
-
-Not all objects can be weakly referenced; those objects which can
-include class instances, functions written in Python (but not in C),
-methods (both bound and unbound), sets, frozensets, file objects,
-generators, type objects, DBcursor objects from the \module{bsddb} module,
-sockets, arrays, deques, and regular expression pattern objects.
-\versionchanged[Added support for files, sockets, arrays, and patterns]{2.4}
-
-Several builtin types such as \class{list} and \class{dict} do not
-directly support weak references but can add support through subclassing:
-
-\begin{verbatim}
-class Dict(dict):
- pass
-
-obj = Dict(red=1, green=2, blue=3) # this object is weak referencable
-\end{verbatim}
-
-Extension types can easily be made to support weak references; see
-``\ulink{Weak Reference Support}{../ext/weakref-support.html}'' in
-\citetitle[../ext/ext.html]{Extending and Embedding the Python
-Interpreter}.
-% The referenced section used to appear in this document with the
-% \label weakref-extension. It would be good to be able to generate a
-% redirect for the corresponding HTML page (weakref-extension.html)
-% for on-line versions of this document.
-
-\begin{classdesc}{ref}{object\optional{, callback}}
- Return a weak reference to \var{object}. The original object can be
- retrieved by calling the reference object if the referent is still
- alive; if the referent is no longer alive, calling the reference
- object will cause \constant{None} to be returned. If \var{callback} is
- provided and not \constant{None}, and the returned weakref object is
- still alive, the callback will be called when the object is about to be
- finalized; the weak reference object will be passed as the only
- parameter to the callback; the referent will no longer be available.
-
- It is allowable for many weak references to be constructed for the
- same object. Callbacks registered for each weak reference will be
- called from the most recently registered callback to the oldest
- registered callback.
-
- Exceptions raised by the callback will be noted on the standard
- error output, but cannot be propagated; they are handled in exactly
- the same way as exceptions raised from an object's
- \method{__del__()} method.
-
- Weak references are hashable if the \var{object} is hashable. They
- will maintain their hash value even after the \var{object} was
- deleted. If \function{hash()} is called the first time only after
- the \var{object} was deleted, the call will raise
- \exception{TypeError}.
-
- Weak references support tests for equality, but not ordering. If
- the referents are still alive, two references have the same
- equality relationship as their referents (regardless of the
- \var{callback}). If either referent has been deleted, the
- references are equal only if the reference objects are the same
- object.
-
- \versionchanged[This is now a subclassable type rather than a
- factory function; it derives from \class{object}]
- {2.4}
-\end{classdesc}
-
-\begin{funcdesc}{proxy}{object\optional{, callback}}
- Return a proxy to \var{object} which uses a weak reference. This
- supports use of the proxy in most contexts instead of requiring the
- explicit dereferencing used with weak reference objects. The
- returned object will have a type of either \code{ProxyType} or
- \code{CallableProxyType}, depending on whether \var{object} is
- callable. Proxy objects are not hashable regardless of the
- referent; this avoids a number of problems related to their
- fundamentally mutable nature, and prevent their use as dictionary
- keys. \var{callback} is the same as the parameter of the same name
- to the \function{ref()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{getweakrefcount}{object}
- Return the number of weak references and proxies which refer to
- \var{object}.
-\end{funcdesc}
-
-\begin{funcdesc}{getweakrefs}{object}
- Return a list of all weak reference and proxy objects which refer to
- \var{object}.
-\end{funcdesc}
-
-\begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
- Mapping class that references keys weakly. Entries in the
- dictionary will be discarded when there is no longer a strong
- reference to the key. This can be used to associate additional data
- with an object owned by other parts of an application without adding
- attributes to those objects. This can be especially useful with
- objects that override attribute accesses.
-
- \note{Caution: Because a \class{WeakKeyDictionary} is built on top
- of a Python dictionary, it must not change size when iterating
- over it. This can be difficult to ensure for a
- \class{WeakKeyDictionary} because actions performed by the
- program during iteration may cause items in the dictionary
- to vanish "by magic" (as a side effect of garbage collection).}
-\end{classdesc}
-
-\class{WeakKeyDictionary} objects have the following additional
-methods. These expose the internal references directly. The
-references are not guaranteed to be ``live'' at the time they are
-used, so the result of calling the references needs to be checked
-before being used. This can be used to avoid creating references that
-will cause the garbage collector to keep the keys around longer than
-needed.
-
-\begin{methoddesc}{iterkeyrefs}{}
- Return an iterator that yields the weak references to the keys.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{keyrefs}{}
- Return a list of weak references to the keys.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{classdesc}{WeakValueDictionary}{\optional{dict}}
- Mapping class that references values weakly. Entries in the
- dictionary will be discarded when no strong reference to the value
- exists any more.
-
- \note{Caution: Because a \class{WeakValueDictionary} is built on top
- of a Python dictionary, it must not change size when iterating
- over it. This can be difficult to ensure for a
- \class{WeakValueDictionary} because actions performed by the
- program during iteration may cause items in the dictionary
- to vanish "by magic" (as a side effect of garbage collection).}
-\end{classdesc}
-
-\class{WeakValueDictionary} objects have the following additional
-methods. These method have the same issues as the
-\method{iterkeyrefs()} and \method{keyrefs()} methods of
-\class{WeakKeyDictionary} objects.
-
-\begin{methoddesc}{itervaluerefs}{}
- Return an iterator that yields the weak references to the values.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{methoddesc}{valuerefs}{}
- Return a list of weak references to the values.
- \versionadded{2.5}
-\end{methoddesc}
-
-\begin{datadesc}{ReferenceType}
- The type object for weak references objects.
-\end{datadesc}
-
-\begin{datadesc}{ProxyType}
- The type object for proxies of objects which are not callable.
-\end{datadesc}
-
-\begin{datadesc}{CallableProxyType}
- The type object for proxies of callable objects.
-\end{datadesc}
-
-\begin{datadesc}{ProxyTypes}
- Sequence containing all the type objects for proxies. This can make
- it simpler to test if an object is a proxy without being dependent
- on naming both proxy types.
-\end{datadesc}
-
-\begin{excdesc}{ReferenceError}
- Exception raised when a proxy object is used but the underlying
- object has been collected. This is the same as the standard
- \exception{ReferenceError} exception.
-\end{excdesc}
-
-
-\begin{seealso}
- \seepep{0205}{Weak References}{The proposal and rationale for this
- feature, including links to earlier implementations
- and information about similar features in other
- languages.}
-\end{seealso}
-
-
-\subsection{Weak Reference Objects
- \label{weakref-objects}}
-
-Weak reference objects have no attributes or methods, but do allow the
-referent to be obtained, if it still exists, by calling it:
-
-\begin{verbatim}
->>> import weakref
->>> class Object:
-... pass
-...
->>> o = Object()
->>> r = weakref.ref(o)
->>> o2 = r()
->>> o is o2
-True
-\end{verbatim}
-
-If the referent no longer exists, calling the reference object returns
-\constant{None}:
-
-\begin{verbatim}
->>> del o, o2
->>> print r()
-None
-\end{verbatim}
-
-Testing that a weak reference object is still live should be done
-using the expression \code{\var{ref}() is not None}. Normally,
-application code that needs to use a reference object should follow
-this pattern:
-
-\begin{verbatim}
-# r is a weak reference object
-o = r()
-if o is None:
- # referent has been garbage collected
- print "Object has been deallocated; can't frobnicate."
-else:
- print "Object is still live!"
- o.do_something_useful()
-\end{verbatim}
-
-Using a separate test for ``liveness'' creates race conditions in
-threaded applications; another thread can cause a weak reference to
-become invalidated before the weak reference is called; the
-idiom shown above is safe in threaded applications as well as
-single-threaded applications.
-
-Specialized versions of \class{ref} objects can be created through
-subclassing. This is used in the implementation of the
-\class{WeakValueDictionary} to reduce the memory overhead for each
-entry in the mapping. This may be most useful to associate additional
-information with a reference, but could also be used to insert
-additional processing on calls to retrieve the referent.
-
-This example shows how a subclass of \class{ref} can be used to store
-additional information about an object and affect the value that's
-returned when the referent is accessed:
-
-\begin{verbatim}
-import weakref
-
-class ExtendedRef(weakref.ref):
- def __init__(self, ob, callback=None, **annotations):
- super(ExtendedRef, self).__init__(ob, callback)
- self.__counter = 0
- for k, v in annotations.iteritems():
- setattr(self, k, v)
-
- def __call__(self):
- """Return a pair containing the referent and the number of
- times the reference has been called.
- """
- ob = super(ExtendedRef, self).__call__()
- if ob is not None:
- self.__counter += 1
- ob = (ob, self.__counter)
- return ob
-\end{verbatim}
-
-
-\subsection{Example \label{weakref-example}}
-
-This simple example shows how an application can use objects IDs to
-retrieve objects that it has seen before. The IDs of the objects can
-then be used in other data structures without forcing the objects to
-remain alive, but the objects can still be retrieved by ID if they
-do.
-
-% Example contributed by Tim Peters.
-\begin{verbatim}
-import weakref
-
-_id2obj_dict = weakref.WeakValueDictionary()
-
-def remember(obj):
- oid = id(obj)
- _id2obj_dict[oid] = obj
- return oid
-
-def id2obj(oid):
- return _id2obj_dict[oid]
-\end{verbatim}
diff --git a/Doc/lib/libwebbrowser.tex b/Doc/lib/libwebbrowser.tex
deleted file mode 100644
index 5d5f236..0000000
--- a/Doc/lib/libwebbrowser.tex
+++ /dev/null
@@ -1,173 +0,0 @@
-\section{\module{webbrowser} ---
- Convenient Web-browser controller}
-
-\declaremodule{standard}{webbrowser}
-\modulesynopsis{Easy-to-use controller for Web browsers.}
-\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The \module{webbrowser} module provides a high-level interface to
-allow displaying Web-based documents to users. Under most
-circumstances, simply calling the \function{open()} function from this
-module will do the right thing.
-
-Under \UNIX{}, graphical browsers are preferred under X11, but text-mode
-browsers will be used if graphical browsers are not available or an X11
-display isn't available. If text-mode browsers are used, the calling
-process will block until the user exits the browser.
-
-If the environment variable \envvar{BROWSER} exists, it
-is interpreted to override the platform default list of browsers, as a
-os.pathsep-separated list of browsers to try in order. When the value of
-a list part contains the string \code{\%s}, then it is
-interpreted as a literal browser command line to be used with the argument URL
-substituted for \code{\%s}; if the part does not contain
-\code{\%s}, it is simply interpreted as the name of the browser to
-launch.
-
-For non-\UNIX{} platforms, or when a remote browser is available on
-\UNIX{}, the controlling process will not wait for the user to finish
-with the browser, but allow the remote browser to maintain its own
-windows on the display. If remote browsers are not available on \UNIX{},
-the controlling process will launch a new browser and wait.
-
-The script \program{webbrowser} can be used as a command-line interface
-for the module. It accepts an URL as the argument. It accepts the following
-optional parameters: \programopt{-n} opens the URL in a new browser window,
-if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The
-options are, naturally, mutually exclusive.
-
-The following exception is defined:
-
-\begin{excdesc}{Error}
- Exception raised when a browser control error occurs.
-\end{excdesc}
-
-The following functions are defined:
-
-\begin{funcdesc}{open}{url\optional{, new=0\optional{, autoraise=1}}}
- Display \var{url} using the default browser. If \var{new} is 0, the
- \var{url} is opened in the same browser window if possible. If \var{new} is 1,
- a new browser window is opened if possible. If \var{new} is 2,
- a new browser page ("tab") is opened if possible. If \var{autoraise} is
- true, the window is raised if possible (note that under many window
- managers this will occur regardless of the setting of this variable).
-\versionchanged[\var{new} can now be 2]{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{open_new}{url}
- Open \var{url} in a new window of the default browser, if possible,
- otherwise, open \var{url} in the only browser window.
-\end{funcdesc}
-
-\begin{funcdesc}{open_new_tab}{url}
- Open \var{url} in a new page ("tab") of the default browser, if possible,
- otherwise equivalent to \function{open_new}.
-\versionadded{2.5}
-\end{funcdesc}
-
-\begin{funcdesc}{get}{\optional{name}}
- Return a controller object for the browser type \var{name}. If
- \var{name} is empty, return a controller for a default browser
- appropriate to the caller's environment.
-\end{funcdesc}
-
-\begin{funcdesc}{register}{name, constructor\optional{, instance}}
- Register the browser type \var{name}. Once a browser type is
- registered, the \function{get()} function can return a controller
- for that browser type. If \var{instance} is not provided, or is
- \code{None}, \var{constructor} will be called without parameters to
- create an instance when needed. If \var{instance} is provided,
- \var{constructor} will never be called, and may be \code{None}.
-
- This entry point is only useful if you plan to either set the
- \envvar{BROWSER} variable or call \function{get} with a nonempty
- argument matching the name of a handler you declare.
-\end{funcdesc}
-
-A number of browser types are predefined. This table gives the type
-names that may be passed to the \function{get()} function and the
-corresponding instantiations for the controller classes, all defined
-in this module.
-
-\begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
- \lineiii{'mozilla'}{\class{Mozilla('mozilla')}}{}
- \lineiii{'firefox'}{\class{Mozilla('mozilla')}}{}
- \lineiii{'netscape'}{\class{Mozilla('netscape')}}{}
- \lineiii{'galeon'}{\class{Galeon('galeon')}}{}
- \lineiii{'epiphany'}{\class{Galeon('epiphany')}}{}
- \lineiii{'skipstone'}{\class{BackgroundBrowser('skipstone')}}{}
- \lineiii{'kfmclient'}{\class{Konqueror()}}{(1)}
- \lineiii{'konqueror'}{\class{Konqueror()}}{(1)}
- \lineiii{'kfm'}{\class{Konqueror()}}{(1)}
- \lineiii{'mosaic'}{\class{BackgroundBrowser('mosaic')}}{}
- \lineiii{'opera'}{\class{Opera()}}{}
- \lineiii{'grail'}{\class{Grail()}}{}
- \lineiii{'links'}{\class{GenericBrowser('links')}}{}
- \lineiii{'elinks'}{\class{Elinks('elinks')}}{}
- \lineiii{'lynx'}{\class{GenericBrowser('lynx')}}{}
- \lineiii{'w3m'}{\class{GenericBrowser('w3m')}}{}
- \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
- \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
- \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)}
-\end{tableiii}
-
-\noindent
-Notes:
-
-\begin{description}
-\item[(1)]
-``Konqueror'' is the file manager for the KDE desktop environment for
-\UNIX{}, and only makes sense to use if KDE is running. Some way of
-reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is
-not sufficient. Note also that the name ``kfm'' is used even when
-using the \program{konqueror} command with KDE 2 --- the
-implementation selects the best strategy for running Konqueror.
-
-\item[(2)]
-Only on Windows platforms.
-
-\item[(3)]
-Only on MacOS platforms; requires the standard MacPython \module{ic}
-module, described in the \citetitle[../mac/module-ic.html]{Macintosh
-Library Modules} manual.
-
-\item[(4)]
-Only on MacOS X platform.
-\end{description}
-
-Here are some simple examples:
-
-\begin{verbatim}
-url = 'http://www.python.org'
-
-# Open URL in a new tab, if a browser window is already open.
-webbrowser.open_new_tab(url + '/doc')
-
-# Open URL in new window, raising the window if possible.
-webbrowser.open_new(url)
-\end{verbatim}
-
-
-\subsection{Browser Controller Objects \label{browser-controllers}}
-
-Browser controllers provide two methods which parallel two of the
-module-level convenience functions:
-
-\begin{methoddesc}[controller]{open}{url\optional{, new\optional{, autoraise=1}}}
- Display \var{url} using the browser handled by this controller.
- If \var{new} is 1, a new browser window is opened if possible.
- If \var{new} is 2, a new browser page ("tab") is opened if possible.
-\end{methoddesc}
-
-\begin{methoddesc}[controller]{open_new}{url}
- Open \var{url} in a new window of the browser handled by this
- controller, if possible, otherwise, open \var{url} in the only
- browser window. Alias \function{open_new}.
-\end{methoddesc}
-
-\begin{methoddesc}[controller]{open_new_tab}{url}
- Open \var{url} in a new page ("tab") of the browser handled by this
- controller, if possible, otherwise equivalent to \function{open_new}.
-\versionadded{2.5}
-\end{methoddesc}
diff --git a/Doc/lib/libwhichdb.tex b/Doc/lib/libwhichdb.tex
deleted file mode 100644
index 92d37e7..0000000
--- a/Doc/lib/libwhichdb.tex
+++ /dev/null
@@ -1,20 +0,0 @@
-\section{\module{whichdb} ---
- Guess which DBM module created a database}
-
-\declaremodule{standard}{whichdb}
-\modulesynopsis{Guess which DBM-style module created a given database.}
-
-
-The single function in this module attempts to guess which of the
-several simple database modules available--\refmodule{dbm},
-\refmodule{gdbm}, or \refmodule{dbhash}--should be used to open a
-given file.
-
-\begin{funcdesc}{whichdb}{filename}
-Returns one of the following values: \code{None} if the file can't be
-opened because it's unreadable or doesn't exist; the empty string
-(\code{''}) if the file's format can't be guessed; or a string
-containing the required module name, such as \code{'dbm'} or
-\code{'gdbm'}.
-\end{funcdesc}
-
diff --git a/Doc/lib/libwinreg.tex b/Doc/lib/libwinreg.tex
deleted file mode 100644
index d31c3ca..0000000
--- a/Doc/lib/libwinreg.tex
+++ /dev/null
@@ -1,414 +0,0 @@
-\section{\module{_winreg} --
- Windows registry access}
-
-\declaremodule[-winreg]{extension}{_winreg}
- \platform{Windows}
-\modulesynopsis{Routines and objects for manipulating the Windows registry.}
-\sectionauthor{Mark Hammond}{MarkH@ActiveState.com}
-
-\versionadded{2.0}
-
-These functions expose the Windows registry API to Python. Instead of
-using an integer as the registry handle, a handle object is used to
-ensure that the handles are closed correctly, even if the programmer
-neglects to explicitly close them.
-
-This module exposes a very low-level interface to the Windows
-registry; it is expected that in the future a new \code{winreg}
-module will be created offering a higher-level interface to the
-registry API.
-
-This module offers the following functions:
-
-
-\begin{funcdesc}{CloseKey}{hkey}
- Closes a previously opened registry key.
- The hkey argument specifies a previously opened key.
-
- Note that if \var{hkey} is not closed using this method (or via
- \method{handle.Close()}), it is closed when the \var{hkey} object
- is destroyed by Python.
-\end{funcdesc}
-
-
-\begin{funcdesc}{ConnectRegistry}{computer_name, key}
- Establishes a connection to a predefined registry handle on
- another computer, and returns a \dfn{handle object}
-
- \var{computer_name} is the name of the remote computer, of the
- form \code{r"\e\e computername"}. If \code{None}, the local computer
- is used.
-
- \var{key} is the predefined handle to connect to.
-
- The return value is the handle of the opened key.
- If the function fails, an \exception{EnvironmentError} exception is
- raised.
-\end{funcdesc}
-
-
-\begin{funcdesc}{CreateKey}{key, sub_key}
- Creates or opens the specified key, returning a \dfn{handle object}
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that names the key this method opens
- or creates.
-
- If \var{key} is one of the predefined keys, \var{sub_key} may
- be \code{None}. In that case, the handle returned is the same key handle
- passed in to the function.
-
- If the key already exists, this function opens the existing key.
-
- The return value is the handle of the opened key.
- If the function fails, an \exception{EnvironmentError} exception is
- raised.
-\end{funcdesc}
-
-\begin{funcdesc}{DeleteKey}{key, sub_key}
- Deletes the specified key.
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that must be a subkey of the key
- identified by the \var{key} parameter. This value must not be
- \code{None}, and the key may not have subkeys.
-
- \emph{This method can not delete keys with subkeys.}
-
- If the method succeeds, the entire key, including all of its values,
- is removed. If the method fails, an \exception{EnvironmentError}
- exception is raised.
-\end{funcdesc}
-
-
-\begin{funcdesc}{DeleteValue}{key, value}
- Removes a named value from a registry key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{value} is a string that identifies the value to remove.
-\end{funcdesc}
-
-
-\begin{funcdesc}{EnumKey}{key, index}
- Enumerates subkeys of an open registry key, returning a string.
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{index} is an integer that identifies the index of the key to
- retrieve.
-
- The function retrieves the name of one subkey each time it
- is called. It is typically called repeatedly until an
- \exception{EnvironmentError} exception
- is raised, indicating, no more values are available.
-\end{funcdesc}
-
-
-\begin{funcdesc}{EnumValue}{key, index}
- Enumerates values of an open registry key, returning a tuple.
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{index} is an integer that identifies the index of the value
- to retrieve.
-
- The function retrieves the name of one subkey each time it is
- called. It is typically called repeatedly, until an
- \exception{EnvironmentError} exception is raised, indicating
- no more values.
-
- The result is a tuple of 3 items:
-
- \begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
- \lineii{0}{A string that identifies the value name}
- \lineii{1}{An object that holds the value data, and whose
- type depends on the underlying registry type}
- \lineii{2}{An integer that identifies the type of the value data}
- \end{tableii}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{FlushKey}{key}
- Writes all the attributes of a key to the registry.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- It is not necessary to call RegFlushKey to change a key.
- Registry changes are flushed to disk by the registry using its lazy
- flusher. Registry changes are also flushed to disk at system
- shutdown. Unlike \function{CloseKey()}, the \function{FlushKey()} method
- returns only when all the data has been written to the registry.
- An application should only call \function{FlushKey()} if it requires absolute
- certainty that registry changes are on disk.
-
- \note{If you don't know whether a \function{FlushKey()} call is required, it
- probably isn't.}
-
-\end{funcdesc}
-
-
-\begin{funcdesc}{RegLoadKey}{key, sub_key, file_name}
- Creates a subkey under the specified key and stores registration
- information from a specified file into that subkey.
-
- \var{key} is an already open key, or any of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that identifies the sub_key to load.
-
- \var {file_name} is the name of the file to load registry data from.
- This file must have been created with the \function{SaveKey()} function.
- Under the file allocation table (FAT) file system, the filename may not
- have an extension.
-
- A call to LoadKey() fails if the calling process does not have the
- \constant{SE_RESTORE_PRIVILEGE} privilege. Note that privileges
- are different than permissions - see the Win32 documentation for
- more details.
-
- If \var{key} is a handle returned by \function{ConnectRegistry()},
- then the path specified in \var{fileName} is relative to the
- remote computer.
-
- The Win32 documentation implies \var{key} must be in the
- \constant{HKEY_USER} or \constant{HKEY_LOCAL_MACHINE} tree.
- This may or may not be true.
-\end{funcdesc}
-
-
-\begin{funcdesc}{OpenKey}{key, sub_key\optional{, res\code{ = 0}}\optional{, sam\code{ = \constant{KEY_READ}}}}
- Opens the specified key, returning a \dfn{handle object}
-
- \var{key} is an already open key, or any one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that identifies the sub_key to open.
-
- \var{res} is a reserved integer, and must be zero. The default is zero.
-
- \var{sam} is an integer that specifies an access mask that describes
- the desired security access for the key. Default is \constant{KEY_READ}
-
- The result is a new handle to the specified key.
-
- If the function fails, \exception{EnvironmentError} is raised.
-\end{funcdesc}
-
-
-\begin{funcdesc}{OpenKeyEx}{}
- The functionality of \function{OpenKeyEx()} is provided via
- \function{OpenKey()}, by the use of default arguments.
-\end{funcdesc}
-
-
-\begin{funcdesc}{QueryInfoKey}{key}
- Returns information about a key, as a tuple.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- The result is a tuple of 3 items:
-
- \begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
- \lineii{0}{An integer giving the number of sub keys this key has.}
- \lineii{1}{An integer giving the number of values this key has.}
- \lineii{2}{A long integer giving when the key was last modified (if
- available) as 100's of nanoseconds since Jan 1, 1600.}
- \end{tableii}
-\end{funcdesc}
-
-
-\begin{funcdesc}{QueryValue}{key, sub_key}
- Retrieves the unnamed value for a key, as a string
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that holds the name of the subkey with which
- the value is associated. If this parameter is \code{None} or empty, the
- function retrieves the value set by the \function{SetValue()} method
- for the key identified by \var{key}.
-
- Values in the registry have name, type, and data components. This
- method retrieves the data for a key's first value that has a NULL name.
- But the underlying API call doesn't return the type, Lame Lame Lame,
- DO NOT USE THIS!!!
-\end{funcdesc}
-
-
-\begin{funcdesc}{QueryValueEx}{key, value_name}
- Retrieves the type and data for a specified value name associated with
- an open registry key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{value_name} is a string indicating the value to query.
-
- The result is a tuple of 2 items:
-
- \begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
- \lineii{0}{The value of the registry item.}
- \lineii{1}{An integer giving the registry type for this value.}
- \end{tableii}
-\end{funcdesc}
-
-
-\begin{funcdesc}{SaveKey}{key, file_name}
- Saves the specified key, and all its subkeys to the specified file.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{file_name} is the name of the file to save registry data to.
- This file cannot already exist. If this filename includes an extension,
- it cannot be used on file allocation table (FAT) file systems by the
- \method{LoadKey()}, \method{ReplaceKey()} or
- \method{RestoreKey()} methods.
-
- If \var{key} represents a key on a remote computer, the path
- described by \var{file_name} is relative to the remote computer.
- The caller of this method must possess the \constant{SeBackupPrivilege}
- security privilege. Note that privileges are different than permissions
- - see the Win32 documentation for more details.
-
- This function passes NULL for \var{security_attributes} to the API.
-\end{funcdesc}
-
-
-\begin{funcdesc}{SetValue}{key, sub_key, type, value}
- Associates a value with a specified key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{sub_key} is a string that names the subkey with which the value
- is associated.
-
- \var{type} is an integer that specifies the type of the data.
- Currently this must be \constant{REG_SZ}, meaning only strings are
- supported. Use the \function{SetValueEx()} function for support for
- other data types.
-
- \var{value} is a string that specifies the new value.
-
- If the key specified by the \var{sub_key} parameter does not exist,
- the SetValue function creates it.
-
- Value lengths are limited by available memory. Long values (more than
- 2048 bytes) should be stored as files with the filenames stored in
- the configuration registry. This helps the registry perform
- efficiently.
-
- The key identified by the \var{key} parameter must have been
- opened with \constant{KEY_SET_VALUE} access.
-\end{funcdesc}
-
-
-\begin{funcdesc}{SetValueEx}{key, value_name, reserved, type, value}
- Stores data in the value field of an open registry key.
-
- \var{key} is an already open key, or one of the predefined
- \constant{HKEY_*} constants.
-
- \var{value_name} is a string that names the subkey with which the
- value is associated.
-
- \var{type} is an integer that specifies the type of the data.
- This should be one of the following constants defined in this module:
-
- \begin{tableii}{l|p{3in}}{constant}{Constant}{Meaning}
- \lineii{REG_BINARY}{Binary data in any form.}
- \lineii{REG_DWORD}{A 32-bit number.}
- \lineii{REG_DWORD_LITTLE_ENDIAN}{A 32-bit number in little-endian format.}
- \lineii{REG_DWORD_BIG_ENDIAN}{A 32-bit number in big-endian format.}
- \lineii{REG_EXPAND_SZ}{Null-terminated string containing references
- to environment variables (\samp{\%PATH\%}).}
- \lineii{REG_LINK}{A Unicode symbolic link.}
- \lineii{REG_MULTI_SZ}{A sequence of null-terminated strings,
- terminated by two null characters. (Python handles
- this termination automatically.)}
- \lineii{REG_NONE}{No defined value type.}
- \lineii{REG_RESOURCE_LIST}{A device-driver resource list.}
- \lineii{REG_SZ}{A null-terminated string.}
- \end{tableii}
-
- \var{reserved} can be anything - zero is always passed to the
- API.
-
- \var{value} is a string that specifies the new value.
-
- This method can also set additional value and type information for the
- specified key. The key identified by the key parameter must have been
- opened with \constant{KEY_SET_VALUE} access.
-
- To open the key, use the \function{CreateKeyEx()} or
- \function{OpenKey()} methods.
-
- Value lengths are limited by available memory. Long values (more than
- 2048 bytes) should be stored as files with the filenames stored in
- the configuration registry. This helps the registry perform efficiently.
-\end{funcdesc}
-
-
-
-\subsection{Registry Handle Objects \label{handle-object}}
-
- This object wraps a Windows HKEY object, automatically closing it when
- the object is destroyed. To guarantee cleanup, you can call either
- the \method{Close()} method on the object, or the
- \function{CloseKey()} function.
-
- All registry functions in this module return one of these objects.
-
- All registry functions in this module which accept a handle object
- also accept an integer, however, use of the handle object is
- encouraged.
-
- Handle objects provide semantics for \method{__bool__()} - thus
-\begin{verbatim}
- if handle:
- print "Yes"
-\end{verbatim}
- will print \code{Yes} if the handle is currently valid (has not been
- closed or detached).
-
- The object also support comparison semantics, so handle
- objects will compare true if they both reference the same
- underlying Windows handle value.
-
- Handle objects can be converted to an integer (e.g., using the
- builtin \function{int()} function), in which case the underlying
- Windows handle value is returned. You can also use the
- \method{Detach()} method to return the integer handle, and
- also disconnect the Windows handle from the handle object.
-
-\begin{methoddesc}[PyHKEY]{Close}{}
- Closes the underlying Windows handle.
-
- If the handle is already closed, no error is raised.
-\end{methoddesc}
-
-
-\begin{methoddesc}[PyHKEY]{Detach}{}
- Detaches the Windows handle from the handle object.
-
- The result is an integer (or long on 64 bit Windows) that holds
- the value of the handle before it is detached. If the
- handle is already detached or closed, this will return zero.
-
- After calling this function, the handle is effectively invalidated,
- but the handle is not closed. You would call this function when
- you need the underlying Win32 handle to exist beyond the lifetime
- of the handle object.
-\end{methoddesc}
diff --git a/Doc/lib/libwinsound.tex b/Doc/lib/libwinsound.tex
deleted file mode 100644
index 5f5b15e..0000000
--- a/Doc/lib/libwinsound.tex
+++ /dev/null
@@ -1,142 +0,0 @@
-\section{\module{winsound} ---
- Sound-playing interface for Windows}
-
-\declaremodule{builtin}{winsound}
- \platform{Windows}
-\modulesynopsis{Access to the sound-playing machinery for Windows.}
-\moduleauthor{Toby Dickenson}{htrd90@zepler.org}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-\versionadded{1.5.2}
-
-The \module{winsound} module provides access to the basic
-sound-playing machinery provided by Windows platforms. It includes
-functions and several constants.
-
-
-\begin{funcdesc}{Beep}{frequency, duration}
- Beep the PC's speaker.
- The \var{frequency} parameter specifies frequency, in hertz, of the
- sound, and must be in the range 37 through 32,767.
- The \var{duration} parameter specifies the number of milliseconds the
- sound should last. If the system is not
- able to beep the speaker, \exception{RuntimeError} is raised.
- \note{Under Windows 95 and 98, the Windows \cfunction{Beep()}
- function exists but is useless (it ignores its arguments). In that
- case Python simulates it via direct port manipulation (added in version
- 2.1). It's unknown whether that will work on all systems.}
- \versionadded{1.6}
-\end{funcdesc}
-
-\begin{funcdesc}{PlaySound}{sound, flags}
- Call the underlying \cfunction{PlaySound()} function from the
- Platform API. The \var{sound} parameter may be a filename, audio
- data as a string, or \code{None}. Its interpretation depends on the
- value of \var{flags}, which can be a bit-wise ORed combination of
- the constants described below. If the system indicates an error,
- \exception{RuntimeError} is raised.
-\end{funcdesc}
-
-\begin{funcdesc}{MessageBeep}{\optional{type=\code{MB_OK}}}
- Call the underlying \cfunction{MessageBeep()} function from the
- Platform API. This plays a sound as specified in the registry. The
- \var{type} argument specifies which sound to play; possible values
- are \code{-1}, \code{MB_ICONASTERISK}, \code{MB_ICONEXCLAMATION},
- \code{MB_ICONHAND}, \code{MB_ICONQUESTION}, and \code{MB_OK}, all
- described below. The value \code{-1} produces a ``simple beep'';
- this is the final fallback if a sound cannot be played otherwise.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{datadesc}{SND_FILENAME}
- The \var{sound} parameter is the name of a WAV file.
- Do not use with \constant{SND_ALIAS}.
-\end{datadesc}
-
-\begin{datadesc}{SND_ALIAS}
- The \var{sound} parameter is a sound association name from the
- registry. If the registry contains no such name, play the system
- default sound unless \constant{SND_NODEFAULT} is also specified.
- If no default sound is registered, raise \exception{RuntimeError}.
- Do not use with \constant{SND_FILENAME}.
-
- All Win32 systems support at least the following; most systems support
- many more:
-
-\begin{tableii}{l|l}{code}
- {\function{PlaySound()} \var{name}}
- {Corresponding Control Panel Sound name}
- \lineii{'SystemAsterisk'} {Asterisk}
- \lineii{'SystemExclamation'}{Exclamation}
- \lineii{'SystemExit'} {Exit Windows}
- \lineii{'SystemHand'} {Critical Stop}
- \lineii{'SystemQuestion'} {Question}
-\end{tableii}
-
- For example:
-
-\begin{verbatim}
-import winsound
-# Play Windows exit sound.
-winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
-
-# Probably play Windows default sound, if any is registered (because
-# "*" probably isn't the registered name of any sound).
-winsound.PlaySound("*", winsound.SND_ALIAS)
-\end{verbatim}
-\end{datadesc}
-
-\begin{datadesc}{SND_LOOP}
- Play the sound repeatedly. The \constant{SND_ASYNC} flag must also
- be used to avoid blocking. Cannot be used with \constant{SND_MEMORY}.
-\end{datadesc}
-
-\begin{datadesc}{SND_MEMORY}
- The \var{sound} parameter to \function{PlaySound()} is a memory
- image of a WAV file, as a string.
-
- \note{This module does not support playing from a memory
- image asynchronously, so a combination of this flag and
- \constant{SND_ASYNC} will raise \exception{RuntimeError}.}
-\end{datadesc}
-
-\begin{datadesc}{SND_PURGE}
- Stop playing all instances of the specified sound.
-\end{datadesc}
-
-\begin{datadesc}{SND_ASYNC}
- Return immediately, allowing sounds to play asynchronously.
-\end{datadesc}
-
-\begin{datadesc}{SND_NODEFAULT}
- If the specified sound cannot be found, do not play the system default
- sound.
-\end{datadesc}
-
-\begin{datadesc}{SND_NOSTOP}
- Do not interrupt sounds currently playing.
-\end{datadesc}
-
-\begin{datadesc}{SND_NOWAIT}
- Return immediately if the sound driver is busy.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONASTERISK}
- Play the \code{SystemDefault} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONEXCLAMATION}
- Play the \code{SystemExclamation} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONHAND}
- Play the \code{SystemHand} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_ICONQUESTION}
- Play the \code{SystemQuestion} sound.
-\end{datadesc}
-
-\begin{datadesc}{MB_OK}
- Play the \code{SystemDefault} sound.
-\end{datadesc}
diff --git a/Doc/lib/libwsgiref.tex b/Doc/lib/libwsgiref.tex
deleted file mode 100755
index 37ded9f..0000000
--- a/Doc/lib/libwsgiref.tex
+++ /dev/null
@@ -1,782 +0,0 @@
-\section{\module{wsgiref} --- WSGI Utilities and Reference
-Implementation}
-\declaremodule{}{wsgiref}
-\moduleauthor{Phillip J. Eby}{pje@telecommunity.com}
-\sectionauthor{Phillip J. Eby}{pje@telecommunity.com}
-\modulesynopsis{WSGI Utilities and Reference Implementation}
-
-\versionadded{2.5}
-
-The Web Server Gateway Interface (WSGI) is a standard interface
-between web server software and web applications written in Python.
-Having a standard interface makes it easy to use an application
-that supports WSGI with a number of different web servers.
-
-Only authors of web servers and programming frameworks need to know
-every detail and corner case of the WSGI design. You don't need to
-understand every detail of WSGI just to install a WSGI application or
-to write a web application using an existing framework.
-
-\module{wsgiref} is a reference implementation of the WSGI specification
-that can be used to add WSGI support to a web server or framework. It
-provides utilities for manipulating WSGI environment variables and
-response headers, base classes for implementing WSGI servers, a demo
-HTTP server that serves WSGI applications, and a validation tool that
-checks WSGI servers and applications for conformance to the
-WSGI specification (\pep{333}).
-
-% XXX If you're just trying to write a web application...
-
-See \url{http://www.wsgi.org} for more information about WSGI,
-and links to tutorials and other resources.
-
-
-
-
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.util} -- WSGI environment utilities}
-\declaremodule{}{wsgiref.util}
-
-This module provides a variety of utility functions for working with
-WSGI environments. A WSGI environment is a dictionary containing
-HTTP request variables as described in \pep{333}. All of the functions
-taking an \var{environ} parameter expect a WSGI-compliant dictionary to
-be supplied; please see \pep{333} for a detailed specification.
-
-\begin{funcdesc}{guess_scheme}{environ}
-Return a guess for whether \code{wsgi.url_scheme} should be ``http'' or
-``https'', by checking for a \code{HTTPS} environment variable in the
-\var{environ} dictionary. The return value is a string.
-
-This function is useful when creating a gateway that wraps CGI or a
-CGI-like protocol such as FastCGI. Typically, servers providing such
-protocols will include a \code{HTTPS} variable with a value of ``1''
-``yes'', or ``on'' when a request is received via SSL. So, this
-function returns ``https'' if such a value is found, and ``http''
-otherwise.
-\end{funcdesc}
-
-\begin{funcdesc}{request_uri}{environ \optional{, include_query=1}}
-Return the full request URI, optionally including the query string,
-using the algorithm found in the ``URL Reconstruction'' section of
-\pep{333}. If \var{include_query} is false, the query string is
-not included in the resulting URI.
-\end{funcdesc}
-
-\begin{funcdesc}{application_uri}{environ}
-Similar to \function{request_uri}, except that the \code{PATH_INFO} and
-\code{QUERY_STRING} variables are ignored. The result is the base URI
-of the application object addressed by the request.
-\end{funcdesc}
-
-\begin{funcdesc}{shift_path_info}{environ}
-Shift a single name from \code{PATH_INFO} to \code{SCRIPT_NAME} and
-return the name. The \var{environ} dictionary is \emph{modified}
-in-place; use a copy if you need to keep the original \code{PATH_INFO}
-or \code{SCRIPT_NAME} intact.
-
-If there are no remaining path segments in \code{PATH_INFO}, \code{None}
-is returned.
-
-Typically, this routine is used to process each portion of a request
-URI path, for example to treat the path as a series of dictionary keys.
-This routine modifies the passed-in environment to make it suitable for
-invoking another WSGI application that is located at the target URI.
-For example, if there is a WSGI application at \code{/foo}, and the
-request URI path is \code{/foo/bar/baz}, and the WSGI application at
-\code{/foo} calls \function{shift_path_info}, it will receive the string
-``bar'', and the environment will be updated to be suitable for passing
-to a WSGI application at \code{/foo/bar}. That is, \code{SCRIPT_NAME}
-will change from \code{/foo} to \code{/foo/bar}, and \code{PATH_INFO}
-will change from \code{/bar/baz} to \code{/baz}.
-
-When \code{PATH_INFO} is just a ``/'', this routine returns an empty
-string and appends a trailing slash to \code{SCRIPT_NAME}, even though
-empty path segments are normally ignored, and \code{SCRIPT_NAME} doesn't
-normally end in a slash. This is intentional behavior, to ensure that
-an application can tell the difference between URIs ending in \code{/x}
-from ones ending in \code{/x/} when using this routine to do object
-traversal.
-
-\end{funcdesc}
-
-\begin{funcdesc}{setup_testing_defaults}{environ}
-Update \var{environ} with trivial defaults for testing purposes.
-
-This routine adds various parameters required for WSGI, including
-\code{HTTP_HOST}, \code{SERVER_NAME}, \code{SERVER_PORT},
-\code{REQUEST_METHOD}, \code{SCRIPT_NAME}, \code{PATH_INFO}, and all of
-the \pep{333}-defined \code{wsgi.*} variables. It only supplies default
-values, and does not replace any existing settings for these variables.
-
-This routine is intended to make it easier for unit tests of WSGI
-servers and applications to set up dummy environments. It should NOT
-be used by actual WSGI servers or applications, since the data is fake!
-\end{funcdesc}
-
-
-
-In addition to the environment functions above, the
-\module{wsgiref.util} module also provides these miscellaneous
-utilities:
-
-\begin{funcdesc}{is_hop_by_hop}{header_name}
-Return true if 'header_name' is an HTTP/1.1 ``Hop-by-Hop'' header, as
-defined by \rfc{2616}.
-\end{funcdesc}
-
-\begin{classdesc}{FileWrapper}{filelike \optional{, blksize=8192}}
-A wrapper to convert a file-like object to an iterator. The resulting
-objects support both \method{__getitem__} and \method{__iter__}
-iteration styles, for compatibility with Python 2.1 and Jython.
-As the object is iterated over, the optional \var{blksize} parameter
-will be repeatedly passed to the \var{filelike} object's \method{read()}
-method to obtain strings to yield. When \method{read()} returns an
-empty string, iteration is ended and is not resumable.
-
-If \var{filelike} has a \method{close()} method, the returned object
-will also have a \method{close()} method, and it will invoke the
-\var{filelike} object's \method{close()} method when called.
-\end{classdesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.headers} -- WSGI response header tools}
-\declaremodule{}{wsgiref.headers}
-
-This module provides a single class, \class{Headers}, for convenient
-manipulation of WSGI response headers using a mapping-like interface.
-
-\begin{classdesc}{Headers}{headers}
-Create a mapping-like object wrapping \var{headers}, which must be a
-list of header name/value tuples as described in \pep{333}. Any changes
-made to the new \class{Headers} object will directly update the
-\var{headers} list it was created with.
-
-\class{Headers} objects support typical mapping operations including
-\method{__getitem__}, \method{get}, \method{__setitem__},
-\method{setdefault}, \method{__delitem__}, \method{__contains__} and
-\method{has_key}. For each of these methods, the key is the header name
-(treated case-insensitively), and the value is the first value
-associated with that header name. Setting a header deletes any existing
-values for that header, then adds a new value at the end of the wrapped
-header list. Headers' existing order is generally maintained, with new
-headers added to the end of the wrapped list.
-
-Unlike a dictionary, \class{Headers} objects do not raise an error when
-you try to get or delete a key that isn't in the wrapped header list.
-Getting a nonexistent header just returns \code{None}, and deleting
-a nonexistent header does nothing.
-
-\class{Headers} objects also support \method{keys()}, \method{values()},
-and \method{items()} methods. The lists returned by \method{keys()}
-and \method{items()} can include the same key more than once if there
-is a multi-valued header. The \code{len()} of a \class{Headers} object
-is the same as the length of its \method{items()}, which is the same
-as the length of the wrapped header list. In fact, the \method{items()}
-method just returns a copy of the wrapped header list.
-
-Calling \code{str()} on a \class{Headers} object returns a formatted
-string suitable for transmission as HTTP response headers. Each header
-is placed on a line with its value, separated by a colon and a space.
-Each line is terminated by a carriage return and line feed, and the
-string is terminated with a blank line.
-
-In addition to their mapping interface and formatting features,
-\class{Headers} objects also have the following methods for querying
-and adding multi-valued headers, and for adding headers with MIME
-parameters:
-
-\begin{methoddesc}{get_all}{name}
-Return a list of all the values for the named header.
-
-The returned list will be sorted in the order they appeared in the
-original header list or were added to this instance, and may contain
-duplicates. Any fields deleted and re-inserted are always appended to
-the header list. If no fields exist with the given name, returns an
-empty list.
-\end{methoddesc}
-
-
-\begin{methoddesc}{add_header}{name, value, **_params}
-Add a (possibly multi-valued) header, with optional MIME parameters
-specified via keyword arguments.
-
-\var{name} is the header field to add. Keyword arguments can be used to
-set MIME parameters for the header field. Each parameter must be a
-string or \code{None}. Underscores in parameter names are converted to
-dashes, since dashes are illegal in Python identifiers, but many MIME
-parameter names include dashes. If the parameter value is a string, it
-is added to the header value parameters in the form \code{name="value"}.
-If it is \code{None}, only the parameter name is added. (This is used
-for MIME parameters without a value.) Example usage:
-
-\begin{verbatim}
-h.add_header('content-disposition', 'attachment', filename='bud.gif')
-\end{verbatim}
-
-The above will add a header that looks like this:
-
-\begin{verbatim}
-Content-Disposition: attachment; filename="bud.gif"
-\end{verbatim}
-\end{methoddesc}
-\end{classdesc}
-
-\subsection{\module{wsgiref.simple_server} -- a simple WSGI HTTP server}
-\declaremodule[wsgiref.simpleserver]{}{wsgiref.simple_server}
-
-This module implements a simple HTTP server (based on
-\module{BaseHTTPServer}) that serves WSGI applications. Each server
-instance serves a single WSGI application on a given host and port. If
-you want to serve multiple applications on a single host and port, you
-should create a WSGI application that parses \code{PATH_INFO} to select
-which application to invoke for each request. (E.g., using the
-\function{shift_path_info()} function from \module{wsgiref.util}.)
-
-
-\begin{funcdesc}{make_server}{host, port, app
-\optional{, server_class=\class{WSGIServer} \optional{,
-handler_class=\class{WSGIRequestHandler}}}}
-Create a new WSGI server listening on \var{host} and \var{port},
-accepting connections for \var{app}. The return value is an instance of
-the supplied \var{server_class}, and will process requests using the
-specified \var{handler_class}. \var{app} must be a WSGI application
-object, as defined by \pep{333}.
-
-Example usage:
-\begin{verbatim}from wsgiref.simple_server import make_server, demo_app
-
-httpd = make_server('', 8000, demo_app)
-print "Serving HTTP on port 8000..."
-
-# Respond to requests until process is killed
-httpd.serve_forever()
-
-# Alternative: serve one request, then exit
-##httpd.handle_request()
-\end{verbatim}
-
-\end{funcdesc}
-
-
-
-
-
-
-\begin{funcdesc}{demo_app}{environ, start_response}
-This function is a small but complete WSGI application that
-returns a text page containing the message ``Hello world!''
-and a list of the key/value pairs provided in the
-\var{environ} parameter. It's useful for verifying that a WSGI server
-(such as \module{wsgiref.simple_server}) is able to run a simple WSGI
-application correctly.
-\end{funcdesc}
-
-
-\begin{classdesc}{WSGIServer}{server_address, RequestHandlerClass}
-Create a \class{WSGIServer} instance. \var{server_address} should be
-a \code{(host,port)} tuple, and \var{RequestHandlerClass} should be
-the subclass of \class{BaseHTTPServer.BaseHTTPRequestHandler} that will
-be used to process requests.
-
-You do not normally need to call this constructor, as the
-\function{make_server()} function can handle all the details for you.
-
-\class{WSGIServer} is a subclass
-of \class{BaseHTTPServer.HTTPServer}, so all of its methods (such as
-\method{serve_forever()} and \method{handle_request()}) are available.
-\class{WSGIServer} also provides these WSGI-specific methods:
-
-\begin{methoddesc}{set_app}{application}
-Sets the callable \var{application} as the WSGI application that will
-receive requests.
-\end{methoddesc}
-
-\begin{methoddesc}{get_app}{}
-Returns the currently-set application callable.
-\end{methoddesc}
-
-Normally, however, you do not need to use these additional methods, as
-\method{set_app()} is normally called by \function{make_server()}, and
-the \method{get_app()} exists mainly for the benefit of request handler
-instances.
-\end{classdesc}
-
-
-
-\begin{classdesc}{WSGIRequestHandler}{request, client_address, server}
-Create an HTTP handler for the given \var{request} (i.e. a socket),
-\var{client_address} (a \code{(\var{host},\var{port})} tuple), and
-\var{server} (\class{WSGIServer} instance).
-
-You do not need to create instances of this class directly; they are
-automatically created as needed by \class{WSGIServer} objects. You
-can, however, subclass this class and supply it as a \var{handler_class}
-to the \function{make_server()} function. Some possibly relevant
-methods for overriding in subclasses:
-
-\begin{methoddesc}{get_environ}{}
-Returns a dictionary containing the WSGI environment for a request. The
-default implementation copies the contents of the \class{WSGIServer}
-object's \member{base_environ} dictionary attribute and then adds
-various headers derived from the HTTP request. Each call to this method
-should return a new dictionary containing all of the relevant CGI
-environment variables as specified in \pep{333}.
-\end{methoddesc}
-
-\begin{methoddesc}{get_stderr}{}
-Return the object that should be used as the \code{wsgi.errors} stream.
-The default implementation just returns \code{sys.stderr}.
-\end{methoddesc}
-
-\begin{methoddesc}{handle}{}
-Process the HTTP request. The default implementation creates a handler
-instance using a \module{wsgiref.handlers} class to implement the actual
-WSGI application interface.
-\end{methoddesc}
-
-\end{classdesc}
-
-
-
-
-
-
-
-
-
-\subsection{\module{wsgiref.validate} -- WSGI conformance checker}
-\declaremodule{}{wsgiref.validate}
-When creating new WSGI application objects, frameworks, servers, or
-middleware, it can be useful to validate the new code's conformance
-using \module{wsgiref.validate}. This module provides a function that
-creates WSGI application objects that validate communications between
-a WSGI server or gateway and a WSGI application object, to check both
-sides for protocol conformance.
-
-Note that this utility does not guarantee complete \pep{333} compliance;
-an absence of errors from this module does not necessarily mean that
-errors do not exist. However, if this module does produce an error,
-then it is virtually certain that either the server or application is
-not 100\% compliant.
-
-This module is based on the \module{paste.lint} module from Ian
-Bicking's ``Python Paste'' library.
-
-\begin{funcdesc}{validator}{application}
-Wrap \var{application} and return a new WSGI application object. The
-returned application will forward all requests to the original
-\var{application}, and will check that both the \var{application} and
-the server invoking it are conforming to the WSGI specification and to
-RFC 2616.
-
-Any detected nonconformance results in an \exception{AssertionError}
-being raised; note, however, that how these errors are handled is
-server-dependent. For example, \module{wsgiref.simple_server} and other
-servers based on \module{wsgiref.handlers} (that don't override the
-error handling methods to do something else) will simply output a
-message that an error has occurred, and dump the traceback to
-\code{sys.stderr} or some other error stream.
-
-This wrapper may also generate output using the \module{warnings} module
-to indicate behaviors that are questionable but which may not actually
-be prohibited by \pep{333}. Unless they are suppressed using Python
-command-line options or the \module{warnings} API, any such warnings
-will be written to \code{sys.stderr} (\emph{not} \code{wsgi.errors},
-unless they happen to be the same object).
-\end{funcdesc}
-
-\subsection{\module{wsgiref.handlers} -- server/gateway base classes}
-\declaremodule{}{wsgiref.handlers}
-
-This module provides base handler classes for implementing WSGI servers
-and gateways. These base classes handle most of the work of
-communicating with a WSGI application, as long as they are given a
-CGI-like environment, along with input, output, and error streams.
-
-
-\begin{classdesc}{CGIHandler}{}
-CGI-based invocation via \code{sys.stdin}, \code{sys.stdout},
-\code{sys.stderr} and \code{os.environ}. This is useful when you have
-a WSGI application and want to run it as a CGI script. Simply invoke
-\code{CGIHandler().run(app)}, where \code{app} is the WSGI application
-object you wish to invoke.
-
-This class is a subclass of \class{BaseCGIHandler} that sets
-\code{wsgi.run_once} to true, \code{wsgi.multithread} to false, and
-\code{wsgi.multiprocess} to true, and always uses \module{sys} and
-\module{os} to obtain the necessary CGI streams and environment.
-\end{classdesc}
-
-
-\begin{classdesc}{BaseCGIHandler}{stdin, stdout, stderr, environ
-\optional{, multithread=True \optional{, multiprocess=False}}}
-
-Similar to \class{CGIHandler}, but instead of using the \module{sys} and
-\module{os} modules, the CGI environment and I/O streams are specified
-explicitly. The \var{multithread} and \var{multiprocess} values are
-used to set the \code{wsgi.multithread} and \code{wsgi.multiprocess}
-flags for any applications run by the handler instance.
-
-This class is a subclass of \class{SimpleHandler} intended for use with
-software other than HTTP ``origin servers''. If you are writing a
-gateway protocol implementation (such as CGI, FastCGI, SCGI, etc.) that
-uses a \code{Status:} header to send an HTTP status, you probably want
-to subclass this instead of \class{SimpleHandler}.
-\end{classdesc}
-
-
-
-\begin{classdesc}{SimpleHandler}{stdin, stdout, stderr, environ
-\optional{,multithread=True \optional{, multiprocess=False}}}
-
-Similar to \class{BaseCGIHandler}, but designed for use with HTTP origin
-servers. If you are writing an HTTP server implementation, you will
-probably want to subclass this instead of \class{BaseCGIHandler}
-
-This class is a subclass of \class{BaseHandler}. It overrides the
-\method{__init__()}, \method{get_stdin()}, \method{get_stderr()},
-\method{add_cgi_vars()}, \method{_write()}, and \method{_flush()}
-methods to support explicitly setting the environment and streams via
-the constructor. The supplied environment and streams are stored in
-the \member{stdin}, \member{stdout}, \member{stderr}, and
-\member{environ} attributes.
-\end{classdesc}
-
-\begin{classdesc}{BaseHandler}{}
-This is an abstract base class for running WSGI applications. Each
-instance will handle a single HTTP request, although in principle you
-could create a subclass that was reusable for multiple requests.
-
-\class{BaseHandler} instances have only one method intended for external
-use:
-
-\begin{methoddesc}{run}{app}
-Run the specified WSGI application, \var{app}.
-\end{methoddesc}
-
-All of the other \class{BaseHandler} methods are invoked by this method
-in the process of running the application, and thus exist primarily to
-allow customizing the process.
-
-The following methods MUST be overridden in a subclass:
-
-\begin{methoddesc}{_write}{data}
-Buffer the string \var{data} for transmission to the client. It's okay
-if this method actually transmits the data; \class{BaseHandler}
-just separates write and flush operations for greater efficiency
-when the underlying system actually has such a distinction.
-\end{methoddesc}
-
-\begin{methoddesc}{_flush}{}
-Force buffered data to be transmitted to the client. It's okay if this
-method is a no-op (i.e., if \method{_write()} actually sends the data).
-\end{methoddesc}
-
-\begin{methoddesc}{get_stdin}{}
-Return an input stream object suitable for use as the \code{wsgi.input}
-of the request currently being processed.
-\end{methoddesc}
-
-\begin{methoddesc}{get_stderr}{}
-Return an output stream object suitable for use as the
-\code{wsgi.errors} of the request currently being processed.
-\end{methoddesc}
-
-\begin{methoddesc}{add_cgi_vars}{}
-Insert CGI variables for the current request into the \member{environ}
-attribute.
-\end{methoddesc}
-
-Here are some other methods and attributes you may wish to override.
-This list is only a summary, however, and does not include every method
-that can be overridden. You should consult the docstrings and source
-code for additional information before attempting to create a customized
-\class{BaseHandler} subclass.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Attributes and methods for customizing the WSGI environment:
-
-\begin{memberdesc}{wsgi_multithread}
-The value to be used for the \code{wsgi.multithread} environment
-variable. It defaults to true in \class{BaseHandler}, but may have
-a different default (or be set by the constructor) in the other
-subclasses.
-\end{memberdesc}
-
-\begin{memberdesc}{wsgi_multiprocess}
-The value to be used for the \code{wsgi.multiprocess} environment
-variable. It defaults to true in \class{BaseHandler}, but may have
-a different default (or be set by the constructor) in the other
-subclasses.
-\end{memberdesc}
-
-\begin{memberdesc}{wsgi_run_once}
-The value to be used for the \code{wsgi.run_once} environment
-variable. It defaults to false in \class{BaseHandler}, but
-\class{CGIHandler} sets it to true by default.
-\end{memberdesc}
-
-\begin{memberdesc}{os_environ}
-The default environment variables to be included in every request's
-WSGI environment. By default, this is a copy of \code{os.environ} at
-the time that \module{wsgiref.handlers} was imported, but subclasses can
-either create their own at the class or instance level. Note that the
-dictionary should be considered read-only, since the default value is
-shared between multiple classes and instances.
-\end{memberdesc}
-
-\begin{memberdesc}{server_software}
-If the \member{origin_server} attribute is set, this attribute's value
-is used to set the default \code{SERVER_SOFTWARE} WSGI environment
-variable, and also to set a default \code{Server:} header in HTTP
-responses. It is ignored for handlers (such as \class{BaseCGIHandler}
-and \class{CGIHandler}) that are not HTTP origin servers.
-\end{memberdesc}
-
-
-
-\begin{methoddesc}{get_scheme}{}
-Return the URL scheme being used for the current request. The default
-implementation uses the \function{guess_scheme()} function from
-\module{wsgiref.util} to guess whether the scheme should be ``http'' or
-``https'', based on the current request's \member{environ} variables.
-\end{methoddesc}
-
-\begin{methoddesc}{setup_environ}{}
-Set the \member{environ} attribute to a fully-populated WSGI
-environment. The default implementation uses all of the above methods
-and attributes, plus the \method{get_stdin()}, \method{get_stderr()},
-and \method{add_cgi_vars()} methods and the \member{wsgi_file_wrapper}
-attribute. It also inserts a \code{SERVER_SOFTWARE} key if not present,
-as long as the \member{origin_server} attribute is a true value and the
-\member{server_software} attribute is set.
-\end{methoddesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Methods and attributes for customizing exception handling:
-
-\begin{methoddesc}{log_exception}{exc_info}
-Log the \var{exc_info} tuple in the server log. \var{exc_info} is a
-\code{(\var{type}, \var{value}, \var{traceback})} tuple. The default
-implementation simply writes the traceback to the request's
-\code{wsgi.errors} stream and flushes it. Subclasses can override this
-method to change the format or retarget the output, mail the traceback
-to an administrator, or whatever other action may be deemed suitable.
-\end{methoddesc}
-
-\begin{memberdesc}{traceback_limit}
-The maximum number of frames to include in tracebacks output by the
-default \method{log_exception()} method. If \code{None}, all frames
-are included.
-\end{memberdesc}
-
-\begin{methoddesc}{error_output}{environ, start_response}
-This method is a WSGI application to generate an error page for the
-user. It is only invoked if an error occurs before headers are sent
-to the client.
-
-This method can access the current error information using
-\code{sys.exc_info()}, and should pass that information to
-\var{start_response} when calling it (as described in the ``Error
-Handling'' section of \pep{333}).
-
-The default implementation just uses the \member{error_status},
-\member{error_headers}, and \member{error_body} attributes to generate
-an output page. Subclasses can override this to produce more dynamic
-error output.
-
-Note, however, that it's not recommended from a security perspective to
-spit out diagnostics to any old user; ideally, you should have to do
-something special to enable diagnostic output, which is why the default
-implementation doesn't include any.
-\end{methoddesc}
-
-
-
-
-\begin{memberdesc}{error_status}
-The HTTP status used for error responses. This should be a status
-string as defined in \pep{333}; it defaults to a 500 code and message.
-\end{memberdesc}
-
-\begin{memberdesc}{error_headers}
-The HTTP headers used for error responses. This should be a list of
-WSGI response headers (\code{(\var{name}, \var{value})} tuples), as
-described in \pep{333}. The default list just sets the content type
-to \code{text/plain}.
-\end{memberdesc}
-
-\begin{memberdesc}{error_body}
-The error response body. This should be an HTTP response body string.
-It defaults to the plain text, ``A server error occurred. Please
-contact the administrator.''
-\end{memberdesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Methods and attributes for \pep{333}'s ``Optional Platform-Specific File
-Handling'' feature:
-
-\begin{memberdesc}{wsgi_file_wrapper}
-A \code{wsgi.file_wrapper} factory, or \code{None}. The default value
-of this attribute is the \class{FileWrapper} class from
-\module{wsgiref.util}.
-\end{memberdesc}
-
-\begin{methoddesc}{sendfile}{}
-Override to implement platform-specific file transmission. This method
-is called only if the application's return value is an instance of
-the class specified by the \member{wsgi_file_wrapper} attribute. It
-should return a true value if it was able to successfully transmit the
-file, so that the default transmission code will not be executed.
-The default implementation of this method just returns a false value.
-\end{methoddesc}
-
-
-Miscellaneous methods and attributes:
-
-\begin{memberdesc}{origin_server}
-This attribute should be set to a true value if the handler's
-\method{_write()} and \method{_flush()} are being used to communicate
-directly to the client, rather than via a CGI-like gateway protocol that
-wants the HTTP status in a special \code{Status:} header.
-
-This attribute's default value is true in \class{BaseHandler}, but
-false in \class{BaseCGIHandler} and \class{CGIHandler}.
-\end{memberdesc}
-
-\begin{memberdesc}{http_version}
-If \member{origin_server} is true, this string attribute is used to
-set the HTTP version of the response set to the client. It defaults to
-\code{"1.0"}.
-\end{memberdesc}
-
-
-
-
-
-\end{classdesc}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Doc/lib/libxdrlib.tex b/Doc/lib/libxdrlib.tex
deleted file mode 100644
index 56474b7..0000000
--- a/Doc/lib/libxdrlib.tex
+++ /dev/null
@@ -1,251 +0,0 @@
-\section{\module{xdrlib} ---
- Encode and decode XDR data}
-
-\declaremodule{standard}{xdrlib}
-\modulesynopsis{Encoders and decoders for the External Data
- Representation (XDR).}
-
-\index{XDR}
-\index{External Data Representation}
-
-The \module{xdrlib} module supports the External Data Representation
-Standard as described in \rfc{1014}, written by Sun Microsystems,
-Inc. June 1987. It supports most of the data types described in the
-RFC.
-
-The \module{xdrlib} module defines two classes, one for packing
-variables into XDR representation, and another for unpacking from XDR
-representation. There are also two exception classes.
-
-\begin{classdesc}{Packer}{}
-\class{Packer} is the class for packing data into XDR representation.
-The \class{Packer} class is instantiated with no arguments.
-\end{classdesc}
-
-\begin{classdesc}{Unpacker}{data}
-\code{Unpacker} is the complementary class which unpacks XDR data
-values from a string buffer. The input buffer is given as
-\var{data}.
-\end{classdesc}
-
-
-\begin{seealso}
- \seerfc{1014}{XDR: External Data Representation Standard}{This RFC
- defined the encoding of data which was XDR at the time
- this module was originally written. It has
- apparently been obsoleted by \rfc{1832}.}
-
- \seerfc{1832}{XDR: External Data Representation Standard}{Newer RFC
- that provides a revised definition of XDR.}
-\end{seealso}
-
-
-\subsection{Packer Objects \label{xdr-packer-objects}}
-
-\class{Packer} instances have the following methods:
-
-\begin{methoddesc}[Packer]{get_buffer}{}
-Returns the current pack buffer as a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{reset}{}
-Resets the pack buffer to the empty string.
-\end{methoddesc}
-
-In general, you can pack any of the most common XDR data types by
-calling the appropriate \code{pack_\var{type}()} method. Each method
-takes a single argument, the value to pack. The following simple data
-type packing methods are supported: \method{pack_uint()},
-\method{pack_int()}, \method{pack_enum()}, \method{pack_bool()},
-\method{pack_uhyper()}, and \method{pack_hyper()}.
-
-\begin{methoddesc}[Packer]{pack_float}{value}
-Packs the single-precision floating point number \var{value}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_double}{value}
-Packs the double-precision floating point number \var{value}.
-\end{methoddesc}
-
-The following methods support packing strings, bytes, and opaque data:
-
-\begin{methoddesc}[Packer]{pack_fstring}{n, s}
-Packs a fixed length string, \var{s}. \var{n} is the length of the
-string but it is \emph{not} packed into the data buffer. The string
-is padded with null bytes if necessary to guaranteed 4 byte alignment.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_fopaque}{n, data}
-Packs a fixed length opaque data stream, similarly to
-\method{pack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_string}{s}
-Packs a variable length string, \var{s}. The length of the string is
-first packed as an unsigned integer, then the string data is packed
-with \method{pack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_opaque}{data}
-Packs a variable length opaque data string, similarly to
-\method{pack_string()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_bytes}{bytes}
-Packs a variable length byte stream, similarly to \method{pack_string()}.
-\end{methoddesc}
-
-The following methods support packing arrays and lists:
-
-\begin{methoddesc}[Packer]{pack_list}{list, pack_item}
-Packs a \var{list} of homogeneous items. This method is useful for
-lists with an indeterminate size; i.e. the size is not available until
-the entire list has been walked. For each item in the list, an
-unsigned integer \code{1} is packed first, followed by the data value
-from the list. \var{pack_item} is the function that is called to pack
-the individual item. At the end of the list, an unsigned integer
-\code{0} is packed.
-
-For example, to pack a list of integers, the code might appear like
-this:
-
-\begin{verbatim}
-import xdrlib
-p = xdrlib.Packer()
-p.pack_list([1, 2, 3], p.pack_int)
-\end{verbatim}
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item}
-Packs a fixed length list (\var{array}) of homogeneous items. \var{n}
-is the length of the list; it is \emph{not} packed into the buffer,
-but a \exception{ValueError} exception is raised if
-\code{len(\var{array})} is not equal to \var{n}. As above,
-\var{pack_item} is the function used to pack each element.
-\end{methoddesc}
-
-\begin{methoddesc}[Packer]{pack_array}{list, pack_item}
-Packs a variable length \var{list} of homogeneous items. First, the
-length of the list is packed as an unsigned integer, then each element
-is packed as in \method{pack_farray()} above.
-\end{methoddesc}
-
-
-\subsection{Unpacker Objects \label{xdr-unpacker-objects}}
-
-The \class{Unpacker} class offers the following methods:
-
-\begin{methoddesc}[Unpacker]{reset}{data}
-Resets the string buffer with the given \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{get_position}{}
-Returns the current unpack position in the data buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{set_position}{position}
-Sets the data buffer unpack position to \var{position}. You should be
-careful about using \method{get_position()} and \method{set_position()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{get_buffer}{}
-Returns the current unpack data buffer as a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{done}{}
-Indicates unpack completion. Raises an \exception{Error} exception
-if all of the data has not been unpacked.
-\end{methoddesc}
-
-In addition, every data type that can be packed with a \class{Packer},
-can be unpacked with an \class{Unpacker}. Unpacking methods are of the
-form \code{unpack_\var{type}()}, and take no arguments. They return the
-unpacked object.
-
-\begin{methoddesc}[Unpacker]{unpack_float}{}
-Unpacks a single-precision floating point number.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_double}{}
-Unpacks a double-precision floating point number, similarly to
-\method{unpack_float()}.
-\end{methoddesc}
-
-In addition, the following methods unpack strings, bytes, and opaque
-data:
-
-\begin{methoddesc}[Unpacker]{unpack_fstring}{n}
-Unpacks and returns a fixed length string. \var{n} is the number of
-characters expected. Padding with null bytes to guaranteed 4 byte
-alignment is assumed.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_fopaque}{n}
-Unpacks and returns a fixed length opaque data stream, similarly to
-\method{unpack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_string}{}
-Unpacks and returns a variable length string. The length of the
-string is first unpacked as an unsigned integer, then the string data
-is unpacked with \method{unpack_fstring()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_opaque}{}
-Unpacks and returns a variable length opaque data string, similarly to
-\method{unpack_string()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_bytes}{}
-Unpacks and returns a variable length byte stream, similarly to
-\method{unpack_string()}.
-\end{methoddesc}
-
-The following methods support unpacking arrays and lists:
-
-\begin{methoddesc}[Unpacker]{unpack_list}{unpack_item}
-Unpacks and returns a list of homogeneous items. The list is unpacked
-one element at a time
-by first unpacking an unsigned integer flag. If the flag is \code{1},
-then the item is unpacked and appended to the list. A flag of
-\code{0} indicates the end of the list. \var{unpack_item} is the
-function that is called to unpack the items.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item}
-Unpacks and returns (as a list) a fixed length array of homogeneous
-items. \var{n} is number of list elements to expect in the buffer.
-As above, \var{unpack_item} is the function used to unpack each element.
-\end{methoddesc}
-
-\begin{methoddesc}[Unpacker]{unpack_array}{unpack_item}
-Unpacks and returns a variable length \var{list} of homogeneous items.
-First, the length of the list is unpacked as an unsigned integer, then
-each element is unpacked as in \method{unpack_farray()} above.
-\end{methoddesc}
-
-
-\subsection{Exceptions \label{xdr-exceptions}}
-
-Exceptions in this module are coded as class instances:
-
-\begin{excdesc}{Error}
-The base exception class. \exception{Error} has a single public data
-member \member{msg} containing the description of the error.
-\end{excdesc}
-
-\begin{excdesc}{ConversionError}
-Class derived from \exception{Error}. Contains no additional instance
-variables.
-\end{excdesc}
-
-Here is an example of how you would catch one of these exceptions:
-
-\begin{verbatim}
-import xdrlib
-p = xdrlib.Packer()
-try:
- p.pack_double(8.01)
-except xdrlib.ConversionError as instance:
- print 'packing the double failed:', instance.msg
-\end{verbatim}
diff --git a/Doc/lib/libxmlrpclib.tex b/Doc/lib/libxmlrpclib.tex
deleted file mode 100644
index 22f29b8..0000000
--- a/Doc/lib/libxmlrpclib.tex
+++ /dev/null
@@ -1,391 +0,0 @@
-\section{\module{xmlrpclib} --- XML-RPC client access}
-
-\declaremodule{standard}{xmlrpclib}
-\modulesynopsis{XML-RPC client access.}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
-
-% Not everything is documented yet. It might be good to describe
-% Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
-
-\versionadded{2.2}
-
-XML-RPC is a Remote Procedure Call method that uses XML passed via
-HTTP as a transport. With it, a client can call methods with
-parameters on a remote server (the server is named by a URI) and get back
-structured data. This module supports writing XML-RPC client code; it
-handles all the details of translating between conformable Python
-objects and XML on the wire.
-
-\begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{,
- encoding\optional{, verbose\optional{,
- allow_none\optional{, use_datetime}}}}}}
-A \class{ServerProxy} instance is an object that manages communication
-with a remote XML-RPC server. The required first argument is a URI
-(Uniform Resource Indicator), and will normally be the URL of the
-server. The optional second argument is a transport factory instance;
-by default it is an internal \class{SafeTransport} instance for https:
-URLs and an internal HTTP \class{Transport} instance otherwise. The
-optional third argument is an encoding, by default UTF-8. The optional
-fourth argument is a debugging flag. If \var{allow_none} is true,
-the Python constant \code{None} will be translated into XML; the
-default behaviour is for \code{None} to raise a \exception{TypeError}.
-This is a commonly-used extension to the XML-RPC specification, but isn't
-supported by all clients and servers; see
-\url{http://ontosys.com/xml-rpc/extensions.php} for a description.
-The \var{use_datetime} flag can be used to cause date/time values to be
-presented as \class{\refmodule{datetime}.datetime} objects; this is false
-by default. \class{\refmodule{datetime}.datetime},
-\class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time}
-objects may be passed to calls. \class{\refmodule{datetime}.date} objects
-are converted with a time of ``00:00:00''.
-\class{\refmodule{datetime}.time} objects are converted using today's date.
-
-Both the HTTP and HTTPS transports support the URL syntax extension for
-HTTP Basic Authentication: \code{http://user:pass@host:port/path}. The
-\code{user:pass} portion will be base64-encoded as an HTTP `Authorization'
-header, and sent to the remote server as part of the connection process
-when invoking an XML-RPC method. You only need to use this if the
-remote server requires a Basic Authentication user and password.
-
-The returned instance is a proxy object with methods that can be used
-to invoke corresponding RPC calls on the remote server. If the remote
-server supports the introspection API, the proxy can also be used to query
-the remote server for the methods it supports (service discovery) and
-fetch other server-associated metadata.
-
-\class{ServerProxy} instance methods take Python basic types and objects as
-arguments and return Python basic types and classes. Types that are
-conformable (e.g. that can be marshalled through XML), include the
-following (and except where noted, they are unmarshalled as the same
-Python type):
-
-\begin{tableii}{l|l}{constant}{Name}{Meaning}
- \lineii{boolean}{The \constant{True} and \constant{False} constants}
- \lineii{integers}{Pass in directly}
- \lineii{floating-point numbers}{Pass in directly}
- \lineii{strings}{Pass in directly}
- \lineii{arrays}{Any Python sequence type containing conformable
- elements. Arrays are returned as lists}
- \lineii{structures}{A Python dictionary. Keys must be strings,
- values may be any conformable type. Objects
- of user-defined classes can be passed in;
- only their \var{__dict__} attribute is
- transmitted.}
- \lineii{dates}{in seconds since the epoch (pass in an instance of the
- \class{DateTime} class) or a
- \class{\refmodule{datetime}.datetime},
- \class{\refmodule{datetime}.date} or
- \class{\refmodule{datetime}.time} instance}
- \lineii{binary data}{pass in an instance of the \class{Binary}
- wrapper class}
-\end{tableii}
-
-This is the full set of data types supported by XML-RPC. Method calls
-may also raise a special \exception{Fault} instance, used to signal
-XML-RPC server errors, or \exception{ProtocolError} used to signal an
-error in the HTTP/HTTPS transport layer. Both \exception{Fault} and
-\exception{ProtocolError} derive from a base class called
-\exception{Error}. Note that even though starting with Python 2.2 you
-can subclass builtin types, the xmlrpclib module currently does not
-marshal instances of such subclasses.
-
-When passing strings, characters special to XML such as \samp{<},
-\samp{>}, and \samp{\&} will be automatically escaped. However, it's
-the caller's responsibility to ensure that the string is free of
-characters that aren't allowed in XML, such as the control characters
-with ASCII values between 0 and 31 (except, of course, tab, newline and
-carriage return); failing to do this will result in
-an XML-RPC request that isn't well-formed XML. If you have to pass
-arbitrary strings via XML-RPC, use the \class{Binary} wrapper class
-described below.
-
-\class{Server} is retained as an alias for \class{ServerProxy} for backwards
-compatibility. New code should use \class{ServerProxy}.
-
-\versionchanged[The \var{use_datetime} flag was added]{2.5}
-
-\versionchanged[Instances of new-style classes can be passed in
-if they have an \var{__dict__} attribute and don't have a base class
-that is marshalled in a special way]{2.6}
-\end{classdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html]
- {XML-RPC HOWTO}{A good description of XML operation and
- client software in several languages. Contains pretty much
- everything an XML-RPC client developer needs to know.}
- \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php]
- {XML-RPC Hacks page}{Extensions for various open-source
- libraries to support introspection and multicall.}
-\end{seealso}
-
-
-\subsection{ServerProxy Objects \label{serverproxy-objects}}
-
-A \class{ServerProxy} instance has a method corresponding to
-each remote procedure call accepted by the XML-RPC server. Calling
-the method performs an RPC, dispatched by both name and argument
-signature (e.g. the same method name can be overloaded with multiple
-argument signatures). The RPC finishes by returning a value, which
-may be either returned data in a conformant type or a \class{Fault} or
-\class{ProtocolError} object indicating an error.
-
-Servers that support the XML introspection API support some common
-methods grouped under the reserved \member{system} member:
-
-\begin{methoddesc}[ServerProxy]{system.listMethods}{}
-This method returns a list of strings, one for each (non-system)
-method supported by the XML-RPC server.
-\end{methoddesc}
-
-\begin{methoddesc}[ServerProxy]{system.methodSignature}{name}
-This method takes one parameter, the name of a method implemented by
-the XML-RPC server.It returns an array of possible signatures for this
-method. A signature is an array of types. The first of these types is
-the return type of the method, the rest are parameters.
-
-Because multiple signatures (ie. overloading) is permitted, this method
-returns a list of signatures rather than a singleton.
-
-Signatures themselves are restricted to the top level parameters
-expected by a method. For instance if a method expects one array of
-structs as a parameter, and it returns a string, its signature is
-simply "string, array". If it expects three integers and returns a
-string, its signature is "string, int, int, int".
-
-If no signature is defined for the method, a non-array value is
-returned. In Python this means that the type of the returned
-value will be something other that list.
-\end{methoddesc}
-
-\begin{methoddesc}[ServerProxy]{system.methodHelp}{name}
-This method takes one parameter, the name of a method implemented by
-the XML-RPC server. It returns a documentation string describing the
-use of that method. If no such string is available, an empty string is
-returned. The documentation string may contain HTML markup.
-\end{methoddesc}
-
-Introspection methods are currently supported by servers written in
-PHP, C and Microsoft .NET. Partial introspection support is included
-in recent updates to UserLand Frontier. Introspection support for
-Perl, Python and Java is available at the \ulink{XML-RPC
-Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} page.
-
-
-\subsection{Boolean Objects \label{boolean-objects}}
-
-This class may be initialized from any Python value; the instance
-returned depends only on its truth value. It supports various Python
-operators through \method{__cmp__()}, \method{__repr__()},
-\method{__int__()}, and \method{__bool__()} methods, all
-implemented in the obvious ways.
-
-It also has the following method, supported mainly for internal use by
-the unmarshalling code:
-
-\begin{methoddesc}[Boolean]{encode}{out}
-Write the XML-RPC encoding of this Boolean item to the out stream object.
-\end{methoddesc}
-
-
-\subsection{DateTime Objects \label{datetime-objects}}
-
-This class may be initialized with seconds since the epoch, a time tuple, an
-ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime},
-{}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time}
-instance. It has the following methods, supported mainly for internal use
-by the marshalling/unmarshalling code:
-
-\begin{methoddesc}[DateTime]{decode}{string}
-Accept a string as the instance's new time value.
-\end{methoddesc}
-
-\begin{methoddesc}[DateTime]{encode}{out}
-Write the XML-RPC encoding of this \class{DateTime} item to the
-\var{out} stream object.
-\end{methoddesc}
-
-It also supports certain of Python's built-in operators through
-\method{__cmp__()} and \method{__repr__()} methods.
-
-
-\subsection{Binary Objects \label{binary-objects}}
-
-This class may be initialized from string data (which may include NULs).
-The primary access to the content of a \class{Binary} object is
-provided by an attribute:
-
-\begin{memberdesc}[Binary]{data}
-The binary data encapsulated by the \class{Binary} instance. The data
-is provided as an 8-bit string.
-\end{memberdesc}
-
-\class{Binary} objects have the following methods, supported mainly
-for internal use by the marshalling/unmarshalling code:
-
-\begin{methoddesc}[Binary]{decode}{string}
-Accept a base64 string and decode it as the instance's new data.
-\end{methoddesc}
-
-\begin{methoddesc}[Binary]{encode}{out}
-Write the XML-RPC base 64 encoding of this binary item to the out
-stream object.
-\end{methoddesc}
-
-It also supports certain of Python's built-in operators through a
-\method{__cmp__()} method.
-
-
-\subsection{Fault Objects \label{fault-objects}}
-
-A \class{Fault} object encapsulates the content of an XML-RPC fault tag.
-Fault objects have the following members:
-
-\begin{memberdesc}[Fault]{faultCode}
-A string indicating the fault type.
-\end{memberdesc}
-
-\begin{memberdesc}[Fault]{faultString}
-A string containing a diagnostic message associated with the fault.
-\end{memberdesc}
-
-
-\subsection{ProtocolError Objects \label{protocol-error-objects}}
-
-A \class{ProtocolError} object describes a protocol error in the
-underlying transport layer (such as a 404 `not found' error if the
-server named by the URI does not exist). It has the following
-members:
-
-\begin{memberdesc}[ProtocolError]{url}
-The URI or URL that triggered the error.
-\end{memberdesc}
-
-\begin{memberdesc}[ProtocolError]{errcode}
-The error code.
-\end{memberdesc}
-
-\begin{memberdesc}[ProtocolError]{errmsg}
-The error message or diagnostic string.
-\end{memberdesc}
-
-\begin{memberdesc}[ProtocolError]{headers}
-A string containing the headers of the HTTP/HTTPS request that
-triggered the error.
-\end{memberdesc}
-
-\subsection{MultiCall Objects}
-
-\versionadded{2.4}
-
-In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach
-is presented to encapsulate multiple calls to a remote server into a
-single request.
-
-\begin{classdesc}{MultiCall}{server}
-
-Create an object used to boxcar method calls. \var{server} is the
-eventual target of the call. Calls can be made to the result object,
-but they will immediately return \code{None}, and only store the
-call name and parameters in the \class{MultiCall} object. Calling
-the object itself causes all stored calls to be transmitted as
-a single \code{system.multicall} request. The result of this call
-is a generator; iterating over this generator yields the individual
-results.
-
-\end{classdesc}
-
-A usage example of this class is
-
-\begin{verbatim}
-multicall = MultiCall(server_proxy)
-multicall.add(2,3)
-multicall.get_address("Guido")
-add_result, address = multicall()
-\end{verbatim}
-
-\subsection{Convenience Functions}
-
-\begin{funcdesc}{boolean}{value}
-Convert any Python value to one of the XML-RPC Boolean constants,
-\code{True} or \code{False}.
-\end{funcdesc}
-
-\begin{funcdesc}{dumps}{params\optional{, methodname\optional{,
- methodresponse\optional{, encoding\optional{,
- allow_none}}}}}
-Convert \var{params} into an XML-RPC request.
-or into a response if \var{methodresponse} is true.
-\var{params} can be either a tuple of arguments or an instance of the
-\exception{Fault} exception class. If \var{methodresponse} is true,
-only a single value can be returned, meaning that \var{params} must be of length 1.
-\var{encoding}, if supplied, is the encoding to use in the generated
-XML; the default is UTF-8. Python's \constant{None} value cannot be
-used in standard XML-RPC; to allow using it via an extension,
-provide a true value for \var{allow_none}.
-\end{funcdesc}
-
-\begin{funcdesc}{loads}{data\optional{, use_datetime}}
-Convert an XML-RPC request or response into Python objects, a
-\code{(\var{params}, \var{methodname})}. \var{params} is a tuple of argument; \var{methodname}
-is a string, or \code{None} if no method name is present in the packet.
-If the XML-RPC packet represents a fault condition, this
-function will raise a \exception{Fault} exception.
-The \var{use_datetime} flag can be used to cause date/time values to be
-presented as \class{\refmodule{datetime}.datetime} objects; this is false
-by default.
-Note that even if you call an XML-RPC method with
-\class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time}
-objects, they are converted to \class{DateTime} objects internally, so only
-{}\class{\refmodule{datetime}.datetime} objects will be returned.
-
-\versionchanged[The \var{use_datetime} flag was added]{2.5}
-\end{funcdesc}
-
-
-
-\subsection{Example of Client Usage \label{xmlrpc-client-example}}
-
-\begin{verbatim}
-# simple test program (from the XML-RPC specification)
-from xmlrpclib import ServerProxy, Error
-
-# server = ServerProxy("http://localhost:8000") # local server
-server = ServerProxy("http://betty.userland.com")
-
-print server
-
-try:
- print server.examples.getStateName(41)
-except Error as v:
- print "ERROR", v
-\end{verbatim}
-
-To access an XML-RPC server through a proxy, you need to define
-a custom transport. The following example,
-written by NoboNobo, % fill in original author's name if we ever learn it
-shows how:
-
-% Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
-\begin{verbatim}
-import xmlrpclib, httplib
-
-class ProxiedTransport(xmlrpclib.Transport):
- def set_proxy(self, proxy):
- self.proxy = proxy
- def make_connection(self, host):
- self.realhost = host
- h = httplib.HTTP(self.proxy)
- return h
- def send_request(self, connection, handler, request_body):
- connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))
- def send_host(self, connection, host):
- connection.putheader('Host', self.realhost)
-
-p = ProxiedTransport()
-p.set_proxy('proxy-server:8080')
-server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p)
-print server.currentTime.getCurrentTime()
-\end{verbatim}
diff --git a/Doc/lib/libzipfile.tex b/Doc/lib/libzipfile.tex
deleted file mode 100644
index 366cee9..0000000
--- a/Doc/lib/libzipfile.tex
+++ /dev/null
@@ -1,371 +0,0 @@
-\section{\module{zipfile} ---
- Work with ZIP archives}
-
-\declaremodule{standard}{zipfile}
-\modulesynopsis{Read and write ZIP-format archive files.}
-\moduleauthor{James C. Ahlstrom}{jim@interet.com}
-\sectionauthor{James C. Ahlstrom}{jim@interet.com}
-% LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>
-
-\versionadded{1.6}
-
-The ZIP file format is a common archive and compression standard.
-This module provides tools to create, read, write, append, and list a
-ZIP file. Any advanced use of this module will require an
-understanding of the format, as defined in
-\citetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
-{PKZIP Application Note}.
-
-This module does not currently handle ZIP files which have appended
-comments, or multi-disk ZIP files. It can handle ZIP files that use
-the ZIP64 extensions (that is ZIP files that are more than 4 GByte in
-size). It supports decryption of encrypted files in ZIP archives, but
-it cannot currently create an encrypted file.
-
-The available attributes of this module are:
-
-\begin{excdesc}{BadZipfile}
- The error raised for bad ZIP files (old name: \code{zipfile.error}).
-\end{excdesc}
-
-\begin{excdesc}{LargeZipFile}
- The error raised when a ZIP file would require ZIP64 functionality but that
- has not been enabled.
-\end{excdesc}
-
-\begin{classdesc*}{ZipFile}
- The class for reading and writing ZIP files. See
- ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
- constructor details.
-\end{classdesc*}
-
-\begin{classdesc*}{PyZipFile}
- Class for creating ZIP archives containing Python libraries.
-\end{classdesc*}
-
-\begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
- Class used to represent information about a member of an archive.
- Instances of this class are returned by the \method{getinfo()} and
- \method{infolist()} methods of \class{ZipFile} objects. Most users
- of the \module{zipfile} module will not need to create these, but
- only use those created by this module.
- \var{filename} should be the full name of the archive member, and
- \var{date_time} should be a tuple containing six fields which
- describe the time of the last modification to the file; the fields
- are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.''
-\end{classdesc}
-
-\begin{funcdesc}{is_zipfile}{filename}
- Returns \code{True} if \var{filename} is a valid ZIP file based on its magic
- number, otherwise returns \code{False}. This module does not currently
- handle ZIP files which have appended comments.
-\end{funcdesc}
-
-\begin{datadesc}{ZIP_STORED}
- The numeric constant for an uncompressed archive member.
-\end{datadesc}
-
-\begin{datadesc}{ZIP_DEFLATED}
- The numeric constant for the usual ZIP compression method. This
- requires the zlib module. No other compression methods are
- currently supported.
-\end{datadesc}
-
-
-\begin{seealso}
- \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
- {PKZIP Application Note}{Documentation on the ZIP file format by
- Phil Katz, the creator of the format and algorithms used.}
-
- \seetitle[http://www.info-zip.org/pub/infozip/]{Info-ZIP Home Page}{
- Information about the Info-ZIP project's ZIP archive
- programs and development libraries.}
-\end{seealso}
-
-
-\subsection{ZipFile Objects \label{zipfile-objects}}
-
-\begin{classdesc}{ZipFile}{file\optional{, mode\optional{, compression\optional{, allowZip64}}}}
- Open a ZIP file, where \var{file} can be either a path to a file
- (a string) or a file-like object. The \var{mode} parameter
- should be \code{'r'} to read an existing file, \code{'w'} to
- truncate and write a new file, or \code{'a'} to append to an
- existing file. If \var{mode} is \code{'a'} and \var{file}
- refers to an existing ZIP file, then additional files are added to
- it. If \var{file} does not refer to a ZIP file, then a new ZIP
- archive is appended to the file. This is meant for adding a ZIP
- archive to another file, such as \file{python.exe}. Using
-
-\begin{verbatim}
-cat myzip.zip >> python.exe
-\end{verbatim}
-
- also works, and at least \program{WinZip} can read such files.
- If \var{mode} is \code{a} and the file does not exist at all,
- it is created.
- \var{compression} is the ZIP compression method to use when writing
- the archive, and should be \constant{ZIP_STORED} or
- \constant{ZIP_DEFLATED}; unrecognized values will cause
- \exception{RuntimeError} to be raised. If \constant{ZIP_DEFLATED}
- is specified but the \refmodule{zlib} module is not available,
- \exception{RuntimeError} is also raised. The default is
- \constant{ZIP_STORED}.
- If \var{allowZip64} is \code{True} zipfile will create ZIP files that use
- the ZIP64 extensions when the zipfile is larger than 2 GB. If it is
- false (the default) \module{zipfile} will raise an exception when the
- ZIP file would require ZIP64 extensions. ZIP64 extensions are disabled by
- default because the default \program{zip} and \program{unzip} commands on
- \UNIX{} (the InfoZIP utilities) don't support these extensions.
-
- \versionchanged[If the file does not exist, it is created if the
- mode is 'a']{2.6}
-\end{classdesc}
-
-\begin{methoddesc}{close}{}
- Close the archive file. You must call \method{close()} before
- exiting your program or essential records will not be written.
-\end{methoddesc}
-
-\begin{methoddesc}{getinfo}{name}
- Return a \class{ZipInfo} object with information about the archive
- member \var{name}. Calling \method{getinfo()} for a name not currently
- contained in the archive will raise a \exception{KeyError}.
-\end{methoddesc}
-
-\begin{methoddesc}{infolist}{}
- Return a list containing a \class{ZipInfo} object for each member of
- the archive. The objects are in the same order as their entries in
- the actual ZIP file on disk if an existing archive was opened.
-\end{methoddesc}
-
-\begin{methoddesc}{namelist}{}
- Return a list of archive members by name.
-\end{methoddesc}
-
-\begin{methoddesc}{open}{name\optional{, mode\optional{, pwd}}}
- Extract a member from the archive as a file-like object (ZipExtFile).
- \var{name} is the name of the file in the archive. The \var{mode}
- parameter, if included, must be one of the following: \code{'r'} (the
- default), \code{'U'}, or \code{'rU'}. Choosing \code{'U'} or
- \code{'rU'} will enable universal newline support in the read-only
- object. \var{pwd} is the password used for encrypted files. Calling
- \method{open()} on a closed ZipFile will raise a
- \exception{RuntimeError}.
- \begin{notice}
- The file-like object is read-only and provides the following methods:
- \method{read()}, \method{readline()}, \method{readlines()},
- \method{__iter__()}, \method{next()}.
- \end{notice}
- \begin{notice}
- If the ZipFile was created by passing in a file-like object as the
- first argument to the constructor, then the object returned by
- \method{open()} shares the ZipFile's file pointer. Under these
- circumstances, the object returned by \method{open()} should not
- be used after any additional operations are performed on the
- ZipFile object. If the ZipFile was created by passing in a string
- (the filename) as the first argument to the constructor, then
- \method{open()} will create a new file object that will be held
- by the ZipExtFile, allowing it to operate independently of the
- ZipFile.
- \end{notice}
-
- \versionadded{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{printdir}{}
- Print a table of contents for the archive to \code{sys.stdout}.
-\end{methoddesc}
-
-\begin{methoddesc}{setpassword}{pwd}
- Set \var{pwd} as default password to extract encrypted files.
- \versionadded{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{read}{name\optional{, pwd}}
- Return the bytes of the file in the archive. The archive must be
- open for read or append. \var{pwd} is the password used for encrypted
- files and, if specified, it will override the default password set with
- \method{setpassword()}. Calling \method{read()} on a closed ZipFile
- will raise a \exception{RuntimeError}.
-
- \versionchanged[\var{pwd} was added]{2.6}
-\end{methoddesc}
-
-\begin{methoddesc}{testzip}{}
- Read all the files in the archive and check their CRC's and file
- headers. Return the name of the first bad file, or else return \code{None}.
- Calling \method{testzip()} on a closed ZipFile will raise a
- \exception{RuntimeError}.
-\end{methoddesc}
-
-\begin{methoddesc}{write}{filename\optional{, arcname\optional{,
- compress_type}}}
- Write the file named \var{filename} to the archive, giving it the
- archive name \var{arcname} (by default, this will be the same as
- \var{filename}, but without a drive letter and with leading path
- separators removed). If given, \var{compress_type} overrides the
- value given for the \var{compression} parameter to the constructor
- for the new entry. The archive must be open with mode \code{'w'}
- or \code{'a'} -- calling \method{write()} on a ZipFile created with
- mode \code{'r'} will raise a \exception{RuntimeError}. Calling
- \method{write()} on a closed ZipFile will raise a
- \exception{RuntimeError}.
-
- \note{There is no official file name encoding for ZIP files.
- If you have unicode file names, please convert them to byte strings
- in your desired encoding before passing them to \method{write()}.
- WinZip interprets all file names as encoded in CP437, also known
- as DOS Latin.}
-
- \note{Archive names should be relative to the archive root, that is,
- they should not start with a path separator.}
-
- \note{If \code{arcname} (or \code{filename}, if \code{arcname} is
- not given) contains a null byte, the name of the file in the archive will
- be truncated at the null byte.}
-
-\end{methoddesc}
-
-\begin{methoddesc}{writestr}{zinfo_or_arcname, bytes}
- Write the string \var{bytes} to the archive; \var{zinfo_or_arcname}
- is either the file name it will be given in the archive, or a
- \class{ZipInfo} instance. If it's an instance, at least the
- filename, date, and time must be given. If it's a name, the date
- and time is set to the current date and time. The archive must be
- opened with mode \code{'w'} or \code{'a'} -- calling
- \method{writestr()} on a ZipFile created with mode \code{'r'}
- will raise a \exception{RuntimeError}. Calling \method{writestr()}
- on a closed ZipFile will raise a \exception{RuntimeError}.
-\end{methoddesc}
-
-
-The following data attribute is also available:
-
-\begin{memberdesc}{debug}
- The level of debug output to use. This may be set from \code{0}
- (the default, no output) to \code{3} (the most output). Debugging
- information is written to \code{sys.stdout}.
-\end{memberdesc}
-
-
-\subsection{PyZipFile Objects \label{pyzipfile-objects}}
-
-The \class{PyZipFile} constructor takes the same parameters as the
-\class{ZipFile} constructor. Instances have one method in addition to
-those of \class{ZipFile} objects.
-
-\begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
- Search for files \file{*.py} and add the corresponding file to the
- archive. The corresponding file is a \file{*.pyo} file if
- available, else a \file{*.pyc} file, compiling if necessary. If the
- pathname is a file, the filename must end with \file{.py}, and just
- the (corresponding \file{*.py[co]}) file is added at the top level
- (no path information). If the pathname is a file that does not end with
- \file{.py}, a \exception{RuntimeError} will be raised. If it is a
- directory, and the directory is not a package directory, then all the
- files \file{*.py[co]} are added at the top level. If the directory is
- a package directory, then all \file{*.py[co]} are added under the package
- name as a file path, and if any subdirectories are package directories, all
- of these are added recursively. \var{basename} is intended for
- internal use only. The \method{writepy()} method makes archives
- with file names like this:
-
-\begin{verbatim}
- string.pyc # Top level name
- test/__init__.pyc # Package directory
- test/testall.pyc # Module test.testall
- test/bogus/__init__.pyc # Subpackage directory
- test/bogus/myfile.pyc # Submodule test.bogus.myfile
-\end{verbatim}
-\end{methoddesc}
-
-
-\subsection{ZipInfo Objects \label{zipinfo-objects}}
-
-Instances of the \class{ZipInfo} class are returned by the
-\method{getinfo()} and \method{infolist()} methods of
-\class{ZipFile} objects. Each object stores information about a
-single member of the ZIP archive.
-
-Instances have the following attributes:
-
-\begin{memberdesc}[ZipInfo]{filename}
- Name of the file in the archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{date_time}
- The time and date of the last modification to the archive
- member. This is a tuple of six values:
-
-\begin{tableii}{c|l}{code}{Index}{Value}
- \lineii{0}{Year}
- \lineii{1}{Month (one-based)}
- \lineii{2}{Day of month (one-based)}
- \lineii{3}{Hours (zero-based)}
- \lineii{4}{Minutes (zero-based)}
- \lineii{5}{Seconds (zero-based)}
-\end{tableii}
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{compress_type}
- Type of compression for the archive member.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{comment}
- Comment for the individual archive member.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{extra}
- Expansion field data. The
- \citetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
- {PKZIP Application Note} contains some comments on the internal
- structure of the data contained in this string.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{create_system}
- System which created ZIP archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{create_version}
- PKZIP version which created ZIP archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{extract_version}
- PKZIP version needed to extract archive.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{reserved}
- Must be zero.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{flag_bits}
- ZIP flag bits.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{volume}
- Volume number of file header.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{internal_attr}
- Internal attributes.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{external_attr}
- External file attributes.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{header_offset}
- Byte offset to the file header.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{CRC}
- CRC-32 of the uncompressed file.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{compress_size}
- Size of the compressed data.
-\end{memberdesc}
-
-\begin{memberdesc}[ZipInfo]{file_size}
- Size of the uncompressed file.
-\end{memberdesc}
diff --git a/Doc/lib/libzipimport.tex b/Doc/lib/libzipimport.tex
deleted file mode 100644
index 8ebe3c5..0000000
--- a/Doc/lib/libzipimport.tex
+++ /dev/null
@@ -1,128 +0,0 @@
-\section{\module{zipimport} ---
- Import modules from Zip archives}
-
-\declaremodule{standard}{zipimport}
-\modulesynopsis{support for importing Python modules from ZIP archives.}
-\moduleauthor{Just van Rossum}{just@letterror.com}
-
-\versionadded{2.3}
-
-This module adds the ability to import Python modules (\file{*.py},
-\file{*.py[co]}) and packages from ZIP-format archives. It is usually
-not needed to use the \module{zipimport} module explicitly; it is
-automatically used by the builtin \keyword{import} mechanism for
-\code{sys.path} items that are paths to ZIP archives.
-
-Typically, \code{sys.path} is a list of directory names as strings. This
-module also allows an item of \code{sys.path} to be a string naming a ZIP
-file archive. The ZIP archive can contain a subdirectory structure to
-support package imports, and a path within the archive can be specified to
-only import from a subdirectory. For example, the path
-\file{/tmp/example.zip/lib/} would only import from the
-\file{lib/} subdirectory within the archive.
-
-Any files may be present in the ZIP archive, but only files \file{.py} and
-\file{.py[co]} are available for import. ZIP import of dynamic modules
-(\file{.pyd}, \file{.so}) is disallowed. Note that if an archive only
-contains \file{.py} files, Python will not attempt to modify the archive
-by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that
-if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather
-slow.
-
-The available attributes of this module are:
-
-\begin{excdesc}{ZipImportError}
- Exception raised by zipimporter objects. It's a subclass of
- \exception{ImportError}, so it can be caught as \exception{ImportError},
- too.
-\end{excdesc}
-
-\begin{classdesc*}{zipimporter}
- The class for importing ZIP files. See
- ``\citetitle{zipimporter Objects}'' (section \ref{zipimporter-objects})
- for constructor details.
-\end{classdesc*}
-
-
-\begin{seealso}
- \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
- {PKZIP Application Note}{Documentation on the ZIP file format by
- Phil Katz, the creator of the format and algorithms used.}
-
- \seepep{0273}{Import Modules from Zip Archives}{Written by James C.
- Ahlstrom, who also provided an implementation. Python 2.3
- follows the specification in PEP 273, but uses an
- implementation written by Just van Rossum that uses the import
- hooks described in PEP 302.}
-
- \seepep{0302}{New Import Hooks}{The PEP to add the import hooks that help
- this module work.}
-\end{seealso}
-
-
-\subsection{zipimporter Objects \label{zipimporter-objects}}
-
-\begin{classdesc}{zipimporter}{archivepath}
- Create a new zipimporter instance. \var{archivepath} must be a path to
- a zipfile. \exception{ZipImportError} is raised if \var{archivepath}
- doesn't point to a valid ZIP archive.
-\end{classdesc}
-
-\begin{methoddesc}{find_module}{fullname\optional{, path}}
- Search for a module specified by \var{fullname}. \var{fullname} must be
- the fully qualified (dotted) module name. It returns the zipimporter
- instance itself if the module was found, or \constant{None} if it wasn't.
- The optional \var{path} argument is ignored---it's there for
- compatibility with the importer protocol.
-\end{methoddesc}
-
-\begin{methoddesc}{get_code}{fullname}
- Return the code object for the specified module. Raise
- \exception{ZipImportError} if the module couldn't be found.
-\end{methoddesc}
-
-\begin{methoddesc}{get_data}{pathname}
- Return the data associated with \var{pathname}. Raise \exception{IOError}
- if the file wasn't found.
-\end{methoddesc}
-
-\begin{methoddesc}{get_source}{fullname}
- Return the source code for the specified module. Raise
- \exception{ZipImportError} if the module couldn't be found, return
- \constant{None} if the archive does contain the module, but has
- no source for it.
-\end{methoddesc}
-
-\begin{methoddesc}{is_package}{fullname}
- Return True if the module specified by \var{fullname} is a package.
- Raise \exception{ZipImportError} if the module couldn't be found.
-\end{methoddesc}
-
-\begin{methoddesc}{load_module}{fullname}
- Load the module specified by \var{fullname}. \var{fullname} must be the
- fully qualified (dotted) module name. It returns the imported
- module, or raises \exception{ZipImportError} if it wasn't found.
-\end{methoddesc}
-
-\subsection{Examples}
-\nodename{zipimport Examples}
-
-Here is an example that imports a module from a ZIP archive - note that
-the \module{zipimport} module is not explicitly used.
-
-\begin{verbatim}
-$ unzip -l /tmp/example.zip
-Archive: /tmp/example.zip
- Length Date Time Name
- -------- ---- ---- ----
- 8467 11-26-02 22:30 jwzthreading.py
- -------- -------
- 8467 1 file
-$ ./python
-Python 2.3 (#1, Aug 1 2003, 19:54:32)
->>> import sys
->>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path
->>> import jwzthreading
->>> jwzthreading.__file__
-'/tmp/example.zip/jwzthreading.py'
-\end{verbatim}
diff --git a/Doc/lib/libzlib.tex b/Doc/lib/libzlib.tex
deleted file mode 100644
index 3cc7b3c..0000000
--- a/Doc/lib/libzlib.tex
+++ /dev/null
@@ -1,197 +0,0 @@
-\section{\module{zlib} ---
- Compression compatible with \program{gzip}}
-
-\declaremodule{builtin}{zlib}
-\modulesynopsis{Low-level interface to compression and decompression
- routines compatible with \program{gzip}.}
-
-
-For applications that require data compression, the functions in this
-module allow compression and decompression, using the zlib library.
-The zlib library has its own home page at \url{http://www.zlib.net}.
-There are known incompatibilities between the Python module and
-versions of the zlib library earlier than 1.1.3; 1.1.3 has a security
-vulnerability, so we recommend using 1.1.4 or later.
-
-zlib's functions have many options and often need to be used in a
-particular order. This documentation doesn't attempt to cover all of
-the permutations; consult the zlib manual at
-\url{http://www.zlib.net/manual.html} for authoritative information.
-
-The available exception and functions in this module are:
-
-\begin{excdesc}{error}
- Exception raised on compression and decompression errors.
-\end{excdesc}
-
-
-\begin{funcdesc}{adler32}{string\optional{, value}}
- Computes a Adler-32 checksum of \var{string}. (An Adler-32
- checksum is almost as reliable as a CRC32 but can be computed much
- more quickly.) If \var{value} is present, it is used as the
- starting value of the checksum; otherwise, a fixed default value is
- used. This allows computing a running checksum over the
- concatenation of several input strings. The algorithm is not
- cryptographically strong, and should not be used for
- authentication or digital signatures. Since the algorithm is
- designed for use as a checksum algorithm, it is not suitable for
- use as a general hash algorithm.
-\end{funcdesc}
-
-\begin{funcdesc}{compress}{string\optional{, level}}
- Compresses the data in \var{string}, returning a string contained
- compressed data. \var{level} is an integer from \code{1} to
- \code{9} controlling the level of compression; \code{1} is fastest
- and produces the least compression, \code{9} is slowest and produces
- the most. The default value is \code{6}. Raises the
- \exception{error} exception if any error occurs.
-\end{funcdesc}
-
-\begin{funcdesc}{compressobj}{\optional{level}}
- Returns a compression object, to be used for compressing data streams
- that won't fit into memory at once. \var{level} is an integer from
- \code{1} to \code{9} controlling the level of compression; \code{1} is
- fastest and produces the least compression, \code{9} is slowest and
- produces the most. The default value is \code{6}.
-\end{funcdesc}
-
-\begin{funcdesc}{crc32}{string\optional{, value}}
- Computes a CRC (Cyclic Redundancy Check)%
- \index{Cyclic Redundancy Check}
- \index{checksum!Cyclic Redundancy Check}
- checksum of \var{string}. If
- \var{value} is present, it is used as the starting value of the
- checksum; otherwise, a fixed default value is used. This allows
- computing a running checksum over the concatenation of several
- input strings. The algorithm is not cryptographically strong, and
- should not be used for authentication or digital signatures. Since
- the algorithm is designed for use as a checksum algorithm, it is not
- suitable for use as a general hash algorithm.
-\end{funcdesc}
-
-\begin{funcdesc}{decompress}{string\optional{, wbits\optional{, bufsize}}}
- Decompresses the data in \var{string}, returning a string containing
- the uncompressed data. The \var{wbits} parameter controls the size of
- the window buffer. If \var{bufsize} is given, it is used as the
- initial size of the output buffer. Raises the \exception{error}
- exception if any error occurs.
-
-The absolute value of \var{wbits} is the base two logarithm of the
-size of the history buffer (the ``window size'') used when compressing
-data. Its absolute value should be between 8 and 15 for the most
-recent versions of the zlib library, larger values resulting in better
-compression at the expense of greater memory usage. The default value
-is 15. When \var{wbits} is negative, the standard
-\program{gzip} header is suppressed; this is an undocumented feature
-of the zlib library, used for compatibility with \program{unzip}'s
-compression file format.
-
-\var{bufsize} is the initial size of the buffer used to hold
-decompressed data. If more space is required, the buffer size will be
-increased as needed, so you don't have to get this value exactly
-right; tuning it will only save a few calls to \cfunction{malloc()}. The
-default size is 16384.
-
-\end{funcdesc}
-
-\begin{funcdesc}{decompressobj}{\optional{wbits}}
- Returns a decompression object, to be used for decompressing data
- streams that won't fit into memory at once. The \var{wbits}
- parameter controls the size of the window buffer.
-\end{funcdesc}
-
-Compression objects support the following methods:
-
-\begin{methoddesc}[Compress]{compress}{string}
-Compress \var{string}, returning a string containing compressed data
-for at least part of the data in \var{string}. This data should be
-concatenated to the output produced by any preceding calls to the
-\method{compress()} method. Some input may be kept in internal buffers
-for later processing.
-\end{methoddesc}
-
-\begin{methoddesc}[Compress]{flush}{\optional{mode}}
-All pending input is processed, and a string containing the remaining
-compressed output is returned. \var{mode} can be selected from the
-constants \constant{Z_SYNC_FLUSH}, \constant{Z_FULL_FLUSH}, or
-\constant{Z_FINISH}, defaulting to \constant{Z_FINISH}. \constant{Z_SYNC_FLUSH} and
-\constant{Z_FULL_FLUSH} allow compressing further strings of data, while
-\constant{Z_FINISH} finishes the compressed stream and
-prevents compressing any more data. After calling
-\method{flush()} with \var{mode} set to \constant{Z_FINISH}, the
-\method{compress()} method cannot be called again; the only realistic
-action is to delete the object.
-\end{methoddesc}
-
-\begin{methoddesc}[Compress]{copy}{}
-Returns a copy of the compression object. This can be used to efficiently
-compress a set of data that share a common initial prefix.
-\versionadded{2.5}
-\end{methoddesc}
-
-Decompression objects support the following methods, and two attributes:
-
-\begin{memberdesc}[Decompress]{unused_data}
-A string which contains any bytes past the end of the compressed data.
-That is, this remains \code{""} until the last byte that contains
-compression data is available. If the whole string turned out to
-contain compressed data, this is \code{""}, the empty string.
-
-The only way to determine where a string of compressed data ends is by
-actually decompressing it. This means that when compressed data is
-contained part of a larger file, you can only find the end of it by
-reading data and feeding it followed by some non-empty string into a
-decompression object's \method{decompress} method until the
-\member{unused_data} attribute is no longer the empty string.
-\end{memberdesc}
-
-\begin{memberdesc}[Decompress]{unconsumed_tail}
-A string that contains any data that was not consumed by the last
-\method{decompress} call because it exceeded the limit for the
-uncompressed data buffer. This data has not yet been seen by the zlib
-machinery, so you must feed it (possibly with further data
-concatenated to it) back to a subsequent \method{decompress} method
-call in order to get correct output.
-\end{memberdesc}
-
-
-\begin{methoddesc}[Decompress]{decompress}{string\optional{, max_length}}
-Decompress \var{string}, returning a string containing the
-uncompressed data corresponding to at least part of the data in
-\var{string}. This data should be concatenated to the output produced
-by any preceding calls to the
-\method{decompress()} method. Some of the input data may be preserved
-in internal buffers for later processing.
-
-If the optional parameter \var{max_length} is supplied then the return value
-will be no longer than \var{max_length}. This may mean that not all of the
-compressed input can be processed; and unconsumed data will be stored
-in the attribute \member{unconsumed_tail}. This string must be passed
-to a subsequent call to \method{decompress()} if decompression is to
-continue. If \var{max_length} is not supplied then the whole input is
-decompressed, and \member{unconsumed_tail} is an empty string.
-\end{methoddesc}
-
-\begin{methoddesc}[Decompress]{flush}{\optional{length}}
-All pending input is processed, and a string containing the remaining
-uncompressed output is returned. After calling \method{flush()}, the
-\method{decompress()} method cannot be called again; the only realistic
-action is to delete the object.
-
-The optional parameter \var{length} sets the initial size of the
-output buffer.
-\end{methoddesc}
-
-\begin{methoddesc}[Decompress]{copy}{}
-Returns a copy of the decompression object. This can be used to save the
-state of the decompressor midway through the data stream in order to speed up
-random seeks into the stream at a future point.
-\versionadded{2.5}
-\end{methoddesc}
-
-\begin{seealso}
- \seemodule{gzip}{Reading and writing \program{gzip}-format files.}
- \seeurl{http://www.zlib.net}{The zlib library home page.}
- \seeurl{http://www.zlib.net/manual.html}{The zlib manual explains
- the semantics and usage of the library's many functions.}
-\end{seealso}
diff --git a/Doc/lib/markup.tex b/Doc/lib/markup.tex
deleted file mode 100644
index 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 5869e22..0000000
--- a/Doc/lib/sqlite3/adapter_datetime.py
+++ /dev/null
@@ -1,14 +0,0 @@
-import sqlite3
-import datetime, time
-
-def adapt_datetime(ts):
- return time.mktime(ts.timetuple())
-
-sqlite3.register_adapter(datetime.datetime, adapt_datetime)
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-
-now = datetime.datetime.now()
-cur.execute("select ?", (now,))
-print(cur.fetchone()[0])
diff --git a/Doc/lib/sqlite3/adapter_point_1.py b/Doc/lib/sqlite3/adapter_point_1.py
deleted file mode 100644
index 1343acd..0000000
--- a/Doc/lib/sqlite3/adapter_point_1.py
+++ /dev/null
@@ -1,16 +0,0 @@
-import sqlite3
-
-class Point(object):
- def __init__(self, x, y):
- self.x, self.y = x, y
-
- def __conform__(self, protocol):
- if protocol is sqlite3.PrepareProtocol:
- return "%f;%f" % (self.x, self.y)
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-
-p = Point(4.0, -3.2)
-cur.execute("select ?", (p,))
-print(cur.fetchone()[0])
diff --git a/Doc/lib/sqlite3/adapter_point_2.py b/Doc/lib/sqlite3/adapter_point_2.py
deleted file mode 100644
index 1e1719a..0000000
--- a/Doc/lib/sqlite3/adapter_point_2.py
+++ /dev/null
@@ -1,17 +0,0 @@
-import sqlite3
-
-class Point(object):
- def __init__(self, x, y):
- self.x, self.y = x, y
-
-def adapt_point(point):
- return "%f;%f" % (point.x, point.y)
-
-sqlite3.register_adapter(Point, adapt_point)
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-
-p = Point(4.0, -3.2)
-cur.execute("select ?", (p,))
-print(cur.fetchone()[0])
diff --git a/Doc/lib/sqlite3/collation_reverse.py b/Doc/lib/sqlite3/collation_reverse.py
deleted file mode 100644
index bfd7f5b..0000000
--- a/Doc/lib/sqlite3/collation_reverse.py
+++ /dev/null
@@ -1,15 +0,0 @@
-import sqlite3
-
-def collate_reverse(string1, string2):
- return -cmp(string1, string2)
-
-con = sqlite3.connect(":memory:")
-con.create_collation("reverse", collate_reverse)
-
-cur = con.cursor()
-cur.execute("create table test(x)")
-cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
-cur.execute("select x from test order by x collate reverse")
-for row in cur:
- print(row)
-con.close()
diff --git a/Doc/lib/sqlite3/complete_statement.py b/Doc/lib/sqlite3/complete_statement.py
deleted file mode 100644
index cd38d73..0000000
--- a/Doc/lib/sqlite3/complete_statement.py
+++ /dev/null
@@ -1,30 +0,0 @@
-# A minimal SQLite shell for experiments
-
-import sqlite3
-
-con = sqlite3.connect(":memory:")
-con.isolation_level = None
-cur = con.cursor()
-
-buffer = ""
-
-print("Enter your SQL commands to execute in sqlite3.")
-print("Enter a blank line to exit.")
-
-while True:
- line = input()
- if line == "":
- break
- buffer += line
- if sqlite3.complete_statement(buffer):
- try:
- buffer = buffer.strip()
- cur.execute(buffer)
-
- if buffer.lstrip().upper().startswith("SELECT"):
- print(cur.fetchall())
- except sqlite3.Error as e:
- print("An error occurred:", e.args[0])
- buffer = ""
-
-con.close()
diff --git a/Doc/lib/sqlite3/connect_db_1.py b/Doc/lib/sqlite3/connect_db_1.py
deleted file mode 100644
index 1b97523..0000000
--- a/Doc/lib/sqlite3/connect_db_1.py
+++ /dev/null
@@ -1,3 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
diff --git a/Doc/lib/sqlite3/connect_db_2.py b/Doc/lib/sqlite3/connect_db_2.py
deleted file mode 100644
index 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 d0707ab..0000000
--- a/Doc/lib/sqlite3/converter_point.py
+++ /dev/null
@@ -1,47 +0,0 @@
-import sqlite3
-
-class Point(object):
- def __init__(self, x, y):
- self.x, self.y = x, y
-
- def __repr__(self):
- return "(%f;%f)" % (self.x, self.y)
-
-def adapt_point(point):
- return "%f;%f" % (point.x, point.y)
-
-def convert_point(s):
- x, y = list(map(float, s.split(";")))
- return Point(x, y)
-
-# Register the adapter
-sqlite3.register_adapter(Point, adapt_point)
-
-# Register the converter
-sqlite3.register_converter("point", convert_point)
-
-p = Point(4.0, -3.2)
-
-#########################
-# 1) Using declared types
-con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
-cur = con.cursor()
-cur.execute("create table test(p point)")
-
-cur.execute("insert into test(p) values (?)", (p,))
-cur.execute("select p from test")
-print("with declared types:", cur.fetchone()[0])
-cur.close()
-con.close()
-
-#######################
-# 1) Using column names
-con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
-cur = con.cursor()
-cur.execute("create table test(p)")
-
-cur.execute("insert into test(p) values (?)", (p,))
-cur.execute('select p as "p [point]" from test')
-print("with column names:", cur.fetchone()[0])
-cur.close()
-con.close()
diff --git a/Doc/lib/sqlite3/countcursors.py b/Doc/lib/sqlite3/countcursors.py
deleted file mode 100644
index ef3e70a..0000000
--- a/Doc/lib/sqlite3/countcursors.py
+++ /dev/null
@@ -1,15 +0,0 @@
-import sqlite3
-
-class CountCursorsConnection(sqlite3.Connection):
- def __init__(self, *args, **kwargs):
- sqlite3.Connection.__init__(self, *args, **kwargs)
- self.numcursors = 0
-
- def cursor(self, *args, **kwargs):
- self.numcursors += 1
- return sqlite3.Connection.cursor(self, *args, **kwargs)
-
-con = sqlite3.connect(":memory:", factory=CountCursorsConnection)
-cur1 = con.cursor()
-cur2 = con.cursor()
-print(con.numcursors)
diff --git a/Doc/lib/sqlite3/createdb.py b/Doc/lib/sqlite3/createdb.py
deleted file mode 100644
index ee2950b..0000000
--- a/Doc/lib/sqlite3/createdb.py
+++ /dev/null
@@ -1,28 +0,0 @@
-# Not referenced from the documentation, but builds the database file the other
-# code snippets expect.
-
-import sqlite3
-import os
-
-DB_FILE = "mydb"
-
-if os.path.exists(DB_FILE):
- os.remove(DB_FILE)
-
-con = sqlite3.connect(DB_FILE)
-cur = con.cursor()
-cur.execute("""
- create table people
- (
- name_last varchar(20),
- age integer
- )
- """)
-
-cur.execute("insert into people (name_last, age) values ('Yeltsin', 72)")
-cur.execute("insert into people (name_last, age) values ('Putin', 51)")
-
-con.commit()
-
-cur.close()
-con.close()
diff --git a/Doc/lib/sqlite3/execsql_fetchonerow.py b/Doc/lib/sqlite3/execsql_fetchonerow.py
deleted file mode 100644
index 078873b..0000000
--- a/Doc/lib/sqlite3/execsql_fetchonerow.py
+++ /dev/null
@@ -1,17 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-SELECT = "select name_last, age from people order by age, name_last"
-
-# 1. Iterate over the rows available from the cursor, unpacking the
-# resulting sequences to yield their elements (name_last, age):
-cur.execute(SELECT)
-for (name_last, age) in cur:
- print('%s is %d years old.' % (name_last, age))
-
-# 2. Equivalently:
-cur.execute(SELECT)
-for row in cur:
- print('%s is %d years old.' % (row[0], row[1]))
diff --git a/Doc/lib/sqlite3/execsql_printall_1.py b/Doc/lib/sqlite3/execsql_printall_1.py
deleted file mode 100644
index a4ce5c5..0000000
--- a/Doc/lib/sqlite3/execsql_printall_1.py
+++ /dev/null
@@ -1,13 +0,0 @@
-import sqlite3
-
-# Create a connection to the database file "mydb":
-con = sqlite3.connect("mydb")
-
-# Get a Cursor object that operates in the context of Connection con:
-cur = con.cursor()
-
-# Execute the SELECT statement:
-cur.execute("select * from people order by age")
-
-# Retrieve all rows as a sequence and print that sequence:
-print(cur.fetchall())
diff --git a/Doc/lib/sqlite3/execute_1.py b/Doc/lib/sqlite3/execute_1.py
deleted file mode 100644
index 3d08840..0000000
--- a/Doc/lib/sqlite3/execute_1.py
+++ /dev/null
@@ -1,11 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-
-who = "Yeltsin"
-age = 72
-
-cur.execute("select name_last, age from people where name_last=? and age=?", (who, age))
-print(cur.fetchone())
diff --git a/Doc/lib/sqlite3/execute_2.py b/Doc/lib/sqlite3/execute_2.py
deleted file mode 100644
index 84734f9..0000000
--- a/Doc/lib/sqlite3/execute_2.py
+++ /dev/null
@@ -1,12 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-
-who = "Yeltsin"
-age = 72
-
-cur.execute("select name_last, age from people where name_last=:who and age=:age",
- {"who": who, "age": age})
-print(cur.fetchone())
diff --git a/Doc/lib/sqlite3/execute_3.py b/Doc/lib/sqlite3/execute_3.py
deleted file mode 100644
index 0353683..0000000
--- a/Doc/lib/sqlite3/execute_3.py
+++ /dev/null
@@ -1,12 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-
-who = "Yeltsin"
-age = 72
-
-cur.execute("select name_last, age from people where name_last=:who and age=:age",
- locals())
-print(cur.fetchone())
diff --git a/Doc/lib/sqlite3/executemany_1.py b/Doc/lib/sqlite3/executemany_1.py
deleted file mode 100644
index efae106..0000000
--- a/Doc/lib/sqlite3/executemany_1.py
+++ /dev/null
@@ -1,24 +0,0 @@
-import sqlite3
-
-class IterChars:
- def __init__(self):
- self.count = ord('a')
-
- def __iter__(self):
- return self
-
- def __next__(self):
- if self.count > ord('z'):
- raise StopIteration
- self.count += 1
- return (chr(self.count - 1),) # this is a 1-tuple
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-cur.execute("create table characters(c)")
-
-theIter = IterChars()
-cur.executemany("insert into characters(c) values (?)", theIter)
-
-cur.execute("select c from characters")
-print(cur.fetchall())
diff --git a/Doc/lib/sqlite3/executemany_2.py b/Doc/lib/sqlite3/executemany_2.py
deleted file mode 100644
index 518cd94..0000000
--- a/Doc/lib/sqlite3/executemany_2.py
+++ /dev/null
@@ -1,15 +0,0 @@
-import sqlite3
-
-def char_generator():
- import string
- for c in string.letters[:26]:
- yield (c,)
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-cur.execute("create table characters(c)")
-
-cur.executemany("insert into characters(c) values (?)", char_generator())
-
-cur.execute("select c from characters")
-print(cur.fetchall())
diff --git a/Doc/lib/sqlite3/executescript.py b/Doc/lib/sqlite3/executescript.py
deleted file mode 100644
index 7e53581..0000000
--- a/Doc/lib/sqlite3/executescript.py
+++ /dev/null
@@ -1,24 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-cur.executescript("""
- create table person(
- firstname,
- lastname,
- age
- );
-
- create table book(
- title,
- author,
- published
- );
-
- insert into book(title, author, published)
- values (
- 'Dirk Gently''s Holistic Detective Agency',
- 'Douglas Adams',
- 1987
- );
- """)
diff --git a/Doc/lib/sqlite3/insert_more_people.py b/Doc/lib/sqlite3/insert_more_people.py
deleted file mode 100644
index edbc79e..0000000
--- a/Doc/lib/sqlite3/insert_more_people.py
+++ /dev/null
@@ -1,16 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-
-newPeople = (
- ('Lebed' , 53),
- ('Zhirinovsky' , 57),
- )
-
-for person in newPeople:
- cur.execute("insert into people (name_last, age) values (?, ?)", person)
-
-# The changes will not be saved unless the transaction is committed explicitly:
-con.commit()
diff --git a/Doc/lib/sqlite3/md5func.py b/Doc/lib/sqlite3/md5func.py
deleted file mode 100644
index b7bc05b..0000000
--- a/Doc/lib/sqlite3/md5func.py
+++ /dev/null
@@ -1,11 +0,0 @@
-import sqlite3
-import hashlib
-
-def md5sum(t):
- return hashlib.md5(t).hexdigest()
-
-con = sqlite3.connect(":memory:")
-con.create_function("md5", 1, md5sum)
-cur = con.cursor()
-cur.execute("select md5(?)", ("foo",))
-print(cur.fetchone()[0])
diff --git a/Doc/lib/sqlite3/mysumaggr.py b/Doc/lib/sqlite3/mysumaggr.py
deleted file mode 100644
index d2dfd2c..0000000
--- a/Doc/lib/sqlite3/mysumaggr.py
+++ /dev/null
@@ -1,20 +0,0 @@
-import sqlite3
-
-class MySum:
- def __init__(self):
- self.count = 0
-
- def step(self, value):
- self.count += value
-
- def finalize(self):
- return self.count
-
-con = sqlite3.connect(":memory:")
-con.create_aggregate("mysum", 1, MySum)
-cur = con.cursor()
-cur.execute("create table test(i)")
-cur.execute("insert into test(i) values (1)")
-cur.execute("insert into test(i) values (2)")
-cur.execute("select mysum(i) from test")
-print(cur.fetchone()[0])
diff --git a/Doc/lib/sqlite3/parse_colnames.py b/Doc/lib/sqlite3/parse_colnames.py
deleted file mode 100644
index cc68c76..0000000
--- a/Doc/lib/sqlite3/parse_colnames.py
+++ /dev/null
@@ -1,8 +0,0 @@
-import sqlite3
-import datetime
-
-con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
-cur = con.cursor()
-cur.execute('select ? as "x [timestamp]"', (datetime.datetime.now(),))
-dt = cur.fetchone()[0]
-print(dt, type(dt))
diff --git a/Doc/lib/sqlite3/pysqlite_datetime.py b/Doc/lib/sqlite3/pysqlite_datetime.py
deleted file mode 100644
index 68d4935..0000000
--- a/Doc/lib/sqlite3/pysqlite_datetime.py
+++ /dev/null
@@ -1,20 +0,0 @@
-import sqlite3
-import datetime
-
-con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
-cur = con.cursor()
-cur.execute("create table test(d date, ts timestamp)")
-
-today = datetime.date.today()
-now = datetime.datetime.now()
-
-cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
-cur.execute("select d, ts from test")
-row = cur.fetchone()
-print(today, "=>", row[0], type(row[0]))
-print(now, "=>", row[1], type(row[1]))
-
-cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
-row = cur.fetchone()
-print("current_date", row[0], type(row[0]))
-print("current_timestamp", row[1], type(row[1]))
diff --git a/Doc/lib/sqlite3/row_factory.py b/Doc/lib/sqlite3/row_factory.py
deleted file mode 100644
index e436ffc..0000000
--- a/Doc/lib/sqlite3/row_factory.py
+++ /dev/null
@@ -1,13 +0,0 @@
-import sqlite3
-
-def dict_factory(cursor, row):
- d = {}
- for idx, col in enumerate(cursor.description):
- d[col[0]] = row[idx]
- return d
-
-con = sqlite3.connect(":memory:")
-con.row_factory = dict_factory
-cur = con.cursor()
-cur.execute("select 1 as a")
-print(cur.fetchone()["a"])
diff --git a/Doc/lib/sqlite3/rowclass.py b/Doc/lib/sqlite3/rowclass.py
deleted file mode 100644
index 3fa0b87..0000000
--- a/Doc/lib/sqlite3/rowclass.py
+++ /dev/null
@@ -1,12 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect("mydb")
-con.row_factory = sqlite3.Row
-
-cur = con.cursor()
-cur.execute("select name_last, age from people")
-for row in cur:
- assert row[0] == row["name_last"]
- assert row["name_last"] == row["nAmE_lAsT"]
- assert row[1] == row["age"]
- assert row[1] == row["AgE"]
diff --git a/Doc/lib/sqlite3/shared_cache.py b/Doc/lib/sqlite3/shared_cache.py
deleted file mode 100644
index bf1d7b4..0000000
--- a/Doc/lib/sqlite3/shared_cache.py
+++ /dev/null
@@ -1,6 +0,0 @@
-import sqlite3
-
-# The shared cache is only available in SQLite versions 3.3.3 or later
-# See the SQLite documentaton for details.
-
-sqlite3.enable_shared_cache(True)
diff --git a/Doc/lib/sqlite3/shortcut_methods.py b/Doc/lib/sqlite3/shortcut_methods.py
deleted file mode 100644
index 596d87c..0000000
--- a/Doc/lib/sqlite3/shortcut_methods.py
+++ /dev/null
@@ -1,21 +0,0 @@
-import sqlite3
-
-persons = [
- ("Hugo", "Boss"),
- ("Calvin", "Klein")
- ]
-
-con = sqlite3.connect(":memory:")
-
-# Create the table
-con.execute("create table person(firstname, lastname)")
-
-# Fill the table
-con.executemany("insert into person(firstname, lastname) values (?, ?)", persons)
-
-# Print the table contents
-for row in con.execute("select firstname, lastname from person"):
- print(row)
-
-# Using a dummy WHERE clause to not let SQLite take the shortcut table deletes.
-print("I just deleted", con.execute("delete from person where 1=1").rowcount, "rows")
diff --git a/Doc/lib/sqlite3/simple_tableprinter.py b/Doc/lib/sqlite3/simple_tableprinter.py
deleted file mode 100644
index 231d872..0000000
--- a/Doc/lib/sqlite3/simple_tableprinter.py
+++ /dev/null
@@ -1,26 +0,0 @@
-import sqlite3
-
-FIELD_MAX_WIDTH = 20
-TABLE_NAME = 'people'
-SELECT = 'select * from %s order by age, name_last' % TABLE_NAME
-
-con = sqlite3.connect("mydb")
-
-cur = con.cursor()
-cur.execute(SELECT)
-
-# Print a header.
-for fieldDesc in cur.description:
- print(fieldDesc[0].ljust(FIELD_MAX_WIDTH), end=' ')
-print() # Finish the header with a newline.
-print('-' * 78)
-
-# For each row, print the value of each field left-justified within
-# the maximum possible width of that field.
-fieldIndices = range(len(cur.description))
-for row in cur:
- for fieldIndex in fieldIndices:
- fieldValue = str(row[fieldIndex])
- print(fieldValue.ljust(FIELD_MAX_WIDTH), end=' ')
-
- print() # Finish the row with a newline.
diff --git a/Doc/lib/sqlite3/text_factory.py b/Doc/lib/sqlite3/text_factory.py
deleted file mode 100644
index 2dab8e4..0000000
--- a/Doc/lib/sqlite3/text_factory.py
+++ /dev/null
@@ -1,42 +0,0 @@
-import sqlite3
-
-con = sqlite3.connect(":memory:")
-cur = con.cursor()
-
-# Create the table
-con.execute("create table person(lastname, firstname)")
-
-AUSTRIA = "\xd6sterreich"
-
-# by default, rows are returned as Unicode
-cur.execute("select ?", (AUSTRIA,))
-row = cur.fetchone()
-assert row[0] == AUSTRIA
-
-# but we can make pysqlite always return bytestrings ...
-con.text_factory = str
-cur.execute("select ?", (AUSTRIA,))
-row = cur.fetchone()
-assert type(row[0]) == str
-# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
-# database ...
-assert row[0] == AUSTRIA.encode("utf-8")
-
-# we can also implement a custom text_factory ...
-# here we implement one that will ignore Unicode characters that cannot be
-# decoded from UTF-8
-con.text_factory = lambda x: str(x, "utf-8", "ignore")
-cur.execute("select ?", ("this is latin1 and would normally create errors" + "\xe4\xf6\xfc".encode("latin1"),))
-row = cur.fetchone()
-assert type(row[0]) == str
-
-# pysqlite offers a builtin optimized text_factory that will return bytestring
-# objects, if the data is in ASCII only, and otherwise return unicode objects
-con.text_factory = sqlite3.OptimizedUnicode
-cur.execute("select ?", (AUSTRIA,))
-row = cur.fetchone()
-assert type(row[0]) == str
-
-cur.execute("select ?", ("Germany",))
-row = cur.fetchone()
-assert type(row[0]) == str
diff --git a/Doc/lib/tkinter.tex b/Doc/lib/tkinter.tex
deleted file mode 100644
index 20b2373..0000000
--- a/Doc/lib/tkinter.tex
+++ /dev/null
@@ -1,1873 +0,0 @@
-\chapter{Graphical User Interfaces with Tk \label{tkinter}}
-
-\index{GUI}
-\index{Graphical User Interface}
-\index{Tkinter}
-\index{Tk}
-
-Tk/Tcl has long been an integral part of Python. It provides a robust
-and platform independent windowing toolkit, that is available to
-Python programmers using the \refmodule{Tkinter} module, and its
-extension, the \refmodule{Tix} module.
-
-The \refmodule{Tkinter} module is a thin object-oriented layer on top of
-Tcl/Tk. To use \refmodule{Tkinter}, you don't need to write Tcl code,
-but you will need to consult the Tk documentation, and occasionally
-the Tcl documentation. \refmodule{Tkinter} is a set of wrappers that
-implement the Tk widgets as Python classes. In addition, the internal
-module \module{\_tkinter} provides a threadsafe mechanism which allows
-Python and Tcl to interact.
-
-Tk is not the only GUI for Python; see
-section~\ref{other-gui-packages}, ``Other User Interface Modules and
-Packages,'' for more information on other GUI toolkits for Python.
-
-% Other sections I have in mind are
-% Tkinter internals
-% Freezing Tkinter applications
-
-\localmoduletable
-
-
-\section{\module{Tkinter} ---
- Python interface to Tcl/Tk}
-
-\declaremodule{standard}{Tkinter}
-\modulesynopsis{Interface to Tcl/Tk for graphical user interfaces}
-\moduleauthor{Guido van Rossum}{guido@Python.org}
-
-The \module{Tkinter} module (``Tk interface'') is the standard Python
-interface to the Tk GUI toolkit. Both Tk and \module{Tkinter} are
-available on most \UNIX{} platforms, as well as on Windows and
-Macintosh systems. (Tk itself is not part of Python; it is maintained
-at ActiveState.)
-
-\begin{seealso}
-\seetitle[http://www.python.org/topics/tkinter/]
- {Python Tkinter Resources}
- {The Python Tkinter Topic Guide provides a great
- deal of information on using Tk from Python and links to
- other sources of information on Tk.}
-
-\seetitle[http://www.pythonware.com/library/an-introduction-to-tkinter.htm]
- {An Introduction to Tkinter}
- {Fredrik Lundh's on-line reference material.}
-
-\seetitle[http://www.nmt.edu/tcc/help/pubs/lang.html]
- {Tkinter reference: a GUI for Python}
- {On-line reference material.}
-
-\seetitle[http://jtkinter.sourceforge.net]
- {Tkinter for JPython}
- {The Jython interface to Tkinter.}
-
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/1884777813]
- {Python and Tkinter Programming}
- {The book by John Grayson (ISBN 1-884777-81-3).}
-\end{seealso}
-
-
-\subsection{Tkinter Modules}
-
-Most of the time, the \refmodule{Tkinter} module is all you really
-need, but a number of additional modules are available as well. The
-Tk interface is located in a binary module named \module{_tkinter}.
-This module contains the low-level interface to Tk, and should never
-be used directly by application programmers. It is usually a shared
-library (or DLL), but might in some cases be statically linked with
-the Python interpreter.
-
-In addition to the Tk interface module, \refmodule{Tkinter} includes a
-number of Python modules. The two most important modules are the
-\refmodule{Tkinter} module itself, and a module called
-\module{Tkconstants}. The former automatically imports the latter, so
-to use Tkinter, all you need to do is to import one module:
-
-\begin{verbatim}
-import Tkinter
-\end{verbatim}
-
-Or, more often:
-
-\begin{verbatim}
-from Tkinter import *
-\end{verbatim}
-
-\begin{classdesc}{Tk}{screenName=None, baseName=None, className='Tk', useTk=1}
-The \class{Tk} class is instantiated without arguments.
-This creates a toplevel widget of Tk which usually is the main window
-of an application. Each instance has its own associated Tcl interpreter.
-% FIXME: The following keyword arguments are currently recognized:
-\versionchanged[The \var{useTk} parameter was added]{2.4}
-\end{classdesc}
-
-\begin{funcdesc}{Tcl}{screenName=None, baseName=None, className='Tk', useTk=0}
-The \function{Tcl} function is a factory function which creates an
-object much like that created by the \class{Tk} class, except that it
-does not initialize the Tk subsystem. This is most often useful when
-driving the Tcl interpreter in an environment where one doesn't want
-to create extraneous toplevel windows, or where one cannot (such as
-\UNIX/Linux systems without an X server). An object created by the
-\function{Tcl} object can have a Toplevel window created (and the Tk
-subsystem initialized) by calling its \method{loadtk} method.
-\versionadded{2.4}
-\end{funcdesc}
-
-Other modules that provide Tk support include:
-
-\begin{description}
-% \declaremodule{standard}{Tkconstants}
-% \modulesynopsis{Constants used by Tkinter}
-% FIXME
-
-\item[\refmodule{ScrolledText}]
-Text widget with a vertical scroll bar built in.
-
-\item[\module{tkColorChooser}]
-Dialog to let the user choose a color.
-
-\item[\module{tkCommonDialog}]
-Base class for the dialogs defined in the other modules listed here.
-
-\item[\module{tkFileDialog}]
-Common dialogs to allow the user to specify a file to open or save.
-
-\item[\module{tkFont}]
-Utilities to help work with fonts.
-
-\item[\module{tkMessageBox}]
-Access to standard Tk dialog boxes.
-
-\item[\module{tkSimpleDialog}]
-Basic dialogs and convenience functions.
-
-\item[\module{Tkdnd}]
-Drag-and-drop support for \refmodule{Tkinter}.
-This is experimental and should become deprecated when it is replaced
-with the Tk DND.
-
-\item[\refmodule{turtle}]
-Turtle graphics in a Tk window.
-
-\end{description}
-
-\subsection{Tkinter Life Preserver}
-\sectionauthor{Matt Conway}{}
-% Converted to LaTeX by Mike Clarkson.
-
-This section is not designed to be an exhaustive tutorial on either
-Tk or Tkinter. Rather, it is intended as a stop gap, providing some
-introductory orientation on the system.
-
-Credits:
-\begin{itemize}
-\item Tkinter was written by Steen Lumholt and Guido van Rossum.
-\item Tk was written by John Ousterhout while at Berkeley.
-\item This Life Preserver was written by Matt Conway at
-the University of Virginia.
-\item The html rendering, and some liberal editing, was
-produced from a FrameMaker version by Ken Manheimer.
-\item Fredrik Lundh elaborated and revised the class interface descriptions,
-to get them current with Tk 4.2.
-\item Mike Clarkson converted the documentation to \LaTeX, and compiled the
-User Interface chapter of the reference manual.
-\end{itemize}
-
-
-\subsubsection{How To Use This Section}
-
-This section is designed in two parts: the first half (roughly) covers
-background material, while the second half can be taken to the
-keyboard as a handy reference.
-
-When trying to answer questions of the form ``how do I do blah'', it
-is often best to find out how to do``blah'' in straight Tk, and then
-convert this back into the corresponding \refmodule{Tkinter} call.
-Python programmers can often guess at the correct Python command by
-looking at the Tk documentation. This means that in order to use
-Tkinter, you will have to know a little bit about Tk. This document
-can't fulfill that role, so the best we can do is point you to the
-best documentation that exists. Here are some hints:
-
-\begin{itemize}
-\item The authors strongly suggest getting a copy of the Tk man
-pages. Specifically, the man pages in the \code{mann} directory are most
-useful. The \code{man3} man pages describe the C interface to the Tk
-library and thus are not especially helpful for script writers.
-
-\item Addison-Wesley publishes a book called \citetitle{Tcl and the
-Tk Toolkit} by John Ousterhout (ISBN 0-201-63337-X) which is a good
-introduction to Tcl and Tk for the novice. The book is not
-exhaustive, and for many details it defers to the man pages.
-
-\item \file{Tkinter.py} is a last resort for most, but can be a good
-place to go when nothing else makes sense.
-\end{itemize}
-
-\begin{seealso}
-\seetitle[http://tcl.activestate.com/]
- {ActiveState Tcl Home Page}
- {The Tk/Tcl development is largely taking place at
- ActiveState.}
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/020163337X]
- {Tcl and the Tk Toolkit}
- {The book by John Ousterhout, the inventor of Tcl .}
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/0130220280]
- {Practical Programming in Tcl and Tk}
- {Brent Welch's encyclopedic book.}
-\end{seealso}
-
-
-\subsubsection{A Simple Hello World Program} % HelloWorld.html
-
-%begin{latexonly}
-%\begin{figure}[hbtp]
-%\centerline{\epsfig{file=HelloWorld.gif,width=.9\textwidth}}
-%\vspace{.5cm}
-%\caption{HelloWorld gadget image}
-%\end{figure}
-%See also the hello-world \ulink{notes}{classes/HelloWorld-notes.html} and
-%\ulink{summary}{classes/HelloWorld-summary.html}.
-%end{latexonly}
-
-
-\begin{verbatim}
-from Tkinter import *
-
-class Application(Frame):
- def say_hi(self):
- print "hi there, everyone!"
-
- def createWidgets(self):
- self.QUIT = Button(self)
- self.QUIT["text"] = "QUIT"
- self.QUIT["fg"] = "red"
- self.QUIT["command"] = self.quit
-
- self.QUIT.pack({"side": "left"})
-
- self.hi_there = Button(self)
- self.hi_there["text"] = "Hello",
- self.hi_there["command"] = self.say_hi
-
- self.hi_there.pack({"side": "left"})
-
- def __init__(self, master=None):
- Frame.__init__(self, master)
- self.pack()
- self.createWidgets()
-
-root = Tk()
-app = Application(master=root)
-app.mainloop()
-root.destroy()
-\end{verbatim}
-
-
-\subsection{A (Very) Quick Look at Tcl/Tk} % BriefTclTk.html
-
-The class hierarchy looks complicated, but in actual practice,
-application programmers almost always refer to the classes at the very
-bottom of the hierarchy.
-
-Notes:
-\begin{itemize}
-\item These classes are provided for the purposes of
-organizing certain functions under one namespace. They aren't meant to
-be instantiated independently.
-
-\item The \class{Tk} class is meant to be instantiated only once in
-an application. Application programmers need not instantiate one
-explicitly, the system creates one whenever any of the other classes
-are instantiated.
-
-\item The \class{Widget} class is not meant to be instantiated, it
-is meant only for subclassing to make ``real'' widgets (in \Cpp, this
-is called an `abstract class').
-\end{itemize}
-
-To make use of this reference material, there will be times when you
-will need to know how to read short passages of Tk and how to identify
-the various parts of a Tk command.
-(See section~\ref{tkinter-basic-mapping} for the
-\refmodule{Tkinter} equivalents of what's below.)
-
-Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are
-just lists of tokens separated by spaces. A Tk widget is just its
-\emph{class}, the \emph{options} that help configure it, and the
-\emph{actions} that make it do useful things.
-
-To make a widget in Tk, the command is always of the form:
-
-\begin{verbatim}
- classCommand newPathname options
-\end{verbatim}
-
-\begin{description}
-\item[\var{classCommand}]
-denotes which kind of widget to make (a button, a label, a menu...)
-
-\item[\var{newPathname}]
-is the new name for this widget. All names in Tk must be unique. To
-help enforce this, widgets in Tk are named with \emph{pathnames}, just
-like files in a file system. The top level widget, the \emph{root},
-is called \code{.} (period) and children are delimited by more
-periods. For example, \code{.myApp.controlPanel.okButton} might be
-the name of a widget.
-
-\item[\var{options}]
-configure the widget's appearance and in some cases, its
-behavior. The options come in the form of a list of flags and values.
-Flags are preceded by a `-', like \UNIX{} shell command flags, and
-values are put in quotes if they are more than one word.
-\end{description}
-
-For example:
-
-\begin{verbatim}
- button .fred -fg red -text "hi there"
- ^ ^ \_____________________/
- | | |
- class new options
- command widget (-opt val -opt val ...)
-\end{verbatim}
-
-Once created, the pathname to the widget becomes a new command. This
-new \var{widget command} is the programmer's handle for getting the new
-widget to perform some \var{action}. In C, you'd express this as
-someAction(fred, someOptions), in \Cpp, you would express this as
-fred.someAction(someOptions), and in Tk, you say:
-
-\begin{verbatim}
- .fred someAction someOptions
-\end{verbatim}
-
-Note that the object name, \code{.fred}, starts with a dot.
-
-As you'd expect, the legal values for \var{someAction} will depend on
-the widget's class: \code{.fred disable} works if fred is a
-button (fred gets greyed out), but does not work if fred is a label
-(disabling of labels is not supported in Tk).
-
-The legal values of \var{someOptions} is action dependent. Some
-actions, like \code{disable}, require no arguments, others, like
-a text-entry box's \code{delete} command, would need arguments
-to specify what range of text to delete.
-
-
-\subsection{Mapping Basic Tk into Tkinter
- \label{tkinter-basic-mapping}}
-
-Class commands in Tk correspond to class constructors in Tkinter.
-
-\begin{verbatim}
- button .fred =====> fred = Button()
-\end{verbatim}
-
-The master of an object is implicit in the new name given to it at
-creation time. In Tkinter, masters are specified explicitly.
-
-\begin{verbatim}
- button .panel.fred =====> fred = Button(panel)
-\end{verbatim}
-
-The configuration options in Tk are given in lists of hyphened tags
-followed by values. In Tkinter, options are specified as
-keyword-arguments in the instance constructor, and keyword-args for
-configure calls or as instance indices, in dictionary style, for
-established instances. See section~\ref{tkinter-setting-options} on
-setting options.
-
-\begin{verbatim}
- button .fred -fg red =====> fred = Button(panel, fg = "red")
- .fred configure -fg red =====> fred["fg"] = red
- OR ==> fred.config(fg = "red")
-\end{verbatim}
-
-In Tk, to perform an action on a widget, use the widget name as a
-command, and follow it with an action name, possibly with arguments
-(options). In Tkinter, you call methods on the class instance to
-invoke actions on the widget. The actions (methods) that a given
-widget can perform are listed in the Tkinter.py module.
-
-\begin{verbatim}
- .fred invoke =====> fred.invoke()
-\end{verbatim}
-
-To give a widget to the packer (geometry manager), you call pack with
-optional arguments. In Tkinter, the Pack class holds all this
-functionality, and the various forms of the pack command are
-implemented as methods. All widgets in \refmodule{Tkinter} are
-subclassed from the Packer, and so inherit all the packing
-methods. See the \refmodule{Tix} module documentation for additional
-information on the Form geometry manager.
-
-\begin{verbatim}
- pack .fred -side left =====> fred.pack(side = "left")
-\end{verbatim}
-
-
-\subsection{How Tk and Tkinter are Related} % Relationship.html
-
-\note{This was derived from a graphical image; the image will be used
- more directly in a subsequent version of this document.}
-
-From the top down:
-\begin{description}
-\item[\b{Your App Here (Python)}]
-A Python application makes a \refmodule{Tkinter} call.
-
-\item[\b{Tkinter (Python Module)}]
-This call (say, for example, creating a button widget), is
-implemented in the \emph{Tkinter} module, which is written in
-Python. This Python function will parse the commands and the
-arguments and convert them into a form that makes them look as if they
-had come from a Tk script instead of a Python script.
-
-\item[\b{tkinter (C)}]
-These commands and their arguments will be passed to a C function
-in the \emph{tkinter} - note the lowercase - extension module.
-
-\item[\b{Tk Widgets} (C and Tcl)]
-This C function is able to make calls into other C modules,
-including the C functions that make up the Tk library. Tk is
-implemented in C and some Tcl. The Tcl part of the Tk widgets is used
-to bind certain default behaviors to widgets, and is executed once at
-the point where the Python \refmodule{Tkinter} module is
-imported. (The user never sees this stage).
-
-\item[\b{Tk (C)}]
-The Tk part of the Tk Widgets implement the final mapping to ...
-
-\item[\b{Xlib (C)}]
-the Xlib library to draw graphics on the screen.
-\end{description}
-
-
-\subsection{Handy Reference}
-
-\subsubsection{Setting Options
- \label{tkinter-setting-options}}
-
-Options control things like the color and border width of a widget.
-Options can be set in three ways:
-
-\begin{description}
-\item[At object creation time, using keyword arguments]:
-\begin{verbatim}
-fred = Button(self, fg = "red", bg = "blue")
-\end{verbatim}
-\item[After object creation, treating the option name like a dictionary index]:
-\begin{verbatim}
-fred["fg"] = "red"
-fred["bg"] = "blue"
-\end{verbatim}
-\item[Use the config() method to update multiple attrs subsequent to
-object creation]:
-\begin{verbatim}
-fred.config(fg = "red", bg = "blue")
-\end{verbatim}
-\end{description}
-
-For a complete explanation of a given option and its behavior, see the
-Tk man pages for the widget in question.
-
-Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC
-OPTIONS" for each widget. The former is a list of options that are
-common to many widgets, the latter are the options that are
-idiosyncratic to that particular widget. The Standard Options are
-documented on the \manpage{options}{3} man page.
-
-No distinction between standard and widget-specific options is made in
-this document. Some options don't apply to some kinds of widgets.
-Whether a given widget responds to a particular option depends on the
-class of the widget; buttons have a \code{command} option, labels do not.
-
-The options supported by a given widget are listed in that widget's
-man page, or can be queried at runtime by calling the
-\method{config()} method without arguments, or by calling the
-\method{keys()} method on that widget. The return value of these
-calls is a dictionary whose key is the name of the option as a string
-(for example, \code{'relief'}) and whose values are 5-tuples.
-
-Some options, like \code{bg} are synonyms for common options with long
-names (\code{bg} is shorthand for "background"). Passing the
-\code{config()} method the name of a shorthand option will return a
-2-tuple, not 5-tuple. The 2-tuple passed back will contain the name of
-the synonym and the ``real'' option (such as \code{('bg',
-'background')}).
-
-\begin{tableiii}{c|l|l}{textrm}{Index}{Meaning}{Example}
- \lineiii{0}{option name} {\code{'relief'}}
- \lineiii{1}{option name for database lookup} {\code{'relief'}}
- \lineiii{2}{option class for database lookup} {\code{'Relief'}}
- \lineiii{3}{default value} {\code{'raised'}}
- \lineiii{4}{current value} {\code{'groove'}}
-\end{tableiii}
-
-
-Example:
-
-\begin{verbatim}
->>> print fred.config()
-{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')}
-\end{verbatim}
-
-Of course, the dictionary printed will include all the options
-available and their values. This is meant only as an example.
-
-
-\subsubsection{The Packer} % Packer.html
-\index{packing (widgets)}
-
-The packer is one of Tk's geometry-management mechanisms.
-% See also \citetitle[classes/ClassPacker.html]{the Packer class interface}.
-
-Geometry managers are used to specify the relative positioning of the
-positioning of widgets within their container - their mutual
-\emph{master}. In contrast to the more cumbersome \emph{placer}
-(which is used less commonly, and we do not cover here), the packer
-takes qualitative relationship specification - \emph{above}, \emph{to
-the left of}, \emph{filling}, etc - and works everything out to
-determine the exact placement coordinates for you.
-
-The size of any \emph{master} widget is determined by the size of
-the "slave widgets" inside. The packer is used to control where slave
-widgets appear inside the master into which they are packed. You can
-pack widgets into frames, and frames into other frames, in order to
-achieve the kind of layout you desire. Additionally, the arrangement
-is dynamically adjusted to accommodate incremental changes to the
-configuration, once it is packed.
-
-Note that widgets do not appear until they have had their geometry
-specified with a geometry manager. It's a common early mistake to
-leave out the geometry specification, and then be surprised when the
-widget is created but nothing appears. A widget will appear only
-after it has had, for example, the packer's \method{pack()} method
-applied to it.
-
-The pack() method can be called with keyword-option/value pairs that
-control where the widget is to appear within its container, and how it
-is to behave when the main application window is resized. Here are
-some examples:
-
-\begin{verbatim}
- fred.pack() # defaults to side = "top"
- fred.pack(side = "left")
- fred.pack(expand = 1)
-\end{verbatim}
-
-
-\subsubsection{Packer Options}
-
-For more extensive information on the packer and the options that it
-can take, see the man pages and page 183 of John Ousterhout's book.
-
-\begin{description}
-\item[\b{anchor }]
-Anchor type. Denotes where the packer is to place each slave in its
-parcel.
-
-\item[\b{expand}]
-Boolean, \code{0} or \code{1}.
-
-\item[\b{fill}]
-Legal values: \code{'x'}, \code{'y'}, \code{'both'}, \code{'none'}.
-
-\item[\b{ipadx} and \b{ipady}]
-A distance - designating internal padding on each side of the slave
-widget.
-
-\item[\b{padx} and \b{pady}]
-A distance - designating external padding on each side of the slave
-widget.
-
-\item[\b{side}]
-Legal values are: \code{'left'}, \code{'right'}, \code{'top'},
-\code{'bottom'}.
-\end{description}
-
-
-\subsubsection{Coupling Widget Variables} % VarCouplings.html
-
-The current-value setting of some widgets (like text entry widgets)
-can be connected directly to application variables by using special
-options. These options are \code{variable}, \code{textvariable},
-\code{onvalue}, \code{offvalue}, and \code{value}. This
-connection works both ways: if the variable changes for any reason,
-the widget it's connected to will be updated to reflect the new value.
-
-Unfortunately, in the current implementation of \refmodule{Tkinter} it is
-not possible to hand over an arbitrary Python variable to a widget
-through a \code{variable} or \code{textvariable} option. The only
-kinds of variables for which this works are variables that are
-subclassed from a class called Variable, defined in the
-\refmodule{Tkinter} module.
-
-There are many useful subclasses of Variable already defined:
-\class{StringVar}, \class{IntVar}, \class{DoubleVar}, and
-\class{BooleanVar}. To read the current value of such a variable,
-call the \method{get()} method on
-it, and to change its value you call the \method{set()} method. If
-you follow this protocol, the widget will always track the value of
-the variable, with no further intervention on your part.
-
-For example:
-\begin{verbatim}
-class App(Frame):
- def __init__(self, master=None):
- Frame.__init__(self, master)
- self.pack()
-
- self.entrythingy = Entry()
- self.entrythingy.pack()
-
- # here is the application variable
- self.contents = StringVar()
- # set it to some value
- self.contents.set("this is a variable")
- # tell the entry widget to watch this variable
- self.entrythingy["textvariable"] = self.contents
-
- # and here we get a callback when the user hits return.
- # we will have the program print out the value of the
- # application variable when the user hits return
- self.entrythingy.bind('<Key-Return>',
- self.print_contents)
-
- def print_contents(self, event):
- print "hi. contents of entry is now ---->", \
- self.contents.get()
-\end{verbatim}
-
-
-\subsubsection{The Window Manager} % WindowMgr.html
-\index{window manager (widgets)}
-
-In Tk, there is a utility command, \code{wm}, for interacting with the
-window manager. Options to the \code{wm} command allow you to control
-things like titles, placement, icon bitmaps, and the like. In
-\refmodule{Tkinter}, these commands have been implemented as methods
-on the \class{Wm} class. Toplevel widgets are subclassed from the
-\class{Wm} class, and so can call the \class{Wm} methods directly.
-
-%See also \citetitle[classes/ClassWm.html]{the Wm class interface}.
-
-To get at the toplevel window that contains a given widget, you can
-often just refer to the widget's master. Of course if the widget has
-been packed inside of a frame, the master won't represent a toplevel
-window. To get at the toplevel window that contains an arbitrary
-widget, you can call the \method{_root()} method. This
-method begins with an underscore to denote the fact that this function
-is part of the implementation, and not an interface to Tk functionality.
-
-Here are some examples of typical usage:
-
-\begin{verbatim}
-from Tkinter import *
-class App(Frame):
- def __init__(self, master=None):
- Frame.__init__(self, master)
- self.pack()
-
-
-# create the application
-myapp = App()
-
-#
-# here are method calls to the window manager class
-#
-myapp.master.title("My Do-Nothing Application")
-myapp.master.maxsize(1000, 400)
-
-# start the program
-myapp.mainloop()
-\end{verbatim}
-
-
-\subsubsection{Tk Option Data Types} % OptionTypes.html
-
-\index{Tk Option Data Types}
-
-\begin{description}
-\item[anchor]
-Legal values are points of the compass: \code{"n"},
-\code{"ne"}, \code{"e"}, \code{"se"}, \code{"s"},
-\code{"sw"}, \code{"w"}, \code{"nw"}, and also
-\code{"center"}.
-
-\item[bitmap]
-There are eight built-in, named bitmaps: \code{'error'}, \code{'gray25'},
-\code{'gray50'}, \code{'hourglass'}, \code{'info'}, \code{'questhead'},
-\code{'question'}, \code{'warning'}. To specify an X bitmap
-filename, give the full path to the file, preceded with an \code{@},
-as in \code{"@/usr/contrib/bitmap/gumby.bit"}.
-
-\item[boolean]
-You can pass integers 0 or 1 or the strings \code{"yes"} or \code{"no"} .
-
-\item[callback]
-This is any Python function that takes no arguments. For example:
-\begin{verbatim}
- def print_it():
- print "hi there"
- fred["command"] = print_it
-\end{verbatim}
-
-\item[color]
-Colors can be given as the names of X colors in the rgb.txt file,
-or as strings representing RGB values in 4 bit: \code{"\#RGB"}, 8
-bit: \code{"\#RRGGBB"}, 12 bit" \code{"\#RRRGGGBBB"}, or 16 bit
-\code{"\#RRRRGGGGBBBB"} ranges, where R,G,B here represent any
-legal hex digit. See page 160 of Ousterhout's book for details.
-
-\item[cursor]
-The standard X cursor names from \file{cursorfont.h} can be used,
-without the \code{XC_} prefix. For example to get a hand cursor
-(\constant{XC_hand2}), use the string \code{"hand2"}. You can also
-specify a bitmap and mask file of your own. See page 179 of
-Ousterhout's book.
-
-\item[distance]
-Screen distances can be specified in either pixels or absolute
-distances. Pixels are given as numbers and absolute distances as
-strings, with the trailing character denoting units: \code{c}
-for centimetres, \code{i} for inches, \code{m} for millimetres,
-\code{p} for printer's points. For example, 3.5 inches is expressed
-as \code{"3.5i"}.
-
-\item[font]
-Tk uses a list font name format, such as \code{\{courier 10 bold\}}.
-Font sizes with positive numbers are measured in points;
-sizes with negative numbers are measured in pixels.
-
-\item[geometry]
-This is a string of the form \samp{\var{width}x\var{height}}, where
-width and height are measured in pixels for most widgets (in
-characters for widgets displaying text). For example:
-\code{fred["geometry"] = "200x100"}.
-
-\item[justify]
-Legal values are the strings: \code{"left"},
-\code{"center"}, \code{"right"}, and \code{"fill"}.
-
-\item[region]
-This is a string with four space-delimited elements, each of
-which is a legal distance (see above). For example: \code{"2 3 4
-5"} and \code{"3i 2i 4.5i 2i"} and \code{"3c 2c 4c 10.43c"}
-are all legal regions.
-
-\item[relief]
-Determines what the border style of a widget will be. Legal
-values are: \code{"raised"}, \code{"sunken"},
-\code{"flat"}, \code{"groove"}, and \code{"ridge"}.
-
-\item[scrollcommand]
-This is almost always the \method{set()} method of some scrollbar
-widget, but can be any widget method that takes a single argument.
-Refer to the file \file{Demo/tkinter/matt/canvas-with-scrollbars.py}
-in the Python source distribution for an example.
-
-\item[wrap:]
-Must be one of: \code{"none"}, \code{"char"}, or \code{"word"}.
-\end{description}
-
-
-\subsubsection{Bindings and Events} % Bindings.html
-
-\index{bind (widgets)}
-\index{events (widgets)}
-
-The bind method from the widget command allows you to watch for
-certain events and to have a callback function trigger when that event
-type occurs. The form of the bind method is:
-
-\begin{verbatim}
- def bind(self, sequence, func, add=''):
-\end{verbatim}
-where:
-
-\begin{description}
-\item[sequence]
-is a string that denotes the target kind of event. (See the bind
-man page and page 201 of John Ousterhout's book for details).
-
-\item[func]
-is a Python function, taking one argument, to be invoked when the
-event occurs. An Event instance will be passed as the argument.
-(Functions deployed this way are commonly known as \var{callbacks}.)
-
-\item[add]
-is optional, either \samp{} or \samp{+}. Passing an empty string
-denotes that this binding is to replace any other bindings that this
-event is associated with. Preceeding with a \samp{+} means that this
-function is to be added to the list of functions bound to this event type.
-\end{description}
-
-For example:
-\begin{verbatim}
- def turnRed(self, event):
- event.widget["activeforeground"] = "red"
-
- self.button.bind("<Enter>", self.turnRed)
-\end{verbatim}
-
-Notice how the widget field of the event is being accessed in the
-\method{turnRed()} callback. This field contains the widget that
-caught the X event. The following table lists the other event fields
-you can access, and how they are denoted in Tk, which can be useful
-when referring to the Tk man pages.
-
-\begin{verbatim}
-Tk Tkinter Event Field Tk Tkinter Event Field
--- ------------------- -- -------------------
-%f focus %A char
-%h height %E send_event
-%k keycode %K keysym
-%s state %N keysym_num
-%t time %T type
-%w width %W widget
-%x x %X x_root
-%y y %Y y_root
-\end{verbatim}
-
-
-\subsubsection{The index Parameter} % Index.html
-
-A number of widgets require``index'' parameters to be passed. These
-are used to point at a specific place in a Text widget, or to
-particular characters in an Entry widget, or to particular menu items
-in a Menu widget.
-
-\begin{description}
-\item[\b{Entry widget indexes (index, view index, etc.)}]
-Entry widgets have options that refer to character positions in the
-text being displayed. You can use these \refmodule{Tkinter} functions
-to access these special points in text widgets:
-
-\begin{description}
-\item[AtEnd()]
-refers to the last position in the text
-
-\item[AtInsert()]
-refers to the point where the text cursor is
-
-\item[AtSelFirst()]
-indicates the beginning point of the selected text
-
-\item[AtSelLast()]
-denotes the last point of the selected text and finally
-
-\item[At(x\optional{, y})]
-refers to the character at pixel location \var{x}, \var{y} (with
-\var{y} not used in the case of a text entry widget, which contains a
-single line of text).
-\end{description}
-
-\item[\b{Text widget indexes}]
-The index notation for Text widgets is very rich and is best described
-in the Tk man pages.
-
-\item[\b{Menu indexes (menu.invoke(), menu.entryconfig(), etc.)}]
-
-Some options and methods for menus manipulate specific menu entries.
-Anytime a menu index is needed for an option or a parameter, you may
-pass in:
-\begin{itemize}
-\item an integer which refers to the numeric position of the entry in
-the widget, counted from the top, starting with 0;
-\item the string \code{'active'}, which refers to the menu position that is
-currently under the cursor;
-\item the string \code{"last"} which refers to the last menu
-item;
-\item An integer preceded by \code{@}, as in \code{@6}, where the integer is
-interpreted as a y pixel coordinate in the menu's coordinate system;
-\item the string \code{"none"}, which indicates no menu entry at all, most
-often used with menu.activate() to deactivate all entries, and
-finally,
-\item a text string that is pattern matched against the label of the
-menu entry, as scanned from the top of the menu to the bottom. Note
-that this index type is considered after all the others, which means
-that matches for menu items labelled \code{last}, \code{active}, or
-\code{none} may be interpreted as the above literals, instead.
-\end{itemize}
-\end{description}
-
-\subsubsection{Images}
-
-Bitmap/Pixelmap images can be created through the subclasses of
-\class{Tkinter.Image}:
-
-\begin{itemize}
-\item \class{BitmapImage} can be used for X11 bitmap data.
-\item \class{PhotoImage} can be used for GIF and PPM/PGM color bitmaps.
-\end{itemize}
-
-Either type of image is created through either the \code{file} or the
-\code{data} option (other options are available as well).
-
-The image object can then be used wherever an \code{image} option is
-supported by some widget (e.g. labels, buttons, menus). In these
-cases, Tk will not keep a reference to the image. When the last Python
-reference to the image object is deleted, the image data is deleted as
-well, and Tk will display an empty box wherever the image was used.
-
-\section{\module{Tix} ---
- Extension widgets for Tk}
-
-\declaremodule{standard}{Tix}
-\modulesynopsis{Tk Extension Widgets for Tkinter}
-\sectionauthor{Mike Clarkson}{mikeclarkson@users.sourceforge.net}
-
-\index{Tix}
-
-The \module{Tix} (Tk Interface Extension) module provides an
-additional rich set of widgets. Although the standard Tk library has
-many useful widgets, they are far from complete. The \module{Tix}
-library provides most of the commonly needed widgets that are missing
-from standard Tk: \class{HList}, \class{ComboBox}, \class{Control}
-(a.k.a. SpinBox) and an assortment of scrollable widgets. \module{Tix}
-also includes many more widgets that are generally useful in a wide
-range of applications: \class{NoteBook}, \class{FileEntry},
-\class{PanedWindow}, etc; there are more than 40 of them.
-
-With all these new widgets, you can introduce new interaction
-techniques into applications, creating more useful and more intuitive
-user interfaces. You can design your application by choosing the most
-appropriate widgets to match the special needs of your application and
-users.
-
-\begin{seealso}
-\seetitle[http://tix.sourceforge.net/]
- {Tix Homepage}
- {The home page for \module{Tix}. This includes links to
- additional documentation and downloads.}
-\seetitle[http://tix.sourceforge.net/dist/current/man/]
- {Tix Man Pages}
- {On-line version of the man pages and reference material.}
-\seetitle[http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html]
- {Tix Programming Guide}
- {On-line version of the programmer's reference material.}
-\seetitle[http://tix.sourceforge.net/Tide/]
- {Tix Development Applications}
- {Tix applications for development of Tix and Tkinter programs.
- Tide applications work under Tk or Tkinter, and include
- \program{TixInspect}, an inspector to remotely modify and
- debug Tix/Tk/Tkinter applications.}
-\end{seealso}
-
-
-\subsection{Using Tix}
-
-\begin{classdesc}{Tix}{screenName\optional{, baseName\optional{, className}}}
- Toplevel widget of Tix which represents mostly the main window
- of an application. It has an associated Tcl interpreter.
-
-Classes in the \refmodule{Tix} module subclasses the classes in the
-\refmodule{Tkinter} module. The former imports the latter, so to use
-\refmodule{Tix} with Tkinter, all you need to do is to import one
-module. In general, you can just import \refmodule{Tix}, and replace
-the toplevel call to \class{Tkinter.Tk} with \class{Tix.Tk}:
-\begin{verbatim}
-import Tix
-from Tkconstants import *
-root = Tix.Tk()
-\end{verbatim}
-\end{classdesc}
-
-To use \refmodule{Tix}, you must have the \refmodule{Tix} widgets installed,
-usually alongside your installation of the Tk widgets.
-To test your installation, try the following:
-\begin{verbatim}
-import Tix
-root = Tix.Tk()
-root.tk.eval('package require Tix')
-\end{verbatim}
-
-If this fails, you have a Tk installation problem which must be
-resolved before proceeding. Use the environment variable \envvar{TIX_LIBRARY}
-to point to the installed \refmodule{Tix} library directory, and
-make sure you have the dynamic object library (\file{tix8183.dll} or
-\file{libtix8183.so}) in the same directory that contains your Tk
-dynamic object library (\file{tk8183.dll} or \file{libtk8183.so}). The
-directory with the dynamic object library should also have a file
-called \file{pkgIndex.tcl} (case sensitive), which contains the line:
-
-\begin{verbatim}
-package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\subsection{Tix Widgets}
-
-\ulink{Tix}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm}
-introduces over 40 widget classes to the \refmodule{Tkinter}
-repertoire. There is a demo of all the \refmodule{Tix} widgets in the
-\file{Demo/tix} directory of the standard distribution.
-
-
-% The Python sample code is still being added to Python, hence commented out
-
-
-\subsubsection{Basic Widgets}
-
-\begin{classdesc}{Balloon}{}
-A \ulink{Balloon}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm}
-that pops up over a widget to provide help. When the user moves the
-cursor inside a widget to which a Balloon widget has been bound, a
-small pop-up window with a descriptive message will be shown on the
-screen.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
-
-\begin{classdesc}{ButtonBox}{}
-The \ulink{ButtonBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm}
-widget creates a box of buttons, such as is commonly used for \code{Ok
-Cancel}.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
-
-\begin{classdesc}{ComboBox}{}
-The \ulink{ComboBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm}
-widget is similar to the combo box control in MS Windows. The user can
-select a choice by either typing in the entry subwdget or selecting
-from the listbox subwidget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
-
-\begin{classdesc}{Control}{}
-The \ulink{Control}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm}
-widget is also known as the \class{SpinBox} widget. The user can
-adjust the value by pressing the two arrow buttons or by entering the
-value directly into the entry. The new value will be checked against
-the user-defined upper and lower limits.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
-
-\begin{classdesc}{LabelEntry}{}
-The \ulink{LabelEntry}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm}
-widget packages an entry widget and a label into one mega widget. It
-can be used be used to simplify the creation of ``entry-form'' type of
-interface.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
-
-\begin{classdesc}{LabelFrame}{}
-The \ulink{LabelFrame}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm}
-widget packages a frame widget and a label into one mega widget. To
-create widgets inside a LabelFrame widget, one creates the new widgets
-relative to the \member{frame} subwidget and manage them inside the
-\member{frame} subwidget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
-
-\begin{classdesc}{Meter}{}
-The \ulink{Meter}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm}
-widget can be used to show the progress of a background job which may
-take a long time to execute.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
-
-\begin{classdesc}{OptionMenu}{}
-The \ulink{OptionMenu}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm}
-creates a menu button of options.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
-
-\begin{classdesc}{PopupMenu}{}
-The \ulink{PopupMenu}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm}
-widget can be used as a replacement of the \code{tk_popup}
-command. The advantage of the \refmodule{Tix} \class{PopupMenu} widget
-is it requires less application code to manipulate.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
-
-\begin{classdesc}{Select}{}
-The \ulink{Select}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm}
-widget is a container of button subwidgets. It can be used to provide
-radio-box or check-box style of selection options for the user.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
-
-\begin{classdesc}{StdButtonBox}{}
-The \ulink{StdButtonBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm}
-widget is a group of standard buttons for Motif-like dialog boxes.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
-
-
-\subsubsection{File Selectors}
-
-\begin{classdesc}{DirList}{}
-The \ulink{DirList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm} widget
-displays a list view of a directory, its previous directories and its
-sub-directories. The user can choose one of the directories displayed
-in the list or change to another directory.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
-
-\begin{classdesc}{DirTree}{}
-The \ulink{DirTree}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm}
-widget displays a tree view of a directory, its previous directories
-and its sub-directories. The user can choose one of the directories
-displayed in the list or change to another directory.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
-
-\begin{classdesc}{DirSelectDialog}{}
-The \ulink{DirSelectDialog}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm}
-widget presents the directories in the file system in a dialog
-window. The user can use this dialog window to navigate through the
-file system to select the desired directory.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
-
-\begin{classdesc}{DirSelectBox}{}
-The \class{DirSelectBox} is similar
-to the standard Motif(TM) directory-selection box. It is generally used for
-the user to choose a directory. DirSelectBox stores the directories mostly
-recently selected into a ComboBox widget so that they can be quickly
-selected again.
-\end{classdesc}
-
-\begin{classdesc}{ExFileSelectBox}{}
-The \ulink{ExFileSelectBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm}
-widget is usually embedded in a tixExFileSelectDialog widget. It
-provides an convenient method for the user to select files. The style
-of the \class{ExFileSelectBox} widget is very similar to the standard
-file dialog on MS Windows 3.1.
-\end{classdesc}
-
-% Python Demo of:
-%\ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
-
-\begin{classdesc}{FileSelectBox}{}
-The \ulink{FileSelectBox}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm}
-is similar to the standard Motif(TM) file-selection box. It is
-generally used for the user to choose a file. FileSelectBox stores the
-files mostly recently selected into a \class{ComboBox} widget so that
-they can be quickly selected again.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
-
-\begin{classdesc}{FileEntry}{}
-The \ulink{FileEntry}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm}
-widget can be used to input a filename. The user can type in the
-filename manually. Alternatively, the user can press the button widget
-that sits next to the entry, which will bring up a file selection
-dialog.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
-
-
-\subsubsection{Hierachical ListBox}
-
-\begin{classdesc}{HList}{}
-The \ulink{HList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm}
-widget can be used to display any data that have a hierarchical
-structure, for example, file system directory trees. The list entries
-are indented and connected by branch lines according to their places
-in the hierarchy.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
-
-\begin{classdesc}{CheckList}{}
-The \ulink{CheckList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm}
-widget displays a list of items to be selected by the user. CheckList
-acts similarly to the Tk checkbutton or radiobutton widgets, except it
-is capable of handling many more items than checkbuttons or
-radiobuttons.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
-% Python Demo of:
-% \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
-% Python Demo of:
-% \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
-
-\begin{classdesc}{Tree}{}
-The \ulink{Tree}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm}
-widget can be used to display hierarchical data in a tree form. The
-user can adjust the view of the tree by opening or closing parts of
-the tree.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
-
-% Python Demo of:
-% \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
-
-
-\subsubsection{Tabular ListBox}
-
-\begin{classdesc}{TList}{}
-The \ulink{TList}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm}
-widget can be used to display data in a tabular format. The list
-entries of a \class{TList} widget are similar to the entries in the Tk
-listbox widget. The main differences are (1) the \class{TList} widget
-can display the list entries in a two dimensional format and (2) you
-can use graphical images as well as multiple colors and fonts for the
-list entries.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
-% Python Demo of:
-% \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
-
-% Grid has yet to be added to Python
-% \subsubsection{Grid Widget}
-% Python Demo of:
-% \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
-% Python Demo of:
-% \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
-% Python Demo of:
-% \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
-
-
-\subsubsection{Manager Widgets}
-
-\begin{classdesc}{PanedWindow}{}
-The \ulink{PanedWindow}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm}
-widget allows the user to interactively manipulate the sizes of
-several panes. The panes can be arranged either vertically or
-horizontally. The user changes the sizes of the panes by dragging the
-resize handle between two panes.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
-
-\begin{classdesc}{ListNoteBook}{}
-The \ulink{ListNoteBook}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm}
-widget is very similar to the \class{TixNoteBook} widget: it can be
-used to display many windows in a limited space using a notebook
-metaphor. The notebook is divided into a stack of pages (windows). At
-one time only one of these pages can be shown. The user can navigate
-through these pages by choosing the name of the desired page in the
-\member{hlist} subwidget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
-
-\begin{classdesc}{NoteBook}{}
-The \ulink{NoteBook}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm}
-widget can be used to display many windows in a limited space using a
-notebook metaphor. The notebook is divided into a stack of pages. At
-one time only one of these pages can be shown. The user can navigate
-through these pages by choosing the visual ``tabs'' at the top of the
-NoteBook widget.
-\end{classdesc}
-
-% Python Demo of:
-% \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
-
-
-% \subsubsection{Scrolled Widgets}
-% Python Demo of:
-% \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
-% Python Demo of:
-% \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
-% Python Demo of:
-% \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
-% Python Demo of:
-% \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
-
-
-\subsubsection{Image Types}
-
-The \refmodule{Tix} module adds:
-\begin{itemize}
-\item
-\ulink{pixmap}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm}
-capabilities to all \refmodule{Tix} and \refmodule{Tkinter} widgets to
-create color images from XPM files.
-
-% Python Demo of:
-% \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
-
-% Python Demo of:
-% \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
-
-\item
-\ulink{Compound}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm}
-image types can be used to create images that consists of multiple
-horizontal lines; each line is composed of a series of items (texts,
-bitmaps, images or spaces) arranged from left to right. For example, a
-compound image can be used to display a bitmap and a text string
-simultaneously in a Tk \class{Button} widget.
-
-% Python Demo of:
-% \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
-
-% Python Demo of:
-% \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
-
-% Python Demo of:
-% \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
-
-% Python Demo of:
-% \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
-\end{itemize}
-
-
-\subsubsection{Miscellaneous Widgets}
-
-\begin{classdesc}{InputOnly}{}
-The \ulink{InputOnly}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm}
-widgets are to accept inputs from the user, which can be done with the
-\code{bind} command (\UNIX{} only).
-\end{classdesc}
-
-\subsubsection{Form Geometry Manager}
-
-In addition, \refmodule{Tix} augments \refmodule{Tkinter} by providing:
-
-\begin{classdesc}{Form}{}
-The \ulink{Form}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm}
-geometry manager based on attachment rules for all Tk widgets.
-\end{classdesc}
-
-
-%begin{latexonly}
-%\subsection{Tix Class Structure}
-%
-%\begin{figure}[hbtp]
-%\centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}}
-%\vspace{.5cm}
-%\caption{The Class Hierarchy of Tix Widgets}
-%\end{figure}
-%end{latexonly}
-
-\subsection{Tix Commands}
-
-\begin{classdesc}{tixCommand}{}
-The \ulink{tix commands}
-{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm}
-provide access to miscellaneous elements of \refmodule{Tix}'s internal
-state and the \refmodule{Tix} application context. Most of the information
-manipulated by these methods pertains to the application as a whole,
-or to a screen or display, rather than to a particular window.
-
-To view the current settings, the common usage is:
-\begin{verbatim}
-import Tix
-root = Tix.Tk()
-print root.tix_configure()
-\end{verbatim}
-\end{classdesc}
-
-\begin{methoddesc}{tix_configure}{\optional{cnf,} **kw}
-Query or modify the configuration options of the Tix application
-context. If no option is specified, returns a dictionary all of the
-available options. If option is specified with no value, then the
-method returns a list describing the one named option (this list will
-be identical to the corresponding sublist of the value returned if no
-option is specified). If one or more option-value pairs are
-specified, then the method modifies the given option(s) to have the
-given value(s); in this case the method returns an empty string.
-Option may be any of the configuration options.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_cget}{option}
-Returns the current value of the configuration option given by
-\var{option}. Option may be any of the configuration options.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_getbitmap}{name}
-Locates a bitmap file of the name \code{name.xpm} or \code{name} in
-one of the bitmap directories (see the \method{tix_addbitmapdir()}
-method). By using \method{tix_getbitmap()}, you can avoid hard
-coding the pathnames of the bitmap files in your application. When
-successful, it returns the complete pathname of the bitmap file,
-prefixed with the character \samp{@}. The returned value can be used to
-configure the \code{bitmap} option of the Tk and Tix widgets.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_addbitmapdir}{directory}
-Tix maintains a list of directories under which the
-\method{tix_getimage()} and \method{tix_getbitmap()} methods will
-search for image files. The standard bitmap directory is
-\file{\$TIX_LIBRARY/bitmaps}. The \method{tix_addbitmapdir()} method
-adds \var{directory} into this list. By using this method, the image
-files of an applications can also be located using the
-\method{tix_getimage()} or \method{tix_getbitmap()} method.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_filedialog}{\optional{dlgclass}}
-Returns the file selection dialog that may be shared among different
-calls from this application. This method will create a file selection
-dialog widget when it is called the first time. This dialog will be
-returned by all subsequent calls to \method{tix_filedialog()}. An
-optional dlgclass parameter can be passed as a string to specified
-what type of file selection dialog widget is desired. Possible
-options are \code{tix}, \code{FileSelectDialog} or
-\code{tixExFileSelectDialog}.
-\end{methoddesc}
-
-
-\begin{methoddesc}{tix_getimage}{self, name}
-Locates an image file of the name \file{name.xpm}, \file{name.xbm} or
-\file{name.ppm} in one of the bitmap directories (see the
-\method{tix_addbitmapdir()} method above). If more than one file with
-the same name (but different extensions) exist, then the image type is
-chosen according to the depth of the X display: xbm images are chosen
-on monochrome displays and color images are chosen on color
-displays. By using \method{tix_getimage()}, you can avoid hard coding
-the pathnames of the image files in your application. When successful,
-this method returns the name of the newly created image, which can be
-used to configure the \code{image} option of the Tk and Tix widgets.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_option_get}{name}
-Gets the options maintained by the Tix scheme mechanism.
-\end{methoddesc}
-
-\begin{methoddesc}{tix_resetoptions}{newScheme, newFontSet\optional{,
- newScmPrio}}
-Resets the scheme and fontset of the Tix application to
-\var{newScheme} and \var{newFontSet}, respectively. This affects only
-those widgets created after this call. Therefore, it is best to call
-the resetoptions method before the creation of any widgets in a Tix
-application.
-
-The optional parameter \var{newScmPrio} can be given to reset the
-priority level of the Tk options set by the Tix schemes.
-
-Because of the way Tk handles the X option database, after Tix has
-been has imported and inited, it is not possible to reset the color
-schemes and font sets using the \method{tix_config()} method.
-Instead, the \method{tix_resetoptions()} method must be used.
-\end{methoddesc}
-
-
-
-\section{\module{ScrolledText} ---
- Scrolled Text Widget}
-
-\declaremodule{standard}{ScrolledText}
- \platform{Tk}
-\modulesynopsis{Text widget with a vertical scroll bar.}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-
-The \module{ScrolledText} module provides a class of the same name
-which implements a basic text widget which has a vertical scroll bar
-configured to do the ``right thing.'' Using the \class{ScrolledText}
-class is a lot easier than setting up a text widget and scroll bar
-directly. The constructor is the same as that of the
-\class{Tkinter.Text} class.
-
-The text widget and scrollbar are packed together in a \class{Frame},
-and the methods of the \class{Grid} and \class{Pack} geometry managers
-are acquired from the \class{Frame} object. This allows the
-\class{ScrolledText} widget to be used directly to achieve most normal
-geometry management behavior.
-
-Should more specific control be necessary, the following attributes
-are available:
-
-\begin{memberdesc}[ScrolledText]{frame}
- The frame which surrounds the text and scroll bar widgets.
-\end{memberdesc}
-
-\begin{memberdesc}[ScrolledText]{vbar}
- The scroll bar widget.
-\end{memberdesc}
-
-
-\input{libturtle}
-
-
-\section{Idle \label{idle}}
-
-%\declaremodule{standard}{idle}
-%\modulesynopsis{A Python Integrated Development Environment}
-\moduleauthor{Guido van Rossum}{guido@Python.org}
-
-Idle is the Python IDE built with the \refmodule{Tkinter} GUI toolkit.
-\index{Idle}
-\index{Python Editor}
-\index{Integrated Development Environment}
-
-
-IDLE has the following features:
-
-\begin{itemize}
-\item coded in 100\% pure Python, using the \refmodule{Tkinter} GUI toolkit
-
-\item cross-platform: works on Windows and \UNIX{} (on Mac OS, there are
-currently problems with Tcl/Tk)
-
-\item multi-window text editor with multiple undo, Python colorizing
-and many other features, e.g. smart indent and call tips
-
-\item Python shell window (a.k.a. interactive interpreter)
-
-\item debugger (not complete, but you can set breakpoints, view and step)
-\end{itemize}
-
-
-\subsection{Menus}
-
-\subsubsection{File menu}
-
-\begin{description}
-\item[New window] create a new editing window
-\item[Open...] open an existing file
-\item[Open module...] open an existing module (searches sys.path)
-\item[Class browser] show classes and methods in current file
-\item[Path browser] show sys.path directories, modules, classes and methods
-\end{description}
-\index{Class browser}
-\index{Path browser}
-
-\begin{description}
-\item[Save] save current window to the associated file (unsaved
-windows have a * before and after the window title)
-
-\item[Save As...] save current window to new file, which becomes
-the associated file
-\item[Save Copy As...] save current window to different file
-without changing the associated file
-\end{description}
-
-\begin{description}
-\item[Close] close current window (asks to save if unsaved)
-\item[Exit] close all windows and quit IDLE (asks to save if unsaved)
-\end{description}
-
-
-\subsubsection{Edit menu}
-
-\begin{description}
-\item[Undo] Undo last change to current window (max 1000 changes)
-\item[Redo] Redo last undone change to current window
-\end{description}
-
-\begin{description}
-\item[Cut] Copy selection into system-wide clipboard; then delete selection
-\item[Copy] Copy selection into system-wide clipboard
-\item[Paste] Insert system-wide clipboard into window
-\item[Select All] Select the entire contents of the edit buffer
-\end{description}
-
-\begin{description}
-\item[Find...] Open a search dialog box with many options
-\item[Find again] Repeat last search
-\item[Find selection] Search for the string in the selection
-\item[Find in Files...] Open a search dialog box for searching files
-\item[Replace...] Open a search-and-replace dialog box
-\item[Go to line] Ask for a line number and show that line
-\end{description}
-
-\begin{description}
-\item[Indent region] Shift selected lines right 4 spaces
-\item[Dedent region] Shift selected lines left 4 spaces
-\item[Comment out region] Insert \#\# in front of selected lines
-\item[Uncomment region] Remove leading \# or \#\# from selected lines
-\item[Tabify region] Turns \emph{leading} stretches of spaces into tabs
-\item[Untabify region] Turn \emph{all} tabs into the right number of spaces
-\item[Expand word] Expand the word you have typed to match another
- word in the same buffer; repeat to get a different expansion
-\item[Format Paragraph] Reformat the current blank-line-separated paragraph
-\end{description}
-
-\begin{description}
-\item[Import module] Import or reload the current module
-\item[Run script] Execute the current file in the __main__ namespace
-\end{description}
-
-\index{Import module}
-\index{Run script}
-
-
-\subsubsection{Windows menu}
-
-\begin{description}
-\item[Zoom Height] toggles the window between normal size (24x80)
- and maximum height.
-\end{description}
-
-The rest of this menu lists the names of all open windows; select one
-to bring it to the foreground (deiconifying it if necessary).
-
-
-\subsubsection{Debug menu (in the Python Shell window only)}
-
-\begin{description}
-\item[Go to file/line] look around the insert point for a filename
- and linenumber, open the file, and show the line.
-\item[Open stack viewer] show the stack traceback of the last exception
-\item[Debugger toggle] Run commands in the shell under the debugger
-\item[JIT Stack viewer toggle] Open stack viewer on traceback
-\end{description}
-
-\index{stack viewer}
-\index{debugger}
-
-
-\subsection{Basic editing and navigation}
-
-\begin{itemize}
-\item \kbd{Backspace} deletes to the left; \kbd{Del} deletes to the right
-\item Arrow keys and \kbd{Page Up}/\kbd{Page Down} to move around
-\item \kbd{Home}/\kbd{End} go to begin/end of line
-\item \kbd{C-Home}/\kbd{C-End} go to begin/end of file
-\item Some \program{Emacs} bindings may also work, including \kbd{C-B},
- \kbd{C-P}, \kbd{C-A}, \kbd{C-E}, \kbd{C-D}, \kbd{C-L}
-\end{itemize}
-
-
-\subsubsection{Automatic indentation}
-
-After a block-opening statement, the next line is indented by 4 spaces
-(in the Python Shell window by one tab). After certain keywords
-(break, return etc.) the next line is dedented. In leading
-indentation, \kbd{Backspace} deletes up to 4 spaces if they are there.
-\kbd{Tab} inserts 1-4 spaces (in the Python Shell window one tab).
-See also the indent/dedent region commands in the edit menu.
-
-
-\subsubsection{Python Shell window}
-
-\begin{itemize}
-\item \kbd{C-C} interrupts executing command
-\item \kbd{C-D} sends end-of-file; closes window if typed at
-a \samp{>>>~} prompt
-\end{itemize}
-
-\begin{itemize}
-\item \kbd{Alt-p} retrieves previous command matching what you have typed
-\item \kbd{Alt-n} retrieves next
-\item \kbd{Return} while on any previous command retrieves that command
-\item \kbd{Alt-/} (Expand word) is also useful here
-\end{itemize}
-
-\index{indentation}
-
-
-\subsection{Syntax colors}
-
-The coloring is applied in a background ``thread,'' so you may
-occasionally see uncolorized text. To change the color
-scheme, edit the \code{[Colors]} section in \file{config.txt}.
-
-\begin{description}
-\item[Python syntax colors:]
-
-\begin{description}
-\item[Keywords] orange
-\item[Strings ] green
-\item[Comments] red
-\item[Definitions] blue
-\end{description}
-
-\item[Shell colors:]
-\begin{description}
-\item[Console output] brown
-\item[stdout] blue
-\item[stderr] dark green
-\item[stdin] black
-\end{description}
-\end{description}
-
-
-\subsubsection{Command line usage}
-
-\begin{verbatim}
-idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ...
-
--c command run this command
--d enable debugger
--e edit mode; arguments are files to be edited
--s run $IDLESTARTUP or $PYTHONSTARTUP first
--t title set title of shell window
-\end{verbatim}
-
-If there are arguments:
-
-\begin{enumerate}
-\item If \programopt{-e} is used, arguments are files opened for
- editing and \code{sys.argv} reflects the arguments passed to
- IDLE itself.
-
-\item Otherwise, if \programopt{-c} is used, all arguments are
- placed in \code{sys.argv[1:...]}, with \code{sys.argv[0]} set
- to \code{'-c'}.
-
-\item Otherwise, if neither \programopt{-e} nor \programopt{-c} is
- used, the first argument is a script which is executed with
- the remaining arguments in \code{sys.argv[1:...]} and
- \code{sys.argv[0]} set to the script name. If the script name
- is '-', no script is executed but an interactive Python
- session is started; the arguments are still available in
- \code{sys.argv}.
-\end{enumerate}
-
-
-\section{Other Graphical User Interface Packages
- \label{other-gui-packages}}
-
-
-There are an number of extension widget sets to \refmodule{Tkinter}.
-
-\begin{seealso*}
-\seetitle[http://pmw.sourceforge.net/]{Python megawidgets}{is a
-toolkit for building high-level compound widgets in Python using the
-\refmodule{Tkinter} module. It consists of a set of base classes and
-a library of flexible and extensible megawidgets built on this
-foundation. These megawidgets include notebooks, comboboxes, selection
-widgets, paned widgets, scrolled widgets, dialog windows, etc. Also,
-with the Pmw.Blt interface to BLT, the busy, graph, stripchart, tabset
-and vector commands are be available.
-
-The initial ideas for Pmw were taken from the Tk \code{itcl}
-extensions \code{[incr Tk]} by Michael McLennan and \code{[incr
-Widgets]} by Mark Ulferts. Several of the megawidgets are direct
-translations from the itcl to Python. It offers most of the range of
-widgets that \code{[incr Widgets]} does, and is almost as complete as
-Tix, lacking however Tix's fast \class{HList} widget for drawing trees.
-}
-
-\seetitle[http://tkinter.effbot.org/]{Tkinter3000 Widget Construction
- Kit (WCK)}{%
-is a library that allows you to write new Tkinter widgets in pure
-Python. The WCK framework gives you full control over widget
-creation, configuration, screen appearance, and event handling. WCK
-widgets can be very fast and light-weight, since they can operate
-directly on Python data structures, without having to transfer data
-through the Tk/Tcl layer.}
-\end{seealso*}
-
-Other GUI packages are also available for Python:
-
-\begin{seealso*}
-\seetitle[http://www.wxpython.org]{wxPython}{
-wxPython is a cross-platform GUI toolkit for Python that is built
-around the popular \ulink{wxWidgets}{http://www.wxwidgets.org/} \Cpp{}
-toolkit.  It provides a native look and feel for applications on
-Windows, Mac OS X, and \UNIX{} systems by using each platform's native
-widgets where ever possible, (GTK+ on \UNIX-like systems).  In
-addition to an extensive set of widgets, wxPython provides classes for
-online documentation and context sensitive help, printing, HTML
-viewing, low-level device context drawing, drag and drop, system
-clipboard access, an XML-based resource format and more, including an
-ever growing library of user-contributed modules.  Both the wxWidgets
-and wxPython projects are under active development and continuous
-improvement, and have active and helpful user and developer
-communities.
-}
-\seetitle[http://www.amazon.com/exec/obidos/ASIN/1932394621]
-{wxPython in Action}{
-The wxPython book, by Noel Rappin and Robin Dunn.
-}
-\seetitle{PyQt}{
-PyQt is a \program{sip}-wrapped binding to the Qt toolkit. Qt is an
-extensive \Cpp{} GUI toolkit that is available for \UNIX, Windows and
-Mac OS X. \program{sip} is a tool for generating bindings for \Cpp{}
-libraries as Python classes, and is specifically designed for Python.
-An online manual is available at
-\url{http://www.opendocspublishing.com/pyqt/} (errata are located at
-\url{http://www.valdyas.org/python/book.html}).
-}
-\seetitle[http://www.riverbankcomputing.co.uk/pykde/index.php]{PyKDE}{
-PyKDE is a \program{sip}-wrapped interface to the KDE desktop
-libraries. KDE is a desktop environment for \UNIX{} computers; the
-graphical components are based on Qt.
-}
-\seetitle[http://fxpy.sourceforge.net/]{FXPy}{
-is a Python extension module which provides an interface to the
-\citetitle[http://www.cfdrc.com/FOX/fox.html]{FOX} GUI.
-FOX is a \Cpp{} based Toolkit for developing Graphical User Interfaces
-easily and effectively. It offers a wide, and growing, collection of
-Controls, and provides state of the art facilities such as drag and
-drop, selection, as well as OpenGL widgets for 3D graphical
-manipulation. FOX also implements icons, images, and user-convenience
-features such as status line help, and tooltips.
-
-Even though FOX offers a large collection of controls already, FOX
-leverages \Cpp{} to allow programmers to easily build additional Controls
-and GUI elements, simply by taking existing controls, and creating a
-derived class which simply adds or redefines the desired behavior.
-}
-\seetitle[http://www.daa.com.au/\textasciitilde james/software/pygtk/]{PyGTK}{
-is a set of bindings for the \ulink{GTK}{http://www.gtk.org/} widget set.
-It provides an object oriented interface that is slightly higher
-level than the C one. It automatically does all the type casting and
-reference counting that you would have to do normally with the C
-API. There are also
-\ulink{bindings}{http://www.daa.com.au/\textasciitilde james/gnome/}
-to \ulink{GNOME}{http://www.gnome.org}, and a
-\ulink{tutorial}
-{http://laguna.fmedic.unam.mx/\textasciitilde daniel/pygtutorial/pygtutorial/index.html}
-is available.
-}
-\end{seealso*}
-
-% XXX Reference URLs that compare the different UI packages
diff --git a/Doc/lib/tzinfo-examples.py b/Doc/lib/tzinfo-examples.py
deleted file mode 100644
index 5a2b8ad..0000000
--- a/Doc/lib/tzinfo-examples.py
+++ /dev/null
@@ -1,139 +0,0 @@
-from datetime import tzinfo, timedelta, datetime
-
-ZERO = timedelta(0)
-HOUR = timedelta(hours=1)
-
-# A UTC class.
-
-class UTC(tzinfo):
- """UTC"""
-
- def utcoffset(self, dt):
- return ZERO
-
- def tzname(self, dt):
- return "UTC"
-
- def dst(self, dt):
- return ZERO
-
-utc = UTC()
-
-# A class building tzinfo objects for fixed-offset time zones.
-# Note that FixedOffset(0, "UTC") is a different way to build a
-# UTC tzinfo object.
-
-class FixedOffset(tzinfo):
- """Fixed offset in minutes east from UTC."""
-
- def __init__(self, offset, name):
- self.__offset = timedelta(minutes = offset)
- self.__name = name
-
- def utcoffset(self, dt):
- return self.__offset
-
- def tzname(self, dt):
- return self.__name
-
- def dst(self, dt):
- return ZERO
-
-# A class capturing the platform's idea of local time.
-
-import time as _time
-
-STDOFFSET = timedelta(seconds = -_time.timezone)
-if _time.daylight:
- DSTOFFSET = timedelta(seconds = -_time.altzone)
-else:
- DSTOFFSET = STDOFFSET
-
-DSTDIFF = DSTOFFSET - STDOFFSET
-
-class LocalTimezone(tzinfo):
-
- def utcoffset(self, dt):
- if self._isdst(dt):
- return DSTOFFSET
- else:
- return STDOFFSET
-
- def dst(self, dt):
- if self._isdst(dt):
- return DSTDIFF
- else:
- return ZERO
-
- def tzname(self, dt):
- return _time.tzname[self._isdst(dt)]
-
- def _isdst(self, dt):
- tt = (dt.year, dt.month, dt.day,
- dt.hour, dt.minute, dt.second,
- dt.weekday(), 0, -1)
- stamp = _time.mktime(tt)
- tt = _time.localtime(stamp)
- return tt.tm_isdst > 0
-
-Local = LocalTimezone()
-
-
-# A complete implementation of current DST rules for major US time zones.
-
-def first_sunday_on_or_after(dt):
- days_to_go = 6 - dt.weekday()
- if days_to_go:
- dt += timedelta(days_to_go)
- return dt
-
-# In the US, DST starts at 2am (standard time) on the first Sunday in April.
-DSTSTART = datetime(1, 4, 1, 2)
-# and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct.
-# which is the first Sunday on or after Oct 25.
-DSTEND = datetime(1, 10, 25, 1)
-
-class USTimeZone(tzinfo):
-
- def __init__(self, hours, reprname, stdname, dstname):
- self.stdoffset = timedelta(hours=hours)
- self.reprname = reprname
- self.stdname = stdname
- self.dstname = dstname
-
- def __repr__(self):
- return self.reprname
-
- def tzname(self, dt):
- if self.dst(dt):
- return self.dstname
- else:
- return self.stdname
-
- def utcoffset(self, dt):
- return self.stdoffset + self.dst(dt)
-
- def dst(self, dt):
- if dt is None or dt.tzinfo is None:
- # An exception may be sensible here, in one or both cases.
- # It depends on how you want to treat them. The default
- # fromutc() implementation (called by the default astimezone()
- # implementation) passes a datetime with dt.tzinfo is self.
- return ZERO
- assert dt.tzinfo is self
-
- # Find first Sunday in April & the last in October.
- start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year))
- end = first_sunday_on_or_after(DSTEND.replace(year=dt.year))
-
- # Can't compare naive to aware objects, so strip the timezone from
- # dt first.
- if start <= dt.replace(tzinfo=None) < end:
- return HOUR
- else:
- return ZERO
-
-Eastern = USTimeZone(-5, "Eastern", "EST", "EDT")
-Central = USTimeZone(-6, "Central", "CST", "CDT")
-Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
-Pacific = USTimeZone(-8, "Pacific", "PST", "PDT")
diff --git a/Doc/lib/windows.tex b/Doc/lib/windows.tex
deleted file mode 100644
index ced3559..0000000
--- a/Doc/lib/windows.tex
+++ /dev/null
@@ -1,8 +0,0 @@
-\chapter{MS Windows Specific Services}
-
-
-This chapter describes modules that are only available on MS Windows
-platforms.
-
-
-\localmoduletable
diff --git a/Doc/lib/xmldom.tex b/Doc/lib/xmldom.tex
deleted file mode 100644
index d651bf0..0000000
--- a/Doc/lib/xmldom.tex
+++ /dev/null
@@ -1,928 +0,0 @@
-\section{\module{xml.dom} ---
- The Document Object Model API}
-
-\declaremodule{standard}{xml.dom}
-\modulesynopsis{Document Object Model API for Python.}
-\sectionauthor{Paul Prescod}{paul@prescod.net}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.0}
-
-The Document Object Model, or ``DOM,'' is a cross-language API from
-the World Wide Web Consortium (W3C) for accessing and modifying XML
-documents. A DOM implementation presents an XML document as a tree
-structure, or allows client code to build such a structure from
-scratch. It then gives access to the structure through a set of
-objects which provided well-known interfaces.
-
-The DOM is extremely useful for random-access applications. SAX only
-allows you a view of one bit of the document at a time. If you are
-looking at one SAX element, you have no access to another. If you are
-looking at a text node, you have no access to a containing element.
-When you write a SAX application, you need to keep track of your
-program's position in the document somewhere in your own code. SAX
-does not do it for you. Also, if you need to look ahead in the XML
-document, you are just out of luck.
-
-Some applications are simply impossible in an event driven model with
-no access to a tree. Of course you could build some sort of tree
-yourself in SAX events, but the DOM allows you to avoid writing that
-code. The DOM is a standard tree representation for XML data.
-
-%What if your needs are somewhere between SAX and the DOM? Perhaps
-%you cannot afford to load the entire tree in memory but you find the
-%SAX model somewhat cumbersome and low-level. There is also a module
-%called xml.dom.pulldom that allows you to build trees of only the
-%parts of a document that you need structured access to. It also has
-%features that allow you to find your way around the DOM.
-% See http://www.prescod.net/python/pulldom
-
-The Document Object Model is being defined by the W3C in stages, or
-``levels'' in their terminology. The Python mapping of the API is
-substantially based on the DOM Level~2 recommendation. The mapping of
-the Level~3 specification, currently only available in draft form, is
-being developed by the \ulink{Python XML Special Interest
-Group}{http://www.python.org/sigs/xml-sig/} as part of the
-\ulink{PyXML package}{http://pyxml.sourceforge.net/}. Refer to the
-documentation bundled with that package for information on the current
-state of DOM Level~3 support.
-
-DOM applications typically start by parsing some XML into a DOM. How
-this is accomplished is not covered at all by DOM Level~1, and Level~2
-provides only limited improvements: There is a
-\class{DOMImplementation} object class which provides access to
-\class{Document} creation methods, but no way to access an XML
-reader/parser/Document builder in an implementation-independent way.
-There is also no well-defined way to access these methods without an
-existing \class{Document} object. In Python, each DOM implementation
-will provide a function \function{getDOMImplementation()}. DOM Level~3
-adds a Load/Store specification, which defines an interface to the
-reader, but this is not yet available in the Python standard library.
-
-Once you have a DOM document object, you can access the parts of your
-XML document through its properties and methods. These properties are
-defined in the DOM specification; this portion of the reference manual
-describes the interpretation of the specification in Python.
-
-The specification provided by the W3C defines the DOM API for Java,
-ECMAScript, and OMG IDL. The Python mapping defined here is based in
-large part on the IDL version of the specification, but strict
-compliance is not required (though implementations are free to support
-the strict mapping from IDL). See section \ref{dom-conformance},
-``Conformance,'' for a detailed discussion of mapping requirements.
-
-
-\begin{seealso}
- \seetitle[http://www.w3.org/TR/DOM-Level-2-Core/]{Document Object
- Model (DOM) Level~2 Specification}
- {The W3C recommendation upon which the Python DOM API is
- based.}
- \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
- Model (DOM) Level~1 Specification}
- {The W3C recommendation for the
- DOM supported by \module{xml.dom.minidom}.}
- \seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a
- full-featured implementation of DOM should use the PyXML
- package.}
- \seetitle[http://www.omg.org/docs/formal/02-11-05.pdf]{Python
- Language Mapping Specification}
- {This specifies the mapping from OMG IDL to Python.}
-\end{seealso}
-
-\subsection{Module Contents}
-
-The \module{xml.dom} contains the following functions:
-
-\begin{funcdesc}{registerDOMImplementation}{name, factory}
-Register the \var{factory} function with the name \var{name}. The
-factory function should return an object which implements the
-\class{DOMImplementation} interface. The factory function can return
-the same object every time, or a new one for each call, as appropriate
-for the specific implementation (e.g. if that implementation supports
-some customization).
-\end{funcdesc}
-
-\begin{funcdesc}{getDOMImplementation}{\optional{name\optional{, features}}}
-Return a suitable DOM implementation. The \var{name} is either
-well-known, the module name of a DOM implementation, or
-\code{None}. If it is not \code{None}, imports the corresponding
-module and returns a \class{DOMImplementation} object if the import
-succeeds. If no name is given, and if the environment variable
-\envvar{PYTHON_DOM} is set, this variable is used to find the
-implementation.
-
-If name is not given, this examines the available implementations to
-find one with the required feature set. If no implementation can be
-found, raise an \exception{ImportError}. The features list must be a
-sequence of \code{(\var{feature}, \var{version})} pairs which are
-passed to the \method{hasFeature()} method on available
-\class{DOMImplementation} objects.
-\end{funcdesc}
-
-
-Some convenience constants are also provided:
-
-\begin{datadesc}{EMPTY_NAMESPACE}
- The value used to indicate that no namespace is associated with a
- node in the DOM. This is typically found as the
- \member{namespaceURI} of a node, or used as the \var{namespaceURI}
- parameter to a namespaces-specific method.
- \versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{XML_NAMESPACE}
- The namespace URI associated with the reserved prefix \code{xml}, as
- defined by
- \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
- (section~4).
- \versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{XMLNS_NAMESPACE}
- The namespace URI for namespace declarations, as defined by
- \citetitle[http://www.w3.org/TR/DOM-Level-2-Core/core.html]{Document
- Object Model (DOM) Level~2 Core Specification} (section~1.1.8).
- \versionadded{2.2}
-\end{datadesc}
-
-\begin{datadesc}{XHTML_NAMESPACE}
- The URI of the XHTML namespace as defined by
- \citetitle[http://www.w3.org/TR/xhtml1/]{XHTML 1.0: The Extensible
- HyperText Markup Language} (section~3.1.1).
- \versionadded{2.2}
-\end{datadesc}
-
-
-% Should the Node documentation go here?
-
-In addition, \module{xml.dom} contains a base \class{Node} class and
-the DOM exception classes. The \class{Node} class provided by this
-module does not implement any of the methods or attributes defined by
-the DOM specification; concrete DOM implementations must provide
-those. The \class{Node} class provided as part of this module does
-provide the constants used for the \member{nodeType} attribute on
-concrete \class{Node} objects; they are located within the class
-rather than at the module level to conform with the DOM
-specifications.
-
-
-\subsection{Objects in the DOM \label{dom-objects}}
-
-The definitive documentation for the DOM is the DOM specification from
-the W3C.
-
-Note that DOM attributes may also be manipulated as nodes instead of
-as simple strings. It is fairly rare that you must do this, however,
-so this usage is not yet documented.
-
-
-\begin{tableiii}{l|l|l}{class}{Interface}{Section}{Purpose}
- \lineiii{DOMImplementation}{\ref{dom-implementation-objects}}
- {Interface to the underlying implementation.}
- \lineiii{Node}{\ref{dom-node-objects}}
- {Base interface for most objects in a document.}
- \lineiii{NodeList}{\ref{dom-nodelist-objects}}
- {Interface for a sequence of nodes.}
- \lineiii{DocumentType}{\ref{dom-documenttype-objects}}
- {Information about the declarations needed to process a document.}
- \lineiii{Document}{\ref{dom-document-objects}}
- {Object which represents an entire document.}
- \lineiii{Element}{\ref{dom-element-objects}}
- {Element nodes in the document hierarchy.}
- \lineiii{Attr}{\ref{dom-attr-objects}}
- {Attribute value nodes on element nodes.}
- \lineiii{Comment}{\ref{dom-comment-objects}}
- {Representation of comments in the source document.}
- \lineiii{Text}{\ref{dom-text-objects}}
- {Nodes containing textual content from the document.}
- \lineiii{ProcessingInstruction}{\ref{dom-pi-objects}}
- {Processing instruction representation.}
-\end{tableiii}
-
-An additional section describes the exceptions defined for working
-with the DOM in Python.
-
-
-\subsubsection{DOMImplementation Objects
- \label{dom-implementation-objects}}
-
-The \class{DOMImplementation} interface provides a way for
-applications to determine the availability of particular features in
-the DOM they are using. DOM Level~2 added the ability to create new
-\class{Document} and \class{DocumentType} objects using the
-\class{DOMImplementation} as well.
-
-\begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version}
-Return true if the feature identified by the pair of strings
-\var{feature} and \var{version} is implemented.
-\end{methoddesc}
-
-\begin{methoddesc}[DOMImplementation]{createDocument}{namespaceUri, qualifiedName, doctype}
-Return a new \class{Document} object (the root of the DOM), with a
-child \class{Element} object having the given \var{namespaceUri} and
-\var{qualifiedName}. The \var{doctype} must be a \class{DocumentType}
-object created by \method{createDocumentType()}, or \code{None}.
-In the Python DOM API, the first two arguments can also be \code{None}
-in order to indicate that no \class{Element} child is to be created.
-\end{methoddesc}
-
-\begin{methoddesc}[DOMImplementation]{createDocumentType}{qualifiedName, publicId, systemId}
-Return a new \class{DocumentType} object that encapsulates the given
-\var{qualifiedName}, \var{publicId}, and \var{systemId} strings,
-representing the information contained in an XML document type
-declaration.
-\end{methoddesc}
-
-
-\subsubsection{Node Objects \label{dom-node-objects}}
-
-All of the components of an XML document are subclasses of
-\class{Node}.
-
-\begin{memberdesc}[Node]{nodeType}
-An integer representing the node type. Symbolic constants for the
-types are on the \class{Node} object:
-\constant{ELEMENT_NODE}, \constant{ATTRIBUTE_NODE},
-\constant{TEXT_NODE}, \constant{CDATA_SECTION_NODE},
-\constant{ENTITY_NODE}, \constant{PROCESSING_INSTRUCTION_NODE},
-\constant{COMMENT_NODE}, \constant{DOCUMENT_NODE},
-\constant{DOCUMENT_TYPE_NODE}, \constant{NOTATION_NODE}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{parentNode}
-The parent of the current node, or \code{None} for the document node.
-The value is always a \class{Node} object or \code{None}. For
-\class{Element} nodes, this will be the parent element, except for the
-root element, in which case it will be the \class{Document} object.
-For \class{Attr} nodes, this is always \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{attributes}
-A \class{NamedNodeMap} of attribute objects. Only elements have
-actual values for this; others provide \code{None} for this attribute.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{previousSibling}
-The node that immediately precedes this one with the same parent. For
-instance the element with an end-tag that comes just before the
-\var{self} element's start-tag. Of course, XML documents are made
-up of more than just elements so the previous sibling could be text, a
-comment, or something else. If this node is the first child of the
-parent, this attribute will be \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{nextSibling}
-The node that immediately follows this one with the same parent. See
-also \member{previousSibling}. If this is the last child of the
-parent, this attribute will be \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{childNodes}
-A list of nodes contained within this node.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{firstChild}
-The first child of the node, if there are any, or \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{lastChild}
-The last child of the node, if there are any, or \code{None}.
-This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{localName}
-The part of the \member{tagName} following the colon if there is one,
-else the entire \member{tagName}. The value is a string.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{prefix}
-The part of the \member{tagName} preceding the colon if there is one,
-else the empty string. The value is a string, or \code{None}
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{namespaceURI}
-The namespace associated with the element name. This will be a
-string or \code{None}. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{nodeName}
-This has a different meaning for each node type; see the DOM
-specification for details. You can always get the information you
-would get here from another property such as the \member{tagName}
-property for elements or the \member{name} property for attributes.
-For all node types, the value of this attribute will be either a
-string or \code{None}. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Node]{nodeValue}
-This has a different meaning for each node type; see the DOM
-specification for details. The situation is similar to that with
-\member{nodeName}. The value is a string or \code{None}.
-\end{memberdesc}
-
-\begin{methoddesc}[Node]{hasAttributes}{}
-Returns true if the node has any attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{hasChildNodes}{}
-Returns true if the node has any child nodes.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{isSameNode}{other}
-Returns true if \var{other} refers to the same node as this node.
-This is especially useful for DOM implementations which use any sort
-of proxy architecture (because more than one object can refer to the
-same node).
-
-\begin{notice}
- This is based on a proposed DOM Level~3 API which is still in the
- ``working draft'' stage, but this particular interface appears
- uncontroversial. Changes from the W3C will not necessarily affect
- this method in the Python DOM interface (though any new W3C API for
- this would also be supported).
-\end{notice}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{appendChild}{newChild}
-Add a new child node to this node at the end of the list of children,
-returning \var{newChild}.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{insertBefore}{newChild, refChild}
-Insert a new child node before an existing child. It must be the case
-that \var{refChild} is a child of this node; if not,
-\exception{ValueError} is raised. \var{newChild} is returned. If
-\var{refChild} is \code{None}, it inserts \var{newChild} at the end of
-the children's list.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{removeChild}{oldChild}
-Remove a child node. \var{oldChild} must be a child of this node; if
-not, \exception{ValueError} is raised. \var{oldChild} is returned on
-success. If \var{oldChild} will not be used further, its
-\method{unlink()} method should be called.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{replaceChild}{newChild, oldChild}
-Replace an existing node with a new node. It must be the case that
-\var{oldChild} is a child of this node; if not,
-\exception{ValueError} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{normalize}{}
-Join adjacent text nodes so that all stretches of text are stored as
-single \class{Text} instances. This simplifies processing text from a
-DOM tree for many applications.
-\versionadded{2.1}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{cloneNode}{deep}
-Clone this node. Setting \var{deep} means to clone all child nodes as
-well. This returns the clone.
-\end{methoddesc}
-
-
-\subsubsection{NodeList Objects \label{dom-nodelist-objects}}
-
-A \class{NodeList} represents a sequence of nodes. These objects are
-used in two ways in the DOM Core recommendation: the
-\class{Element} objects provides one as its list of child nodes, and
-the \method{getElementsByTagName()} and
-\method{getElementsByTagNameNS()} methods of \class{Node} return
-objects with this interface to represent query results.
-
-The DOM Level~2 recommendation defines one method and one attribute
-for these objects:
-
-\begin{methoddesc}[NodeList]{item}{i}
- Return the \var{i}'th item from the sequence, if there is one, or
- \code{None}. The index \var{i} is not allowed to be less then zero
- or greater than or equal to the length of the sequence.
-\end{methoddesc}
-
-\begin{memberdesc}[NodeList]{length}
- The number of nodes in the sequence.
-\end{memberdesc}
-
-In addition, the Python DOM interface requires that some additional
-support is provided to allow \class{NodeList} objects to be used as
-Python sequences. All \class{NodeList} implementations must include
-support for \method{__len__()} and \method{__getitem__()}; this allows
-iteration over the \class{NodeList} in \keyword{for} statements and
-proper support for the \function{len()} built-in function.
-
-If a DOM implementation supports modification of the document, the
-\class{NodeList} implementation must also support the
-\method{__setitem__()} and \method{__delitem__()} methods.
-
-
-\subsubsection{DocumentType Objects \label{dom-documenttype-objects}}
-
-Information about the notations and entities declared by a document
-(including the external subset if the parser uses it and can provide
-the information) is available from a \class{DocumentType} object. The
-\class{DocumentType} for a document is available from the
-\class{Document} object's \member{doctype} attribute; if there is no
-\code{DOCTYPE} declaration for the document, the document's
-\member{doctype} attribute will be set to \code{None} instead of an
-instance of this interface.
-
-\class{DocumentType} is a specialization of \class{Node}, and adds the
-following attributes:
-
-\begin{memberdesc}[DocumentType]{publicId}
- The public identifier for the external subset of the document type
- definition. This will be a string or \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{systemId}
- The system identifier for the external subset of the document type
- definition. This will be a URI as a string, or \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{internalSubset}
- A string giving the complete internal subset from the document.
- This does not include the brackets which enclose the subset. If the
- document has no internal subset, this should be \code{None}.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{name}
- The name of the root element as given in the \code{DOCTYPE}
- declaration, if present.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{entities}
- This is a \class{NamedNodeMap} giving the definitions of external
- entities. For entity names defined more than once, only the first
- definition is provided (others are ignored as required by the XML
- recommendation). This may be \code{None} if the information is not
- provided by the parser, or if no entities are defined.
-\end{memberdesc}
-
-\begin{memberdesc}[DocumentType]{notations}
- This is a \class{NamedNodeMap} giving the definitions of notations.
- For notation names defined more than once, only the first definition
- is provided (others are ignored as required by the XML
- recommendation). This may be \code{None} if the information is not
- provided by the parser, or if no notations are defined.
-\end{memberdesc}
-
-
-\subsubsection{Document Objects \label{dom-document-objects}}
-
-A \class{Document} represents an entire XML document, including its
-constituent elements, attributes, processing instructions, comments
-etc. Remeber that it inherits properties from \class{Node}.
-
-\begin{memberdesc}[Document]{documentElement}
-The one and only root element of the document.
-\end{memberdesc}
-
-\begin{methoddesc}[Document]{createElement}{tagName}
-Create and return a new element node. The element is not inserted
-into the document when it is created. You need to explicitly insert
-it with one of the other methods such as \method{insertBefore()} or
-\method{appendChild()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName}
-Create and return a new element with a namespace. The
-\var{tagName} may have a prefix. The element is not inserted into the
-document when it is created. You need to explicitly insert it with
-one of the other methods such as \method{insertBefore()} or
-\method{appendChild()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createTextNode}{data}
-Create and return a text node containing the data passed as a
-parameter. As with the other creation methods, this one does not
-insert the node into the tree.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createComment}{data}
-Create and return a comment node containing the data passed as a
-parameter. As with the other creation methods, this one does not
-insert the node into the tree.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createProcessingInstruction}{target, data}
-Create and return a processing instruction node containing the
-\var{target} and \var{data} passed as parameters. As with the other
-creation methods, this one does not insert the node into the tree.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createAttribute}{name}
-Create and return an attribute node. This method does not associate
-the attribute node with any particular element. You must use
-\method{setAttributeNode()} on the appropriate \class{Element} object
-to use the newly created attribute instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName}
-Create and return an attribute node with a namespace. The
-\var{tagName} may have a prefix. This method does not associate the
-attribute node with any particular element. You must use
-\method{setAttributeNode()} on the appropriate \class{Element} object
-to use the newly created attribute instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{getElementsByTagName}{tagName}
-Search for all descendants (direct children, children's children,
-etc.) with a particular element type name.
-\end{methoddesc}
-
-\begin{methoddesc}[Document]{getElementsByTagNameNS}{namespaceURI, localName}
-Search for all descendants (direct children, children's children,
-etc.) with a particular namespace URI and localname. The localname is
-the part of the namespace after the prefix.
-\end{methoddesc}
-
-
-\subsubsection{Element Objects \label{dom-element-objects}}
-
-\class{Element} is a subclass of \class{Node}, so inherits all the
-attributes of that class.
-
-\begin{memberdesc}[Element]{tagName}
-The element type name. In a namespace-using document it may have
-colons in it. The value is a string.
-\end{memberdesc}
-
-\begin{methoddesc}[Element]{getElementsByTagName}{tagName}
-Same as equivalent method in the \class{Document} class.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName}
-Same as equivalent method in the \class{Document} class.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{hasAttribute}{name}
-Returns true if the element has an attribute named by \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{hasAttributeNS}{namespaceURI, localName}
-Returns true if the element has an attribute named by
-\var{namespaceURI} and \var{localName}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttribute}{name}
-Return the value of the attribute named by \var{name} as a
-string. If no such attribute exists, an empty string is returned,
-as if the attribute had no value.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttributeNode}{attrname}
-Return the \class{Attr} node for the attribute named by
-\var{attrname}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttributeNS}{namespaceURI, localName}
-Return the value of the attribute named by \var{namespaceURI} and
-\var{localName} as a string. If no such attribute exists, an empty
-string is returned, as if the attribute had no value.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{getAttributeNodeNS}{namespaceURI, localName}
-Return an attribute value as a node, given a \var{namespaceURI} and
-\var{localName}.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{removeAttribute}{name}
-Remove an attribute by name. No exception is raised if there is no
-matching attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{removeAttributeNode}{oldAttr}
-Remove and return \var{oldAttr} from the attribute list, if present.
-If \var{oldAttr} is not present, \exception{NotFoundErr} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{removeAttributeNS}{namespaceURI, localName}
-Remove an attribute by name. Note that it uses a localName, not a
-qname. No exception is raised if there is no matching attribute.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttribute}{name, value}
-Set an attribute value from a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttributeNode}{newAttr}
-Add a new attribute node to the element, replacing an existing
-attribute if necessary if the \member{name} attribute matches. If a
-replacement occurs, the old attribute node will be returned. If
-\var{newAttr} is already in use, \exception{InuseAttributeErr} will be
-raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttributeNodeNS}{newAttr}
-Add a new attribute node to the element, replacing an existing
-attribute if necessary if the \member{namespaceURI} and
-\member{localName} attributes match. If a replacement occurs, the old
-attribute node will be returned. If \var{newAttr} is already in use,
-\exception{InuseAttributeErr} will be raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Element]{setAttributeNS}{namespaceURI, qname, value}
-Set an attribute value from a string, given a \var{namespaceURI} and a
-\var{qname}. Note that a qname is the whole attribute name. This is
-different than above.
-\end{methoddesc}
-
-
-\subsubsection{Attr Objects \label{dom-attr-objects}}
-
-\class{Attr} inherits from \class{Node}, so inherits all its
-attributes.
-
-\begin{memberdesc}[Attr]{name}
-The attribute name. In a namespace-using document it may have colons
-in it.
-\end{memberdesc}
-
-\begin{memberdesc}[Attr]{localName}
-The part of the name following the colon if there is one, else the
-entire name. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[Attr]{prefix}
-The part of the name preceding the colon if there is one, else the
-empty string.
-\end{memberdesc}
-
-
-\subsubsection{NamedNodeMap Objects \label{dom-attributelist-objects}}
-
-\class{NamedNodeMap} does \emph{not} inherit from \class{Node}.
-
-\begin{memberdesc}[NamedNodeMap]{length}
-The length of the attribute list.
-\end{memberdesc}
-
-\begin{methoddesc}[NamedNodeMap]{item}{index}
-Return an attribute with a particular index. The order you get the
-attributes in is arbitrary but will be consistent for the life of a
-DOM. Each item is an attribute node. Get its value with the
-\member{value} attribute.
-\end{methoddesc}
-
-There are also experimental methods that give this class more mapping
-behavior. You can use them or you can use the standardized
-\method{getAttribute*()} family of methods on the \class{Element}
-objects.
-
-
-\subsubsection{Comment Objects \label{dom-comment-objects}}
-
-\class{Comment} represents a comment in the XML document. It is a
-subclass of \class{Node}, but cannot have child nodes.
-
-\begin{memberdesc}[Comment]{data}
-The content of the comment as a string. The attribute contains all
-characters between the leading \code{<!-}\code{-} and trailing
-\code{-}\code{->}, but does not include them.
-\end{memberdesc}
-
-
-\subsubsection{Text and CDATASection Objects \label{dom-text-objects}}
-
-The \class{Text} interface represents text in the XML document. If
-the parser and DOM implementation support the DOM's XML extension,
-portions of the text enclosed in CDATA marked sections are stored in
-\class{CDATASection} objects. These two interfaces are identical, but
-provide different values for the \member{nodeType} attribute.
-
-These interfaces extend the \class{Node} interface. They cannot have
-child nodes.
-
-\begin{memberdesc}[Text]{data}
-The content of the text node as a string.
-\end{memberdesc}
-
-\begin{notice}
- The use of a \class{CDATASection} node does not indicate that the
- node represents a complete CDATA marked section, only that the
- content of the node was part of a CDATA section. A single CDATA
- section may be represented by more than one node in the document
- tree. There is no way to determine whether two adjacent
- \class{CDATASection} nodes represent different CDATA marked
- sections.
-\end{notice}
-
-
-\subsubsection{ProcessingInstruction Objects \label{dom-pi-objects}}
-
-Represents a processing instruction in the XML document; this inherits
-from the \class{Node} interface and cannot have child nodes.
-
-\begin{memberdesc}[ProcessingInstruction]{target}
-The content of the processing instruction up to the first whitespace
-character. This is a read-only attribute.
-\end{memberdesc}
-
-\begin{memberdesc}[ProcessingInstruction]{data}
-The content of the processing instruction following the first
-whitespace character.
-\end{memberdesc}
-
-
-\subsubsection{Exceptions \label{dom-exceptions}}
-
-\versionadded{2.1}
-
-The DOM Level~2 recommendation defines a single exception,
-\exception{DOMException}, and a number of constants that allow
-applications to determine what sort of error occurred.
-\exception{DOMException} instances carry a \member{code} attribute
-that provides the appropriate value for the specific exception.
-
-The Python DOM interface provides the constants, but also expands the
-set of exceptions so that a specific exception exists for each of the
-exception codes defined by the DOM. The implementations must raise
-the appropriate specific exception, each of which carries the
-appropriate value for the \member{code} attribute.
-
-\begin{excdesc}{DOMException}
- Base exception class used for all specific DOM exceptions. This
- exception class cannot be directly instantiated.
-\end{excdesc}
-
-\begin{excdesc}{DomstringSizeErr}
- Raised when a specified range of text does not fit into a string.
- This is not known to be used in the Python DOM implementations, but
- may be received from DOM implementations not written in Python.
-\end{excdesc}
-
-\begin{excdesc}{HierarchyRequestErr}
- Raised when an attempt is made to insert a node where the node type
- is not allowed.
-\end{excdesc}
-
-\begin{excdesc}{IndexSizeErr}
- Raised when an index or size parameter to a method is negative or
- exceeds the allowed values.
-\end{excdesc}
-
-\begin{excdesc}{InuseAttributeErr}
- Raised when an attempt is made to insert an \class{Attr} node that
- is already present elsewhere in the document.
-\end{excdesc}
-
-\begin{excdesc}{InvalidAccessErr}
- Raised if a parameter or an operation is not supported on the
- underlying object.
-\end{excdesc}
-
-\begin{excdesc}{InvalidCharacterErr}
- This exception is raised when a string parameter contains a
- character that is not permitted in the context it's being used in by
- the XML 1.0 recommendation. For example, attempting to create an
- \class{Element} node with a space in the element type name will
- cause this error to be raised.
-\end{excdesc}
-
-\begin{excdesc}{InvalidModificationErr}
- Raised when an attempt is made to modify the type of a node.
-\end{excdesc}
-
-\begin{excdesc}{InvalidStateErr}
- Raised when an attempt is made to use an object that is not defined or is no
- longer usable.
-\end{excdesc}
-
-\begin{excdesc}{NamespaceErr}
- If an attempt is made to change any object in a way that is not
- permitted with regard to the
- \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
- recommendation, this exception is raised.
-\end{excdesc}
-
-\begin{excdesc}{NotFoundErr}
- Exception when a node does not exist in the referenced context. For
- example, \method{NamedNodeMap.removeNamedItem()} will raise this if
- the node passed in does not exist in the map.
-\end{excdesc}
-
-\begin{excdesc}{NotSupportedErr}
- Raised when the implementation does not support the requested type
- of object or operation.
-\end{excdesc}
-
-\begin{excdesc}{NoDataAllowedErr}
- This is raised if data is specified for a node which does not
- support data.
- % XXX a better explanation is needed!
-\end{excdesc}
-
-\begin{excdesc}{NoModificationAllowedErr}
- Raised on attempts to modify an object where modifications are not
- allowed (such as for read-only nodes).
-\end{excdesc}
-
-\begin{excdesc}{SyntaxErr}
- Raised when an invalid or illegal string is specified.
- % XXX how is this different from InvalidCharacterErr ???
-\end{excdesc}
-
-\begin{excdesc}{WrongDocumentErr}
- Raised when a node is inserted in a different document than it
- currently belongs to, and the implementation does not support
- migrating the node from one document to the other.
-\end{excdesc}
-
-The exception codes defined in the DOM recommendation map to the
-exceptions described above according to this table:
-
-\begin{tableii}{l|l}{constant}{Constant}{Exception}
- \lineii{DOMSTRING_SIZE_ERR}{\exception{DomstringSizeErr}}
- \lineii{HIERARCHY_REQUEST_ERR}{\exception{HierarchyRequestErr}}
- \lineii{INDEX_SIZE_ERR}{\exception{IndexSizeErr}}
- \lineii{INUSE_ATTRIBUTE_ERR}{\exception{InuseAttributeErr}}
- \lineii{INVALID_ACCESS_ERR}{\exception{InvalidAccessErr}}
- \lineii{INVALID_CHARACTER_ERR}{\exception{InvalidCharacterErr}}
- \lineii{INVALID_MODIFICATION_ERR}{\exception{InvalidModificationErr}}
- \lineii{INVALID_STATE_ERR}{\exception{InvalidStateErr}}
- \lineii{NAMESPACE_ERR}{\exception{NamespaceErr}}
- \lineii{NOT_FOUND_ERR}{\exception{NotFoundErr}}
- \lineii{NOT_SUPPORTED_ERR}{\exception{NotSupportedErr}}
- \lineii{NO_DATA_ALLOWED_ERR}{\exception{NoDataAllowedErr}}
- \lineii{NO_MODIFICATION_ALLOWED_ERR}{\exception{NoModificationAllowedErr}}
- \lineii{SYNTAX_ERR}{\exception{SyntaxErr}}
- \lineii{WRONG_DOCUMENT_ERR}{\exception{WrongDocumentErr}}
-\end{tableii}
-
-
-\subsection{Conformance \label{dom-conformance}}
-
-This section describes the conformance requirements and relationships
-between the Python DOM API, the W3C DOM recommendations, and the OMG
-IDL mapping for Python.
-
-
-\subsubsection{Type Mapping \label{dom-type-mapping}}
-
-The primitive IDL types used in the DOM specification are mapped to
-Python types according to the following table.
-
-\begin{tableii}{l|l}{code}{IDL Type}{Python Type}
- \lineii{boolean}{\code{IntegerType} (with a value of \code{0} or \code{1})}
- \lineii{int}{\code{IntegerType}}
- \lineii{long int}{\code{IntegerType}}
- \lineii{unsigned int}{\code{IntegerType}}
-\end{tableii}
-
-Additionally, the \class{DOMString} defined in the recommendation is
-mapped to a Python string or Unicode string. Applications should
-be able to handle Unicode whenever a string is returned from the DOM.
-
-The IDL \keyword{null} value is mapped to \code{None}, which may be
-accepted or provided by the implementation whenever \keyword{null} is
-allowed by the API.
-
-
-\subsubsection{Accessor Methods \label{dom-accessor-methods}}
-
-The mapping from OMG IDL to Python defines accessor functions for IDL
-\keyword{attribute} declarations in much the way the Java mapping
-does. Mapping the IDL declarations
-
-\begin{verbatim}
-readonly attribute string someValue;
- attribute string anotherValue;
-\end{verbatim}
-
-yields three accessor functions: a ``get'' method for
-\member{someValue} (\method{_get_someValue()}), and ``get'' and
-``set'' methods for
-\member{anotherValue} (\method{_get_anotherValue()} and
-\method{_set_anotherValue()}). The mapping, in particular, does not
-require that the IDL attributes are accessible as normal Python
-attributes: \code{\var{object}.someValue} is \emph{not} required to
-work, and may raise an \exception{AttributeError}.
-
-The Python DOM API, however, \emph{does} require that normal attribute
-access work. This means that the typical surrogates generated by
-Python IDL compilers are not likely to work, and wrapper objects may
-be needed on the client if the DOM objects are accessed via CORBA.
-While this does require some additional consideration for CORBA DOM
-clients, the implementers with experience using DOM over CORBA from
-Python do not consider this a problem. Attributes that are declared
-\keyword{readonly} may not restrict write access in all DOM
-implementations.
-
-In the Python DOM API, accessor functions are not required. If provided,
-they should take the form defined by the Python IDL mapping, but
-these methods are considered unnecessary since the attributes are
-accessible directly from Python. ``Set'' accessors should never be
-provided for \keyword{readonly} attributes.
-
-The IDL definitions do not fully embody the requirements of the W3C DOM
-API, such as the notion of certain objects, such as the return value of
-\method{getElementsByTagName()}, being ``live''. The Python DOM API
-does not require implementations to enforce such requirements.
diff --git a/Doc/lib/xmldomminidom.tex b/Doc/lib/xmldomminidom.tex
deleted file mode 100644
index 093915f..0000000
--- a/Doc/lib/xmldomminidom.tex
+++ /dev/null
@@ -1,285 +0,0 @@
-\section{\module{xml.dom.minidom} ---
- Lightweight DOM implementation}
-
-\declaremodule{standard}{xml.dom.minidom}
-\modulesynopsis{Lightweight Document Object Model (DOM) implementation.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
-\sectionauthor{Paul Prescod}{paul@prescod.net}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.0}
-
-\module{xml.dom.minidom} is a light-weight implementation of the
-Document Object Model interface. It is intended to be
-simpler than the full DOM and also significantly smaller.
-
-DOM applications typically start by parsing some XML into a DOM. With
-\module{xml.dom.minidom}, this is done through the parse functions:
-
-\begin{verbatim}
-from xml.dom.minidom import parse, parseString
-
-dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name
-
-datasource = open('c:\\temp\\mydata.xml')
-dom2 = parse(datasource) # parse an open file
-
-dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
-\end{verbatim}
-
-The \function{parse()} function can take either a filename or an open
-file object.
-
-\begin{funcdesc}{parse}{filename_or_file{, parser}}
- Return a \class{Document} from the given input. \var{filename_or_file}
- may be either a file name, or a file-like object. \var{parser}, if
- given, must be a SAX2 parser object. This function will change the
- document handler of the parser and activate namespace support; other
- parser configuration (like setting an entity resolver) must have been
- done in advance.
-\end{funcdesc}
-
-If you have XML in a string, you can use the
-\function{parseString()} function instead:
-
-\begin{funcdesc}{parseString}{string\optional{, parser}}
- Return a \class{Document} that represents the \var{string}. This
- method creates a \class{StringIO} object for the string and passes
- that on to \function{parse}.
-\end{funcdesc}
-
-Both functions return a \class{Document} object representing the
-content of the document.
-
-What the \function{parse()} and \function{parseString()} functions do
-is connect an XML parser with a ``DOM builder'' that can accept parse
-events from any SAX parser and convert them into a DOM tree. The name
-of the functions are perhaps misleading, but are easy to grasp when
-learning the interfaces. The parsing of the document will be
-completed before these functions return; it's simply that these
-functions do not provide a parser implementation themselves.
-
-You can also create a \class{Document} by calling a method on a ``DOM
-Implementation'' object. You can get this object either by calling
-the \function{getDOMImplementation()} function in the
-\refmodule{xml.dom} package or the \module{xml.dom.minidom} module.
-Using the implementation from the \module{xml.dom.minidom} module will
-always return a \class{Document} instance from the minidom
-implementation, while the version from \refmodule{xml.dom} may provide
-an alternate implementation (this is likely if you have the
-\ulink{PyXML package}{http://pyxml.sourceforge.net/} installed). Once
-you have a \class{Document}, you can add child nodes to it to populate
-the DOM:
-
-\begin{verbatim}
-from xml.dom.minidom import getDOMImplementation
-
-impl = getDOMImplementation()
-
-newdoc = impl.createDocument(None, "some_tag", None)
-top_element = newdoc.documentElement
-text = newdoc.createTextNode('Some textual content.')
-top_element.appendChild(text)
-\end{verbatim}
-
-Once you have a DOM document object, you can access the parts of your
-XML document through its properties and methods. These properties are
-defined in the DOM specification. The main property of the document
-object is the \member{documentElement} property. It gives you the
-main element in the XML document: the one that holds all others. Here
-is an example program:
-
-\begin{verbatim}
-dom3 = parseString("<myxml>Some data</myxml>")
-assert dom3.documentElement.tagName == "myxml"
-\end{verbatim}
-
-When you are finished with a DOM, you should clean it up. This is
-necessary because some versions of Python do not support garbage
-collection of objects that refer to each other in a cycle. Until this
-restriction is removed from all versions of Python, it is safest to
-write your code as if cycles would not be cleaned up.
-
-The way to clean up a DOM is to call its \method{unlink()} method:
-
-\begin{verbatim}
-dom1.unlink()
-dom2.unlink()
-dom3.unlink()
-\end{verbatim}
-
-\method{unlink()} is a \module{xml.dom.minidom}-specific extension to
-the DOM API. After calling \method{unlink()} on a node, the node and
-its descendants are essentially useless.
-
-\begin{seealso}
- \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object
- Model (DOM) Level 1 Specification}
- {The W3C recommendation for the
- DOM supported by \module{xml.dom.minidom}.}
-\end{seealso}
-
-
-\subsection{DOM Objects \label{dom-objects}}
-
-The definition of the DOM API for Python is given as part of the
-\refmodule{xml.dom} module documentation. This section lists the
-differences between the API and \refmodule{xml.dom.minidom}.
-
-
-\begin{methoddesc}[Node]{unlink}{}
-Break internal references within the DOM so that it will be garbage
-collected on versions of Python without cyclic GC. Even when cyclic
-GC is available, using this can make large amounts of memory available
-sooner, so calling this on DOM objects as soon as they are no longer
-needed is good practice. This only needs to be called on the
-\class{Document} object, but may be called on child nodes to discard
-children of that node.
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{writexml}{writer\optional{,indent=""\optional{,addindent=""\optional{,newl=""}}}}
-Write XML to the writer object. The writer should have a
-\method{write()} method which matches that of the file object
-interface. The \var{indent} parameter is the indentation of the current
-node. The \var{addindent} parameter is the incremental indentation to use
-for subnodes of the current one. The \var{newl} parameter specifies the
-string to use to terminate newlines.
-
-\versionchanged[The optional keyword parameters
-\var{indent}, \var{addindent}, and \var{newl} were added to support pretty
-output]{2.1}
-
-\versionchanged[For the \class{Document} node, an additional keyword
-argument \var{encoding} can be used to specify the encoding field of the XML
-header]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{toxml}{\optional{encoding}}
-Return the XML that the DOM represents as a string.
-
-With no argument, the XML header does not specify an encoding, and the
-result is Unicode string if the default encoding cannot represent all
-characters in the document. Encoding this string in an encoding other
-than UTF-8 is likely incorrect, since UTF-8 is the default encoding of
-XML.
-
-With an explicit \var{encoding} argument, the result is a byte string
-in the specified encoding. It is recommended that this argument is
-always specified. To avoid \exception{UnicodeError} exceptions in case of
-unrepresentable text data, the encoding argument should be specified
-as "utf-8".
-
-\versionchanged[the \var{encoding} argument was introduced]{2.3}
-\end{methoddesc}
-
-\begin{methoddesc}[Node]{toprettyxml}{\optional{indent\optional{, newl}}}
-Return a pretty-printed version of the document. \var{indent} specifies
-the indentation string and defaults to a tabulator; \var{newl} specifies
-the string emitted at the end of each line and defaults to \code{\e n}.
-
-\versionadded{2.1}
-\versionchanged[the encoding argument; see \method{toxml()}]{2.3}
-\end{methoddesc}
-
-The following standard DOM methods have special considerations with
-\refmodule{xml.dom.minidom}:
-
-\begin{methoddesc}[Node]{cloneNode}{deep}
-Although this method was present in the version of
-\refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously
-broken. This has been corrected for subsequent releases.
-\end{methoddesc}
-
-
-\subsection{DOM Example \label{dom-example}}
-
-This example program is a fairly realistic example of a simple
-program. In this particular case, we do not take much advantage
-of the flexibility of the DOM.
-
-\verbatiminput{minidom-example.py}
-
-
-\subsection{minidom and the DOM standard \label{minidom-and-dom}}
-
-The \refmodule{xml.dom.minidom} module is essentially a DOM
-1.0-compatible DOM with some DOM 2 features (primarily namespace
-features).
-
-Usage of the DOM interface in Python is straight-forward. The
-following mapping rules apply:
-
-\begin{itemize}
-\item Interfaces are accessed through instance objects. Applications
- should not instantiate the classes themselves; they should use
- the creator functions available on the \class{Document} object.
- Derived interfaces support all operations (and attributes) from
- the base interfaces, plus any new operations.
-
-\item Operations are used as methods. Since the DOM uses only
- \keyword{in} parameters, the arguments are passed in normal
- order (from left to right). There are no optional
- arguments. \keyword{void} operations return \code{None}.
-
-\item IDL attributes map to instance attributes. For compatibility
- with the OMG IDL language mapping for Python, an attribute
- \code{foo} can also be accessed through accessor methods
- \method{_get_foo()} and \method{_set_foo()}. \keyword{readonly}
- attributes must not be changed; this is not enforced at
- runtime.
-
-\item The types \code{short int}, \code{unsigned int}, \code{unsigned
- long long}, and \code{boolean} all map to Python integer
- objects.
-
-\item The type \code{DOMString} maps to Python strings.
- \refmodule{xml.dom.minidom} supports either byte or Unicode
- strings, but will normally produce Unicode strings. Values
- of type \code{DOMString} may also be \code{None} where allowed
- to have the IDL \code{null} value by the DOM specification from
- the W3C.
-
-\item \keyword{const} declarations map to variables in their
- respective scope
- (e.g. \code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE});
- they must not be changed.
-
-\item \code{DOMException} is currently not supported in
- \refmodule{xml.dom.minidom}. Instead,
- \refmodule{xml.dom.minidom} uses standard Python exceptions such
- as \exception{TypeError} and \exception{AttributeError}.
-
-\item \class{NodeList} objects are implemented using Python's built-in
- list type. Starting with Python 2.2, these objects provide the
- interface defined in the DOM specification, but with earlier
- versions of Python they do not support the official API. They
- are, however, much more ``Pythonic'' than the interface defined
- in the W3C recommendations.
-\end{itemize}
-
-
-The following interfaces have no implementation in
-\refmodule{xml.dom.minidom}:
-
-\begin{itemize}
-\item \class{DOMTimeStamp}
-
-\item \class{DocumentType} (added in Python 2.1)
-
-\item \class{DOMImplementation} (added in Python 2.1)
-
-\item \class{CharacterData}
-
-\item \class{CDATASection}
-
-\item \class{Notation}
-
-\item \class{Entity}
-
-\item \class{EntityReference}
-
-\item \class{DocumentFragment}
-\end{itemize}
-
-Most of these reflect information in the XML document that is not of
-general utility to most DOM users.
diff --git a/Doc/lib/xmldompulldom.tex b/Doc/lib/xmldompulldom.tex
deleted file mode 100644
index a2ce667..0000000
--- a/Doc/lib/xmldompulldom.tex
+++ /dev/null
@@ -1,61 +0,0 @@
-\section{\module{xml.dom.pulldom} ---
- Support for building partial DOM trees}
-
-\declaremodule{standard}{xml.dom.pulldom}
-\modulesynopsis{Support for building partial DOM trees from SAX events.}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
-
-\versionadded{2.0}
-
-\module{xml.dom.pulldom} allows building only selected portions of a
-Document Object Model representation of a document from SAX events.
-
-
-\begin{classdesc}{PullDOM}{\optional{documentFactory}}
- \class{xml.sax.handler.ContentHandler} implementation that ...
-\end{classdesc}
-
-
-\begin{classdesc}{DOMEventStream}{stream, parser, bufsize}
- ...
-\end{classdesc}
-
-
-\begin{classdesc}{SAX2DOM}{\optional{documentFactory}}
- \class{xml.sax.handler.ContentHandler} implementation that ...
-\end{classdesc}
-
-
-\begin{funcdesc}{parse}{stream_or_string\optional{,
- parser\optional{, bufsize}}}
- ...
-\end{funcdesc}
-
-
-\begin{funcdesc}{parseString}{string\optional{, parser}}
- ...
-\end{funcdesc}
-
-
-\begin{datadesc}{default_bufsize}
- Default value for the \var{bufsize} parameter to \function{parse()}.
- \versionchanged[The value of this variable can be changed before
- calling \function{parse()} and the new value will
- take effect]{2.1}
-\end{datadesc}
-
-
-\subsection{DOMEventStream Objects \label{domeventstream-objects}}
-
-
-\begin{methoddesc}[DOMEventStream]{getEvent}{}
- ...
-\end{methoddesc}
-
-\begin{methoddesc}[DOMEventStream]{expandNode}{node}
- ...
-\end{methoddesc}
-
-\begin{methoddesc}[DOMEventStream]{reset}{}
- ...
-\end{methoddesc}
diff --git a/Doc/lib/xmletree.tex b/Doc/lib/xmletree.tex
deleted file mode 100644
index 789062d..0000000
--- a/Doc/lib/xmletree.tex
+++ /dev/null
@@ -1,27 +0,0 @@
-\section{\module{xml.etree} ---
- The ElementTree API for XML}
-
-\declaremodule{standard}{xml.etree}
-\modulesynopsis{Package containing common ElementTree modules.}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-
-\versionadded{2.5}
-
-The ElementTree package is a simple, efficient, and quite popular
-library for XML manipulation in Python.
-
-The \module{xml.etree} package contains the most common components
-from the ElementTree API library.
-In the current release, this package contains the \module{ElementTree},
-\module{ElementPath}, and \module{ElementInclude} modules from the full
-ElementTree distribution.
-
-% XXX To be continued!
-
-\begin{seealso}
-\seetitle[http://effbot.org/tag/elementtree]
- {ElementTree Overview}
- {The home page for \module{ElementTree}. This includes links
- to additional documentation, alternative implementations, and
- other add-ons.}
-\end{seealso}
diff --git a/Doc/lib/xmlsax.tex b/Doc/lib/xmlsax.tex
deleted file mode 100644
index 838c279..0000000
--- a/Doc/lib/xmlsax.tex
+++ /dev/null
@@ -1,143 +0,0 @@
-\section{\module{xml.sax} ---
- Support for SAX2 parsers}
-
-\declaremodule{standard}{xml.sax}
-\modulesynopsis{Package containing SAX2 base classes and convenience
- functions.}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-
-\versionadded{2.0}
-
-
-The \module{xml.sax} package provides a number of modules which
-implement the Simple API for XML (SAX) interface for Python. The
-package itself provides the SAX exceptions and the convenience
-functions which will be most used by users of the SAX API.
-
-The convenience functions are:
-
-\begin{funcdesc}{make_parser}{\optional{parser_list}}
- Create and return a SAX \class{XMLReader} object. The first parser
- found will be used. If \var{parser_list} is provided, it must be a
- sequence of strings which name modules that have a function named
- \function{create_parser()}. Modules listed in \var{parser_list}
- will be used before modules in the default list of parsers.
-\end{funcdesc}
-
-\begin{funcdesc}{parse}{filename_or_stream, handler\optional{, error_handler}}
- Create a SAX parser and use it to parse a document. The document,
- passed in as \var{filename_or_stream}, can be a filename or a file
- object. The \var{handler} parameter needs to be a SAX
- \class{ContentHandler} instance. If \var{error_handler} is given,
- it must be a SAX \class{ErrorHandler} instance; if omitted,
- \exception{SAXParseException} will be raised on all errors. There
- is no return value; all work must be done by the \var{handler}
- passed in.
-\end{funcdesc}
-
-\begin{funcdesc}{parseString}{string, handler\optional{, error_handler}}
- Similar to \function{parse()}, but parses from a buffer \var{string}
- received as a parameter.
-\end{funcdesc}
-
-A typical SAX application uses three kinds of objects: readers,
-handlers and input sources. ``Reader'' in this context is another
-term for parser, i.e.\ some piece of code that reads the bytes or
-characters from the input source, and produces a sequence of events.
-The events then get distributed to the handler objects, i.e.\ the
-reader invokes a method on the handler. A SAX application must
-therefore obtain a reader object, create or open the input sources,
-create the handlers, and connect these objects all together. As the
-final step of preparation, the reader is called to parse the input.
-During parsing, methods on the handler objects are called based on
-structural and syntactic events from the input data.
-
-For these objects, only the interfaces are relevant; they are normally
-not instantiated by the application itself. Since Python does not have
-an explicit notion of interface, they are formally introduced as
-classes, but applications may use implementations which do not inherit
-from the provided classes. The \class{InputSource}, \class{Locator},
-\class{Attributes}, \class{AttributesNS}, and
-\class{XMLReader} interfaces are defined in the module
-\refmodule{xml.sax.xmlreader}. The handler interfaces are defined in
-\refmodule{xml.sax.handler}. For convenience, \class{InputSource}
-(which is often instantiated directly) and the handler classes are
-also available from \module{xml.sax}. These interfaces are described
-below.
-
-In addition to these classes, \module{xml.sax} provides the following
-exception classes.
-
-\begin{excclassdesc}{SAXException}{msg\optional{, exception}}
- Encapsulate an XML error or warning. This class can contain basic
- error or warning information from either the XML parser or the
- application: it can be subclassed to provide additional
- functionality or to add localization. Note that although the
- handlers defined in the \class{ErrorHandler} interface receive
- instances of this exception, it is not required to actually raise
- the exception --- it is also useful as a container for information.
-
- When instantiated, \var{msg} should be a human-readable description
- of the error. The optional \var{exception} parameter, if given,
- should be \code{None} or an exception that was caught by the parsing
- code and is being passed along as information.
-
- This is the base class for the other SAX exception classes.
-\end{excclassdesc}
-
-\begin{excclassdesc}{SAXParseException}{msg, exception, locator}
- Subclass of \exception{SAXException} raised on parse errors.
- Instances of this class are passed to the methods of the SAX
- \class{ErrorHandler} interface to provide information about the
- parse error. This class supports the SAX \class{Locator} interface
- as well as the \class{SAXException} interface.
-\end{excclassdesc}
-
-\begin{excclassdesc}{SAXNotRecognizedException}{msg\optional{, exception}}
- Subclass of \exception{SAXException} raised when a SAX
- \class{XMLReader} is confronted with an unrecognized feature or
- property. SAX applications and extensions may use this class for
- similar purposes.
-\end{excclassdesc}
-
-\begin{excclassdesc}{SAXNotSupportedException}{msg\optional{, exception}}
- Subclass of \exception{SAXException} raised when a SAX
- \class{XMLReader} is asked to enable a feature that is not
- supported, or to set a property to a value that the implementation
- does not support. SAX applications and extensions may use this
- class for similar purposes.
-\end{excclassdesc}
-
-
-\begin{seealso}
- \seetitle[http://www.saxproject.org/]{SAX: The Simple API for
- XML}{This site is the focal point for the definition of
- the SAX API. It provides a Java implementation and online
- documentation. Links to implementations and historical
- information are also available.}
-
- \seemodule{xml.sax.handler}{Definitions of the interfaces for
- application-provided objects.}
-
- \seemodule{xml.sax.saxutils}{Convenience functions for use in SAX
- applications.}
-
- \seemodule{xml.sax.xmlreader}{Definitions of the interfaces for
- parser-provided objects.}
-\end{seealso}
-
-
-\subsection{SAXException Objects \label{sax-exception-objects}}
-
-The \class{SAXException} exception class supports the following
-methods:
-
-\begin{methoddesc}[SAXException]{getMessage}{}
- Return a human-readable message describing the error condition.
-\end{methoddesc}
-
-\begin{methoddesc}[SAXException]{getException}{}
- Return an encapsulated exception object, or \code{None}.
-\end{methoddesc}
diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex
deleted file mode 100644
index c3c72e7..0000000
--- a/Doc/lib/xmlsaxhandler.tex
+++ /dev/null
@@ -1,381 +0,0 @@
-\section{\module{xml.sax.handler} ---
- Base classes for SAX handlers}
-
-\declaremodule{standard}{xml.sax.handler}
-\modulesynopsis{Base classes for SAX event handlers.}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-
-\versionadded{2.0}
-
-
-The SAX API defines four kinds of handlers: content handlers, DTD
-handlers, error handlers, and entity resolvers. Applications normally
-only need to implement those interfaces whose events they are
-interested in; they can implement the interfaces in a single object or
-in multiple objects. Handler implementations should inherit from the
-base classes provided in the module \module{xml.sax.handler}, so that all
-methods get default implementations.
-
-\begin{classdesc*}{ContentHandler}
- This is the main callback interface in SAX, and the one most
- important to applications. The order of events in this interface
- mirrors the order of the information in the document.
-\end{classdesc*}
-
-\begin{classdesc*}{DTDHandler}
- Handle DTD events.
-
- This interface specifies only those DTD events required for basic
- parsing (unparsed entities and attributes).
-\end{classdesc*}
-
-\begin{classdesc*}{EntityResolver}
- Basic interface for resolving entities. If you create an object
- implementing this interface, then register the object with your
- Parser, the parser will call the method in your object to resolve all
- external entities.
-\end{classdesc*}
-
-\begin{classdesc*}{ErrorHandler}
- Interface used by the parser to present error and warning messages
- to the application. The methods of this object control whether errors
- are immediately converted to exceptions or are handled in some other
- way.
-\end{classdesc*}
-
-In addition to these classes, \module{xml.sax.handler} provides
-symbolic constants for the feature and property names.
-
-\begin{datadesc}{feature_namespaces}
- Value: \code{"http://xml.org/sax/features/namespaces"}\\
- true: Perform Namespace processing.\\
- false: Optionally do not perform Namespace processing
- (implies namespace-prefixes; default).\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_namespace_prefixes}
- Value: \code{"http://xml.org/sax/features/namespace-prefixes"}\\
- true: Report the original prefixed names and attributes used for Namespace
- declarations.\\
- false: Do not report attributes used for Namespace declarations, and
- optionally do not report original prefixed names (default).\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_string_interning}
- Value: \code{"http://xml.org/sax/features/string-interning"}\\
- true: All element names, prefixes, attribute names, Namespace URIs, and
- local names are interned using the built-in intern function.\\
- false: Names are not necessarily interned, although they may be (default).\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_validation}
- Value: \code{"http://xml.org/sax/features/validation"}\\
- true: Report all validation errors (implies external-general-entities and
- external-parameter-entities).\\
- false: Do not report validation errors.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_external_ges}
- Value: \code{"http://xml.org/sax/features/external-general-entities"}\\
- true: Include all external general (text) entities.\\
- false: Do not include external general entities.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{feature_external_pes}
- Value: \code{"http://xml.org/sax/features/external-parameter-entities"}\\
- true: Include all external parameter entities, including the external
- DTD subset.\\
- false: Do not include any external parameter entities, even the external
- DTD subset.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{all_features}
- List of all features.
-\end{datadesc}
-
-\begin{datadesc}{property_lexical_handler}
- Value: \code{"http://xml.org/sax/properties/lexical-handler"}\\
- data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)\\
- description: An optional extension handler for lexical events like comments.\\
- access: read/write
-\end{datadesc}
-
-\begin{datadesc}{property_declaration_handler}
- Value: \code{"http://xml.org/sax/properties/declaration-handler"}\\
- data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)\\
- description: An optional extension handler for DTD-related events other
- than notations and unparsed entities.\\
- access: read/write
-\end{datadesc}
-
-\begin{datadesc}{property_dom_node}
- Value: \code{"http://xml.org/sax/properties/dom-node"}\\
- data type: org.w3c.dom.Node (not supported in Python 2) \\
- description: When parsing, the current DOM node being visited if this is
- a DOM iterator; when not parsing, the root DOM node for
- iteration.\\
- access: (parsing) read-only; (not parsing) read/write
-\end{datadesc}
-
-\begin{datadesc}{property_xml_string}
- Value: \code{"http://xml.org/sax/properties/xml-string"}\\
- data type: String\\
- description: The literal string of characters that was the source for
- the current event.\\
- access: read-only
-\end{datadesc}
-
-\begin{datadesc}{all_properties}
- List of all known property names.
-\end{datadesc}
-
-
-\subsection{ContentHandler Objects \label{content-handler-objects}}
-
-Users are expected to subclass \class{ContentHandler} to support their
-application. The following methods are called by the parser on the
-appropriate events in the input document:
-
-\begin{methoddesc}[ContentHandler]{setDocumentLocator}{locator}
- Called by the parser to give the application a locator for locating
- the origin of document events.
-
- SAX parsers are strongly encouraged (though not absolutely required)
- to supply a locator: if it does so, it must supply the locator to
- the application by invoking this method before invoking any of the
- other methods in the DocumentHandler interface.
-
- The locator allows the application to determine the end position of
- any document-related event, even if the parser is not reporting an
- error. Typically, the application will use this information for
- reporting its own errors (such as character content that does not
- match an application's business rules). The information returned by
- the locator is probably not sufficient for use with a search engine.
-
- Note that the locator will return correct information only during
- the invocation of the events in this interface. The application
- should not attempt to use it at any other time.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startDocument}{}
- Receive notification of the beginning of a document.
-
- The SAX parser will invoke this method only once, before any other
- methods in this interface or in DTDHandler (except for
- \method{setDocumentLocator()}).
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endDocument}{}
- Receive notification of the end of a document.
-
- The SAX parser will invoke this method only once, and it will be the
- last method invoked during the parse. The parser shall not invoke
- this method until it has either abandoned parsing (because of an
- unrecoverable error) or reached the end of input.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startPrefixMapping}{prefix, uri}
- Begin the scope of a prefix-URI Namespace mapping.
-
- The information from this event is not necessary for normal
- Namespace processing: the SAX XML reader will automatically replace
- prefixes for element and attribute names when the
- \code{feature_namespaces} feature is enabled (the default).
-
-%% XXX This is not really the default, is it? MvL
-
- There are cases, however, when applications need to use prefixes in
- character data or in attribute values, where they cannot safely be
- expanded automatically; the \method{startPrefixMapping()} and
- \method{endPrefixMapping()} events supply the information to the
- application to expand prefixes in those contexts itself, if
- necessary.
-
- Note that \method{startPrefixMapping()} and
- \method{endPrefixMapping()} events are not guaranteed to be properly
- nested relative to each-other: all \method{startPrefixMapping()}
- events will occur before the corresponding \method{startElement()}
- event, and all \method{endPrefixMapping()} events will occur after
- the corresponding \method{endElement()} event, but their order is
- not guaranteed.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix}
- End the scope of a prefix-URI mapping.
-
- See \method{startPrefixMapping()} for details. This event will
- always occur after the corresponding \method{endElement()} event,
- but the order of \method{endPrefixMapping()} events is not otherwise
- guaranteed.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startElement}{name, attrs}
- Signals the start of an element in non-namespace mode.
-
- The \var{name} parameter contains the raw XML 1.0 name of the
- element type as a string and the \var{attrs} parameter holds an
- object of the \ulink{\class{Attributes}
- interface}{attributes-objects.html} containing the attributes of the
- element. The object passed as \var{attrs} may be re-used by the
- parser; holding on to a reference to it is not a reliable way to
- keep a copy of the attributes. To keep a copy of the attributes,
- use the \method{copy()} method of the \var{attrs} object.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endElement}{name}
- Signals the end of an element in non-namespace mode.
-
- The \var{name} parameter contains the name of the element type, just
- as with the \method{startElement()} event.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs}
- Signals the start of an element in namespace mode.
-
- The \var{name} parameter contains the name of the element type as a
- \code{(\var{uri}, \var{localname})} tuple, the \var{qname} parameter
- contains the raw XML 1.0 name used in the source document, and the
- \var{attrs} parameter holds an instance of the
- \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
- containing the attributes of the element. If no namespace is
- associated with the element, the \var{uri} component of \var{name}
- will be \code{None}. The object passed as \var{attrs} may be
- re-used by the parser; holding on to a reference to it is not a
- reliable way to keep a copy of the attributes. To keep a copy of
- the attributes, use the \method{copy()} method of the \var{attrs}
- object.
-
- Parsers may set the \var{qname} parameter to \code{None}, unless the
- \code{feature_namespace_prefixes} feature is activated.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{endElementNS}{name, qname}
- Signals the end of an element in namespace mode.
-
- The \var{name} parameter contains the name of the element type, just
- as with the \method{startElementNS()} method, likewise the
- \var{qname} parameter.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{characters}{content}
- Receive notification of character data.
-
- The Parser will call this method to report each chunk of character
- data. SAX parsers may return all contiguous character data in a
- single chunk, or they may split it into several chunks; however, all
- of the characters in any single event must come from the same
- external entity so that the Locator provides useful information.
-
- \var{content} may be a Unicode string or a byte string; the
- \code{expat} reader module produces always Unicode strings.
-
- \note{The earlier SAX 1 interface provided by the Python
- XML Special Interest Group used a more Java-like interface for this
- method. Since most parsers used from Python did not take advantage
- of the older interface, the simpler signature was chosen to replace
- it. To convert old code to the new interface, use \var{content}
- instead of slicing content with the old \var{offset} and
- \var{length} parameters.}
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{ignorableWhitespace}{whitespace}
- Receive notification of ignorable whitespace in element content.
-
- Validating Parsers must use this method to report each chunk
- of ignorable whitespace (see the W3C XML 1.0 recommendation,
- section 2.10): non-validating parsers may also use this method
- if they are capable of parsing and using content models.
-
- SAX parsers may return all contiguous whitespace in a single
- chunk, or they may split it into several chunks; however, all
- of the characters in any single event must come from the same
- external entity, so that the Locator provides useful
- information.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{processingInstruction}{target, data}
- Receive notification of a processing instruction.
-
- The Parser will invoke this method once for each processing
- instruction found: note that processing instructions may occur
- before or after the main document element.
-
- A SAX parser should never report an XML declaration (XML 1.0,
- section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
- this method.
-\end{methoddesc}
-
-\begin{methoddesc}[ContentHandler]{skippedEntity}{name}
- Receive notification of a skipped entity.
-
- The Parser will invoke this method once for each entity
- skipped. Non-validating processors may skip entities if they have
- not seen the declarations (because, for example, the entity was
- declared in an external DTD subset). All processors may skip
- external entities, depending on the values of the
- \code{feature_external_ges} and the
- \code{feature_external_pes} properties.
-\end{methoddesc}
-
-
-\subsection{DTDHandler Objects \label{dtd-handler-objects}}
-
-\class{DTDHandler} instances provide the following methods:
-
-\begin{methoddesc}[DTDHandler]{notationDecl}{name, publicId, systemId}
- Handle a notation declaration event.
-\end{methoddesc}
-
-\begin{methoddesc}[DTDHandler]{unparsedEntityDecl}{name, publicId,
- systemId, ndata}
- Handle an unparsed entity declaration event.
-\end{methoddesc}
-
-
-\subsection{EntityResolver Objects \label{entity-resolver-objects}}
-
-\begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId}
- Resolve the system identifier of an entity and return either the
- system identifier to read from as a string, or an InputSource to
- read from. The default implementation returns \var{systemId}.
-\end{methoddesc}
-
-
-\subsection{ErrorHandler Objects \label{sax-error-handler}}
-
-Objects with this interface are used to receive error and warning
-information from the \class{XMLReader}. If you create an object that
-implements this interface, then register the object with your
-\class{XMLReader}, the parser will call the methods in your object to
-report all warnings and errors. There are three levels of errors
-available: warnings, (possibly) recoverable errors, and unrecoverable
-errors. All methods take a \exception{SAXParseException} as the only
-parameter. Errors and warnings may be converted to an exception by
-raising the passed-in exception object.
-
-\begin{methoddesc}[ErrorHandler]{error}{exception}
- Called when the parser encounters a recoverable error. If this method
- does not raise an exception, parsing may continue, but further document
- information should not be expected by the application. Allowing the
- parser to continue may allow additional errors to be discovered in the
- input document.
-\end{methoddesc}
-
-\begin{methoddesc}[ErrorHandler]{fatalError}{exception}
- Called when the parser encounters an error it cannot recover from;
- parsing is expected to terminate when this method returns.
-\end{methoddesc}
-
-\begin{methoddesc}[ErrorHandler]{warning}{exception}
- Called when the parser presents minor warning information to the
- application. Parsing is expected to continue when this method returns,
- and document information will continue to be passed to the application.
- Raising an exception in this method will cause parsing to end.
-\end{methoddesc}
diff --git a/Doc/lib/xmlsaxreader.tex b/Doc/lib/xmlsaxreader.tex
deleted file mode 100644
index d669581..0000000
--- a/Doc/lib/xmlsaxreader.tex
+++ /dev/null
@@ -1,351 +0,0 @@
-\section{\module{xml.sax.xmlreader} ---
- Interface for XML parsers}
-
-\declaremodule{standard}{xml.sax.xmlreader}
-\modulesynopsis{Interface which SAX-compliant XML parsers must implement.}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-
-\versionadded{2.0}
-
-
-SAX parsers implement the \class{XMLReader} interface. They are
-implemented in a Python module, which must provide a function
-\function{create_parser()}. This function is invoked by
-\function{xml.sax.make_parser()} with no arguments to create a new
-parser object.
-
-\begin{classdesc}{XMLReader}{}
- Base class which can be inherited by SAX parsers.
-\end{classdesc}
-
-\begin{classdesc}{IncrementalParser}{}
- In some cases, it is desirable not to parse an input source at once,
- but to feed chunks of the document as they get available. Note that
- the reader will normally not read the entire file, but read it in
- chunks as well; still \method{parse()} won't return until the entire
- document is processed. So these interfaces should be used if the
- blocking behaviour of \method{parse()} is not desirable.
-
- When the parser is instantiated it is ready to begin accepting data
- from the feed method immediately. After parsing has been finished
- with a call to close the reset method must be called to make the
- parser ready to accept new data, either from feed or using the parse
- method.
-
- Note that these methods must \emph{not} be called during parsing,
- that is, after parse has been called and before it returns.
-
- By default, the class also implements the parse method of the
- XMLReader interface using the feed, close and reset methods of the
- IncrementalParser interface as a convenience to SAX 2.0 driver
- writers.
-\end{classdesc}
-
-\begin{classdesc}{Locator}{}
- Interface for associating a SAX event with a document location. A
- locator object will return valid results only during calls to
- DocumentHandler methods; at any other time, the results are
- unpredictable. If information is not available, methods may return
- \code{None}.
-\end{classdesc}
-
-\begin{classdesc}{InputSource}{\optional{systemId}}
- Encapsulation of the information needed by the \class{XMLReader} to
- read entities.
-
- This class may include information about the public identifier,
- system identifier, byte stream (possibly with character encoding
- information) and/or the character stream of an entity.
-
- Applications will create objects of this class for use in the
- \method{XMLReader.parse()} method and for returning from
- EntityResolver.resolveEntity.
-
- An \class{InputSource} belongs to the application, the
- \class{XMLReader} is not allowed to modify \class{InputSource} objects
- passed to it from the application, although it may make copies and
- modify those.
-\end{classdesc}
-
-\begin{classdesc}{AttributesImpl}{attrs}
- This is an implementation of the \ulink{\class{Attributes}
- interface}{attributes-objects.html} (see
- section~\ref{attributes-objects}). This is a dictionary-like
- object which represents the element attributes in a
- \method{startElement()} call. In addition to the most useful
- dictionary operations, it supports a number of other methods as
- described by the interface. Objects of this class should be
- instantiated by readers; \var{attrs} must be a dictionary-like
- object containing a mapping from attribute names to attribute
- values.
-\end{classdesc}
-
-\begin{classdesc}{AttributesNSImpl}{attrs, qnames}
- Namespace-aware variant of \class{AttributesImpl}, which will be
- passed to \method{startElementNS()}. It is derived from
- \class{AttributesImpl}, but understands attribute names as
- two-tuples of \var{namespaceURI} and \var{localname}. In addition,
- it provides a number of methods expecting qualified names as they
- appear in the original document. This class implements the
- \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
- (see section~\ref{attributes-ns-objects}).
-\end{classdesc}
-
-
-\subsection{XMLReader Objects \label{xmlreader-objects}}
-
-The \class{XMLReader} interface supports the following methods:
-
-\begin{methoddesc}[XMLReader]{parse}{source}
- Process an input source, producing SAX events. The \var{source}
- object can be a system identifier (a string identifying the
- input source -- typically a file name or an URL), a file-like
- object, or an \class{InputSource} object. When \method{parse()}
- returns, the input is completely processed, and the parser object
- can be discarded or reset. As a limitation, the current implementation
- only accepts byte streams; processing of character streams is for
- further study.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getContentHandler}{}
- Return the current \class{ContentHandler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setContentHandler}{handler}
- Set the current \class{ContentHandler}. If no
- \class{ContentHandler} is set, content events will be discarded.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getDTDHandler}{}
- Return the current \class{DTDHandler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setDTDHandler}{handler}
- Set the current \class{DTDHandler}. If no \class{DTDHandler} is
- set, DTD events will be discarded.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getEntityResolver}{}
- Return the current \class{EntityResolver}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setEntityResolver}{handler}
- Set the current \class{EntityResolver}. If no
- \class{EntityResolver} is set, attempts to resolve an external
- entity will result in opening the system identifier for the entity,
- and fail if it is not available.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getErrorHandler}{}
- Return the current \class{ErrorHandler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setErrorHandler}{handler}
- Set the current error handler. If no \class{ErrorHandler} is set,
- errors will be raised as exceptions, and warnings will be printed.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setLocale}{locale}
- Allow an application to set the locale for errors and warnings.
-
- SAX parsers are not required to provide localization for errors and
- warnings; if they cannot support the requested locale, however, they
- must throw a SAX exception. Applications may request a locale change
- in the middle of a parse.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getFeature}{featurename}
- Return the current setting for feature \var{featurename}. If the
- feature is not recognized, \exception{SAXNotRecognizedException} is
- raised. The well-known featurenames are listed in the module
- \module{xml.sax.handler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setFeature}{featurename, value}
- Set the \var{featurename} to \var{value}. If the feature is not
- recognized, \exception{SAXNotRecognizedException} is raised. If the
- feature or its setting is not supported by the parser,
- \var{SAXNotSupportedException} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{getProperty}{propertyname}
- Return the current setting for property \var{propertyname}. If the
- property is not recognized, a \exception{SAXNotRecognizedException}
- is raised. The well-known propertynames are listed in the module
- \module{xml.sax.handler}.
-\end{methoddesc}
-
-\begin{methoddesc}[XMLReader]{setProperty}{propertyname, value}
- Set the \var{propertyname} to \var{value}. If the property is not
- recognized, \exception{SAXNotRecognizedException} is raised. If the
- property or its setting is not supported by the parser,
- \var{SAXNotSupportedException} is raised.
-\end{methoddesc}
-
-
-\subsection{IncrementalParser Objects
- \label{incremental-parser-objects}}
-
-Instances of \class{IncrementalParser} offer the following additional
-methods:
-
-\begin{methoddesc}[IncrementalParser]{feed}{data}
- Process a chunk of \var{data}.
-\end{methoddesc}
-
-\begin{methoddesc}[IncrementalParser]{close}{}
- Assume the end of the document. That will check well-formedness
- conditions that can be checked only at the end, invoke handlers, and
- may clean up resources allocated during parsing.
-\end{methoddesc}
-
-\begin{methoddesc}[IncrementalParser]{reset}{}
- This method is called after close has been called to reset the
- parser so that it is ready to parse new documents. The results of
- calling parse or feed after close without calling reset are
- undefined.
-\end{methoddesc}
-
-
-\subsection{Locator Objects \label{locator-objects}}
-
-Instances of \class{Locator} provide these methods:
-
-\begin{methoddesc}[Locator]{getColumnNumber}{}
- Return the column number where the current event ends.
-\end{methoddesc}
-
-\begin{methoddesc}[Locator]{getLineNumber}{}
- Return the line number where the current event ends.
-\end{methoddesc}
-
-\begin{methoddesc}[Locator]{getPublicId}{}
- Return the public identifier for the current event.
-\end{methoddesc}
-
-\begin{methoddesc}[Locator]{getSystemId}{}
- Return the system identifier for the current event.
-\end{methoddesc}
-
-
-\subsection{InputSource Objects \label{input-source-objects}}
-
-\begin{methoddesc}[InputSource]{setPublicId}{id}
- Sets the public identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getPublicId}{}
- Returns the public identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setSystemId}{id}
- Sets the system identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getSystemId}{}
- Returns the system identifier of this \class{InputSource}.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setEncoding}{encoding}
- Sets the character encoding of this \class{InputSource}.
-
- The encoding must be a string acceptable for an XML encoding
- declaration (see section 4.3.3 of the XML recommendation).
-
- The encoding attribute of the \class{InputSource} is ignored if the
- \class{InputSource} also contains a character stream.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getEncoding}{}
- Get the character encoding of this InputSource.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setByteStream}{bytefile}
- Set the byte stream (a Python file-like object which does not
- perform byte-to-character conversion) for this input source.
-
- The SAX parser will ignore this if there is also a character stream
- specified, but it will use a byte stream in preference to opening a
- URI connection itself.
-
- If the application knows the character encoding of the byte stream,
- it should set it with the setEncoding method.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getByteStream}{}
- Get the byte stream for this input source.
-
- The getEncoding method will return the character encoding for this
- byte stream, or None if unknown.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{setCharacterStream}{charfile}
- Set the character stream for this input source. (The stream must be
- a Python 1.6 Unicode-wrapped file-like that performs conversion to
- Unicode strings.)
-
- If there is a character stream specified, the SAX parser will ignore
- any byte stream and will not attempt to open a URI connection to the
- system identifier.
-\end{methoddesc}
-
-\begin{methoddesc}[InputSource]{getCharacterStream}{}
- Get the character stream for this input source.
-\end{methoddesc}
-
-
-\subsection{The \class{Attributes} Interface \label{attributes-objects}}
-
-\class{Attributes} objects implement a portion of the mapping
-protocol, including the methods \method{copy()}, \method{get()},
-\method{has_key()}, \method{items()}, \method{keys()}, and
-\method{values()}. The following methods are also provided:
-
-\begin{methoddesc}[Attributes]{getLength}{}
- Return the number of attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[Attributes]{getNames}{}
- Return the names of the attributes.
-\end{methoddesc}
-
-\begin{methoddesc}[Attributes]{getType}{name}
- Returns the type of the attribute \var{name}, which is normally
- \code{'CDATA'}.
-\end{methoddesc}
-
-\begin{methoddesc}[Attributes]{getValue}{name}
- Return the value of attribute \var{name}.
-\end{methoddesc}
-
-% getValueByQName, getNameByQName, getQNameByName, getQNames available
-% here already, but documented only for derived class.
-
-
-\subsection{The \class{AttributesNS} Interface \label{attributes-ns-objects}}
-
-This interface is a subtype of the \ulink{\class{Attributes}
-interface}{attributes-objects.html} (see
-section~\ref{attributes-objects}). All methods supported by that
-interface are also available on \class{AttributesNS} objects.
-
-The following methods are also available:
-
-\begin{methoddesc}[AttributesNS]{getValueByQName}{name}
- Return the value for a qualified name.
-\end{methoddesc}
-
-\begin{methoddesc}[AttributesNS]{getNameByQName}{name}
- Return the \code{(\var{namespace}, \var{localname})} pair for a
- qualified \var{name}.
-\end{methoddesc}
-
-\begin{methoddesc}[AttributesNS]{getQNameByName}{name}
- Return the qualified name for a \code{(\var{namespace},
- \var{localname})} pair.
-\end{methoddesc}
-
-\begin{methoddesc}[AttributesNS]{getQNames}{}
- Return the qualified names of all attributes.
-\end{methoddesc}
diff --git a/Doc/lib/xmlsaxutils.tex b/Doc/lib/xmlsaxutils.tex
deleted file mode 100644
index 64221f5..0000000
--- a/Doc/lib/xmlsaxutils.tex
+++ /dev/null
@@ -1,81 +0,0 @@
-\section{\module{xml.sax.saxutils} ---
- SAX Utilities}
-
-\declaremodule{standard}{xml.sax.saxutils}
-\modulesynopsis{Convenience functions and classes for use with SAX.}
-\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
-\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no}
-
-\versionadded{2.0}
-
-
-The module \module{xml.sax.saxutils} contains a number of classes and
-functions that are commonly useful when creating SAX applications,
-either in direct use, or as base classes.
-
-\begin{funcdesc}{escape}{data\optional{, entities}}
- Escape \character{\&}, \character{<}, and \character{>} in a string
- of data.
-
- You can escape other strings of data by passing a dictionary as the
- optional \var{entities} parameter. The keys and values must all be
- strings; each key will be replaced with its corresponding value.
-\end{funcdesc}
-
-\begin{funcdesc}{unescape}{data\optional{, entities}}
- Unescape \character{\&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}