Doc/lib/libmhlib.tex

   1 \section{\module{mhlib} ---
   2          Access to MH mailboxes}
   3
   4 % LaTeX'ized from the comments in the module by Skip Montanaro
   5 % <skip@mojam.com>.
   6
   7 \declaremodule{standard}{mhlib}
   8 \modulesynopsis{Manipulate MH mailboxes from Python.}
   9
  10
  11 The \module{mhlib} module provides a Python interface to MH folders and
  12 their contents.
  13
  14 The module contains three basic classes, \class{MH}, which represents a
  15 particular collection of folders, \class{Folder}, which represents a single
  16 folder, and \class{Message}, which represents a single message.
  17
  18
  19 \begin{classdesc}{MH}{\optional{path\optional{, profile}}}
  20 \class{MH} represents a collection of MH folders.
  21 \end{classdesc}
  22
  23 \begin{classdesc}{Folder}{mh, name}
  24 The \class{Folder} class represents a single folder and its messages.
  25 \end{classdesc}
  26
  27 \begin{classdesc}{Message}{folder, number\optional{, name}}
  28 \class{Message} objects represent individual messages in a folder.  The
  29 Message class is derived from \class{mimetools.Message}.
  30 \end{classdesc}
  31
  32
  33 \subsection{MH Objects \label{mh-objects}}
  34
  35 \class{MH} instances have the following methods:
  36
  37
  38 \begin{methoddesc}[MH]{error}{format\optional{, ...}}
  39 Print an error message -- can be overridden.
  40 \end{methoddesc}
  41
  42 \begin{methoddesc}[MH]{getprofile}{key}
  43 Return a profile entry (\code{None} if not set).
  44 \end{methoddesc}
  45
  46 \begin{methoddesc}[MH]{getpath}{}
  47 Return the mailbox pathname.
  48 \end{methoddesc}
  49
  50 \begin{methoddesc}[MH]{getcontext}{}
  51 Return the current folder name.
  52 \end{methoddesc}
  53
  54 \begin{methoddesc}[MH]{setcontext}{name}
  55 Set the current folder name.
  56 \end{methoddesc}
  57
  58 \begin{methoddesc}[MH]{listfolders}{}
  59 Return a list of top-level folders.
  60 \end{methoddesc}
  61
  62 \begin{methoddesc}[MH]{listallfolders}{}
  63 Return a list of all folders.
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}[MH]{listsubfolders}{name}
  67 Return a list of direct subfolders of the given folder.
  68 \end{methoddesc}
  69
  70 \begin{methoddesc}[MH]{listallsubfolders}{name}
  71 Return a list of all subfolders of the given folder.
  72 \end{methoddesc}
  73
  74 \begin{methoddesc}[MH]{makefolder}{name}
  75 Create a new folder.
  76 \end{methoddesc}
  77
  78 \begin{methoddesc}[MH]{deletefolder}{name}
  79 Delete a folder -- must have no subfolders.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}[MH]{openfolder}{name}
  83 Return a new open folder object.
  84 \end{methoddesc}
  85
  86
  87
  88 \subsection{Folder Objects \label{mh-folder-objects}}
  89
  90 \class{Folder} instances represent open folders and have the following
  91 methods:
  92
  93
  94 \begin{methoddesc}[Folder]{error}{format\optional{, ...}}
  95 Print an error message -- can be overridden.
  96 \end{methoddesc}
  97
  98 \begin{methoddesc}[Folder]{getfullname}{}
  99 Return the folder's full pathname.
 100 \end{methoddesc}
 101
 102 \begin{methoddesc}[Folder]{getsequencesfilename}{}
 103 Return the full pathname of the folder's sequences file.
 104 \end{methoddesc}
 105
 106 \begin{methoddesc}[Folder]{getmessagefilename}{n}
 107 Return the full pathname of message \var{n} of the folder.
 108 \end{methoddesc}
 109
 110 \begin{methoddesc}[Folder]{listmessages}{}
 111 Return a list of messages in the folder (as numbers).
 112 \end{methoddesc}
 113
 114 \begin{methoddesc}[Folder]{getcurrent}{}
 115 Return the current message number.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}[Folder]{setcurrent}{n}
 119 Set the current message number to \var{n}.
 120 \end{methoddesc}
 121
 122 \begin{methoddesc}[Folder]{parsesequence}{seq}
 123 Parse msgs syntax into list of messages.
 124 \end{methoddesc}
 125
 126 \begin{methoddesc}[Folder]{getlast}{}
 127 Get last message, or \code{0} if no messages are in the folder.
 128 \end{methoddesc}
 129
 130 \begin{methoddesc}[Folder]{setlast}{n}
 131 Set last message (internal use only).
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}[Folder]{getsequences}{}
 135 Return dictionary of sequences in folder.  The sequence names are used
 136 as keys, and the values are the lists of message numbers in the
 137 sequences.
 138 \end{methoddesc}
 139
 140 \begin{methoddesc}[Folder]{putsequences}{dict}
 141 Return dictionary of sequences in folder {name: list}.
 142 \end{methoddesc}
 143
 144 \begin{methoddesc}[Folder]{removemessages}{list}
 145 Remove messages in list from folder.
 146 \end{methoddesc}
 147
 148 \begin{methoddesc}[Folder]{refilemessages}{list, tofolder}
 149 Move messages in list to other folder.
 150 \end{methoddesc}
 151
 152 \begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton}
 153 Move one message to a given destination in another folder.
 154 \end{methoddesc}
 155
 156 \begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton}
 157 Copy one message to a given destination in another folder.
 158 \end{methoddesc}
 159
 160
 161 \subsection{Message Objects \label{mh-message-objects}}
 162
 163 The \class{Message} class adds one method to those of
 164 \class{mimetools.Message}:
 165
 166 \begin{methoddesc}[Message]{openmessage}{n}
 167 Return a new open message object (costs a file descriptor).
 168 \end{methoddesc}