t.m.imap4 : module documentation

Part of twisted.mail View Source

An IMAP4 protocol implementation
AuthorJp Calderone

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
Class MessageSet Essentially an infinite bitfield, with some extra features.
Class LiteralString No class docstring; 1/3 methods documented
Class LiteralFile No class docstring; 1/3 methods documented
Class WriteBuffer Buffer up a bunch of writes before sending them all to a transport at once.
Class Command Undocumented
Class LOGINCredentials Undocumented
Class PLAINCredentials Undocumented
Class IMAP4Exception Undocumented
Class IllegalClientResponse Undocumented
Class IllegalOperation Undocumented
Class IllegalMailboxEncoding Undocumented
Interface IMailboxListener Interface for objects interested in mailbox events
Class IMAP4Server Protocol implementation for an IMAP4rev1 server.
Class UnhandledResponse Undocumented
Class NegativeResponse Undocumented
Class NoSupportedAuthentication Undocumented
Class IllegalServerResponse Undocumented
Class IMAP4Client IMAP4 client protocol implementation
Class IllegalIdentifierError Undocumented
Function parseIdList Parse a message set search key into a MessageSet.
Class IllegalQueryError Undocumented
Function Query Create a query string
Function Or The disjunction of two or more queries
Function Not The negation of a query
Class MismatchedNesting Undocumented
Class MismatchedQuoting Undocumented
Function wildcardToRegexp Undocumented
Function splitQuoted Split a string into whitespace delimited tokens
Function splitOn Undocumented
Function collapseStrings Turns a list of length-one strings and lists into a list of longer strings and lists. For example,
Function parseNestedParens Parse an s-exp-like string into a more useful data structure.
Class DontQuoteMe Undocumented
Function collapseNestedLists Turn a nested list structure into an s-exp-like string.
Interface IClientAuthentication No interface docstring; 2/2 methods documented
Class CramMD5ClientAuthenticator Undocumented
Class LOGINAuthenticator Undocumented
Class PLAINAuthenticator Undocumented
Class MailboxException Undocumented
Class MailboxCollision Undocumented
Class NoSuchMailbox Undocumented
Class ReadOnlyMailbox Undocumented
Interface IAccount Interface for Account classes
Interface INamespacePresenter No interface docstring; 3/3 methods documented
Class MemoryAccount Undocumented
Function statusRequestHelper Undocumented
Function parseAddr Undocumented
Function getEnvelope Undocumented
Function getLineCount Undocumented
Function unquote Undocumented
Function getBodyStructure

