[Python-checkins] python/nondist/sandbox/mailbox README, NONE, 1.1 libmailbox.tex, NONE, 1.1

[gregorykjohnson@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/sandbox/mailbox
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10425

Added Files:
	README libmailbox.tex 
Log Message:
Initial commit for Summer of Code mailbox project.
There's only documentation for now. Code will follow.


--- NEW FILE: README ---
This is a backward-compatible rewrite of the mailbox module to support
mailbox modification and mailbox-format-specific message attributes.

It's being written as part of Google's Summer of Code program[1] by
Gregory K. Johnson with mentoring from A.M. Kuchling. Greg's project
proposal[2] is available online, and summaries[3] of all of the accepted
proposals for Python are on the Python Wiki.

[1] http://code.google.com/summerofcode.html
[2] http://gkj.freeshell.org/summer_of_code/
[3] http://wiki.python.org/moin/SummerOfCode

--- NEW FILE: libmailbox.tex ---
\section{\module{mailbox} ---
          Manipulate mailboxes in various formats}

\declaremodule{}{mailbox}
\moduleauthor{Gregory K.~Johnson}{gkj at gregorykjohnson.com}
\sectionauthor{Gregory K.~Johnson}{gkj at gregorykjohnson.com}
\modulesynopsis{Manipulate mailboxes in various formats}


The \module{mailbox} module defines objects for accessing and manipulating
Maildir, mbox, MH, Babyl, and MMDF mailboxes and the messages they contain.
(These formats are commonly used on \UNIX{} to store email messages on disk.)

\class{Mailbox} and \class{Message} are the two main classes offered by the
module. \class{Mailbox} offers a dictionary-like mapping from keys to
messages. \class{Message} extends the \module{email.Message} module's
\class{Message} class with format-specific state and behavior. Both
\class{Mailbox} and \class{Message} are extended by format-specific subclasses
and are generally not instantiated directly.

A \class{Mailbox} instance's keys are immutable objects, issued by the
\class{Mailbox} instance, that are used to select messages from it. They
remain meaningful for the life of the \class{Mailbox} instance, even if the
mailbox is modified. Each time the value corresponding to a key is requested,
a new message representation is created. Typically, messages are representated
as \class{Message} instances, but a custom factory function may be specified.
A message representation is independent of the particular \class{Mailbox}
instance that created it (if any). For message modifications to be reflected
in a mailbox, the modified message representation must be explicitly assigned
back into the \class{Mailbox} instance's mapping.


\begin{seealso}
    \seemodule{email}{Represent and manipulate messages.}
    \seemodule{poplib}{Access mail via POP3.}
    \seemodule{imaplib}{Access mail via IMAP4.}
    \seemodule{smtplib}{Transfer mail via SMTP.}
\end{seealso}


\subsection{\class{Mailbox} objects}
\label{mailbox-objects}

The \class{Mailbox} interface is dictionary-like, with small keys
corresponding to messages. Keys are issued by the \class{Mailbox} instance
with which they will be used and are only meaningful to that \class{Mailbox}
instance. (\strong{Implementation note:} \class{mbox}, \class{MH},
\class{Babyl}, and \class{MMDF} instances use integers as keys, and
\class{Maildir} instances uses short strings.) A key continues to identify a
message even if the corresponding message is modified by replacing it with
another message. Because keys are issued by a \class{Mailbox} instance rather
than being chosen, the conventional method for adding an item to a mapping
(assigning a value to a new key) cannot be used. Instead, messages may be
added to a \class{Mailbox} instance using the set-like method \method{add()}.
For uniformity, \method{remove()} and \method{discard()} are also available.

\class{Mailbox} semantics differ from dictionary semantics in important ways.
Each time a message is requested, a new message representation (typically a
\class{Message} instance) is generated based upon the current state of the
underlying message. Similarly, when a message representation is assigned into
a \class{Mailbox} instance's mapping, the message representation's contents
are copied into the mailbox. In neither case is a reference to the message
representation kept by the \class{Mailbox} instance.

Also unlike dictionaries, the default \class{Mailbox} iterator iterates over
message representations, not keys. Moreover, modification of a mailbox during
iteration is safe and well-defined. Messages added to the mailbox after an
iterator is created will not be seen by the iterator, and messages removed
from the mailbox before the iterator yields them will be silently skipped. All
three kinds of iterator---key, value, and item---have this behavior.

\class{Mailbox} itself is not intended to be instantiated. Rather, it is
intended to define an interface and to be inherited from by format-specific
subclasses. You may directly instantiate a subclass, or alternatively you may
use the module-level \function{open()} function to instantiate the appropriate
subclass.

\begin{funcdesc}{open}{path\optional{, format, factory}}
Instantiate and return an instance of the appropriate \class{Mailbox} subclass
for the mailbox at \var{path}. The mailbox is created if it does not already
exist.
    
If \var{format} is specified, it should be one of "Maildir", "mbox", "MH",
"Babyl", or "MMDF" (case insensitive). If \var{format} is not specified, then
the format of the mailbox will be automatically detected. Automatic detection
involves inspecting the mailbox at \var{path} if such a mailbox exists or if
no such mailbox exists inspecting \var{path} itself and assuming Maildir
format if \var{path} ends with the system's path separator (e.g., "/" or
"\textbackslash") or mbox format otherwise.

