diff options
Diffstat (limited to 'Doc')
62 files changed, 520 insertions, 282 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index fbf62f6..4b04cc3 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -4,14 +4,23 @@ LIBDEST=$LIBDESTDIR/python DOCDESTDIR=$LIBDEST/doc DVIPS= dvips -f -all: tut lib ref ext +all: tut.dvi lib.dvi ref.dvi ext.dvi -tut: +ext: ext.dvi +tut: tut.dvi +qua: qua.dvi +ref: ref.dvi +lib: lib.dvi + +tut.dvi lib.dvi ref.dvi ext.dvi: myformat.sty fix_hack + +tut.dvi: tut.tex latex tut latex tut $(DVIPS) tut >tut.ps -ref: +ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \ + ref7.tex ref8.tex touch ref.ind latex ref ./fix_hack ref.idx @@ -19,7 +28,29 @@ ref: latex ref $(DVIPS) ref >ref.ps -lib: +# LaTeX source files for the Python Library Reference +LIBFILES = lib.tex \ +libal.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \ +libbltin.tex \ +libcrypto.tex \ +libdbm.tex \ +libexcs.tex \ +libfcntl.tex libfl.tex libfm.tex libfuncs.tex \ +libgdbm.tex libgetopt.tex libgl.tex libgrp.tex \ +libimageop.tex libimgfile.tex libintro.tex \ +libjpeg.tex \ +libmac.tex libmain.tex libmarshal.tex libmath.tex \ + libmd5.tex libmm.tex libmods.tex libmpz.tex \ +libobjs.tex libos.tex \ +libpanel.tex libposix.tex libposixfile.tex libppath.tex libpwd.tex \ +librand.tex libregex.tex libregsub.tex librgbimg.tex librotor.tex \ +libselect.tex libsgi.tex libsocket.tex libstd.tex libstdwin.tex \ + libstring.tex libstruct.tex libsun.tex libsys.tex \ +libthread.tex libtime.tex libtypes.tex \ +libunix.tex \ +libwhrandom.tex + +lib.dvi: $(LIBFILES) touch lib.ind latex lib ./fix_hack lib.idx @@ -27,7 +58,7 @@ lib: latex lib $(DVIPS) lib >lib.ps -ext: +ext.dvi: ext.tex touch ext.ind latex ext ./fix_hack ext.idx @@ -35,7 +66,7 @@ ext: latex ext $(DVIPS) ext >ext.ps -qua: +qua.dvi: qua.tex quabib.bib latex qua bibtex qua latex qua diff --git a/Doc/ext.tex b/Doc/ext.tex index a7d4221..48cf0d1 100644 --- a/Doc/ext.tex +++ b/Doc/ext.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! % Tell \index to actually write the .idx file \makeindex @@ -23,7 +23,7 @@ \begin{abstract} \noindent -This document describes how to write modules in C or C++ to extend the +This document describes how to write modules in C or \Cpp{} to extend the Python interpreter. It also describes how to use Python as an `embedded' language, and how extension modules can be loaded dynamically (at run time) into the interpreter, if the operating @@ -43,7 +43,7 @@ system supports this feature. \pagenumbering{arabic} -\chapter{Extending Python with C or C++ code} +\chapter{Extending Python with C or \Cpp{} code} \section{Introduction} @@ -57,12 +57,9 @@ excellent examples of how to create an extension. Extension modules can do two things that can't be done directly in Python: they can implement new data types (which are different from -classes by the way), and they can make system calls or call C library -functions. Since the latter is usually the most important reason for -adding an extension, I'll concentrate on adding `wrappers' around C -library functions; the concrete example uses the wrapper for -\code{system()} in module \code{posix}, found in (of course) the file -\file{Modules/posixmodule.c}. +classes, by the way), and they can make system calls or call C library +functions. We'll see how both types of extension are implemented by +examining the code for a Python curses interface. Note: unless otherwise mentioned, all file references in this document are relative to the toplevel directory of the Python @@ -112,7 +109,7 @@ in Python (here the single expression \code{'ls -l'}) to the arguments that are passed to the C function. The C function always has two parameters, conventionally named \var{self} and \var{args}. The \var{self} argument is used when the C function implements a builtin -method --- this is advanced material and not covered in this document. +method---this will be discussed later. In the example, \var{self} will always be a \code{NULL} pointer, since we are defining a function, not a method (this is done so that the interpreter doesn't have to understand two different types of C @@ -780,9 +777,9 @@ which you keep references in your object, but you should not use \code{DECREF()} on your object. You should use \code{DEL()} instead. -\section{Writing extensions in C++} +\section{Writing extensions in \Cpp{}} -It is possible to write extension modules in C++. Some restrictions +It is possible to write extension modules in \Cpp{}. Some restrictions apply: since the main program (the Python interpreter) is compiled and linked by the C compiler, global or static objects with constructors cannot be used. All functions that will be called directly or @@ -797,7 +794,7 @@ It is unnecessary to enclose the Python header files in Embedding Python is similar to extending it, but not quite. The difference is that when you extend Python, the main program of the -application is still the Python interpreter, while of you embed +application is still the Python interpreter, while if you embed Python, the main program may have nothing to do with Python --- instead, some parts of the application occasionally call the Python interpreter to run some Python code. @@ -820,13 +817,13 @@ A simple demo of embedding Python can be found in the directory \file{Demo/embed}. -\section{Embedding Python in C++} +\section{Embedding Python in \Cpp{}} -It is also possible to embed Python in a C++ program; how this is done -exactly will depend on the details of the C++ system used; in general -you will need to write the main program in C++, and use the C++ -compiler to compile and link your program. There is no need to -recompile Python itself with C++. +It is also possible to embed Python in a \Cpp{} program; precisely how this +is done will depend on the details of the \Cpp{} system used; in general you +will need to write the main program in \Cpp{}, and use the \Cpp{} compiler +to compile and link your program. There is no need to recompile Python +itself using \Cpp{}. \chapter{Dynamic Loading} @@ -860,7 +857,7 @@ loading. \subsection{Shared libraries} -The following systems supports dynamic loading using shared libraries: +The following systems support dynamic loading using shared libraries: SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all systems derived from SVR4, or at least those SVR4 derivatives that support shared libraries (are there any that don't?). diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex index a7d4221..48cf0d1 100644 --- a/Doc/ext/ext.tex +++ b/Doc/ext/ext.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! % Tell \index to actually write the .idx file \makeindex @@ -23,7 +23,7 @@ \begin{abstract} \noindent -This document describes how to write modules in C or C++ to extend the +This document describes how to write modules in C or \Cpp{} to extend the Python interpreter. It also describes how to use Python as an `embedded' language, and how extension modules can be loaded dynamically (at run time) into the interpreter, if the operating @@ -43,7 +43,7 @@ system supports this feature. \pagenumbering{arabic} -\chapter{Extending Python with C or C++ code} +\chapter{Extending Python with C or \Cpp{} code} \section{Introduction} @@ -57,12 +57,9 @@ excellent examples of how to create an extension. Extension modules can do two things that can't be done directly in Python: they can implement new data types (which are different from -classes by the way), and they can make system calls or call C library -functions. Since the latter is usually the most important reason for -adding an extension, I'll concentrate on adding `wrappers' around C -library functions; the concrete example uses the wrapper for -\code{system()} in module \code{posix}, found in (of course) the file -\file{Modules/posixmodule.c}. +classes, by the way), and they can make system calls or call C library +functions. We'll see how both types of extension are implemented by +examining the code for a Python curses interface. Note: unless otherwise mentioned, all file references in this document are relative to the toplevel directory of the Python @@ -112,7 +109,7 @@ in Python (here the single expression \code{'ls -l'}) to the arguments that are passed to the C function. The C function always has two parameters, conventionally named \var{self} and \var{args}. The \var{self} argument is used when the C function implements a builtin -method --- this is advanced material and not covered in this document. +method---this will be discussed later. In the example, \var{self} will always be a \code{NULL} pointer, since we are defining a function, not a method (this is done so that the interpreter doesn't have to understand two different types of C @@ -780,9 +777,9 @@ which you keep references in your object, but you should not use \code{DECREF()} on your object. You should use \code{DEL()} instead. -\section{Writing extensions in C++} +\section{Writing extensions in \Cpp{}} -It is possible to write extension modules in C++. Some restrictions +It is possible to write extension modules in \Cpp{}. Some restrictions apply: since the main program (the Python interpreter) is compiled and linked by the C compiler, global or static objects with constructors cannot be used. All functions that will be called directly or @@ -797,7 +794,7 @@ It is unnecessary to enclose the Python header files in Embedding Python is similar to extending it, but not quite. The difference is that when you extend Python, the main program of the -application is still the Python interpreter, while of you embed +application is still the Python interpreter, while if you embed Python, the main program may have nothing to do with Python --- instead, some parts of the application occasionally call the Python interpreter to run some Python code. @@ -820,13 +817,13 @@ A simple demo of embedding Python can be found in the directory \file{Demo/embed}. -\section{Embedding Python in C++} +\section{Embedding Python in \Cpp{}} -It is also possible to embed Python in a C++ program; how this is done -exactly will depend on the details of the C++ system used; in general -you will need to write the main program in C++, and use the C++ -compiler to compile and link your program. There is no need to -recompile Python itself with C++. +It is also possible to embed Python in a \Cpp{} program; precisely how this +is done will depend on the details of the \Cpp{} system used; in general you +will need to write the main program in \Cpp{}, and use the \Cpp{} compiler +to compile and link your program. There is no need to recompile Python +itself using \Cpp{}. \chapter{Dynamic Loading} @@ -860,7 +857,7 @@ loading. \subsection{Shared libraries} -The following systems supports dynamic loading using shared libraries: +The following systems support dynamic loading using shared libraries: SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all systems derived from SVR4, or at least those SVR4 derivatives that support shared libraries (are there any that don't?). diff --git a/Doc/lib.tex b/Doc/lib.tex index 72d09c4..a0cc009 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! \makeindex % tell \index to actually write the .idx file diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 72d09c4..a0cc009 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! \makeindex % tell \index to actually write the .idx file diff --git a/Doc/lib/libal.tex b/Doc/lib/libal.tex index 708c54e..51a0312 100644 --- a/Doc/lib/libal.tex +++ b/Doc/lib/libal.tex @@ -23,7 +23,7 @@ documented upper limit.) Module \code{al} defines the following functions: \renewcommand{\indexsubitem}{(in module al)} -\begin{funcdesc}{openport}{name\, direction\, config} +\begin{funcdesc}{openport}{name\, direction\optional{\, config}} Equivalent to the C function ALopenport(). The name and direction arguments are strings. The optional config argument is an opaque configuration object as returned by \code{al.newconfig()}. The return diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex index 21122f0..034ac32 100644 --- a/Doc/lib/libarray.tex +++ b/Doc/lib/libarray.tex @@ -20,14 +20,14 @@ which is a single character. The following type codes are defined: \end{tableiii} The actual representation of values is determined by the machine -architecture (strictly spoken, by the C implementation). The actual +architecture (strictly speaking, by the C implementation). The actual size can be accessed through the \var{typecode} attribute. The module defines the following function: \renewcommand{\indexsubitem}{(in module array)} -\begin{funcdesc}{array}{typecode\, initializer} +\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 or a string. The list or string is passed to the new array's @@ -51,7 +51,7 @@ Append a new item with value \var{x} to the end of the array. \begin{funcdesc}{byteswap}{x} ``Byteswap'' all items of the array. This is only supported for -integer values. It is useful when reading data ffrom a file written +integer values. It is useful when reading data from a file written on a machine with a different byte order. \end{funcdesc} diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex index 734065a..61ab7fc 100644 --- a/Doc/lib/libaudioop.tex +++ b/Doc/lib/libaudioop.tex @@ -43,7 +43,7 @@ This function returns the average over all samples in the fragment. \begin{funcdesc}{avgpp}{fragment\, width} This function returns the average peak-peak value over all samples in -the fragment. No filtering is done, so the useability of this routine +the fragment. No filtering is done, so the usefulness of this routine is questionable. \end{funcdesc} @@ -74,9 +74,9 @@ match \var{reference} as good as possible to a portion of (conceptually) does this by taking slices out of \var{fragment}, using \code{findfactor} to compute the best match, and minimizing the result. -It returns a tuple \code{(\var{offset}, \var{factor})} with offset the +It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the (integer) offset into \var{fragment} where the optimal match started -and \var{factor} the floating-point factor as per findfactor. +and \var{factor} the floating-point factor as per \code{findfactor}. \end{funcdesc} \begin{funcdesc}{findmax}{fragment\, length} @@ -101,8 +101,8 @@ This function converts samples between 1-, 2- and 4-byte formats. This function converts 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 algorythm has been selected for -use by the IMA, so may well become a standard. +(varying) step. The Intel/DVI ADPCM algorithm has been selected for +use by the IMA, so it may well become a standard. \code{State} is a tuple containing the state of the coder. The coder returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the @@ -120,7 +120,7 @@ discouraged. \begin{funcdesc}{lin2ulaw}{fragment\, width} This function converts samples in the audio fragment to U-LAW encoding -and returns this as a python string. U-LAW is an audio encoding format +and returns 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} diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex index 467bee4..302b50d 100644 --- a/Doc/lib/libcrypto.tex +++ b/Doc/lib/libcrypto.tex @@ -2,4 +2,11 @@ The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the -installation. +installation. +\index{cryptography} + +%Hardcore cypherpunks will probably find the Python Cryptography Kit of +%further interest; the package adds built-in modules for DES and IDEA +%encryption, and provides a Python module for reading and decrypting PGP files. +%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher} +%\index{Python Cryptography Kit} diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex index dd5212b..e361d5e 100644 --- a/Doc/lib/libfcntl.tex +++ b/Doc/lib/libfcntl.tex @@ -13,12 +13,12 @@ The module defines the following functions: \renewcommand{\indexsubitem}{(in module struct)} -\begin{funcdesc}{fcntl}{fd\, op\, arg} +\begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}} Perform the requested operation on file descriptor \code{\var{fd}}. The operation is defined by \code{\var{op}} and is operating system dependent. Typically these codes can be retrieved from the library - module \code{FCNTL}. The argument \code{\var{arg}} is optional. When - it is missing it is interpreted as the integer value \code{0}. When + module \code{FCNTL}. The argument \code{\var{arg}} is optional, and + defaults to the integer value \code{0}. When it is 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 real \code{fcntl()} diff --git a/Doc/lib/libfl.tex b/Doc/lib/libfl.tex index b705a6b..5af1a04 100644 --- a/Doc/lib/libfl.tex +++ b/Doc/lib/libfl.tex @@ -78,11 +78,11 @@ Show a dialog box with a three-line message and YES and NO buttons. It returns \code{1} if the user pressed YES, \code{0} if NO. \end{funcdesc} -\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\, but2\, but3} +\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\optional{\, but2\, +but3}} Show a dialog box with a three-line message and up to three buttons. It returns the number of the button clicked by the user (\code{1}, \code{2} or \code{3}). -The \var{but2} and \var{but3} arguments are optional. \end{funcdesc} \begin{funcdesc}{show_input}{prompt\, default} diff --git a/Doc/lib/libfm.tex b/Doc/lib/libfm.tex index acbc05d..45d820c 100644 --- a/Doc/lib/libfm.tex +++ b/Doc/lib/libfm.tex @@ -77,7 +77,8 @@ Calls \code{fmgetcomment(\var{fh})}. Returns a tuple giving some pertinent data about this font. This is an interface to \code{fmgetfontinfo()}. The returned tuple contains the following numbers: -\code{(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, \var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}. +{\tt(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, +\var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}. \end{funcdesc} \begin{funcdesc}{getstrwidth}{string} diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index 2c30c14..b37920d 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -78,7 +78,7 @@ exactly one argument.) \code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}. \end{funcdesc} -\begin{funcdesc}{eval}{s\, globals\, locals} +\begin{funcdesc}{eval}{s\optional{\, globals\optional{\, locals}}} The arguments are a string and two optional dictionaries. The string argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the dictionaries as @@ -156,11 +156,11 @@ removed. object.) \end{funcdesc} -\begin{funcdesc}{input}{prompt} - Almost equivalent to \code{eval(raw_input(\var{prompt}))}. As for - \code{raw_input()}, the prompt argument is optional. The difference is - that a long input expression may be broken over multiple lines using the - backslash convention. +\begin{funcdesc}{input}{\optional{prompt}} + Almost equivalent to \code{eval(raw_input(\var{prompt}))}. Like + \code{raw_input()}, the \var{prompt} argument is optional. The difference + is that a long input expression may be broken over multiple lines using + the backslash convention. \end{funcdesc} \begin{funcdesc}{int}{x} @@ -206,7 +206,7 @@ any kind of sequence; the result is always a list. expression. \end{funcdesc} -\begin{funcdesc}{open}{filename\, mode\, bufsize} +\begin{funcdesc}{open}{filename\, \optional{mode\optional{\, bufsize}}} Return a new file object (described earlier under Built-in Types). The first two arguments are the same as for \code{stdio}'s \code{fopen()}: \var{filename} is the file name to be opened, @@ -238,15 +238,17 @@ there's no reliable way to determine whether this is the case.} \code{chr()}. \end{funcdesc} -\begin{funcdesc}{pow}{x\, y} - Return \var{x} to the power \var{y}. The arguments must have +\begin{funcdesc}{pow}{x\, y\optional{\, z}} + Return \var{x} to the power \var{y}; if \var{z} is present, $x^y \bmod z$ + is returned. The arguments must have numeric types. With mixed operand types, the rules for binary arithmetic operators apply. The effective operand type is also the type of the result; if the result is not expressible in this type, the - function raises an exception; e.g., \code{pow(2, -1)} is not allowed. + function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2, + 35000)} is not allowed. \end{funcdesc} -\begin{funcdesc}{range}{start\, end\, step} +\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}} This is a versatile function to create lists containing arithmetic progressions. It is most often used in \code{for} loops. The arguments must be plain integers. If the \var{step} argument is @@ -278,13 +280,11 @@ there's no reliable way to determine whether this is the case.} \end{verbatim}\ecode \end{funcdesc} -\begin{funcdesc}{raw_input}{prompt} - The string argument is optional; if present, it is written to - standard - output without a trailing newline. The function then reads a line - from input, converts it to a string (stripping a trailing newline), - and returns that. When \EOF{} is read, \code{EOFError} is raised. - Example: +\begin{funcdesc}{raw_input}{\optional{prompt}} + If the \var{prompt} argument is present, it is written to standard output + without a trailing newline. The function then reads a line from input, + converts it to a string (stripping a trailing newline), and returns that. + When \EOF{} is read, \code{EOFError} is raised. Example: \bcode\begin{verbatim} >>> s = raw_input('--> ') @@ -295,7 +295,7 @@ there's no reliable way to determine whether this is the case.} \end{verbatim}\ecode \end{funcdesc} -\begin{funcdesc}{reduce}{function\, list\, initializer} +\begin{funcdesc}{reduce}{function\, list\optional{\, initializer}} Apply the binary \var{function} to the items of \var{list} so as to reduce the list to a single value. E.g., \code{reduce(lambda x, y: x*y, \var{list}, 1)} returns the product of @@ -378,7 +378,7 @@ cannot normally be affected this way, but variables retrieved from other scopes can be. This may change.} \end{funcdesc} -\begin{funcdesc}{xrange}{start\, end\, step} +\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}} This function is very similar to \code{range()}, but returns an ``xrange object'' instead of a list. This is an opaque sequence type which yields the same values as the corresponding list, without diff --git a/Doc/lib/libimageop.tex b/Doc/lib/libimageop.tex index c1cdac4..4481e61 100644 --- a/Doc/lib/libimageop.tex +++ b/Doc/lib/libimageop.tex @@ -19,7 +19,7 @@ per pixel, etc. \begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1} This function takes the image in \code{image}, which should by \code{width} by \code{height} in size and consist of pixels of -\code{psize} bytes, and returns the selected part of that image. \code{X0}, +\code{psize} bytes, and returns the selected part of that image. \code{x0}, \code{y0}, \code{x1} and \code{y1} are like the \code{lrectread} parameters, i.e. the boundary is included in the new image. The new boundaries need not be inside the picture. Pixels that fall diff --git a/Doc/lib/libimgfile.tex b/Doc/lib/libimgfile.tex index 99efaf4..2da8d9d 100644 --- a/Doc/lib/libimgfile.tex +++ b/Doc/lib/libimgfile.tex @@ -29,7 +29,7 @@ the string. This format is suitable to pass to \code{gl.lrectwrite}, for instance. \end{funcdesc} -\begin{funcdesc}{readscaled}{file\, x\, y\, filter\, blur} +\begin{funcdesc}{readscaled}{file\, x\, y\, filter\optional{\, blur}} This function is identical to read but it returns an image that is scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and \var{blur} parameters are omitted scaling is done by @@ -42,7 +42,7 @@ after scaling. The filter forms supported are \code{'impulse'}, \code{'gaussian'}. If a filter is specified \var{blur} is an optional parameter specifying the blurriness of the filter. It defaults to \code{1.0}. -Readscaled makes no +\code{readscaled} makes no attempt to keep the aspect ratio correct, so that is the users' responsibility. \end{funcdesc} diff --git a/Doc/lib/libjpeg.tex b/Doc/lib/libjpeg.tex index d0c1604..a4e931f 100644 --- a/Doc/lib/libjpeg.tex +++ b/Doc/lib/libjpeg.tex @@ -4,7 +4,7 @@ The module jpeg provides access to the jpeg compressor and decompressor written by the Independent JPEG Group. JPEG is a (draft?) standard for compressing pictures. For details on jpeg or the -Indepent JPEG Group software refer to the JPEG standard or the +Independent JPEG Group software refer to the JPEG standard or the documentation provided with the software. The jpeg module defines these functions: @@ -12,10 +12,10 @@ The jpeg module defines these functions: \renewcommand{\indexsubitem}{(in module jpeg)} \begin{funcdesc}{compress}{data\, w\, h\, b} Treat data as a pixmap of width w and height h, with b bytes per -pixel. The data is in sgi gl order, so the first pixel is in the +pixel. The data is in SGI GL order, so the first pixel is in the lower-left corner. This means that lrectread return data can immedeately be passed to compress. Currently only 1 byte and 4 byte -pixels are allowed, the former being treaded as greyscale and the +pixels are allowed, the former being treated as greyscale and the latter as RGB color. Compress returns a string that contains the compressed picture, in JFIF format. \end{funcdesc} @@ -39,7 +39,7 @@ Set the quality of the compressed image to a value between \code{0} and \code{100} (default is \code{75}). Compress only. \item[\code{'optimize'}] -Perform huffman table optimization. Takes longer, but results in +Perform Huffman table optimization. Takes longer, but results in smaller compressed image. Compress only. \item[\code{'smooth'}] diff --git a/Doc/lib/libmd5.tex b/Doc/lib/libmd5.tex index 29e4b31..edaa727 100644 --- a/Doc/lib/libmd5.tex +++ b/Doc/lib/libmd5.tex @@ -2,16 +2,17 @@ \bimodindex{md5} This module implements the interface to RSA's MD5 message digest -algorithm (see also the file \file{md5.doc}). It's use is very +algorithm (see also the file \file{md5.doc}). Its use is quite straightforward: use the function \code{md5} to create an \dfn{md5}-object. You can now ``feed'' this object with arbitrary strings. -At any time you can ask the ``final'' digest of the object. Internally, -a temorary copy of the object is made and the digest is computed and -returned. Because of the copy, the digest operation is not desctructive -for the object. Before a more exact description of the use, a small -example: to obtain the digest of the string \code{'abc'}, use \ldots +At any time you can ask for the ``final'' digest of the object. Internally, +a temporary copy of the object is made and the digest is computed and +returned. Because of the copy, the digest operation is not destructive +for the object. Before a more exact description of the module's use, a small +example will be helpful: +to obtain the digest of the string \code{'abc'}, use \ldots \bcode\begin{verbatim} >>> from md5 import md5 @@ -29,8 +30,8 @@ More condensed: \end{verbatim}\ecode \renewcommand{\indexsubitem}{(in module md5)} -\begin{funcdesc}{md5}{arg} - Create a new md5-object. \var{arg} is optional: if present, an initial +\begin{funcdesc}{md5}{\optional{arg}} + Create a new md5-object. If \var{arg} is present, an initial \code{update} method is called with \var{arg} as argument. \end{funcdesc} @@ -42,6 +43,7 @@ An md5-object has the following methods: \end{funcdesc} \begin{funcdesc}{digest}{} +% XXX The following is not quite clear; what does MD5Final do? Return the \dfn{digest} of this md5-object. Internally, a copy is made and the \C-function \code{MD5Final} is called. Finally the digest is returned. diff --git a/Doc/lib/libposixfile.tex b/Doc/lib/libposixfile.tex index 673ed6f..0d9cb32 100644 --- a/Doc/lib/libposixfile.tex +++ b/Doc/lib/libposixfile.tex @@ -47,17 +47,14 @@ The posixfile module defines the following functions: The posixfile object defines the following additional methods: \renewcommand{\indexsubitem}{(posixfile method)} -\begin{funcdesc}{lock}{fmt\, len\, start\, whence} +\begin{funcdesc}{lock}{fmt\, \optional{len\optional{\, start +\optional{\, whence}}}} Lock the specified section of the file that the file object is - referring to. The arguments \code{\var{len}}, \code{\var{start}} - and \code{\var{whence}} are optional with the understanding that - if \code{\var{start}} is used \code{\var{len}} becomes mandatory, - and if \code{\var{whence}} is used \code{\var{len}} and - \code{\var{start}} become mandatory. The format is explained - below in a table. The length argument specifies the length of the - section that should be locked. The default is \code{0}. The start - specifies the starting offset of the section. The default is - \code{0}. The whence argument specifies where the offset is + referring to. The format is explained + below in a table. The \var{len} argument specifies the length of the + section that should be locked. The default is \code{0}. \var{start} + specifies the starting offset of the section, where the default is + \code{0}. The \var{whence} argument specifies where the offset is relative to. It accepts one of the constants \code{SEEK_SET}, \code{SEEK_CUR} or \code{SEEK_END}. The default is \code{SEEK_SET}. For more information about the arguments refer to the fcntl @@ -69,7 +66,7 @@ The posixfile object defines the following additional methods: to. The new flags are ORed with the old flags, unless specified otherwise. The format is explained below in a table. Without arguments a string indicating the current flags is returned (this is - the same as the '?'modifier). For more information about the flags + the same as the '?' modifier). For more information about the flags refer to the fcntl manual page on your system. \end{funcdesc} @@ -105,8 +102,8 @@ In addition the following modifiers can be added to the format: \begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes} \lineiii{|}{wait until the lock has been granted}{} - \lineiii{?}{return the first lock conflicting with the requested lock, - or \code{None} if there is no conflict.}{(1)} + \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)} + {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\ \end{tableiii} Note: @@ -138,7 +135,7 @@ Note: (1) The \code{!} and \code{=} modifiers are mutually exclusive. -(2) This string represents the flag after they may have been altered +(2) This string represents the flags after they may have been altered by the same call. Examples: diff --git a/Doc/lib/libregex.tex b/Doc/lib/libregex.tex index 13b3e20..f3df684 100644 --- a/Doc/lib/libregex.tex +++ b/Doc/lib/libregex.tex @@ -41,7 +41,7 @@ The module defines these functions, and an exception: anywhere!). \end{funcdesc} -\begin{funcdesc}{compile}{pattern\, translate} +\begin{funcdesc}{compile}{pattern\optional{\, translate}} Compile a regular expression pattern into a regular expression object, which can be used for matching using its \code{match} and \code{search} methods, described below. The optional @@ -82,7 +82,7 @@ expressions.) more information. \end{funcdesc} -\begin{funcdesc}{symcomp}{pattern\, translate} +\begin{funcdesc}{symcomp}{pattern\optional{\, translate}} This is like \code{compile}, but supports symbolic group names: if a parentheses-enclosed group begins with a group name in angular brackets, e.g. \code{'\e(<id>[a-z][a-z0-9]*\e)'}, the group can @@ -108,7 +108,7 @@ equivalents. Compiled regular expression objects support these methods: \renewcommand{\indexsubitem}{(regex method)} -\begin{funcdesc}{match}{string\, pos} +\begin{funcdesc}{match}{string\optional{\, pos}} Return how many characters at the beginning of \var{string} match the compiled regular expression. Return \code{-1} if the string does not match the pattern (this is different from a zero-length @@ -122,7 +122,7 @@ Compiled regular expression objects support these methods: is to start. \end{funcdesc} -\begin{funcdesc}{search}{string\, pos} +\begin{funcdesc}{search}{string\optional{\, pos}} Return the first position in \var{string} that matches the regular expression \code{pattern}. Return \code{-1} if no position in the string matches the pattern (this is different from a zero-length diff --git a/Doc/lib/librotor.tex b/Doc/lib/librotor.tex index 657d2ac..b931333 100644 --- a/Doc/lib/librotor.tex +++ b/Doc/lib/librotor.tex @@ -1,6 +1,105 @@ \section{Built-in module \sectcode{rotor}} \bimodindex{rotor} -This module implements a rotor-based encryption algorithm, contributed -by Lance Ellinghouse. Currently no further documentation is available ---- you are kindly advised to read the source... +This module implements a rotor-based encryption algorithm, contributed by +Lance Ellinghouse. The design is derived from the Enigma device, a machine +used during World War II to encipher messages. A rotor is simply a +permutation. For example, if the character `A' is the origin of the rotor, +then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on. +To encrypt, we choose several different rotors, and set the origins of the +rotors to known positions; their initial position is the ciphering key. To +encipher a character, we permute the original character by the first rotor, +and then apply the second rotor's permutation to the result. We continue +until we've applied all the rotors; the resulting character is our +ciphertext. We then change the origin of the final rotor by one position, +from `A' to `B'; if the final rotor has made a complete revolution, then we +rotate the next-to-last rotor by one position, and apply the same procedure +recursively. In other words, after enciphering one character, we advance +the rotors in the same fashion as a car's odometer. Decoding works in the +same way, except we reverse the permutations and apply them in the opposite +order. +\index{Ellinghouse, Lance} +\indexii{Enigma}{cipher} + +The available functions in this module are: + +\renewcommand{\indexsubitem}{(in module rotor)} +\begin{funcdesc}{newrotor}{key\optional{\, numrotors}} +Returns a rotor object. \var{key} is a string containing the encryption key +for the object; it can contain arbitrary binary data. The key will be used +to randomly generate the rotor permutations and their initial positions. +\var{numrotors} is the number of rotor permutations in the returned object; +if it is omitted, a default value of 6 will be used. +\end{funcdesc} + +Rotor objects have the following methods: + +\renewcommand{\indexsubitem}{(rotor method)} +\begin{funcdesc}{setkey}{} +Resets the rotor to its initial state. +\end{funcdesc} + +\begin{funcdesc}{encrypt}{plaintext} +Resets the rotor object to its initial state and encrypts \var{plaintext}, +returning a string containing the ciphertext. The ciphertext is always the +same length as the original plaintext. +\end{funcdesc} + +\begin{funcdesc}{encryptmore}{plaintext} +Encrypts \var{plaintext} without resetting the rotor object, and returns a +string containing the ciphertext. +\end{funcdesc} + +\begin{funcdesc}{decrypt}{ciphertext} +Resets the rotor object to its initial state and decrypts \var{ciphertext}, +returning a string containing the ciphertext. The plaintext string will +always be the same length as the ciphertext. +\end{funcdesc} + +\begin{funcdesc}{decryptmore}{ciphertext} +Decrypts \var{ciphertext} without resetting the rotor object, and returns a +string containing the ciphertext. +\end{funcdesc} + +An example usage: +\bcode\begin{verbatim} +>>> import rotor +>>> rt = rotor.newrotor('key', 12) +>>> rt.encrypt('bar') +'\2534\363' +>>> rt.encryptmore('bar') +'\357\375$' +>>> rt.encrypt('bar') +'\2534\363' +>>> rt.decrypt('\2534\363') +'bar' +>>> rt.decryptmore('\357\375$') +'bar' +>>> rt.decrypt('\357\375$') +'l(\315' +>>> del rt +\end{verbatim}\ecode + +The module's code is not an exact simulation of the original Enigma device; +it implements the rotor encryption scheme differently from the original. The +most important difference is that in the original Enigma, there were only 5 +or 6 different rotors in existence, and they were applied twice to each +character; the cipher key was the order in which they were placed in the +machine. The Python rotor module uses the supplied key to initialize a +random number generator; the rotor permutations and their initial positions +are then randomly generated. The original device only enciphered the +letters of the alphabet, while this module can handle any 8-bit binary data; +it also produces binary output. This module can also operate with an +arbitrary number of rotors. + +The original Enigma cipher was broken in 1944. % XXX: Is this right? +The version implemented here is probably a good deal more difficult to crack +(especially if you use many rotors), but it won't be impossible for +a truly skilful and determined attacker to break the cipher. So if you want +to keep the NSA out of your files, this rotor cipher may well be unsafe, but +for discouraging casual snooping through your files, it will probably be +just fine, and may be somewhat safer than using the Unix \file{crypt} +command. +\index{National Security Agency}\index{crypt(1)} +% XXX How were Unix commands represented in the docs? + diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex index f051be8..244ef67 100644 --- a/Doc/lib/libsocket.tex +++ b/Doc/lib/libsocket.tex @@ -76,8 +76,10 @@ is an IP address itself it is returned unchanged. \end{funcdesc} \begin{funcdesc}{gethostname}{} -Return the current host's canonical name, as a string -(e.g. \code{'voorn.cwi.nl'}). +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, use +\code{socket.gethostbyname( socket.gethostname() )} instead. \end{funcdesc} \begin{funcdesc}{getservbyname}{servicename\, protocolname} diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex index 12771c9..df37707 100644 --- a/Doc/lib/libstdwin.tex +++ b/Doc/lib/libstdwin.tex @@ -102,7 +102,7 @@ Return the screen size in millimeters. \begin{funcdesc}{fetchcolor}{colorname} Return the pixel value corresponding to the given color name. Return the default foreground color for unknown color names. -Hint: the following code tests wheter you are on a machine that +Hint: the following code tests whether you are on a machine that supports more than two colors: \bcode\begin{verbatim} if stdwin.fetchcolor('black') <> \ @@ -372,7 +372,7 @@ for the meaning of \var{i}.) Return true if it succeeds. If succeeds, the window ``owns'' the selection until -(a) another applications takes ownership of the selection; or +(a) another application takes ownership of the selection; or (b) the window is deleted; or (c) the application clears ownership by calling \code{stdwin.resetselection(\var{i})}. @@ -571,7 +571,6 @@ window. When an object to be drawn falls partly outside the clipping region, the set of pixels drawn is the intersection of the clipping region and the set of pixels that would be drawn by the same operation in the absence of a clipping region. -clipping region \end{funcdesc} \begin{funcdesc}{noclip}{} diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex index bf7ad09..7d99a36 100644 --- a/Doc/lib/libstring.tex +++ b/Doc/lib/libstring.tex @@ -108,24 +108,24 @@ This doesn't understand other non-printing characters or escape sequences. \end{funcdesc} -\begin{funcdesc}{find}{s\, sub\, i} -Return the lowest index in \var{s} not smaller than \var{i} where the +\begin{funcdesc}{find}{s\, sub\optional{\, start}} +Return the lowest index in \var{s} not smaller than \var{start} where the substring \var{sub} is found. Return \code{-1} when \var{sub} -does not occur as a substring of \var{s} with index at least \var{i}. -If \var{i} is omitted, it defaults to \code{0}. If \var{i} is +does not occur as a substring of \var{s} with index at least \var{start}. +If \var{start} is omitted, it defaults to \code{0}. If \var{start} is negative, \code{len(\var{s})} is added. \end{funcdesc} -\begin{funcdesc}{rfind}{s\, sub\, i} +\begin{funcdesc}{rfind}{s\, sub\optional{\, start}} Like \code{find} but finds the highest index. \end{funcdesc} -\begin{funcdesc}{index}{s\, sub\, i} +\begin{funcdesc}{index}{s\, sub\optional{\, start}} Like \code{find} but raise \code{index_error} when the substring is not found. \end{funcdesc} -\begin{funcdesc}{rindex}{s\, sub\, i} +\begin{funcdesc}{rindex}{s\, sub\optional{\, start}} Like \code{rfind} but raise \code{index_error} when the substring is not found. \end{funcdesc} diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex index ba6b896..cd2c646 100644 --- a/Doc/lib/libsys.tex +++ b/Doc/lib/libsys.tex @@ -57,7 +57,7 @@ It is always available. 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 cause the error (which + without having to re-execute the command that caused the error (which may be hard to reproduce). The meaning of the variables is the same as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback}, respectively. diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex index fe8b7dc..7e83f4e 100644 --- a/Doc/lib/libtime.tex +++ b/Doc/lib/libtime.tex @@ -10,7 +10,7 @@ An explanation of some terminology and conventions is in order. \begin{itemize} \item -The ``epoch'' is the point where the time starts. On January 1st that +The ``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 the first element of \code{gmtime(0)}. diff --git a/Doc/libal.tex b/Doc/libal.tex index 708c54e..51a0312 100644 --- a/Doc/libal.tex +++ b/Doc/libal.tex @@ -23,7 +23,7 @@ documented upper limit.) Module \code{al} defines the following functions: \renewcommand{\indexsubitem}{(in module al)} -\begin{funcdesc}{openport}{name\, direction\, config} +\begin{funcdesc}{openport}{name\, direction\optional{\, config}} Equivalent to the C function ALopenport(). The name and direction arguments are strings. The optional config argument is an opaque configuration object as returned by \code{al.newconfig()}. The return diff --git a/Doc/libarray.tex b/Doc/libarray.tex index 21122f0..034ac32 100644 --- a/Doc/libarray.tex +++ b/Doc/libarray.tex @@ -20,14 +20,14 @@ which is a single character. The following type codes are defined: \end{tableiii} The actual representation of values is determined by the machine -architecture (strictly spoken, by the C implementation). The actual +architecture (strictly speaking, by the C implementation). The actual size can be accessed through the \var{typecode} attribute. The module defines the following function: \renewcommand{\indexsubitem}{(in module array)} -\begin{funcdesc}{array}{typecode\, initializer} +\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 or a string. The list or string is passed to the new array's @@ -51,7 +51,7 @@ Append a new item with value \var{x} to the end of the array. \begin{funcdesc}{byteswap}{x} ``Byteswap'' all items of the array. This is only supported for -integer values. It is useful when reading data ffrom a file written +integer values. It is useful when reading data from a file written on a machine with a different byte order. \end{funcdesc} diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex index 734065a..61ab7fc 100644 --- a/Doc/libaudioop.tex +++ b/Doc/libaudioop.tex @@ -43,7 +43,7 @@ This function returns the average over all samples in the fragment. \begin{funcdesc}{avgpp}{fragment\, width} This function returns the average peak-peak value over all samples in -the fragment. No filtering is done, so the useability of this routine +the fragment. No filtering is done, so the usefulness of this routine is questionable. \end{funcdesc} @@ -74,9 +74,9 @@ match \var{reference} as good as possible to a portion of (conceptually) does this by taking slices out of \var{fragment}, using \code{findfactor} to compute the best match, and minimizing the result. -It returns a tuple \code{(\var{offset}, \var{factor})} with offset the +It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the (integer) offset into \var{fragment} where the optimal match started -and \var{factor} the floating-point factor as per findfactor. +and \var{factor} the floating-point factor as per \code{findfactor}. \end{funcdesc} \begin{funcdesc}{findmax}{fragment\, length} @@ -101,8 +101,8 @@ This function converts samples between 1-, 2- and 4-byte formats. This function converts 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 algorythm has been selected for -use by the IMA, so may well become a standard. +(varying) step. The Intel/DVI ADPCM algorithm has been selected for +use by the IMA, so it may well become a standard. \code{State} is a tuple containing the state of the coder. The coder returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the @@ -120,7 +120,7 @@ discouraged. \begin{funcdesc}{lin2ulaw}{fragment\, width} This function converts samples in the audio fragment to U-LAW encoding -and returns this as a python string. U-LAW is an audio encoding format +and returns 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} diff --git a/Doc/libcrypto.tex b/Doc/libcrypto.tex index 467bee4..302b50d 100644 --- a/Doc/libcrypto.tex +++ b/Doc/libcrypto.tex @@ -2,4 +2,11 @@ The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the -installation. +installation. +\index{cryptography} + +%Hardcore cypherpunks will probably find the Python Cryptography Kit of +%further interest; the package adds built-in modules for DES and IDEA +%encryption, and provides a Python module for reading and decrypting PGP files. +%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher} +%\index{Python Cryptography Kit} diff --git a/Doc/libfcntl.tex b/Doc/libfcntl.tex index dd5212b..e361d5e 100644 --- a/Doc/libfcntl.tex +++ b/Doc/libfcntl.tex @@ -13,12 +13,12 @@ The module defines the following functions: \renewcommand{\indexsubitem}{(in module struct)} -\begin{funcdesc}{fcntl}{fd\, op\, arg} +\begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}} Perform the requested operation on file descriptor \code{\var{fd}}. The operation is defined by \code{\var{op}} and is operating system dependent. Typically these codes can be retrieved from the library - module \code{FCNTL}. The argument \code{\var{arg}} is optional. When - it is missing it is interpreted as the integer value \code{0}. When + module \code{FCNTL}. The argument \code{\var{arg}} is optional, and + defaults to the integer value \code{0}. When it is 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 real \code{fcntl()} diff --git a/Doc/libfl.tex b/Doc/libfl.tex index b705a6b..5af1a04 100644 --- a/Doc/libfl.tex +++ b/Doc/libfl.tex @@ -78,11 +78,11 @@ Show a dialog box with a three-line message and YES and NO buttons. It returns \code{1} if the user pressed YES, \code{0} if NO. \end{funcdesc} -\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\, but2\, but3} +\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\optional{\, but2\, +but3}} Show a dialog box with a three-line message and up to three buttons. It returns the number of the button clicked by the user (\code{1}, \code{2} or \code{3}). -The \var{but2} and \var{but3} arguments are optional. \end{funcdesc} \begin{funcdesc}{show_input}{prompt\, default} diff --git a/Doc/libfm.tex b/Doc/libfm.tex index acbc05d..45d820c 100644 --- a/Doc/libfm.tex +++ b/Doc/libfm.tex @@ -77,7 +77,8 @@ Calls \code{fmgetcomment(\var{fh})}. Returns a tuple giving some pertinent data about this font. This is an interface to \code{fmgetfontinfo()}. The returned tuple contains the following numbers: -\code{(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, \var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}. +{\tt(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, +\var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}. \end{funcdesc} \begin{funcdesc}{getstrwidth}{string} diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex index 2c30c14..b37920d 100644 --- a/Doc/libfuncs.tex +++ b/Doc/libfuncs.tex @@ -78,7 +78,7 @@ exactly one argument.) \code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}. \end{funcdesc} -\begin{funcdesc}{eval}{s\, globals\, locals} +\begin{funcdesc}{eval}{s\optional{\, globals\optional{\, locals}}} The arguments are a string and two optional dictionaries. The string argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the dictionaries as @@ -156,11 +156,11 @@ removed. object.) \end{funcdesc} -\begin{funcdesc}{input}{prompt} - Almost equivalent to \code{eval(raw_input(\var{prompt}))}. As for - \code{raw_input()}, the prompt argument is optional. The difference is - that a long input expression may be broken over multiple lines using the - backslash convention. +\begin{funcdesc}{input}{\optional{prompt}} + Almost equivalent to \code{eval(raw_input(\var{prompt}))}. Like + \code{raw_input()}, the \var{prompt} argument is optional. The difference + is that a long input expression may be broken over multiple lines using + the backslash convention. \end{funcdesc} \begin{funcdesc}{int}{x} @@ -206,7 +206,7 @@ any kind of sequence; the result is always a list. expression. \end{funcdesc} -\begin{funcdesc}{open}{filename\, mode\, bufsize} +\begin{funcdesc}{open}{filename\, \optional{mode\optional{\, bufsize}}} Return a new file object (described earlier under Built-in Types). The first two arguments are the same as for \code{stdio}'s \code{fopen()}: \var{filename} is the file name to be opened, @@ -238,15 +238,17 @@ there's no reliable way to determine whether this is the case.} \code{chr()}. \end{funcdesc} -\begin{funcdesc}{pow}{x\, y} - Return \var{x} to the power \var{y}. The arguments must have +\begin{funcdesc}{pow}{x\, y\optional{\, z}} + Return \var{x} to the power \var{y}; if \var{z} is present, $x^y \bmod z$ + is returned. The arguments must have numeric types. With mixed operand types, the rules for binary arithmetic operators apply. The effective operand type is also the type of the result; if the result is not expressible in this type, the - function raises an exception; e.g., \code{pow(2, -1)} is not allowed. + function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2, + 35000)} is not allowed. \end{funcdesc} -\begin{funcdesc}{range}{start\, end\, step} +\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}} This is a versatile function to create lists containing arithmetic progressions. It is most often used in \code{for} loops. The arguments must be plain integers. If the \var{step} argument is @@ -278,13 +280,11 @@ there's no reliable way to determine whether this is the case.} \end{verbatim}\ecode \end{funcdesc} -\begin{funcdesc}{raw_input}{prompt} - The string argument is optional; if present, it is written to - standard - output without a trailing newline. The function then reads a line - from input, converts it to a string (stripping a trailing newline), - and returns that. When \EOF{} is read, \code{EOFError} is raised. - Example: +\begin{funcdesc}{raw_input}{\optional{prompt}} + If the \var{prompt} argument is present, it is written to standard output + without a trailing newline. The function then reads a line from input, + converts it to a string (stripping a trailing newline), and returns that. + When \EOF{} is read, \code{EOFError} is raised. Example: \bcode\begin{verbatim} >>> s = raw_input('--> ') @@ -295,7 +295,7 @@ there's no reliable way to determine whether this is the case.} \end{verbatim}\ecode \end{funcdesc} -\begin{funcdesc}{reduce}{function\, list\, initializer} +\begin{funcdesc}{reduce}{function\, list\optional{\, initializer}} Apply the binary \var{function} to the items of \var{list} so as to reduce the list to a single value. E.g., \code{reduce(lambda x, y: x*y, \var{list}, 1)} returns the product of @@ -378,7 +378,7 @@ cannot normally be affected this way, but variables retrieved from other scopes can be. This may change.} \end{funcdesc} -\begin{funcdesc}{xrange}{start\, end\, step} +\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}} This function is very similar to \code{range()}, but returns an ``xrange object'' instead of a list. This is an opaque sequence type which yields the same values as the corresponding list, without diff --git a/Doc/libimageop.tex b/Doc/libimageop.tex index c1cdac4..4481e61 100644 --- a/Doc/libimageop.tex +++ b/Doc/libimageop.tex @@ -19,7 +19,7 @@ per pixel, etc. \begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1} This function takes the image in \code{image}, which should by \code{width} by \code{height} in size and consist of pixels of -\code{psize} bytes, and returns the selected part of that image. \code{X0}, +\code{psize} bytes, and returns the selected part of that image. \code{x0}, \code{y0}, \code{x1} and \code{y1} are like the \code{lrectread} parameters, i.e. the boundary is included in the new image. The new boundaries need not be inside the picture. Pixels that fall diff --git a/Doc/libimgfile.tex b/Doc/libimgfile.tex index 99efaf4..2da8d9d 100644 --- a/Doc/libimgfile.tex +++ b/Doc/libimgfile.tex @@ -29,7 +29,7 @@ the string. This format is suitable to pass to \code{gl.lrectwrite}, for instance. \end{funcdesc} -\begin{funcdesc}{readscaled}{file\, x\, y\, filter\, blur} +\begin{funcdesc}{readscaled}{file\, x\, y\, filter\optional{\, blur}} This function is identical to read but it returns an image that is scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and \var{blur} parameters are omitted scaling is done by @@ -42,7 +42,7 @@ after scaling. The filter forms supported are \code{'impulse'}, \code{'gaussian'}. If a filter is specified \var{blur} is an optional parameter specifying the blurriness of the filter. It defaults to \code{1.0}. -Readscaled makes no +\code{readscaled} makes no attempt to keep the aspect ratio correct, so that is the users' responsibility. \end{funcdesc} diff --git a/Doc/libjpeg.tex b/Doc/libjpeg.tex index d0c1604..a4e931f 100644 --- a/Doc/libjpeg.tex +++ b/Doc/libjpeg.tex @@ -4,7 +4,7 @@ The module jpeg provides access to the jpeg compressor and decompressor written by the Independent JPEG Group. JPEG is a (draft?) standard for compressing pictures. For details on jpeg or the -Indepent JPEG Group software refer to the JPEG standard or the +Independent JPEG Group software refer to the JPEG standard or the documentation provided with the software. The jpeg module defines these functions: @@ -12,10 +12,10 @@ The jpeg module defines these functions: \renewcommand{\indexsubitem}{(in module jpeg)} \begin{funcdesc}{compress}{data\, w\, h\, b} Treat data as a pixmap of width w and height h, with b bytes per -pixel. The data is in sgi gl order, so the first pixel is in the +pixel. The data is in SGI GL order, so the first pixel is in the lower-left corner. This means that lrectread return data can immedeately be passed to compress. Currently only 1 byte and 4 byte -pixels are allowed, the former being treaded as greyscale and the +pixels are allowed, the former being treated as greyscale and the latter as RGB color. Compress returns a string that contains the compressed picture, in JFIF format. \end{funcdesc} @@ -39,7 +39,7 @@ Set the quality of the compressed image to a value between \code{0} and \code{100} (default is \code{75}). Compress only. \item[\code{'optimize'}] -Perform huffman table optimization. Takes longer, but results in +Perform Huffman table optimization. Takes longer, but results in smaller compressed image. Compress only. \item[\code{'smooth'}] diff --git a/Doc/libmd5.tex b/Doc/libmd5.tex index 29e4b31..edaa727 100644 --- a/Doc/libmd5.tex +++ b/Doc/libmd5.tex @@ -2,16 +2,17 @@ \bimodindex{md5} This module implements the interface to RSA's MD5 message digest -algorithm (see also the file \file{md5.doc}). It's use is very +algorithm (see also the file \file{md5.doc}). Its use is quite straightforward: use the function \code{md5} to create an \dfn{md5}-object. You can now ``feed'' this object with arbitrary strings. -At any time you can ask the ``final'' digest of the object. Internally, -a temorary copy of the object is made and the digest is computed and -returned. Because of the copy, the digest operation is not desctructive -for the object. Before a more exact description of the use, a small -example: to obtain the digest of the string \code{'abc'}, use \ldots +At any time you can ask for the ``final'' digest of the object. Internally, +a temporary copy of the object is made and the digest is computed and +returned. Because of the copy, the digest operation is not destructive +for the object. Before a more exact description of the module's use, a small +example will be helpful: +to obtain the digest of the string \code{'abc'}, use \ldots \bcode\begin{verbatim} >>> from md5 import md5 @@ -29,8 +30,8 @@ More condensed: \end{verbatim}\ecode \renewcommand{\indexsubitem}{(in module md5)} -\begin{funcdesc}{md5}{arg} - Create a new md5-object. \var{arg} is optional: if present, an initial +\begin{funcdesc}{md5}{\optional{arg}} + Create a new md5-object. If \var{arg} is present, an initial \code{update} method is called with \var{arg} as argument. \end{funcdesc} @@ -42,6 +43,7 @@ An md5-object has the following methods: \end{funcdesc} \begin{funcdesc}{digest}{} +% XXX The following is not quite clear; what does MD5Final do? Return the \dfn{digest} of this md5-object. Internally, a copy is made and the \C-function \code{MD5Final} is called. Finally the digest is returned. diff --git a/Doc/libmods.tex b/Doc/libmods.tex index 3b902de..5bc6ee2 100755 --- a/Doc/libmods.tex +++ b/Doc/libmods.tex @@ -2,6 +2,6 @@ The modules described in this chapter are built into the interpreter and considered part of Python's standard environment: they are always -avaialble.\footnote{at least in theory --- it is possible to specify +available.\footnote{at least in theory --- it is possible to specify at build time that one or more of these modules should be excluded, but it would be antisocial to do so.} diff --git a/Doc/libposixfile.tex b/Doc/libposixfile.tex index 673ed6f..0d9cb32 100644 --- a/Doc/libposixfile.tex +++ b/Doc/libposixfile.tex @@ -47,17 +47,14 @@ The posixfile module defines the following functions: The posixfile object defines the following additional methods: \renewcommand{\indexsubitem}{(posixfile method)} -\begin{funcdesc}{lock}{fmt\, len\, start\, whence} +\begin{funcdesc}{lock}{fmt\, \optional{len\optional{\, start +\optional{\, whence}}}} Lock the specified section of the file that the file object is - referring to. The arguments \code{\var{len}}, \code{\var{start}} - and \code{\var{whence}} are optional with the understanding that - if \code{\var{start}} is used \code{\var{len}} becomes mandatory, - and if \code{\var{whence}} is used \code{\var{len}} and - \code{\var{start}} become mandatory. The format is explained - below in a table. The length argument specifies the length of the - section that should be locked. The default is \code{0}. The start - specifies the starting offset of the section. The default is - \code{0}. The whence argument specifies where the offset is + referring to. The format is explained + below in a table. The \var{len} argument specifies the length of the + section that should be locked. The default is \code{0}. \var{start} + specifies the starting offset of the section, where the default is + \code{0}. The \var{whence} argument specifies where the offset is relative to. It accepts one of the constants \code{SEEK_SET}, \code{SEEK_CUR} or \code{SEEK_END}. The default is \code{SEEK_SET}. For more information about the arguments refer to the fcntl @@ -69,7 +66,7 @@ The posixfile object defines the following additional methods: to. The new flags are ORed with the old flags, unless specified otherwise. The format is explained below in a table. Without arguments a string indicating the current flags is returned (this is - the same as the '?'modifier). For more information about the flags + the same as the '?' modifier). For more information about the flags refer to the fcntl manual page on your system. \end{funcdesc} @@ -105,8 +102,8 @@ In addition the following modifiers can be added to the format: \begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes} \lineiii{|}{wait until the lock has been granted}{} - \lineiii{?}{return the first lock conflicting with the requested lock, - or \code{None} if there is no conflict.}{(1)} + \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)} + {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\ \end{tableiii} Note: @@ -138,7 +135,7 @@ Note: (1) The \code{!} and \code{=} modifiers are mutually exclusive. -(2) This string represents the flag after they may have been altered +(2) This string represents the flags after they may have been altered by the same call. Examples: diff --git a/Doc/libregex.tex b/Doc/libregex.tex index 13b3e20..f3df684 100644 --- a/Doc/libregex.tex +++ b/Doc/libregex.tex @@ -41,7 +41,7 @@ The module defines these functions, and an exception: anywhere!). \end{funcdesc} -\begin{funcdesc}{compile}{pattern\, translate} +\begin{funcdesc}{compile}{pattern\optional{\, translate}} Compile a regular expression pattern into a regular expression object, which can be used for matching using its \code{match} and \code{search} methods, described below. The optional @@ -82,7 +82,7 @@ expressions.) more information. \end{funcdesc} -\begin{funcdesc}{symcomp}{pattern\, translate} +\begin{funcdesc}{symcomp}{pattern\optional{\, translate}} This is like \code{compile}, but supports symbolic group names: if a parentheses-enclosed group begins with a group name in angular brackets, e.g. \code{'\e(<id>[a-z][a-z0-9]*\e)'}, the group can @@ -108,7 +108,7 @@ equivalents. Compiled regular expression objects support these methods: \renewcommand{\indexsubitem}{(regex method)} -\begin{funcdesc}{match}{string\, pos} +\begin{funcdesc}{match}{string\optional{\, pos}} Return how many characters at the beginning of \var{string} match the compiled regular expression. Return \code{-1} if the string does not match the pattern (this is different from a zero-length @@ -122,7 +122,7 @@ Compiled regular expression objects support these methods: is to start. \end{funcdesc} -\begin{funcdesc}{search}{string\, pos} +\begin{funcdesc}{search}{string\optional{\, pos}} Return the first position in \var{string} that matches the regular expression \code{pattern}. Return \code{-1} if no position in the string matches the pattern (this is different from a zero-length diff --git a/Doc/librotor.tex b/Doc/librotor.tex index 657d2ac..b931333 100644 --- a/Doc/librotor.tex +++ b/Doc/librotor.tex @@ -1,6 +1,105 @@ \section{Built-in module \sectcode{rotor}} \bimodindex{rotor} -This module implements a rotor-based encryption algorithm, contributed -by Lance Ellinghouse. Currently no further documentation is available ---- you are kindly advised to read the source... +This module implements a rotor-based encryption algorithm, contributed by +Lance Ellinghouse. The design is derived from the Enigma device, a machine +used during World War II to encipher messages. A rotor is simply a +permutation. For example, if the character `A' is the origin of the rotor, +then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on. +To encrypt, we choose several different rotors, and set the origins of the +rotors to known positions; their initial position is the ciphering key. To +encipher a character, we permute the original character by the first rotor, +and then apply the second rotor's permutation to the result. We continue +until we've applied all the rotors; the resulting character is our +ciphertext. We then change the origin of the final rotor by one position, +from `A' to `B'; if the final rotor has made a complete revolution, then we +rotate the next-to-last rotor by one position, and apply the same procedure +recursively. In other words, after enciphering one character, we advance +the rotors in the same fashion as a car's odometer. Decoding works in the +same way, except we reverse the permutations and apply them in the opposite +order. +\index{Ellinghouse, Lance} +\indexii{Enigma}{cipher} + +The available functions in this module are: + +\renewcommand{\indexsubitem}{(in module rotor)} +\begin{funcdesc}{newrotor}{key\optional{\, numrotors}} +Returns a rotor object. \var{key} is a string containing the encryption key +for the object; it can contain arbitrary binary data. The key will be used +to randomly generate the rotor permutations and their initial positions. +\var{numrotors} is the number of rotor permutations in the returned object; +if it is omitted, a default value of 6 will be used. +\end{funcdesc} + +Rotor objects have the following methods: + +\renewcommand{\indexsubitem}{(rotor method)} +\begin{funcdesc}{setkey}{} +Resets the rotor to its initial state. +\end{funcdesc} + +\begin{funcdesc}{encrypt}{plaintext} +Resets the rotor object to its initial state and encrypts \var{plaintext}, +returning a string containing the ciphertext. The ciphertext is always the +same length as the original plaintext. +\end{funcdesc} + +\begin{funcdesc}{encryptmore}{plaintext} +Encrypts \var{plaintext} without resetting the rotor object, and returns a +string containing the ciphertext. +\end{funcdesc} + +\begin{funcdesc}{decrypt}{ciphertext} +Resets the rotor object to its initial state and decrypts \var{ciphertext}, +returning a string containing the ciphertext. The plaintext string will +always be the same length as the ciphertext. +\end{funcdesc} + +\begin{funcdesc}{decryptmore}{ciphertext} +Decrypts \var{ciphertext} without resetting the rotor object, and returns a +string containing the ciphertext. +\end{funcdesc} + +An example usage: +\bcode\begin{verbatim} +>>> import rotor +>>> rt = rotor.newrotor('key', 12) +>>> rt.encrypt('bar') +'\2534\363' +>>> rt.encryptmore('bar') +'\357\375$' +>>> rt.encrypt('bar') +'\2534\363' +>>> rt.decrypt('\2534\363') +'bar' +>>> rt.decryptmore('\357\375$') +'bar' +>>> rt.decrypt('\357\375$') +'l(\315' +>>> del rt +\end{verbatim}\ecode + +The module's code is not an exact simulation of the original Enigma device; +it implements the rotor encryption scheme differently from the original. The +most important difference is that in the original Enigma, there were only 5 +or 6 different rotors in existence, and they were applied twice to each +character; the cipher key was the order in which they were placed in the +machine. The Python rotor module uses the supplied key to initialize a +random number generator; the rotor permutations and their initial positions +are then randomly generated. The original device only enciphered the +letters of the alphabet, while this module can handle any 8-bit binary data; +it also produces binary output. This module can also operate with an +arbitrary number of rotors. + +The original Enigma cipher was broken in 1944. % XXX: Is this right? +The version implemented here is probably a good deal more difficult to crack +(especially if you use many rotors), but it won't be impossible for +a truly skilful and determined attacker to break the cipher. So if you want +to keep the NSA out of your files, this rotor cipher may well be unsafe, but +for discouraging casual snooping through your files, it will probably be +just fine, and may be somewhat safer than using the Unix \file{crypt} +command. +\index{National Security Agency}\index{crypt(1)} +% XXX How were Unix commands represented in the docs? + diff --git a/Doc/libsocket.tex b/Doc/libsocket.tex index f051be8..244ef67 100644 --- a/Doc/libsocket.tex +++ b/Doc/libsocket.tex @@ -76,8 +76,10 @@ is an IP address itself it is returned unchanged. \end{funcdesc} \begin{funcdesc}{gethostname}{} -Return the current host's canonical name, as a string -(e.g. \code{'voorn.cwi.nl'}). +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, use +\code{socket.gethostbyname( socket.gethostname() )} instead. \end{funcdesc} \begin{funcdesc}{getservbyname}{servicename\, protocolname} diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex index 12771c9..df37707 100644 --- a/Doc/libstdwin.tex +++ b/Doc/libstdwin.tex @@ -102,7 +102,7 @@ Return the screen size in millimeters. \begin{funcdesc}{fetchcolor}{colorname} Return the pixel value corresponding to the given color name. Return the default foreground color for unknown color names. -Hint: the following code tests wheter you are on a machine that +Hint: the following code tests whether you are on a machine that supports more than two colors: \bcode\begin{verbatim} if stdwin.fetchcolor('black') <> \ @@ -372,7 +372,7 @@ for the meaning of \var{i}.) Return true if it succeeds. If succeeds, the window ``owns'' the selection until -(a) another applications takes ownership of the selection; or +(a) another application takes ownership of the selection; or (b) the window is deleted; or (c) the application clears ownership by calling \code{stdwin.resetselection(\var{i})}. @@ -571,7 +571,6 @@ window. When an object to be drawn falls partly outside the clipping region, the set of pixels drawn is the intersection of the clipping region and the set of pixels that would be drawn by the same operation in the absence of a clipping region. -clipping region \end{funcdesc} \begin{funcdesc}{noclip}{} diff --git a/Doc/libstring.tex b/Doc/libstring.tex index bf7ad09..7d99a36 100644 --- a/Doc/libstring.tex +++ b/Doc/libstring.tex @@ -108,24 +108,24 @@ This doesn't understand other non-printing characters or escape sequences. \end{funcdesc} -\begin{funcdesc}{find}{s\, sub\, i} -Return the lowest index in \var{s} not smaller than \var{i} where the +\begin{funcdesc}{find}{s\, sub\optional{\, start}} +Return the lowest index in \var{s} not smaller than \var{start} where the substring \var{sub} is found. Return \code{-1} when \var{sub} -does not occur as a substring of \var{s} with index at least \var{i}. -If \var{i} is omitted, it defaults to \code{0}. If \var{i} is +does not occur as a substring of \var{s} with index at least \var{start}. +If \var{start} is omitted, it defaults to \code{0}. If \var{start} is negative, \code{len(\var{s})} is added. \end{funcdesc} -\begin{funcdesc}{rfind}{s\, sub\, i} +\begin{funcdesc}{rfind}{s\, sub\optional{\, start}} Like \code{find} but finds the highest index. \end{funcdesc} -\begin{funcdesc}{index}{s\, sub\, i} +\begin{funcdesc}{index}{s\, sub\optional{\, start}} Like \code{find} but raise \code{index_error} when the substring is not found. \end{funcdesc} -\begin{funcdesc}{rindex}{s\, sub\, i} +\begin{funcdesc}{rindex}{s\, sub\optional{\, start}} Like \code{rfind} but raise \code{index_error} when the substring is not found. \end{funcdesc} diff --git a/Doc/libsys.tex b/Doc/libsys.tex index ba6b896..cd2c646 100644 --- a/Doc/libsys.tex +++ b/Doc/libsys.tex @@ -57,7 +57,7 @@ It is always available. 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 cause the error (which + without having to re-execute the command that caused the error (which may be hard to reproduce). The meaning of the variables is the same as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback}, respectively. diff --git a/Doc/libtime.tex b/Doc/libtime.tex index fe8b7dc..7e83f4e 100644 --- a/Doc/libtime.tex +++ b/Doc/libtime.tex @@ -10,7 +10,7 @@ An explanation of some terminology and conventions is in order. \begin{itemize} \item -The ``epoch'' is the point where the time starts. On January 1st that +The ``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 the first element of \code{gmtime(0)}. diff --git a/Doc/myformat.sty b/Doc/myformat.sty index c4fa2d8..22d7ad4 100644 --- a/Doc/myformat.sty +++ b/Doc/myformat.sty @@ -48,17 +48,10 @@ } % Command to generate two index entries (using subentries) -\newcommand{\indexii}[2]{ -\index{#1!#2} -\index{#2!#1} -} +\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}} % And three entries (using only one level of subentries) -\newcommand{\indexiii}[3]{ -\index{#1!#2 #3} -\index{#2!#3, #1} -\index{#3!#1 #2} -} +\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}} % And four (again, using only one level of subentries) \newcommand{\indexiv}[4]{ @@ -113,6 +106,8 @@ \newcommand{\funcline}[2]{\item[\code{#1(\varvars{#2})}]\ttindex{#1}} \newcommand{\funcdesc}[2]{\fulllineitems\funcline{#1}{#2}} \let\endfuncdesc\endfulllineitems +\newcommand{\optional}[1]{{\ \Large[}{#1}\hspace{0.5mm}{\Large]}\ } + % same for excdesc \newcommand{\excline}[1]{\item[\code{#1}]\ttindex{#1}} @@ -145,6 +140,7 @@ \newcommand{\UNIX}{{\sc Unix}} \newcommand{\ASCII}{{\sc ascii}} %\newcommand{\C}{{\bf C}} +\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}} \newcommand{\C}{C} \newcommand{\EOF}{{\sc eof}} diff --git a/Doc/partparse.py b/Doc/partparse.py index 757fc02..be9b1c8 100644 --- a/Doc/partparse.py +++ b/Doc/partparse.py @@ -854,7 +854,7 @@ class Wobj: self.data = self.data + data # ignore these commands -ignoredcommands = ('bcode', 'ecode') +ignoredcommands = ('bcode', 'ecode', 'optional') # map commands like these to themselves as plaintext wordsselves = ('UNIX', 'ABC', 'C', 'ASCII', 'EOF') # \{ --> {, \} --> }, etc diff --git a/Doc/qua.tex b/Doc/qua.tex index 7cca09d..a56905c 100644 --- a/Doc/qua.tex +++ b/Doc/qua.tex @@ -1,4 +1,5 @@ \documentstyle[11pt]{article} +\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}} \title{ Interactively Testing Remote Servers Using the Python Programming Language @@ -550,7 +551,7 @@ x = Foo().init('Dr. Strangelove') Any user-defined class can be used as a base class to derive other classes. However, built-in types like lists cannot be used as base -classes. (Incidentally, the same is true in C++ and Modula-3.) A +classes. (Incidentally, the same is true in \Cpp{} and Modula-3.) A class may override any method of its base classes. Instance methods are first searched in the method list of their class, and then, recursively, in the method lists of their base class. Initialization @@ -668,7 +669,7 @@ C preprocessor, so we get macros, include files and conditional compilation for free. AIL's type declaration syntax is a superset of C's, so the user can include C header files to use the types declared there as function parameter types --- which are declared using -function prototypes as in C++ or Standard C\@. It should be clear by +function prototypes as in \Cpp{} or Standard C\@. It should be clear by now that AIL's lexical conventions are also identical to C's. The same is true for its expression syntax. @@ -768,7 +769,7 @@ Since AIL class inheritance only means interface sharing, not implementation sharing, inheriting the same class multiple times is never a problem and has the same effect as inheriting it once. -Note that the power of AIL classes doesn't go as far as C++. +Note that the power of AIL classes doesn't go as far as \Cpp{}. AIL classes cannot have data members, and there is no mechanism for a server that implements a derived class to inherit the implementation of the base @@ -1007,7 +1008,7 @@ value passed together with the exception is used to relay the error code returned by the server to the handler. Since in general RPC failures are rare, Python test programs can usually ignore exceptions --- making the program simpler --- without the risk of occasional -errors going undetected. (I still remember the embarrassment a +errors going undetected. (I still remember the embarrassment of a hundredfold speed improvement reported, long, long, ago, about a new version of a certain program, which later had to be attributed to a benchmark that silently dumped core...) diff --git a/Doc/ref.tex b/Doc/ref.tex index 11a5d08..9fb37b6 100644 --- a/Doc/ref.tex +++ b/Doc/ref.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! % Tell \index to actually write the .idx file \makeindex diff --git a/Doc/ref/ref.tex b/Doc/ref/ref.tex index 11a5d08..9fb37b6 100644 --- a/Doc/ref/ref.tex +++ b/Doc/ref/ref.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! % Tell \index to actually write the .idx file \makeindex diff --git a/Doc/ref/ref1.tex b/Doc/ref/ref1.tex index 169c244..0b006ba 100644 --- a/Doc/ref/ref1.tex +++ b/Doc/ref/ref1.tex @@ -5,7 +5,7 @@ It is not intended as a tutorial. While I am trying to be as precise as possible, I chose to use English rather than formal specifications for everything except syntax and -lexical analysis. This should make the document better understandable +lexical analysis. This should make the document more understandable to the average reader, but will leave room for ambiguities. Consequently, if you were coming from Mars and tried to re-implement Python from this document alone, you might have to guess things and in diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex index 67f22f8..c08f829 100644 --- a/Doc/ref/ref2.tex +++ b/Doc/ref/ref2.tex @@ -354,7 +354,8 @@ meaning: \begin{verbatim} ( ) [ ] { } -; , : . ` = +, : . " ` ' += ; \end{verbatim} The following printing ASCII characters are not used in Python. Their @@ -363,7 +364,7 @@ error: \index{ASCII} \begin{verbatim} -@ $ " ? +@ $ ? \end{verbatim} They may be used by future versions of the language though! diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex index c14fada..c4c4abc 100644 --- a/Doc/ref/ref4.tex +++ b/Doc/ref/ref4.tex @@ -9,7 +9,7 @@ A {\em code block} is a piece of Python program text that can be executed as a unit, such as a module, a class definition or a function body. Some code blocks (like modules) are executed only once, others -(like function bodies) may be executed many times. Code block may +(like function bodies) may be executed many times. Code blocks may textually contain other code blocks. Code blocks may invoke other code blocks (that may or may not be textually contained in them) as part of their execution, e.g. by invoking (calling) a function. @@ -72,7 +72,7 @@ When a global name is not found in the global name space, it is searched in the list of ``built-in'' names (which is actually the global name space of the module \verb@__builtin__@). When a name is not found at all, the \verb@NameError@ exception is raised.% -\footnote{If the code block contains \verb@exec@ statement or the +\footnote{If the code block contains \verb@exec@ statements or the construct \verb@from ... import *@, the semantics of names not explicitly mentioned in a \verb@global@ statement change subtly: name lookup first searches the local name space, then the global one, then diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex index 3e60931..a4a7b53 100644 --- a/Doc/ref/ref5.tex +++ b/Doc/ref/ref5.tex @@ -133,7 +133,7 @@ tuples are immutable, the rules for literals apply here. (Note that tuples are not formed by the parentheses, but rather by use of the comma operator. The exception is the empty tuple, for which parentheses {\em are} required --- allowing unparenthesized ``nothing'' -in expressions would causes ambiguities and allow common typos to +in expressions would cause ambiguities and allow common typos to pass uncaught.) \index{comma} \indexii{tuple}{display} @@ -677,7 +677,7 @@ comma-separated values is required. An expression (condition) list containing at least one comma yields a tuple. The length of the tuple is the number of expressions (conditions) in the list. The expressions (conditions) are evaluated -from left to right. (Conditions lists are used syntactically is a few +from left to right. (Condition lists are used syntactically is a few places where no tuple is constructed but a list of values is needed nevertheless.) \obindex{tuple} diff --git a/Doc/ref1.tex b/Doc/ref1.tex index 169c244..0b006ba 100644 --- a/Doc/ref1.tex +++ b/Doc/ref1.tex @@ -5,7 +5,7 @@ It is not intended as a tutorial. While I am trying to be as precise as possible, I chose to use English rather than formal specifications for everything except syntax and -lexical analysis. This should make the document better understandable +lexical analysis. This should make the document more understandable to the average reader, but will leave room for ambiguities. Consequently, if you were coming from Mars and tried to re-implement Python from this document alone, you might have to guess things and in diff --git a/Doc/ref2.tex b/Doc/ref2.tex index 67f22f8..c08f829 100644 --- a/Doc/ref2.tex +++ b/Doc/ref2.tex @@ -354,7 +354,8 @@ meaning: \begin{verbatim} ( ) [ ] { } -; , : . ` = +, : . " ` ' += ; \end{verbatim} The following printing ASCII characters are not used in Python. Their @@ -363,7 +364,7 @@ error: \index{ASCII} \begin{verbatim} -@ $ " ? +@ $ ? \end{verbatim} They may be used by future versions of the language though! diff --git a/Doc/ref4.tex b/Doc/ref4.tex index c14fada..c4c4abc 100644 --- a/Doc/ref4.tex +++ b/Doc/ref4.tex @@ -9,7 +9,7 @@ A {\em code block} is a piece of Python program text that can be executed as a unit, such as a module, a class definition or a function body. Some code blocks (like modules) are executed only once, others -(like function bodies) may be executed many times. Code block may +(like function bodies) may be executed many times. Code blocks may textually contain other code blocks. Code blocks may invoke other code blocks (that may or may not be textually contained in them) as part of their execution, e.g. by invoking (calling) a function. @@ -72,7 +72,7 @@ When a global name is not found in the global name space, it is searched in the list of ``built-in'' names (which is actually the global name space of the module \verb@__builtin__@). When a name is not found at all, the \verb@NameError@ exception is raised.% -\footnote{If the code block contains \verb@exec@ statement or the +\footnote{If the code block contains \verb@exec@ statements or the construct \verb@from ... import *@, the semantics of names not explicitly mentioned in a \verb@global@ statement change subtly: name lookup first searches the local name space, then the global one, then diff --git a/Doc/ref5.tex b/Doc/ref5.tex index 3e60931..a4a7b53 100644 --- a/Doc/ref5.tex +++ b/Doc/ref5.tex @@ -133,7 +133,7 @@ tuples are immutable, the rules for literals apply here. (Note that tuples are not formed by the parentheses, but rather by use of the comma operator. The exception is the empty tuple, for which parentheses {\em are} required --- allowing unparenthesized ``nothing'' -in expressions would causes ambiguities and allow common typos to +in expressions would cause ambiguities and allow common typos to pass uncaught.) \index{comma} \indexii{tuple}{display} @@ -677,7 +677,7 @@ comma-separated values is required. An expression (condition) list containing at least one comma yields a tuple. The length of the tuple is the number of expressions (conditions) in the list. The expressions (conditions) are evaluated -from left to right. (Conditions lists are used syntactically is a few +from left to right. (Condition lists are used syntactically is a few places where no tuple is constructed but a list of values is needed nevertheless.) \obindex{tuple} diff --git a/Doc/tools/partparse.py b/Doc/tools/partparse.py index 757fc02..be9b1c8 100644 --- a/Doc/tools/partparse.py +++ b/Doc/tools/partparse.py @@ -854,7 +854,7 @@ class Wobj: self.data = self.data + data # ignore these commands -ignoredcommands = ('bcode', 'ecode') +ignoredcommands = ('bcode', 'ecode', 'optional') # map commands like these to themselves as plaintext wordsselves = ('UNIX', 'ABC', 'C', 'ASCII', 'EOF') # \{ --> {, \} --> }, etc diff --git a/Doc/tut.tex b/Doc/tut.tex index 5353d56..f20d77c 100644 --- a/Doc/tut.tex +++ b/Doc/tut.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! \begin{document} @@ -1434,7 +1434,7 @@ If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are better off using a text editor to prepare the input for the interpreter -and run it with that file as input instead. This is known as creating a +and running it with that file as input instead. This is known as creating a {\em script}. As your program gets longer, you may want to split it into several files for easier maintenance. You may also want to use a handy function that you've written in several programs without copying @@ -2028,7 +2028,7 @@ clauses or one {\tt finally} clause, but not both. Python's class mechanism adds classes to the language with a minimum of new syntax and semantics. It is a mixture of the class mechanisms -found in C++ and Modula-3. As is true for modules, classes in Python +found in \Cpp{} and Modula-3. As is true for modules, classes in Python do not put an absolute barrier between definition and user, but rather rely on the politeness of the user not to ``break into the definition.'' The most important features of classes are retained @@ -2037,7 +2037,7 @@ multiple base classes, a derived class can override any methods of its base class(es), a method can call the method of a base class with the same name. Objects can contain an arbitrary amount of private data. -In C++ terminology, all class members (including the data members) are +In \Cpp{} terminology, all class members (including the data members) are {\em public}, and all member functions are {\em virtual}. There are no special constructors or destructors. As in Modula-3, there are no shorthands for referencing the object's members from its methods: the @@ -2045,9 +2045,9 @@ method function is declared with an explicit first argument representing the object, which is provided implicitly by the call. As in Smalltalk, classes themselves are objects, albeit in the wider sense of the word: in Python, all data types are objects. This -provides semantics for importing and renaming. But, just like in C++ +provides semantics for importing and renaming. But, just like in \Cpp{} or Modula-3, built-in types cannot be used as base classes for -extension by the user. Also, like in C++ but unlike in Modula-3, most +extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most built-in operators with special syntax (arithmetic operators, subscripting etc.) can be redefined for class members. @@ -2055,13 +2055,13 @@ subscripting etc.) can be redefined for class members. \section{A word about terminology} Lacking universally accepted terminology to talk about classes, I'll -make occasional use of Smalltalk and C++ terms. (I'd use Modula-3 +make occasional use of Smalltalk and \Cpp{} terms. (I'd use Modula-3 terms, since its object-oriented semantics are closer to those of -Python than C++, but I expect that few readers have heard of it...) +Python than \Cpp{}, but I expect that few readers have heard of it...) I also have to warn you that there's a terminological pitfall for object-oriented readers: the word ``object'' in Python does not -necessarily mean a class instance. Like C++ and Modula-3, and unlike +necessarily mean a class instance. Like \Cpp{} and Modula-3, and unlike Smalltalk, not all types in Python are classes: the basic built-in types like integers and lists aren't, and even somewhat more exotic types like files aren't. However, {\em all} Python types share a little @@ -2273,7 +2273,7 @@ understood by instance objects are attribute references. There are two kinds of valid attribute names. The first I'll call {\em data attributes}. These correspond to -``instance variables'' in Smalltalk, and to ``data members'' in C++. +``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}. Data attributes need not be declared; like local variables, they spring into existence when they are first assigned to. For example, if \verb\x\ in the instance of \verb\MyClass\ created above, the @@ -2549,7 +2549,7 @@ Derived classes may override methods of their base classes. Because methods have no special privileges when calling other methods of the same object, a method of a base class that calls another method defined in the same base class, may in fact end up calling a method of -a derived class that overrides it. (For C++ programmers: all methods +a derived class that overrides it. (For \Cpp{} programmers: all methods in Python are ``virtual functions''.) An overriding method in a derived class may in fact want to extend @@ -2643,14 +2643,14 @@ Python is an evolving language. Since this tutorial was last thoroughly revised, several new features have been added to the language. While ideally I should revise the tutorial to incorporate them in the mainline of the text, lack of time currently requires me -to a more modest approach. In this chapter I will briefly list the +to follow a more modest approach. In this chapter I will briefly list the most important improvements to the language and how you can use them to your benefit. \section{The Last Printed Expression} In interactive mode, the last printed expression is assigned to the -variable \code\_\. This means that when you are using Python as a +variable \code\_. This means that when you are using Python as a desk calculator, it is somewhat easier to continue calculations, for example: @@ -2851,7 +2851,7 @@ This feature may be combined with the previous, e.g. \subsection{Lambda Forms} -On popular demand, a few features commonly found in functional +By popular demand, a few features commonly found in functional programming languages and Lisp have been added to Python. With the \verb\lambda\ keyword, small anonymous functions can be created. Here's a function that returns the sum of its two arguments: diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index 5353d56..f20d77c 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -9,7 +9,7 @@ E-mail: {\tt guido@cwi.nl} } -\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release! +\date{14 July 1994 \\ Release 1.0.3} % XXX update before release! \begin{document} @@ -1434,7 +1434,7 @@ If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are better off using a text editor to prepare the input for the interpreter -and run it with that file as input instead. This is known as creating a +and running it with that file as input instead. This is known as creating a {\em script}. As your program gets longer, you may want to split it into several files for easier maintenance. You may also want to use a handy function that you've written in several programs without copying @@ -2028,7 +2028,7 @@ clauses or one {\tt finally} clause, but not both. Python's class mechanism adds classes to the language with a minimum of new syntax and semantics. It is a mixture of the class mechanisms -found in C++ and Modula-3. As is true for modules, classes in Python +found in \Cpp{} and Modula-3. As is true for modules, classes in Python do not put an absolute barrier between definition and user, but rather rely on the politeness of the user not to ``break into the definition.'' The most important features of classes are retained @@ -2037,7 +2037,7 @@ multiple base classes, a derived class can override any methods of its base class(es), a method can call the method of a base class with the same name. Objects can contain an arbitrary amount of private data. -In C++ terminology, all class members (including the data members) are +In \Cpp{} terminology, all class members (including the data members) are {\em public}, and all member functions are {\em virtual}. There are no special constructors or destructors. As in Modula-3, there are no shorthands for referencing the object's members from its methods: the @@ -2045,9 +2045,9 @@ method function is declared with an explicit first argument representing the object, which is provided implicitly by the call. As in Smalltalk, classes themselves are objects, albeit in the wider sense of the word: in Python, all data types are objects. This -provides semantics for importing and renaming. But, just like in C++ +provides semantics for importing and renaming. But, just like in \Cpp{} or Modula-3, built-in types cannot be used as base classes for -extension by the user. Also, like in C++ but unlike in Modula-3, most +extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most built-in operators with special syntax (arithmetic operators, subscripting etc.) can be redefined for class members. @@ -2055,13 +2055,13 @@ subscripting etc.) can be redefined for class members. \section{A word about terminology} Lacking universally accepted terminology to talk about classes, I'll -make occasional use of Smalltalk and C++ terms. (I'd use Modula-3 +make occasional use of Smalltalk and \Cpp{} terms. (I'd use Modula-3 terms, since its object-oriented semantics are closer to those of -Python than C++, but I expect that few readers have heard of it...) +Python than \Cpp{}, but I expect that few readers have heard of it...) I also have to warn you that there's a terminological pitfall for object-oriented readers: the word ``object'' in Python does not -necessarily mean a class instance. Like C++ and Modula-3, and unlike +necessarily mean a class instance. Like \Cpp{} and Modula-3, and unlike Smalltalk, not all types in Python are classes: the basic built-in types like integers and lists aren't, and even somewhat more exotic types like files aren't. However, {\em all} Python types share a little @@ -2273,7 +2273,7 @@ understood by instance objects are attribute references. There are two kinds of valid attribute names. The first I'll call {\em data attributes}. These correspond to -``instance variables'' in Smalltalk, and to ``data members'' in C++. +``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}. Data attributes need not be declared; like local variables, they spring into existence when they are first assigned to. For example, if \verb\x\ in the instance of \verb\MyClass\ created above, the @@ -2549,7 +2549,7 @@ Derived classes may override methods of their base classes. Because methods have no special privileges when calling other methods of the same object, a method of a base class that calls another method defined in the same base class, may in fact end up calling a method of -a derived class that overrides it. (For C++ programmers: all methods +a derived class that overrides it. (For \Cpp{} programmers: all methods in Python are ``virtual functions''.) An overriding method in a derived class may in fact want to extend @@ -2643,14 +2643,14 @@ Python is an evolving language. Since this tutorial was last thoroughly revised, several new features have been added to the language. While ideally I should revise the tutorial to incorporate them in the mainline of the text, lack of time currently requires me -to a more modest approach. In this chapter I will briefly list the +to follow a more modest approach. In this chapter I will briefly list the most important improvements to the language and how you can use them to your benefit. \section{The Last Printed Expression} In interactive mode, the last printed expression is assigned to the -variable \code\_\. This means that when you are using Python as a +variable \code\_. This means that when you are using Python as a desk calculator, it is somewhat easier to continue calculations, for example: @@ -2851,7 +2851,7 @@ This feature may be combined with the previous, e.g. \subsection{Lambda Forms} -On popular demand, a few features commonly found in functional +By popular demand, a few features commonly found in functional programming languages and Lisp have been added to Python. With the \verb\lambda\ keyword, small anonymous functions can be created. Here's a function that returns the sum of its two arguments: |