gh-143715: deprecate incomplete initialization of struct.Struct()

Doc/deprecations/pending-removal-in-3.20.rst

@@ -1,6 +1,13 @@
 Pending removal in Python 3.20
 ------------------------------
 
+* Calling the ``Struct.__new__()`` without required argument now is
+  deprecated and will be removed in Python 3.20.  Calling
+  :meth:`~object.__init__` method on initialized :class:`~struct.Struct`
+  objects is deprecated and will be removed in Python 3.20.
+
+  (Contributed by Sergey B Kirpichev in :gh:`143715`.)
+
 * The ``__version__``, ``version`` and ``VERSION`` attributes have been
   deprecated in these standard library modules and will be removed in
   Python 3.20. Use :py:data:`sys.version_info` instead.

Doc/whatsnew/3.15.rst

@@ -1527,6 +1527,15 @@ New deprecations
 
     (Contributed by Bénédikt Tran in :gh:`134978`.)
 
+* :mod:`struct`:
+
+  * Calling the ``Struct.__new__()`` without required argument now is
+    deprecated and will be removed in Python 3.20.  Calling
+    :meth:`~object.__init__` method on initialized :class:`~struct.Struct`
+    objects is deprecated and will be removed in Python 3.20.
+
+    (Contributed by Sergey B Kirpichev in :gh:`143715`.)
+
 * ``__version__``
 
   * The ``__version__``, ``version`` and ``VERSION`` attributes have been

Lib/test/test_struct.py

@@ -585,11 +585,13 @@ def test_Struct_reinitialization(self):
         # Struct instance.  This test can be used to detect the leak
         # when running with regrtest -L.
         s = struct.Struct('i')
-        s.__init__('ii')
+        with self.assertWarns(DeprecationWarning):
+            s.__init__('<ii')
+        self.assertEqual(s.format, '<ii')
 
     def check_sizeof(self, format_str, number_of_codes):
         # The size of 'PyStructObject'
-        totalsize = support.calcobjsize('2n3P')
+        totalsize = support.calcobjsize('2n3P?')
         # The size taken up by the 'formatcode' dynamic array
         totalsize += struct.calcsize('P3n0P') * (number_of_codes + 1)
         support.check_sizeof(self, struct.Struct(format_str), totalsize)
@@ -793,8 +795,40 @@ class MyStruct(struct.Struct):
             def __init__(self):
                 super().__init__('>h')
 
+        with self.assertWarns(DeprecationWarning):
+            my_struct = MyStruct()
+        self.assertEqual(my_struct.format, '>h')
+
+        # New way, no warnings:
+        class MyStruct(struct.Struct):
+            def __new__(cls):
+                return super().__new__(cls, '>h')
         my_struct = MyStruct()
-        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        self.assertEqual(my_struct.format, '>h')
+
+        class MyStruct(struct.Struct):
+            def __new__(cls, arg):
+                self = super().__new__(cls, '>h')
+                return self
+
+        my_struct = MyStruct(5)
+        self.assertEqual(my_struct.format, '>h')
+
+        class MyStruct(struct.Struct):
+            def __init__(self, *args, **kwargs):
+                super().__init__('>h')
+
+        with self.assertWarns(DeprecationWarning):
+            my_struct = MyStruct('<h')
+        self.assertEqual(my_struct.format, '>h')
+
+        with self.assertWarns(DeprecationWarning):
+            my_struct = MyStruct(5)
+        self.assertEqual(my_struct.format, '>h')
+
+        with self.assertWarns(DeprecationWarning):
+            my_struct = MyStruct('>h')
+        self.assertEqual(my_struct.format, '>h')
 
     def test_repr(self):
         s = struct.Struct('=i2H')
@@ -827,7 +861,8 @@ def test_endian_table_init_subinterpreters(self):
             self.assertListEqual(list(results), [None] * 5)
 
     def test_operations_on_half_initialized_Struct(self):
-        S = struct.Struct.__new__(struct.Struct)
+        with self.assertWarns(DeprecationWarning):
+            S = struct.Struct.__new__(struct.Struct)
 
         spam = array.array('b', b' ')
         self.assertRaises(RuntimeError, S.iter_unpack, spam)

Misc/NEWS.d/next/Library/2026-01-10-16-23-21.gh-issue-143715.HZrfSA.rst

@@ -0,0 +1,3 @@
+:mod:`struct`: Calling the ``Struct.__new__()`` without required argument now is deprecated.
+Calling :meth:`~object.__init__` method on initialized :class:`~struct.Struct`
+objects is deprecated.  Patch by Sergey B Kirpichev.

Modules/_struct.c

@@ -70,6 +70,7 @@ typedef struct {
     formatcode *s_codes;
     PyObject *s_format;
     PyObject *weakreflist; /* List of weak references */
+    bool init_called;
 } PyStructObject;
 
 #define PyStructObject_CAST(op)     ((PyStructObject *)(op))
@@ -1765,30 +1766,88 @@ prepare_s(PyStructObject *self)
     return -1;
 }
 
