Doc/library/mhlib.rst

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