[3.14] gh-71086: Document negative offset support in struct.pack_into() and unpack_fr...

(cherry picked from commit 1706d14a2a1f009f786b8d7599e53c168b0392e0)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index f504f931f0fa20a9a0e44ee2d512b8e41903994e..f4fdff951661b6d61b58b51d91ec744c23b7004c 100644 (file)
--- a/Doc/library/struct.rst
+++ b/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)

diff --git a/Modules/_struct.c b/Modules/_struct.c
index d14ad25c1a450bd8a779f9e8b577ee52e6fd66f4..efeebb98e4b34dd64710cbccde57d75fbdd6a134 100644 (file)
--- a/Modules/_struct.c
+++ b/Modules/_struct.c
@@ -1960,7 +1960,8 @@ Return a tuple containing unpacked values.
 Values are unpacked according to the format string Struct.format.
 
 The buffer's size in bytes, starting at position offset, must be
-at least Struct.size.
+at least Struct.size.  A negative offset counts from the end of the
+buffer.
 
 See help(struct) for more on format strings.
 [clinic start generated code]*/
@@ -1968,7 +1969,7 @@ See help(struct) for more on format strings.
 static PyObject *
 Struct_unpack_from_impl(PyStructObject *self, Py_buffer *buffer,
                         Py_ssize_t offset)
-/*[clinic end generated code: output=57fac875e0977316 input=cafd4851d473c894]*/
+/*[clinic end generated code: output=57fac875e0977316 input=3451f778ed8a5345]*/
 {
     _structmodulestate *state = get_struct_state_structinst(self);
     ENSURE_STRUCT_IS_READY(self);
@@ -2296,8 +2297,9 @@ PyDoc_STRVAR(s_pack_into__doc__,
 \n\
 Pack the values v1, v2, ... according to the format string S.format\n\
 and write the packed bytes into the writable buffer buf starting at\n\
-offset.  Note that the offset is a required argument.  See\n\
-help(struct) for more on format strings.");
+offset.  Note that the offset is a required argument.  A negative\n\
+offset counts from the end of the buffer.  See help(struct) for more\n\
+on format strings.");
 
 static PyObject *
 s_pack_into(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
@@ -2593,8 +2595,8 @@ PyDoc_STRVAR(pack_into_doc,
 \n\
 Pack the values v1, v2, ... according to the format string and write\n\
 the packed bytes into the writable buffer buf starting at offset.  Note\n\
-that the offset is a required argument.  See help(struct) for more\n\
-on format strings.");
+that the offset is a required argument.  A negative offset counts from\n\
+the end of the buffer.  See help(struct) for more on format strings.");
 
 static PyObject *
 pack_into(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
@@ -2648,6 +2650,7 @@ 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).
+A negative offset counts from the end of the buffer.
 
 See help(struct) for more on format strings.
 [clinic start generated code]*/
@@ -2655,7 +2658,7 @@ See help(struct) for more on format strings.
 static PyObject *
 unpack_from_impl(PyObject *module, PyStructObject *s_object,
                  Py_buffer *buffer, Py_ssize_t offset)
-/*[clinic end generated code: output=1042631674c6e0d3 input=6e80a5398e985025]*/
+/*[clinic end generated code: output=1042631674c6e0d3 input=e383ecb97728be2b]*/
 {
     return Struct_unpack_from_impl(s_object, buffer, offset);
 }

diff --git a/Modules/clinic/_struct.c.h b/Modules/clinic/_struct.c.h
index e4eaadb91eb2312730c24023156223d3d33fe2e8..7c5186ebb3e157feabc67358ef94f703cebf4d6e 100644 (file)
--- a/Modules/clinic/_struct.c.h
+++ b/Modules/clinic/_struct.c.h
@@ -117,7 +117,8 @@ PyDoc_STRVAR(Struct_unpack_from__doc__,
 "Values are unpacked according to the format string Struct.format.\n"
 "\n"
 "The buffer\'s size in bytes, starting at position offset, must be\n"
-"at least Struct.size.\n"
+"at least Struct.size.  A negative offset counts from the end of the\n"
+"buffer.\n"
 "\n"
 "See help(struct) for more on format strings.");
 
@@ -331,6 +332,7 @@ PyDoc_STRVAR(unpack_from__doc__,
 "Return a tuple containing values unpacked according to the format string.\n"
 "\n"
 "The buffer\'s size, minus offset, must be at least calcsize(format).\n"
+"A negative offset counts from the end of the buffer.\n"
 "\n"
 "See help(struct) for more on format strings.");
 
@@ -458,4 +460,4 @@ exit:
 
     return return_value;
 }
-/*[clinic end generated code: output=caa7f36443e91cb9 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=000e11080c1bc7ef input=a9049054013a1b77]*/