Parameter \var{factory} is a callable object that accepts a file-like object
containing a raw message as its parameter and returns a message
representation. If \var{factory} is not specified, \class{Message} instances
are used to represent messages.

For historic reasons, some subclasses of \class{Mailbox} take instantiation
arguments with different purposes, names, or default values. The
\function{open()} function is intended to present a convenient, uniform
interface for \class{Mailbox} instantiation while maintaining backward
compatibility.
\end{funcdesc}

\class{Mailbox} instances have the following methods:

\begin{methoddesc}[Mailbox]{add}{message}
Add \var{message} to the mailbox and return the key that has been assigned to
it.

Parameter \var{message} may be a \class{Message} instance, an
\class{email.Message.Message} instance, a string, or a file-like object. If
\var{message} is an instance of the appropriate format-specific
\class{Message} subclass (e.g., if it's an \class{mboxMessage} instance and
this is an \class{mbox} instance), its format-specific information will be
used. Otherwise, reasonable defaults for format-specific information will be
used.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{remove}{key}
Delete the message corresponding to \var{key} from the mailbox. Raise a
\exception{KeyError} exception if no such message exists.

The behavior of \method{discard()} may be preferred to that of
\method{remove()} if the underlying mailbox format supports concurrent
modification by other processes, as is the case for Maildir.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{discard}{key}
Delete the message corresponding to \var{key} from the mailbox, or do nothing
if no such message exists.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{iterkeys}{}
Return an iterator over all keys.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{keys}{}
Return a list of all keys.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{itervalues}{}
Return an iterator over representations of all messages. The messages are
represented as \class{Message} instances unless a custom message factory was
specified when the \class{Mailbox} instance was initialized.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{values}{}
Return a list of representations of all messages. The messages are represented
as \class{Message} instances unless a custom message factory was specified
when the \class{Mailbox} instance was initialized. \warning{This may require a
large amount of memory.}
\end{methoddesc}

\begin{methoddesc}[Mailbox]{iteritems}{}
Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is a
key and \var{message} is a message representation. The messages are
represented as \class{Message} instances unless a custom message factory was
specified when the \class{Mailbox} instance was initialized.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{items}{}
Return a list of (\var{key}, \var{message}) pairs, where \var{key} is a key
and \var{message} is a message representation. The messages are represented as
\class{Message} instances unless a custom message factory was specified when
the \class{Mailbox} instance was initialized. \warning{This may require a
large amount of memory.}
\end{methoddesc}

\begin{methoddesc}[Mailbox]{get}{key\optional{, default=None}}
Return a representation of the message corresponding to \var{key}, or
\var{default} if no such message exists. The message is represented as a
\class{Message} instance unless a custom message factory was specified when
the \class{Mailbox} instance was initialized.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{get_message}{key\optional{, default=None}}
Return a \class{Message} representation of the message corresponding to
\var{key}, or \var{default} if no such message exists.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{get_string}{key\optional{, default=None}}
Return a string representation of the message corresponding to \var{key}, or
\var{default} if no such message exists.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{get_file}{key\optional{, default=None}}
Return a file-like representation of the message corresponding to \var{key},
or \var{default} if no such message exists.

