twisted.protocols.imap4

Package twisted :: Package protocols :: Module imap4

Module twisted.protocols.imap4

An IMAP4 protocol implementation

API Stability: Semi-stable

@author: U{Jp Calderone<mailto:exarkun@twistedmatrix.com>}

To do:
  Suspend idle timeout while server is processing
  Use an async message parser instead of buffering in memory
  Figure out a way to not queue multi-message client requests (Flow? A simple callback?)
  Clarify some API docs (Query, etc)
  Make APPEND recognize (again) non-existent mailboxes before accepting the literal

Classes
`_FetchParser`
`Command`
`CramMD5ClientAuthenticator`
`DontQuoteMe`
`FileProducer`
`IAccount`	Interface for Account classes
`IClientAuthentication`
`ICloseableMailbox`	A supplementary interface for mailboxes which require cleanup on close.
`IMailbox`
`IMailboxInfo`	Interface specifying only the methods required for `listMailboxes`.
`IMailboxListener`	Interface for objects interested in mailbox events
`IMAP4Client`	IMAP4 client protocol implementation
`IMAP4Server`	Protocol implementation for an IMAP4rev1 server.
`IMessage`
`IMessageCopier`
`IMessageFile`
`IMessagePart`
`INamespacePresenter`
`ISearchableMailbox`
`LiteralFile`
`LiteralString`
`LOGINAuthenticator`
`LOGINCredentials`
`MemoryAccount`
`MessageProducer`
`MessageSet`	Essentially an infinite bitfield, with some extra features.
`PLAINAuthenticator`
`PLAINCredentials`
`StreamReader`
`StreamWriter`
`WriteBuffer`	Buffer up a bunch of writes before sending them all to a transport at once.

Exceptions
`IllegalClientResponse`
`IllegalIdentifierError`
`IllegalMailboxEncoding`
`IllegalOperation`
`IllegalQueryError`
`IllegalServerResponse`
`IMAP4Exception`
`MailboxCollision`
`MailboxException`
`MismatchedNesting`
`MismatchedQuoting`
`NegativeResponse`
`NoSuchMailbox`
`NoSupportedAuthentication`
`ReadOnlyMailbox`
`UnhandledResponse`

Function Summary
	`_formatHeaders(headers)`
	`_literal(s)`
	`_needsLiteral(s)`
	`_needsQuote(s)`
	`_quote(s)`
`str`	`collapseNestedLists(items)` Turn a nested list structure into an s-exp-like string.
`list` of `str` and `list`	`collapseStrings(results)` Turns a list of length-one strings and lists into a list of longer strings and lists.
	`decoder(s)`
	`encoder(s)`
	`getBodyStructure(msg, extended)`
	`getEnvelope(msg)`
	`getLineCount(msg)`
	`imap4_utf_7(name)`
`Deferred`	`iterateInReactor(i)` Consume an interator at most a single iteration per reactor iteration.
	`modified_base64(s)`
	`modified_unbase64(s)`
	`Not(query)` The negation of a query
	`Or(*args)` The disjunction of two or more queries
	`parseAddr(addr)`
	`parseIdList(s)`
`list` of `str` and `list`	`parseNestedParens(s, handleLiteral)` Parse an s-exp-like string into a more useful data structure.
	`parseTime(s)`
	`Query(sorted, **kwarg)` Create a query string Among the accepted keywords are: all : If set to a true value, search all messages in the current mailbox answered : If set to a true value, search messages flagged with \Answered bcc : A substring to search the BCC header field for before : Search messages with an internal date before this value.
	`splitOn(sequence, predicate, transformers)`
`list` of `str`	`splitQuoted(s)` Split a string into whitespace delimited tokens
	`statusRequestHelper(mbox, names)`
	`subparts(m)`
	`wildcardToRegexp(wildcard, delim)`

Variable Summary
`str`	`_ATOM_SPECIALS` = `'(){ %*"'`
`tuple`	`_NO_QUOTES` = `('LARGER', 'SMALLER', 'UID')`
`tuple`	`_SIMPLE_BOOL` = `('ALL', 'ANSWERED', 'DELETED', 'DRAFT', '...`
`dict`	`_statusRequestDict` = `{'UIDNEXT': 'getUIDNext', 'UIDVALID...`
`xrange`	`infrangeobject` = `xrange(2147483647)`

Function Details

collapseNestedLists(items)

Turn a nested list structure into an s-exp-like string.

Strings in items will be sent as literals if they contain CR or LF, otherwise they will be quoted. References to None in items will be translated to the atom NIL. Objects with a 'read' attribute will have it called on them with no arguments and the returned string will be inserted into the output as a literal. Integers will be converted to strings and inserted into the output unquoted. Instances of DontQuoteMe will be converted to strings and inserted into the output unquoted.

This function used to be much nicer, and only quote things that really needed to be quoted (and DontQuoteMe did not exist), however, many broken IMAP4 clients were unable to deal with this level of sophistication, forcing the current behavior to be adopted for practical reasons.

Parameters:: items
(type=Any iterable)

Returns:: str

collapseStrings(results)

Turns a list of length-one strings and lists into a list of longer strings and lists. For example,

['a', 'b', ['c', 'd']] is returned as ['ab', ['cd']]

