From 658cef0141ebbbcd21dd411f0cfb7101f29c79b2 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Mon, 15 Mar 1999 15:44:18 +0000 Subject: Preliminary mhlib and telnetlib documents from Skip Montanaro -- thanks, Skip! --- Doc/lib/lib.tex | 2 + Doc/lib/libmhlib.tex | 165 +++++++++++++++++++++++++++++++++++++++++++++++ Doc/lib/libtelnetlib.tex | 154 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 321 insertions(+) create mode 100644 Doc/lib/libmhlib.tex create mode 100644 Doc/lib/libtelnetlib.tex 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 +% . + +\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 +% . + +\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} -- cgit v0.12