imaplib: accept structured arguments so the module handles quoting and encoding

[serhiy-storchaka]

Feature or enhancement

imaplib command methods currently require the caller to preformat and quote
arguments: a message set as a string like '2:4,7', a flag list as
r'(\Deleted \Seen)', and search values pre-quoted like '"John Smith"'.
Quoting and escaping is the caller's responsibility.

The module should do this instead, for two reasons.

Manual quoting is error-prone: the caller has to know IMAP's atom / quoted-string
rules and escape \ and " correctly.

More fundamentally, not every value can be written as a quoted string. A value
that contains a newline or NUL, that is binary, or that is too large for a single
line cannot be quoted at all; IMAP represents such values with a literal ({n})
or literal8 (~{n}). The client can only choose that representation if it
controls serialization. A pre-quoted string forecloses it -- once the user has
wrapped a value in "...", the module can no longer decide to send it as a
literal.

Proposal: accept structured, unquoted values and let imaplib serialize them:

• a message_set as an integer, a sequence of integers, (start, stop) ranges,
  or range objects, instead of a preformatted string;
• flags and other atom lists as sequences instead of a parenthesized string;
• a params= argument that substitutes and quotes ? placeholders in the
  value-bearing arguments, so values are never hand-quoted.

Because the module owns the value in each case, it can choose the correct wire
form -- atom, quoted string, or (in the future) a literal / literal8 selected by
the value's content and size. imaplib does not yet emit literals for parts of
search criteria, but this design leaves room to add it later -- which is
impossible on top of a pre-quoted user string.

The existing string forms keep working.

Linked PRs

• gh-153521: Support structured arguments in imaplib commands #153522

[bitdancer]

While it is true that the substitution mirrors sqlite, it mirrors the "older" substitution syntax. sqlite also supports named arguments and a dictionary of parameters. Have you thought about this? Specifically about whether the syntax you chose will harmonize with adding the capability for named parameters later.

[serhiy-storchaka]

I think that such change would be a small part of the current PR, and can be lost in other changes, so it is better to do this in a follow-up (if there is need). The syntax can be ?(name)s or something like. We can change it at any time before the 3.16 feature freeze. Or we can change it right now -- like you wish.

[bitdancer]

I don't care if we do it now, I just wanted to make sure the syntax didn't make it confusing. I like your ?(name)x syntax, and that's a clear path forward if someone wants to do it at some point.