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.