RFC 3501, 7.4.2, BODYSTRUCTURE:
Interface IMessagePart No interface docstring; 5/5 methods documented
Interface IMessage No interface docstring; 3/3 methods documented
Interface IMessageFile Optional message interface for representing messages as files.
Interface ISearchableMailbox No interface docstring; 1/1 methods documented
Interface IMessageCopier No interface docstring; 1/1 methods documented
Interface IMailboxInfo Interface specifying only the methods required for listMailboxes.
Interface IMailbox No interface docstring; 15/15 methods documented
Interface ICloseableMailbox A supplementary interface for mailboxes which require cleanup on close.
Function subparts Undocumented
Function iterateInReactor Consume an interator at most a single iteration per reactor iteration.
Class MessageProducer No class docstring; 1/3 methods documented
Class FileProducer Undocumented
Function parseTime Undocumented
Function modified_base64 Undocumented
Function modified_unbase64 Undocumented
Function encoder Encode the given unicode string using the IMAP4 specific variation of UTF-7.
Function decoder Decode the given str using the IMAP4 specific variation of UTF-7.
Class StreamReader Undocumented
Class StreamWriter Undocumented
Function imap4_utf_7 Undocumented
Function _quote Undocumented
Function _literal Undocumented
Function _needsQuote Undocumented
Function _prepareMailboxName Undocumented
Function _needsLiteral Undocumented
Function _getContentType Return a two-tuple of the main and subtype of the given message.
Function _getMessageStructure Construct an appropriate type of message structure object for the given message object.
Class _MessageStructure _MessageStructure is a helper base class for message structure classes representing the structure of particular kinds of messages, as defined by their MIME type.
Class _SinglepartMessageStructure _SinglepartMessageStructure represents the message structure of a non-multipart/* message.
Class _TextMessageStructure _TextMessageStructure represents the message structure of a text/* message.
Class _RFC822MessageStructure _RFC822MessageStructure represents the message structure of a message/rfc822 message.
Class _MultipartMessageStructure _MultipartMessageStructure represents the message structure of a multipart/* message.
Function _formatHeaders Undocumented
Class _FetchParser Undocumented
def parseIdList(s, lastMessageId=None): (source)
Parse a message set search key into a MessageSet.
ParameterssA string description of a id list, for example "1:3, 4:*" (type: str)
lastMessageIdThe last message sequence id or UID, depending on whether we are parsing the list in UID or sequence id context. The caller should pass in the correct value. (type: int)
ReturnsA MessageSet that contains the ids defined in the list (type: MessageSet)
def Query(sorted=0, **kwarg): (source)

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
ParameterssortedIf 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. (type: bool)
ReturnsThe formatted query string (type: str)
def Or(*args): (source)
The disjunction of two or more queries
def Not(query): (source)
The negation of a query
def wildcardToRegexp(wildcard, delim=None): (source)
Undocumented
def splitQuoted(s): (source)
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.

ParameterssThe string to be split (type: str)
ReturnsA list of the resulting tokens (type: list of str)
RaisesMismatchedQuotingRaised if an odd number of quotes are present
def splitOn(sequence, predicate, transformers): (source)
Undocumented
def collapseStrings(results): (source)
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']]

ParametersresultsThe list to be collapsed (type: list of str and list)
ReturnsA new list which is the collapsed form of results (type: list of str and list)
def parseNestedParens(s, handleLiteral=1): (source)
Parse an s-exp-like string into a more useful data structure.
ParameterssThe s-exp-like string to parse (type: str)
ReturnsA list containing the tokens present in the input. (type: list of str and list)
RaisesMismatchedNestingRaised if the number or placement of opening or closing parenthesis is invalid.
def _quote(s): (source)
Undocumented
def _literal(s): (source)
Undocumented
def _needsQuote(s): (source)
Undocumented
def _prepareMailboxName(name): (source)
Undocumented
def _needsLiteral(s): (source)
Undocumented
def collapseNestedLists(items): (source)
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.

Returns (type: str)
def statusRequestHelper(mbox, names): (source)
Undocumented
def parseAddr(addr): (source)
Undocumented
def getEnvelope(msg): (source)
Undocumented
def getLineCount(msg): (source)
Undocumented
def unquote(s): (source)
Undocumented
def _getContentType(msg): (source)
Return a two-tuple of the main and subtype of the given message.
def _getMessageStructure(message): (source)
Construct an appropriate type of message structure object for the given message object.
ParametersmessageA IMessagePart provider
ReturnsA _MessageStructure instance of the most specific type available for the given message, determined by inspecting the MIME type of the message.
def getBodyStructure(msg, extended=False): (source)
RFC 3501, 7.4.2, BODYSTRUCTURE:

 A parenthesized list that describes the [MIME-IMB] body structure of a
 message.  This is computed by the server by parsing the [MIME-IMB] header
 fields, defaulting various fields as necessary.

   For example, a simple text message of 48 lines and 2279 octets can have
   a body structure of: ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL
   "7BIT" 2279 48)

This is represented as:

   ["TEXT", "PLAIN", ["CHARSET", "US-ASCII"], None, None, "7BIT", 2279, 48]

These basic fields are documented in the RFC as:

  1. body type

    A string giving the content media type name as defined in [MIME-IMB].

  2. body subtype

    A string giving the content subtype name as defined in [MIME-IMB].

  3. body parameter parenthesized list

    A parenthesized list of attribute/value pairs [e.g., ("foo" "bar" "baz" "rag") where "bar" is the value of "foo" and "rag" is the value of "baz"] as defined in [MIME-IMB].

  4. body id

    A string giving the content id as defined in [MIME-IMB].

  5. body description

    A string giving the content description as defined in [MIME-IMB].

  6. body encoding

    A string giving the content transfer encoding as defined in [MIME-IMB].

  7. body size

    A number giving the size of the body in octets. Note that this size is the size in its transfer encoding and not the resulting size after any decoding.

Put another way, the body structure is a list of seven elements. The semantics of the elements of this list are:

  1. Byte string giving the major MIME type
  2. Byte string giving the minor MIME type
  3. A list giving the Content-Type parameters of the message
  4. A byte string giving the content identifier for the message part, or None if it has no content identifier.
  5. A byte string giving the content description for the message part, or None if it has no content description.
  6. A byte string giving the Content-Encoding of the message body
  7. An integer giving the number of octets in the message body

The RFC goes on:

   Multiple parts are indicated by parenthesis nesting.  Instead of a body
   type as the first element of the parenthesized list, there is a sequence
   of one or more nested body structures.  The second element of the
   parenthesized list is the multipart subtype (mixed, digest, parallel,
   alternative, etc.).

   For example, a two part message consisting of a text and a
   BASE64-encoded text attachment can have a body structure of: (("TEXT"
   "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 23)("TEXT" "PLAIN"
   ("CHARSET" "US-ASCII" "NAME" "cc.diff")
   "<960723163407.20117h@cac.washington.edu>" "Compiler diff" "BASE64" 4554
   73) "MIXED")

This is represented as:

   [["TEXT", "PLAIN", ["CHARSET", "US-ASCII"], None, None, "7BIT", 1152,
     23],
    ["TEXT", "PLAIN", ["CHARSET", "US-ASCII", "NAME", "cc.diff"],
     "<960723163407.20117h@cac.washington.edu>", "Compiler diff",
     "BASE64", 4554, 73],
    "MIXED"]

In other words, a list of N + 1 elements, where N is the number of parts in the message. The first N elements are structures as defined by the previous section. The last element is the minor MIME subtype of the multipart message.

Additionally, the RFC describes extension data:

   Extension data follows the multipart subtype.  Extension data is never
   returned with the BODY fetch, but can be returned with a BODYSTRUCTURE
   fetch.  Extension data, if present, MUST be in the defined order.

The extended flag controls whether extension data might be returned with the normal data.

def _formatHeaders(headers): (source)
Undocumented
def subparts(m): (source)
Undocumented
def iterateInReactor(i): (source)
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.

ReturnsA deferred which fires (with None) when the iterator is exhausted or whose errback is called if there is an exception. (type: Deferred)
def parseTime(s): (source)
Undocumented
def modified_base64(s): (source)
Undocumented
def modified_unbase64(s): (source)
Undocumented
def encoder(s, errors=None): (source)
Encode the given unicode string using the IMAP4 specific variation of UTF-7.
ParameterssThe text to encode. (type: unicode)
errorsPolicy for handling encoding errors. Currently ignored.
Returnstuple of a str giving the encoded bytes and an int giving the number of code units consumed from the input.
def decoder(s, errors=None): (source)
Decode the given str using the IMAP4 specific variation of UTF-7.
ParameterssThe bytes to decode. (type: str)
errorsPolicy for handling decoding errors. Currently ignored.
Returnsa tuple of a unicode string giving the text which was decoded and an int giving the number of bytes consumed from the input.
def imap4_utf_7(name): (source)
Undocumented
API Documentation for Twisted, generated by pydoctor at 2012-09-01 11:44:56.