+/* This should be moved to s_new() when Struct___init__() will
+   be removed (see gh-143715 and gh-94532). */
+static int
+s_create(PyStructObject *self, PyObject *format)
+{
+    if (PyUnicode_Check(format)) {
+        format = PyUnicode_AsASCIIString(format);
+        if (format == NULL) {
+            return -1;
+        }
+    }
+    else {
+        Py_INCREF(format);
+    }
+    if (!PyBytes_Check(format)) {
+        PyErr_Format(PyExc_TypeError,
+                     "Struct() argument 1 must be a str or bytes object, "
+                     "not %T", format);
+        Py_DECREF(format);
+        return -1;
+    }
+    Py_SETREF(self->s_format, format);
+    if (prepare_s(self)) {
+        return -1;
+    }
+    return 0;
+}
+
 static PyObject *
 s_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 {
-    PyObject *self;
+    PyObject *mod = PyType_GetModuleByDef(type, &_structmodule);
+    _structmodulestate *state = PyModule_GetState(mod);
+    PyStructObject *self;
+    bool implicit_new_call = s_new == PyType_GetSlot(type, Py_tp_new);
+    bool in_subclass = type != (PyTypeObject *)state->PyStructType;
 
     assert(type != NULL);
     allocfunc alloc_func = PyType_GetSlot(type, Py_tp_alloc);
     assert(alloc_func != NULL);
-
-    self = alloc_func(type, 0);
-    if (self != NULL) {
-        PyStructObject *s = (PyStructObject*)self;
-        s->s_format = Py_NewRef(Py_None);
-        s->s_codes = NULL;
-        s->s_size = -1;
-        s->s_len = -1;
+    self = (PyStructObject *)alloc_func(type, 0);
+    if (self == NULL) {
+        return NULL;
     }
-    return self;
+    self->s_format = Py_None;
+    self->s_codes = NULL;
+    self->s_size = -1;
+    self->s_len = -1;
+    self->init_called = false;
+    if (PyTuple_GET_SIZE(args) != 1) {
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                         "Struct.__new__() has one positional argument", 1)) {
+            goto err;
+        }
+    }
+    else {
+        if (implicit_new_call && in_subclass) {
+            if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                             ("Creation of half-initialized Struct() objects"
+                              " is deprecated, use Struct.__new__(cls, format)"), 1))
+            {
+                goto err;
+            }
+        }
+        else {
+            PyObject *format = PyTuple_GET_ITEM(args, 0);
+            if (s_create(self, format)) {
+                goto err;
+            }
+        }
+    }
+    return (PyObject *)self;
+err:
+    Py_DECREF(self);
+    return NULL;
 }
 
 /*[clinic input]
+@text_signature "(format)"
 Struct.__init__
 
-    format: object
+    format: object = NULL
 
 Create a compiled struct object.
 
@@ -1798,32 +1857,33 @@ to the format string.  See help(struct) for more on format strings.
 
 static int
 Struct___init___impl(PyStructObject *self, PyObject *format)
-/*[clinic end generated code: output=b8e80862444e92d0 input=1af78a5f57d82cec]*/
+/*[clinic end generated code: output=b8e80862444e92d0 input=dcf0b5a00eb0dbd9]*/
 {
-    int ret = 0;
+    bool explicit_init_call = (Struct___init__
+                               != PyType_GetSlot(Py_TYPE(self), Py_tp_init));
 
-    if (PyUnicode_Check(format)) {
-        format = PyUnicode_AsASCIIString(format);
-        if (format == NULL)
+    if (!format && !self->s_codes) {
+        PyErr_SetString(PyExc_TypeError,
+                        "Struct() missing required argument 'format' (pos 1)");
+        return -1;
+    }
+    if (self->init_called) {
+        if (self->s_codes
+            && PyErr_WarnEx(PyExc_DeprecationWarning,
+                            ("Explicit call of __init__() on "
+                             "initialized Struct() is deprecated"), 1))
+        {
             return -1;
+        }
+        return s_create(self, format);
     }
     else {
-        Py_INCREF(format);
-    }
-
-    if (!PyBytes_Check(format)) {
-        Py_DECREF(format);
-        PyErr_Format(PyExc_TypeError,
-                     "Struct() argument 1 must be a str or bytes object, "
-                     "not %.200s",
-                     _PyType_Name(Py_TYPE(format)));
-        return -1;
+        if (explicit_init_call && s_create(self, format)) {
+            return -1;
+        }
+        self->init_called = true;
+        return 0;
     }
-
-    Py_SETREF(self->s_format, format);
-
-    ret = prepare_s(self);
-    return ret;
 }
 
 static int
@@ -2438,9 +2498,7 @@ static PyType_Slot PyStructType_slots[] = {
     {Py_tp_members, s_members},
     {Py_tp_getset, s_getsetlist},
     {Py_tp_init, Struct___init__},
-    {Py_tp_alloc, PyType_GenericAlloc},
     {Py_tp_new, s_new},
-    {Py_tp_free, PyObject_GC_Del},
     {0, 0},
 };