Doc/library/mhlib.rst

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