Module t.m.imap4

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 )

The disjunction of two or more queries

The negation of a query

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

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 )

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.

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	(type: str )

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 )

Encode the given unicode string using the IMAP4 specific variation of UTF-7.

Parameters	s	The text to encode. (type: unicode )
	errors	Policy for handling encoding errors. Currently ignored.
Returns	tuple of a str giving the encoded bytes and an int giving the number of code units consumed from the input.

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.