\note{Unlike other representations of messages, file-like representations are
not independent of the \class{Mailbox} instance that created them or of the
underlying mailbox. If the mailbox is modified, the file-like representation
may become unusable. More specific documentation is provided by each
subclass.}
\end{methoddesc}

\begin{methoddesc}[Mailbox]{has_key}{key}
Return \code{True} if \var{key} corresponds to a message, \code{False}
otherwise.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{__iter__}{}
Synonymous with \method{itervalues()}. \note{This is unlike the default
iteration behavior of dictionaries.}
\end{methoddesc}

\begin{methoddesc}[Mailbox]{__getitem__}{key}
Like \method{get()}, except raises a \exception{KeyError} exception if the
message corresponding to \var{key} does not exist.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{__setitem__}{key, message}
Replace the message corresponding to \var{key} with the message represented by
\var{message}. Raise a \exception{KeyError} exception if no message already
corresponds to the given key.

As with \method{add()}, parameter \var{message} may be a \class{Message}
instance, an \class{email.Message.Message} instance, a string, or a file-like
object. If \var{message} is an instance of the appropriate format-specific
\class{Message} subclass (e.g., if it's an \class{mboxMessage} instance and
this is an \class{mbox} instance), its format-specific information will be
used. Otherwise, reasonable defaults for format-specific information will be
used. 
\end{methoddesc}

\begin{methoddesc}[Mailbox]{__delitem__}{key}
Synonymous with \method{remove()}.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{__contains__}{key}
Synonymous with \method{has_key()}.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{__len__}{}
Return a count of messages in the mailbox.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{clear}{}
Delete all messages from the mailbox.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{pop}{key\optional{, default}}
Return a representation of the message corresponding to \var{key} and delete
the message. If no such message exists, return \var{default} if it was
supplied or if \var{default} was not supplied raise a \exception{KeyError}
exception. The message is represented as a \class{Message} instance unless a
custom message factory was specified when the \class{Mailbox} instance was
initialized.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{popitem}{}
Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a key
and \var{message} is a message representation, and delete the corresponding
message from the mailbox. If the mailbox is empty, raise a
\exception{KeyError} exception. The message is represented as a
\class{Message} instance unless a custom message factory was specified when
the \class{Mailbox} instance was initialized.
\end{methoddesc}

\begin{methoddesc}[Mailbox]{update}{arg}
If \var{arg} is a mailbox-like \var{key}-to-\var{message} mapping or an
iterable of (\var{key}, \var{message}) pairs, update the mailbox so that, for
each given \var{key} and \var{message}, the message corresponding to \var{key}
is set to \var{message} as if by using \method{__setitem__()}. \note{Keyword
arguments are not supported, unlike with dictionaries.}
\end{methoddesc}


\subsubsection{\class{Maildir}}
\label{mailbox-maildir}


\subsubsection{\class{mbox}}
\label{mailbox-mbox}


\subsubsection{\class{MH}}
\label{mailbox-mh}


\subsubsection{\class{Babyl}}
\label{mailbox-babyl}


\subsubsection{\class{MMDF}}
\label{mailbox-mmdf}


\subsection{\class{Message} objects}
\label{mailbox-message-objects}


\subsubsection{\class{MaildirMessage}}
\label{mailbox-maildirmessage}


\subsubsection{\class{mboxMessage}}
\label{mailbox-mboxmessage}


\subsubsection{\class{MHMessage}}
\label{mailbox-mhmessage}


\subsubsection{\class{BabylMessage}}
\label{mailbox-babylmessage}


\subsubsection{\class{MMDFMessage}}
\label{mailbox-mmdfmessage}

\subsection{Deprecated classes}
\label{mailbox-deprecated-classes}

\subsection{Examples}
\label{mailbox-examples}