\section{\module{mhlib} ---
         Access to MH mailboxes}

% LaTeX'ized from the comments in the module by Skip Montanaro
% <skip@mojam.com>.

\declaremodule{standard}{mhlib}
\modulesynopsis{Manipulate MH mailboxes from Python.}


The \module{mhlib} module provides a Python interface to MH folders and
their contents.

The module contains three basic classes, \class{MH}, which represents a
particular collection of folders, \class{Folder}, which represents a single
folder, and \class{Message}, which represents a single message.


\begin{classdesc}{MH}{\optional{path\optional{, profile}}}
\class{MH} represents a collection of MH folders.
\end{classdesc}

\begin{classdesc}{Folder}{mh, name}
The \class{Folder} class represents a single folder and its messages.
\end{classdesc}

\begin{classdesc}{Message}{folder, number\optional{, name}}
\class{Message} objects represent individual messages in a folder.  The
Message class is derived from \class{mimetools.Message}.
\end{classdesc}


\subsection{MH Objects \label{mh-objects}}

\class{MH} instances have the following methods:


\begin{methoddesc}[MH]{error}{format\optional{, ...}}
Print an error message -- can be overridden.
\end{methoddesc}

\begin{methoddesc}[MH]{getprofile}{key}
Return a profile entry (\code{None} if not set).
\end{methoddesc}

\begin{methoddesc}[MH]{getpath}{}
Return the mailbox pathname.
\end{methoddesc}

\begin{methoddesc}[MH]{getcontext}{}
Return the current folder name.
\end{methoddesc}

\begin{methoddesc}[MH]{setcontext}{name}
Set the current folder name.
\end{methoddesc}

\begin{methoddesc}[MH]{listfolders}{}
Return a list of top-level folders.
\end{methoddesc}

\begin{methoddesc}[MH]{listallfolders}{}
Return a list of all folders.
\end{methoddesc}

\begin{methoddesc}[MH]{listsubfolders}{name}
Return a list of direct subfolders of the given folder.
\end{methoddesc}

\begin{methoddesc}[MH]{listallsubfolders}{name}
Return a list of all subfolders of the given folder.
\end{methoddesc}

\begin{methoddesc}[MH]{makefolder}{name}
Create a new folder.
\end{methoddesc}

\begin{methoddesc}[MH]{deletefolder}{name}
Delete a folder -- must have no subfolders.
\end{methoddesc}

\begin{methoddesc}[MH]{openfolder}{name}
Return a new open folder object.
\end{methoddesc}


\subsection{Folder Objects \label{mh-folder-objects}}

\class{Folder} instances represent open folders and have the following
methods:


\begin{methoddesc}[Folder]{error}{format\optional{, ...}}
Print an error message -- can be overridden.
\end{methoddesc}

\begin{methoddesc}[Folder]{getfullname}{}
Return the folder's full pathname.
\end{methoddesc}

\begin{methoddesc}[Folder]{getsequencesfilename}{}
Return the full pathname of the folder's sequences file.
\end{methoddesc}

\begin{methoddesc}[Folder]{getmessagefilename}{n}
Return the full pathname of message \var{n} of the folder.
\end{methoddesc}

\begin{methoddesc}[Folder]{listmessages}{}
Return a list of messages in the folder (as numbers).
\end{methoddesc}

\begin{methoddesc}[Folder]{getcurrent}{}
Return the current message number.
\end{methoddesc}

\begin{methoddesc}[Folder]{setcurrent}{n}
Set the current message number to \var{n}.
\end{methoddesc}

\begin{methoddesc}[Folder]{parsesequence}{seq}
Parse msgs syntax into list of messages.
\end{methoddesc}

\begin{methoddesc}[Folder]{getlast}{}
Get last message, or \code{0} if no messages are in the folder.
\end{methoddesc}

\begin{methoddesc}[Folder]{setlast}{n}
Set last message (internal use only).
\end{methoddesc}

\begin{methoddesc}[Folder]{getsequences}{}
Return dictionary of sequences in folder.  The sequence names are used 
as keys, and the values are the lists of message numbers in the
sequences.
\end{methoddesc}

\begin{methoddesc}[Folder]{putsequences}{dict}
Return dictionary of sequences in folder {name: list}.
\end{methoddesc}

\begin{methoddesc}[Folder]{removemessages}{list}
Remove messages in list from folder.
\end{methoddesc}

\begin{methoddesc}[Folder]{refilemessages}{list, tofolder}
Move messages in list to other folder.
\end{methoddesc}

\begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton}
Move one message to a given destination in another folder.
\end{methoddesc}

\begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton}
Copy one message to a given destination in another folder.
\end{methoddesc}


\subsection{Message Objects \label{mh-message-objects}}

The \class{Message} class adds one method to those of
\class{mimetools.Message}:

\begin{methoddesc}[Message]{openmessage}{n}
Return a new open message object (costs a file descriptor).
\end{methoddesc}