Parameters:: results - The list to be collapsed
(type=list of str and list)

Returns:: A new list which is the collapsed form of results
(type=list of str and list)

iterateInReactor(i)

Consume an interator at most a single iteration per reactor iteration.

If the iterator produces a Deferred, the next iteration will not occur until the Deferred fires, otherwise the next iteration will be taken in the next reactor iteration.

Returns:: A deferred which fires (with None) when the iterator is exhausted or whose errback is called if there is an exception.
(type=Deferred)

Not(query)

The negation of a query

Or(*args)

The disjunction of two or more queries

parseNestedParens(s, handleLiteral=1)

Parse an s-exp-like string into a more useful data structure.

Parameters:: s - The s-exp-like string to parse
(type=str)

Returns:: A list containing the tokens present in the input.
(type=list of str and list)

Raises:: MismatchedNesting - Raised if the number or placement of opening or closing parenthesis is invalid.

Query(sorted=0, **kwarg)

Create a query string

Among the accepted keywords are:

    all         : If set to a true value, search all messages in the
                  current mailbox

    answered    : If set to a true value, search messages flagged with
                  \Answered

    bcc         : A substring to search the BCC header field for

    before      : Search messages with an internal date before this
                  value.  The given date should be a string in the format
                  of 'DD-Mon-YYYY'.  For example, '03-Mar-2003'.

    body        : A substring to search the body of the messages for

    cc          : A substring to search the CC header field for

    deleted     : If set to a true value, search messages flagged with
                  \Deleted

    draft       : If set to a true value, search messages flagged with
                  \Draft

    flagged     : If set to a true value, search messages flagged with
                  \Flagged

    from        : A substring to search the From header field for

    header      : A two-tuple of a header name and substring to search
                  for in that header

    keyword     : Search for messages with the given keyword set

    larger      : Search for messages larger than this number of octets

    messages    : Search only the given message sequence set.

    new         : If set to a true value, search messages flagged with
                  \Recent but not \Seen

    old         : If set to a true value, search messages not flagged with
                  \Recent

    on          : Search messages with an internal date which is on this
                  date.  The given date should be a string in the format
                  of 'DD-Mon-YYYY'.  For example, '03-Mar-2003'.

    recent      : If set to a true value, search for messages flagged with
                  \Recent

    seen        : If set to a true value, search for messages flagged with
                  \Seen

    sentbefore  : Search for messages with an RFC822 'Date' header before
                  this date.  The given date should be a string in the format
                  of 'DD-Mon-YYYY'.  For example, '03-Mar-2003'.

    senton      : Search for messages with an RFC822 'Date' header which is
                  on this date  The given date should be a string in the format
                  of 'DD-Mon-YYYY'.  For example, '03-Mar-2003'.

    sentsince   : Search for messages with an RFC822 'Date' header which is
                  after this date.  The given date should be a string in the format
                  of 'DD-Mon-YYYY'.  For example, '03-Mar-2003'.

    since       : Search for messages with an internal date that is after
                  this date..  The given date should be a string in the format
                  of 'DD-Mon-YYYY'.  For example, '03-Mar-2003'.

    smaller     : Search for messages smaller than this number of octets

    subject     : A substring to search the 'subject' header for

    text        : A substring to search the entire message for

    to          : A substring to search the 'to' header for

    uid         : Search only the messages in the given message set

    unanswered  : If set to a true value, search for messages not
                  flagged with \Answered

    undeleted   : If set to a true value, search for messages not
                  flagged with \Deleted

    undraft     : If set to a true value, search for messages not
                  flagged with \Draft

    unflagged   : If set to a true value, search for messages not
                  flagged with \Flagged

    unkeyword   : Search for messages without the given keyword set

    unseen      : If set to a true value, search for messages not
                  flagged with \Seen

@type sorted: C{bool}
@param sorted: If true, the output will be sorted, alphabetically.
The standard does not require it, but it makes testing this function
easier.  The default is zero, and this should be acceptable for any
application.

@rtype: C{str}
@return: The formatted query string

splitQuoted(s)

Split a string into whitespace delimited tokens

Tokens that would otherwise be separated but are surrounded by " remain as a single token. Any token that is not quoted and is equal to "NIL" is tokenized as None.

Parameters:: s - The string to be split
(type=str)

Returns:: A list of the resulting tokens
(type=list of str)

Raises:: MismatchedQuoting - Raised if an odd number of quotes are present

Variable Details

_ATOM_SPECIALS

Type:: str
Value:: '(){ %*"'

_NO_QUOTES

Type:: tuple
Value:: ('LARGER', 'SMALLER', 'UID')

_SIMPLE_BOOL

Type:: tuple
Value:: ('ALL', 'ANSWERED', 'DELETED', 'DRAFT', 'FLAGGED', 'NEW', 'OLD', 'RECENT', ...

_statusRequestDict

Type:: dict
Value:: {'MESSAGES': 'getMessageCount', 'RECENT': 'getRecentCount', 'UIDNEXT': 'getUIDNext', 'UIDVALIDITY': 'getUIDValidity', 'UNSEEN': 'getUnseenCount'}

infrangeobject

Type:: xrange
Value:: xrange(2147483647)

Generated by Epydoc 2.0 on Sat May 15 20:08:54 2004

http://epydoc.sf.net