A subclass of Mailbox for mailboxes in MH format. Parameter
factory is a callable object that accepts a file-like message
representation (which behaves as if opened in binary mode) and returns a custom
representation. If factory is None, MHMessage is used as
the default message representation. If create is True, the mailbox
is created if it does not exist.
MH is a directory-based mailbox format invented for the MH Message Handling
System, a mail user agent. Each message in an MH mailbox resides in its own
file. An MH mailbox may contain other MH mailboxes (called folders) in
addition to messages. Folders may be nested indefinitely. MH mailboxes also
support sequences, which are named lists used to logically group messages
without moving them to sub-folders. Sequences are defined in a file called
.mh_sequences in each folder.
The MH class manipulates MH mailboxes, but it does not attempt to
emulate all of mh's behaviors. In particular, it does not modify and
is not affected by the context or .mh_profile files that are used
by mh to store its state and configuration.
MH instances have all of the methods of Mailbox in addition to
the following:
list_folders(
)
Return a list of the names of all folders.
get_folder(
folder)
Return an MH instance representing the folder whose name is
folder. A NoSuchMailboxError exception is raised if the
folder does not exist.
add_folder(
folder)
Create a folder whose name is folder and return an MH instance
representing it.
remove_folder(
folder)
Delete the folder whose name is folder. If the folder contains any
messages, a NotEmptyError exception will be raised and the folder
will not be deleted.
get_sequences(
)
Return a dictionary of sequence names mapped to key lists. If there are no
sequences, the empty dictionary is returned.
set_sequences(
sequences)
Re-define the sequences that exist in the mailbox based upon sequences, a
dictionary of names mapped to key lists, like returned by
get_sequences().
pack(
)
Rename messages in the mailbox as necessary to eliminate gaps in numbering.
Entries in the sequences list are updated correspondingly. Note:
Already-issued
keys are invalidated by this operation and should not be subsequently used.
Some Mailbox methods implemented by MH deserve special remarks:
remove(
key)
__delitem__(
key)
discard(
key)
These methods immediately delete the message. The MH convention of marking a
message for deletion by prepending a comma to its name is not used.
lock(
)
unlock(
)
Three locking mechanisms are used--dot locking and, if available, the
flock() and lockf() system calls. For MH mailboxes,
locking the mailbox means locking the .mh_sequences file and, only for
the duration of any operations that affect them, locking individual message
files.
get_file(
key)
Depending upon the host platform, it may not be possible to remove the
underlying message while the returned file remains open.
flush(
)
All changes to MH mailboxes are immediately applied, so this method does
nothing.
close(
)
MH instances do not keep any open files, so this method is equivelant
to unlock().
