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
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 asr'(\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 itcontrols 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 aliteral.
Proposal: accept structured, unquoted values and let imaplib serialize them:
(start, stop)ranges,or
rangeobjects, instead of a preformatted string;params=argument that substitutes and quotes?placeholders in thevalue-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