twisted.mail.imap4

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.

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']]

Decode the given str using the IMAP4 specific variation of UTF-7.

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

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.

Undocumented

Undocumented

Undocumented

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.

Undocumented

Undocumented

The negation of a query

The disjunction of two or more queries

Undocumented

Parse a message set search key into a MessageSet.

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

Undocumented

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

Undocumented

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.

Undocumented

Undocumented

Undocumented

Undocumented