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

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

Author: serhiy-storchaka

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`,

Lib/imaplib.py

@@ -1623,7 +1623,7 @@ def _encode_mailbox(self, arg, safe):
         # 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 @@ def _encode_mailbox(self, arg, safe):
         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):

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.