gh-153494: Add What's New entry and clarify the charset docs

Document that str search criteria are encoded to the declared charset only
when a charset is given; under UTF8=ACCEPT the charset is None and criteria
are sent using the connection encoding.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/imaplib.rst

@@ -610,10 +610,12 @@ An :class:`IMAP4` instance has the following methods:
    If *uid* is true, the message numbers in the response are UIDs
    (``UID SEARCH``).
 
-   A criterion passed as :class:`str` is encoded to *charset* (which must name
-   a codec known to Python); pass :class:`bytes` to send a criterion that is
-   already encoded, for example when *charset* is one that Python does not
-   support.
+   A criterion passed as :class:`str` is encoded to *charset*
+   (which must name a codec known to Python);
+   pass :class:`bytes` to send a criterion that is already encoded,
+   for example when *charset* is one that Python does not support.
+   When *charset* is ``None`` (as it must be under ``UTF8=ACCEPT``),
+   the criterion is sent using the connection's encoding instead.
 
    Example::
 
@@ -690,8 +692,9 @@ An :class:`IMAP4` instance has the following methods:
 
    If *uid* is true, the message numbers in the response are UIDs (``UID SORT``).
 
-   As with :meth:`search`, a *search_criterion* passed as :class:`str` is
-   encoded to *charset*; pass :class:`bytes` to send one already encoded.
+   As with :meth:`search`,
+   a *search_criterion* passed as :class:`str` is encoded to *charset*;
+   pass :class:`bytes` to send one already encoded.
 
    This is an ``IMAP4rev1`` extension command.
 
@@ -786,8 +789,9 @@ An :class:`IMAP4` instance has the following methods:
    If *uid* is true, the message numbers in the response are UIDs
    (``UID THREAD``).
 
-   As with :meth:`search`, a *search_criterion* passed as :class:`str` is
-   encoded to *charset*; pass :class:`bytes` to send one already encoded.
+   As with :meth:`search`,
+   a *search_criterion* passed as :class:`str` is encoded to *charset*;
+   pass :class:`bytes` to send one already encoded.
 
    This is an ``IMAP4rev1`` extension command.
 

Doc/whatsnew/3.16.rst

@@ -276,6 +276,14 @@ imaplib
   :meth:`~imaplib.IMAP4.uid`.
   (Contributed by Serhiy Storchaka in :gh:`153502`.)
 
+* :meth:`~imaplib.IMAP4.search`, :meth:`~imaplib.IMAP4.sort`
+  and :meth:`~imaplib.IMAP4.thread` (and the corresponding ``uid`` commands)
+  now encode :class:`str` search criteria to the declared *charset*,
+  so international search text can be passed as an ordinary :class:`str`.
+  When *charset* is ``None`` (as it must be under ``UTF8=ACCEPT``),
+  the criteria are sent using the connection encoding instead.
+  (Contributed by Serhiy Storchaka in :gh:`153494`.)
+
 
 ipaddress
 ---------

Misc/NEWS.d/next/Library/2026-07-10-16-00-00.gh-issue-153494.qCh8rT.rst

@@ -1,6 +1,8 @@
-:meth:`imaplib.IMAP4.search`, :meth:`~imaplib.IMAP4.sort` and
-:meth:`~imaplib.IMAP4.thread` (and the corresponding ``uid`` commands) now
-encode :class:`str` search criteria to the declared *charset*, so
-international search text can be passed as ordinary :class:`str`.  A criterion
-passed as :class:`bytes` is sent unchanged, for use with a charset that Python
-has no codec for.
+:meth:`imaplib.IMAP4.search`, :meth:`~imaplib.IMAP4.sort`
+and :meth:`~imaplib.IMAP4.thread` (and the corresponding ``uid`` commands)
+now encode :class:`str` search criteria to the declared *charset*,
+so international search text can be passed as ordinary :class:`str`.
+When *charset* is ``None`` (as it must be under ``UTF8=ACCEPT``),
+the criteria are sent using the connection encoding instead.
+A criterion passed as :class:`bytes` is sent unchanged,
+for use with a charset that Python has no codec for.