Repository navigation
imaplib: accept structured arguments so the module handles quoting and encoding #153521
Description
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,
orrangeobjects, 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.
Activity
bitdancer commentedon Jul 11, 2026
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 commentedon Jul 11, 2026
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)sor 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 commentedon Jul 11, 2026
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)xsyntax, and that's a clear path forward if someone wants to do it at some point.gh-153521: Support structured arguments in imaplib commands (GH-153522)
gh-153521: Preserve bytes message sets in imaplib (GH-153907)
pythongh-153521: Preserve bytes message sets in imaplib (pythonGH-153907