gh-49555: Clarify imaplib modified UTF-7 docs and comments (GH-153485)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst
index da98f1ad6b9bc3be41532bd7f9db0cbee4bcf59f..fad723ba3f4cb6310cb744ae9d966fb9d4bb295c 100644 (file)
--- a/Doc/whatsnew/3.16.rst
+++ b/Doc/whatsnew/3.16.rst
@@ -263,8 +263,9 @@ imaplib
   (Contributed by Przemysław Buczkowski and Serhiy Storchaka in :gh:`89869`.)
 
 * Non-ASCII mailbox names are now automatically encoded as modified UTF-7
-  (:rfc:`3501`, section 5.1.3), so international mailbox names can be passed
-  as ordinary :class:`str`.
+  (:rfc:`3501`, section 5.1.3) in the default mode, so international mailbox
+  names can be passed as ordinary :class:`str` without enabling ``UTF8=ACCEPT``
+  (under which they are sent as UTF-8).
   (Contributed by Serhiy Storchaka in :gh:`49555`.)
 
 * The :meth:`~imaplib.IMAP4.copy`, :meth:`~imaplib.IMAP4.move`,

diff --git a/Lib/imaplib.py b/Lib/imaplib.py
index ed5b528976448a7163df9177a354f25f22a5b87b..538a858b33e8ae3ac5fc6d0dc3433a28f9ec0a87 100644 (file)
--- a/Lib/imaplib.py
+++ b/Lib/imaplib.py
@@ -1623,7 +1623,7 @@ class IMAP4:
         # UTF-7 token -- one that needs no quoting, or an explicitly quoted
         # string -- is passed through unchanged, so that a name obtained as raw
         # bytes from LIST (and decoded as ASCII) round-trips without being
-        # encoded again.  Pass bytes to bypass encoding entirely.
+        # encoded again.  self._encoding is only ever 'ascii' or 'utf-8'.
         if self._encoding != 'ascii':
             return bytes(arg, self._encoding)
         try:
@@ -1639,11 +1639,15 @@ class IMAP4:
         return arg.encode('utf-7-imap')
 
     def _mailbox(self, arg):
+        # A str name is encoded for the wire; pass bytes to send the name
+        # verbatim, bypassing encoding entirely.
         if isinstance(arg, str):
             arg = self._encode_mailbox(arg, _non_astring_char)
         return self._astring(arg)
 
     def _list_mailbox(self, arg):
+        # As _mailbox(), but for a LIST/LSUB pattern; pass bytes to bypass
+        # encoding.
         if isinstance(arg, str):
             arg = self._encode_mailbox(arg, _non_list_char)
         if _quoted.fullmatch(arg):

diff --git a/Misc/NEWS.d/next/Library/2026-07-09-12-00-00.gh-issue-49555.Ka9Lm2.rst b/Misc/NEWS.d/next/Library/2026-07-09-12-00-00.gh-issue-49555.Ka9Lm2.rst
index 87236e98a079015a9facf2ca8d05c0a0308f997a..56860e53db88627a525486276aa262c878621195 100644 (file)
--- a/Misc/NEWS.d/next/Library/2026-07-09-12-00-00.gh-issue-49555.Ka9Lm2.rst
+++ b/Misc/NEWS.d/next/Library/2026-07-09-12-00-00.gh-issue-49555.Ka9Lm2.rst
@@ -1,4 +1,7 @@
 :mod:`imaplib` now encodes non-ASCII mailbox names as modified UTF-7
-(:rfc:`3501`, section 5.1.3), so international mailbox names can be passed as
-ordinary :class:`str`.  A ``str`` that is already valid modified UTF-7, or a
-:class:`bytes` object, is sent unchanged.
+(:rfc:`3501`, section 5.1.3) in the default mode, so international mailbox
+names can be passed as ordinary :class:`str`; under ``UTF8=ACCEPT`` they are
+sent as UTF-8 instead.  A name that is not valid modified UTF-7, such as one
+with a bare ``&``, is now encoded correctly instead of being sent as is.
+A ``str`` that is already valid modified UTF-7, or a :class:`bytes` object,
+is sent unchanged.