7.3.1.1 Maildir

7.3.1.1 `Maildir`

class Maildir( dirname[, factory=rfc822.Message[, create=True]]): A subclass of Mailbox for mailboxes in Maildir 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, MaildirMessage is used as the default message representation. If create is True, the mailbox is created if it does not exist.
It is for historical reasons that factory defaults to rfc822.Message and that dirname is named as such rather than path. For a Maildir instance that behaves like instances of other Mailbox subclasses, set factory to None.

Maildir is a directory-based mailbox format invented for the qmail mail transfer agent and now widely supported by other programs. Messages in a Maildir mailbox are stored in separate files within a common directory structure. This design allows Maildir mailboxes to be accessed and modified by multiple unrelated programs without data corruption, so file locking is unnecessary.

Maildir mailboxes contain three subdirectories, namely: tmp, new, and cur. Messages are created momentarily in the tmp subdirectory and then moved to the new subdirectory to finalize delivery. A mail user agent may subsequently move the message to the cur subdirectory and store information about the state of the message in a special "info" section appended to its file name.

Folders of the style introduced by the Courier mail transfer agent are also supported. Any subdirectory of the main mailbox is considered a folder if "." is the first character in its name. Folder names are represented by Maildir without the leading ".". Each folder is itself a Maildir mailbox but should not contain other folders. Instead, a logical nesting is indicated using "." to delimit levels, e.g., "Archived.2005.07".

Note: The Maildir specification requires the use of a colon (":") in certain message file names. However, some operating systems do not permit this character in file names, If you wish to use a Maildir-like format on such an operating system, you should specify another character to use instead. The exclamation point ("!") is a popular choice. For example:

import mailbox
mailbox.Maildir.colon = '!'

The colon attribute may also be set on a per-instance basis.

Maildir 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 a Maildir 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 a Maildir 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.

clean( ): Delete temporary files from the mailbox that have not been accessed in the last 36 hours. The Maildir specification says that mail-reading programs should do this occasionally.

Some Mailbox methods implemented by Maildir deserve special remarks:

add( message)
__setitem__( key, message)
update( arg): Warning: These methods generate unique file names based upon the current process ID. When using multiple threads, undetected name clashes may occur and cause corruption of the mailbox unless threads are coordinated to avoid using these methods to manipulate the same mailbox simultaneously.

flush( ): All changes to Maildir mailboxes are immediately applied, so this method does nothing.

lock( )
unlock( ): Maildir mailboxes do not support (or require) locking, so these methods do nothing.

close( ): Maildir instances do not keep any open files and the underlying mailboxes do not support locking, so this method does nothing.

get_file( key): Depending upon the host platform, it may not be possible to modify or remove the underlying message while the returned file remains open.