###
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.

See Also:

maildir man page from qmail
  The original specification of the format.

Using maildir format
  Notes on Maildir by its inventor. Includes an updated name-creation scheme and details on "info" semantics.

maildir man page from Courier
  Another specification of the format. Describes a common extension for supporting folders.