Merge branch 'main' into main

Author: Santhosh-I

Doc/library/struct.rst

@@ -68,6 +68,7 @@ The module defines the following exception and functions:
    Pack the values *v1*, *v2*, ... according to the format string *format* and
    write the packed bytes into the writable buffer *buffer* starting at
    position *offset*.  Note that *offset* is a required argument.
+   A negative *offset* counts from the end of *buffer*.
 
 
 .. function:: unpack(format, buffer)
@@ -84,6 +85,7 @@ The module defines the following exception and functions:
    string *format*.  The result is a tuple even if it contains exactly one
    item.  The buffer's size in bytes, starting at position *offset*, must be at
    least the size required by the format, as reflected by :func:`calcsize`.
+   A negative *offset* counts from the end of *buffer*.
 
 
 .. function:: iter_unpack(format, buffer)

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.

Modules/_struct.c

@@ -2156,14 +2156,14 @@ Return a tuple containing unpacked values.
 
 Values are unpacked according to the struct format string.  The
 buffer's size in bytes, starting at position offset, must be at
-least the struct size.  See help(struct) for more on format
-strings.
+least the struct size.  A negative offset counts from the end of
+the buffer.  See help(struct) for more on format strings.
 [clinic start generated code]*/
 
 static PyObject *
 Struct_unpack_from_impl(PyStructObject *self, Py_buffer *buffer,
                         Py_ssize_t offset)
-/*[clinic end generated code: output=57fac875e0977316 input=57cfcf84c088faa4]*/
+/*[clinic end generated code: output=57fac875e0977316 input=49b7c90dd8faeb97]*/
 {
     _structmodulestate *state = get_struct_state_structinst(self);
     ENSURE_STRUCT_IS_READY(self);
@@ -2497,15 +2497,16 @@ Pack values and write the packed bytes into the buffer.
 
 Pack the provided values according to the struct format string
 and write the packed bytes into the writable buffer starting at
-offset.  Note that the offset is a required argument.  See
-help(struct) for more on format strings.
+offset.  Note that the offset is a required argument.  A negative
+offset counts from the end of the buffer.  See help(struct) for
+more on format strings.
 [clinic start generated code]*/
 
 static PyObject *
 Struct_pack_into_impl(PyStructObject *self, Py_buffer *buffer,
                       Py_ssize_t offset, PyObject * const *values,
                       Py_ssize_t values_length)
-/*[clinic end generated code: output=aa9d9a93f5f8f77b input=9d842a368ee14245]*/
+/*[clinic end generated code: output=aa9d9a93f5f8f77b input=a2b8749e3843f01b]*/
 {
     _structmodulestate *state = get_struct_state_structinst(self);
 
@@ -2735,15 +2736,15 @@ Pack values and write the packed bytes into the buffer.
 
 Pack the provided values according to the format string and write the
 packed bytes into the writable buffer starting at offset.  Note that the
-offset is a required argument.  See help(struct) for more on format
-strings.
+offset is a required argument.  A negative offset counts from the end of
+the buffer.  See help(struct) for more on format strings.
 [clinic start generated code]*/
 
 static PyObject *
 pack_into_impl(PyObject *module, PyStructObject *s_object, Py_buffer *buffer,
                Py_ssize_t offset, PyObject * const *values,
                Py_ssize_t values_length)
-/*[clinic end generated code: output=e8bf7d422b2088ef input=086867c0f5d8a8e4]*/
+/*[clinic end generated code: output=e8bf7d422b2088ef input=548c35c57db7436a]*/
 {
     return Struct_pack_into_impl(s_object, buffer, offset,
                                  values, values_length);
@@ -2781,14 +2782,15 @@ unpack_from
 
 Return a tuple containing values unpacked according to the format string.
 
-The buffer's size, minus offset, must be at least calcsize(format).  See
+The buffer must contain at least calcsize(format) bytes starting at
+offset.  A negative offset counts from the end of the buffer.  See
 help(struct) for more on format strings.
 [clinic start generated code]*/
 
 static PyObject *
 unpack_from_impl(PyObject *module, PyStructObject *s_object,
                  Py_buffer *buffer, Py_ssize_t offset)
-/*[clinic end generated code: output=1042631674c6e0d3 input=3e46619756fb0293]*/
+/*[clinic end generated code: output=1042631674c6e0d3 input=fb755400a7a47a51]*/
 {
     return Struct_unpack_from_impl(s_object, buffer, offset);
 }