7.3.1.3 MH

###
7.3.1.3 `MH`

class `MH`( | path[, factory=None[, create=True]])

  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()`.

See Also:

nmh - Message Handling System
  Home page of nmh, an updated version of the original mh.

MH & nmh: Email for Users & Programmers
  A GPL-licensed book on mh and nmh, with some information on the mailbox format.