gh-153521: Support structured arguments in imaplib commands

[serhiy-storchaka]

imaplib command methods now accept structured arguments, so the module takes care of quoting and the caller no longer has to preformat and quote strings by hand. This matters not only because hand-quoting is error-prone, but because a pre-quoted string cannot represent every value: one containing a newline or NUL, binary data, or a value too large for a single line must be sent as a literal or literal8, which the caller cannot express in a plain string. Owning the value keeps that door open for future literal support.

Two things change:

• A message_set and lists of flags or other atoms can be passed as sequences instead of preformatted parenthesized strings. A message set may be an integer, or a sequence of integers, (start, stop) ranges (with None or '*' meaning the last message) and range objects.

• The search, fetch, sort, thread and uid methods gain a keyword-only params argument that substitutes and quotes ? placeholders in their value-bearing arguments, in the manner of sqlite3 parameter substitution. ?f substitutes a flag or list of flags, ?s a structured message set, and ?? a literal ?. Substitution runs only when params is given, so existing calls that contain a literal ? are unaffected.

Both preformatted strings and the pre-existing behaviour continue to work, so the change is backward compatible.

• Issue: imaplib: accept structured arguments so the module handles quoting and encoding #153521

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33534211 | 📁 Comparing d916684 against main (f96c427)

  🔍 Preview build  

3 files changed

± library/imaplib.html
± whatsnew/3.16.html
± whatsnew/changelog.html