/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
 14The :mod:`mhlib` module provides a Python interface to MH folders and their
 15contents.
 16
 17The module contains three basic classes, :class:`MH`, which represents a
 18particular collection of folders, :class:`Folder`, which represents a single
 19folder, 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
 40MH 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
108Folder 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
197Message Objects
198---------------
199
200The :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