twisted.mail.imap4
module documentationtwisted.mail
View Source
An IMAP4 protocol implementation
Author | Jp 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 | IMAP4Exception | Undocumented |
Class | IllegalClientResponse | Undocumented |
Class | IllegalOperation | Undocumented |
Class | MailboxException | Undocumented |
Class | IllegalMailboxEncoding | Undocumented |
Class | MailboxCollision | Undocumented |
Class | NoSuchMailbox | Undocumented |
Class | ReadOnlyMailbox | Undocumented |
Class | UnhandledResponse | Undocumented |
Class | NegativeResponse | Undocumented |
Class | NoSupportedAuthentication | Undocumented |
Class | IllegalIdentifierError | Undocumented |
Class | IllegalQueryError | Undocumented |
Class | MismatchedNesting | Undocumented |
Class | MismatchedQuoting | Undocumented |
Class | IllegalServerResponse | Undocumented |
Class | MessageSet | A set of message identifiers usable by both IMAP4Client and
IMAP4Server
via IMailboxIMAP.store
and IMailboxIMAP.fetch . |
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 | IMAP4Server | Protocol implementation for an IMAP4rev1 server. |
Class | IMAP4Client | IMAP4 client protocol implementation |
Function | parseIdList | Parse a message set search key into a MessageSet . |
Function | Query | Create a query string |
Function | Or | The disjunction of two or more queries |
Function | Not | The negation of a query |
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. |
Class | MemoryAccountWithoutNamespaces | Undocumented |
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: |
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 | No class docstring; 2/6 methods documented |
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 | _swap | Swap this with that if this is
ifIs . |
Function | _swapAllPairs | Swap each element in each pair in of with that
it is ifIs . |
Function | _quote | Undocumented |
Function | _literal | Undocumented |
Function | _needsQuote | Undocumented |
Function | _parseMbox | 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 |
Swap this
with that
if this
is
ifIs
.
Parameters | this | The object that may be replaced. |
that | The object that may replace this . | |
ifIs | An object whose identity will be compared to this . |
Parse a message set search key into a MessageSet
.
Parameters | s | A string description of an id list, for example "1:3, 4:*" (type: bytes ) |
lastMessageId | The 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 ) | |
Returns | A MessageSet that contains the ids defined in the list (type: MessageSet ) |
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
Parameters | 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. (type: bool ) |
Returns | The formatted query string (type: str ) |
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: bytes ) |
Returns | A list of the resulting tokens (type: list
of bytes ) | |
Raises | MismatchedQuoting | Raised if an odd number of quotes are present |
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 bytes
and list ) |
Returns | A new list which is the collapsed form of results (type: list
of bytes
and list ) |
Parse an s-exp-like string into a more useful data structure.
Parameters | s | The s-exp-like string to parse (type: bytes ) |
Returns | A list containing the tokens present in the input. (type: list
of bytes
and list ) | |
Raises | MismatchedNesting | Raised if the number or placement of opening or closing parenthesis is invalid. |
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 ) |
Construct an appropriate type of message structure object for the given message object.
Parameters | message | A IMessagePart
provider |
Returns | A _MessageStructure
instance of the most specific type available for the given message,
determined by inspecting the MIME type of the message. |
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:
A string giving the content media type name as defined in [MIME-IMB].
A string giving the content subtype name as defined in [MIME-IMB].
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].
A string giving the content id as defined in [MIME-IMB].
A string giving the content description as defined in [MIME-IMB].
A string giving the content transfer encoding as defined in [MIME-IMB].
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:
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.
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 ) |
Decode the given str
using the IMAP4 specific variation of UTF-7.
Parameters | s | The bytes to decode. (type: str ) |
errors | Policy for handling decoding errors. Currently ignored. | |
Returns | a tuple
of a unicode string giving the text which was decoded and an
int
giving the number of bytes consumed from the input. |