Preliminary mhlib and telnetlib documents from Skip Montanaro -- thanks, Skip!

3 files changed, 321 insertions, 0 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index cec6c83..214674b 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -177,6 +177,7 @@ add new extensions to Python and how to embed it in other applications.
 \input{libimaplib}
 \input{libnntplib}
 \input{libsmtplib}
+\input{libtelnetlib}
 \input{liburlparse}
 \input{libsocksvr}
 \input{libbasehttp}
@@ -199,6 +200,7 @@ add new extensions to Python and how to embed it in other applications.
 \input{libbase64}
 \input{libquopri}
 \input{libmailbox}
+\input{libmhlib}
 \input{libmimify}
 \input{libnetrc}
 
diff --git a/Doc/lib/libmhlib.tex b/Doc/lib/libmhlib.tex
new file mode 100644
index 0000000..3676a1f
--- /dev/null
+++ b/Doc/lib/libmhlib.tex
@@ -0,0 +1,165 @@
+% LaTeX'ized from the comments in the module by Skip Montanaro
+% <skip@mojam.com>.
+
+\section{\module{mhlib} ---
+         Object-oriented access to MH mailboxes}
+
+\declaremodule{standard}{mhlib}
+\modulesynopsis{Manipulate MH mailboxes from Python.}
+
+
+The \module{mhlib} module provides a Python interface to MH folders and
+their contents.
+
+The module contains three basic classes, \class{MH}, which represents a
+particular collection of folders, \class{Folder}, which represents a single
+folder, and \class{Message}, which represents a single message.
+
+
+\begin{classdesc}{MH}{\optional{path\optional{, profile}}}
+\class{MH} represents a collection of MH folders.
+\end{classdesc}
+
+\begin{classdesc}{Folder}{mh, name}
+The \class{Folder} class represents a single folder and its messages.
+\end{classdesc}
+
+\begin{classdesc}{Message}{folder, number\optional{, name}}
+\class{Message} objects represent individual messages in a folder.  The
+Message class is derived from \class{mimetools.Message}.
+\end{classdesc}
+
+
+\subsection{MH Objects \label{mh-objects}}
+
+\class{MH} instances have the following methods:
+
+
+\begin{methoddesc}[MH]{error}{format\optional{, ...}}
+Print an error message -- can be overridden.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{getprofile}{key}
+Return a profile entry (\code{None} if not set).
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{getpath}{}
+Return the mailbox pathname.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{getcontext}{}
+Return the current folder name.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{setcontext}{name}
+Set the current folder name.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{listfolders}{}
+Return a list of top-level folders.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{listallfolders}{}
+Return a list of all folders.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{listsubfolders}{name}
+Return a list of direct subfolders of the given folder.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{listallsubfolders}{name}
+Return a list of all subfolders of the given folder.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{makefolder}{name}
+Create a new folder.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{deletefolder}{name}
+Delete a folder -- must have no subfolders.
+\end{methoddesc}
+
+\begin{methoddesc}[MH]{openfolder}{name}
+Return a new open folder object.
+\end{methoddesc}
+
+
+
+\subsection{Folder Objects \label{mh-folder-objects}}
+
+\class{Folder} instances represent open folders and have the following
+methods:
+
+
+\begin{methoddesc}[Folder]{error}{format\optional{, ...}}
+Print an error message -- can be overridden.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{getfullname}{}
+Return the folder's full pathname.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{getsequencesfilename}{}
+Return the full pathname of the folder's sequences file.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{getmessagefilename}{n}
+Return the full pathname of message \var{n} of the folder.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{listmessages}{}
+Return a list of messages in the folder (as numbers).
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{getcurrent}{}
+Return the current message number.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{setcurrent}{n}
+Set the current message number to \var{n}.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{parsesequence}{seq}
+Parse msgs syntax into list of messages.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{getlast}{}
+Get last message, or \code{0} if no messages are in the folder.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{setlast}{n}
+Set last message (internal use only).
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{getsequences}{}
+Return dictionary of sequences in folder.  The sequence names are used 
+as keys, and the values are the lists of message numbers in the
+sequences.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{putsequences}{dict}
+Return dictionary of sequences in folder {name: list}.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{removemessages}{list}
+Remove messages in list from folder.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{refilemessages}{list, tofolder}
+Move messages in list to other folder.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton}
+Move one message to a given destination in another folder.
+\end{methoddesc}
+
+\begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton}
+Copy one message to a given destination in another folder.
+\end{methoddesc}
+
+
+\subsection{Message Objects \label{mh-message-objects}}
+
+\begin{methoddesc}[Message]{openmessage}{n}
+Return a new open message object (costs a file descriptor).
+\end{methoddesc}
diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex
new file mode 100644
index 0000000..18fcc97
--- /dev/null
+++ b/Doc/lib/libtelnetlib.tex
@@ -0,0 +1,154 @@
+% LaTeX'ized from the comments in the module by Skip Montanaro
+% <skip@mojam.com>.
+
+\section{\module{telnetlib} ---
+         Telnet client}
+
+\declaremodule{standard}{telnetlib}
+\modulesynopsis{Telnet client class.}
+
+
+The \module{telnetlib} module provides a \class{Telnet} class that
+implements the Telnet protocol.  See \rfc{854} for details about the
+protocol.
+
+
+\begin{classdesc}{Telnet}{\optional{host\optional{, port=0}}}
+\class{Telnet} represents a connection to a telnet server. The
+instance is initially not connected; the \method{open()} method must
+be used to establish a connection.  Alternatively, the host name and
+optional port number can be passed to the constructor, too.
+
+Do not reopen an already connected instance.
+
+This class has many \method{read_*()} methods.  Note that some of them 
+raise \exception{EOFError} when the end of the connection is read,
+because they can return an empty string for other reasons.  See the
+individual doc strings.
+\end{classdesc}
+
+
+\subsection{Telnet Objects \label{telnet-objects}}
+
+\class{Telnet} instances have the following methods:
+
+
+\begin{methoddesc}[Telnet]{read_until}{expected\optional{, timeout}}
+Read until a given string is encountered or until timeout.
+
+When no match is found, return whatever is available instead,
+possibly the empty string.  Raise \exception{EOFError} if the connection
+is closed and no cooked data is available.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{read_all}{}
+Read all data until EOF; block until connection closed.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{read_some}{}
+Read at least one byte of cooked data unless EOF is hit.
+
+Return \code{''} if EOF is hit.  Block if no data is immediately available.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{read_very_eager}{}
+Read everything that's possible without blocking in I/O (eager).
+
+Raise \exception{EOFError} if connection closed and no cooked data
+available.  Return \code{''} if no cooked data available otherwise.
+Don't block unless in the midst of an IAC sequence.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{read_eager}{}
+Read readily available data.
+
+Raise \exception{EOFError} if connection closed and no cooked data
+available.  Return \code{''} if no cooked data available otherwise.
+Don't block unless in the midst of an IAC sequence.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{read_lazy}{}
+Process and return data that's already in the queues (lazy).
+
+Raise \exception{EOFError} if connection closed and no data available.
+Return \code{''} if no cooked data available otherwise.  Don't block
+unless in the midst of an IAC sequence.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{read_very_lazy}{}
+Return any data available in the cooked queue (very lazy).
+
+Raise \exception{EOFError} if connection closed and no data available.
+Return \code{''} if no cooked data available otherwise.  Don't block.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{open}{host\optional{, port=0}}
+Connect to a host.
+
+The optional second argument is the port number, which
+defaults to the standard telnet port (23).
+
+Don't try to reopen an already connected instance.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}}
+Print a debug message, when the debug level is > 0.
+
+If extra arguments are present, they are substituted in the
+message using the standard string formatting operator.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{set_debuglevel}{debuglevel}
+Set the debug level.
+
+The higher it is, the more debug output you get (on sys.stdout).
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{close}{}
+Close the connection.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{get_socket}{}
+Return the socket object used internally.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{fileno}{}
+Return the fileno() of the socket object used internally.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{write}{buffer}
+Write a string to the socket, doubling any IAC characters.
+
+Can block if the connection is blocked.  May raise
+socket.error if the connection is closed.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{interact}{}
+Interaction function, emulates a very dumb telnet client.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{mt_interact}{}
+Multithreaded version of \method{interact}.
+\end{methoddesc}
+
+\begin{methoddesc}[Telnet]{expect}{list, timeout=None}
+Read until one from a list of a regular expressions matches.
+
+The first argument is a list of regular expressions, either
+compiled (\class{re.RegexObject} instances) or uncompiled (strings).
+The optional second argument is a timeout, in seconds; default
+is no timeout.
+
+Return a tuple of three items: the index in the list of the
+first regular expression that matches; the match object
+returned; and the text read up till and including the match.
+
+If end of file is found and no text was read, raise
+\exception{EOFError}.  Otherwise, when nothing matches, return
+\code{(-1, None, \var{text})} where \var{text} is the text received so
+far (may be the empty string if a timeout happened).
+
+If a regular expression ends with a greedy match (e.g. \regexp{.*})
+or if more than one expression can match the same input, the
+results are undeterministic, and may depend on the I/O timing.
+\end{methoddesc}