Package twisted :: Package protocols :: Module imap4

[frames | no frames]

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