imaplib: add a uid keyword to command methods with a UID variant

[serhiy-storchaka]

Feature or enhancement

Several IMAP4 commands have a UID variant (UID COPY, UID MOVE, UID FETCH,
UID STORE, UID SEARCH, UID SORT, UID THREAD, UID EXPUNGE), selecting
messages by UID rather than sequence number.

Currently the only way to issue them from imaplib is the generic
IMAP4.uid method, which takes the command name as a string:

M.uid('FETCH', message_set, '(FLAGS)')
M.uid('STORE', message_set, '+FLAGS', r'(\Deleted)')

This is inconvenient: the arguments are the same as the regular method, but they
must be passed positionally after a command-name string, and the return value of
uid() is not always the same as the corresponding method (e.g. uid('COPY')
returns the untagged FETCH responses rather than the tagged completion text).

Proposal: add a keyword-only uid=False parameter to the command methods that
have a UID variant, so that

M.fetch(message_set, '(FLAGS)', uid=True)

is equivalent to M.uid('FETCH', ...).

Affected methods: copy, move, fetch, store, search, sort, thread
and expunge. UID EXPUNGE (RFC 4315) takes a message set, so expunge()
also gains an optional message_set argument, required when uid=True.

uid() stays for extension commands and forward compatibility.

Linked PRs

• gh-153502: Add uid parameter to imaplib command methods #153508