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.