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,16 @@ 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')
+        packed = b'\x01\x00\x00\x00\x02\x00\x00\x00'
+        self.assertEqual(s.pack(1, 2), packed)
+        self.assertEqual(s.unpack(packed), (1, 2))
 
     def check_sizeof(self, format_str, number_of_codes):
         # The size of 'PyStructObject'
-        totalsize = support.calcobjsize('2n3P')
+        totalsize = support.calcobjsize('2n3P1?')
         # 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)
@@ -787,14 +792,150 @@ def test_error_propagation(fmt_str):
         test_error_propagation('N')
         test_error_propagation('n')
 
-    def test_struct_subclass_instantiation(self):
+    def test_custom_struct_init(self):
         # Regression test for https://github.com/python/cpython/issues/112358
         class MyStruct(struct.Struct):
-            def __init__(self):
+            def __init__(self, *args, **kwargs):
                 super().__init__('>h')
 
+        my_struct = MyStruct('>h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct(format='>h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+
+        warnmsg = r"Different format arguments for __new__\(\) and __init__\(\) methods of Struct"
+        with self.assertWarnsRegex(FutureWarning, warnmsg):
+            my_struct = MyStruct('<h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(FutureWarning, warnmsg):
+            my_struct = MyStruct(format='<h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+
+        warnmsg = r"Struct\(\) missing required argument 'format' \(pos 1\)"
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg):
+            my_struct = MyStruct()
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg):
+            my_struct = MyStruct(arg='>h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+
+        warnmsg = r"Struct\(\) takes at most 1 argument \(2 given\)"
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg):
+            my_struct = MyStruct('>h', 42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg):
+            my_struct = MyStruct('>h', arg=42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg):
+            my_struct = MyStruct('>h', format=42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg):
+            my_struct = MyStruct(format='>h', arg=42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+
+        warnmsg = r"Invalid 'format' argument for Struct\.__new__\(\): "
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg + '.*must be'):
+            my_struct = MyStruct(42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg + '.*must be'):
+            my_struct = MyStruct(format=42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg + 'bad char'):
+            my_struct = MyStruct('$')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg + 'bad char'):
+            my_struct = MyStruct(format='$')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg + ".*can't encode"):
+            my_struct = MyStruct('\u20ac')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertWarnsRegex(DeprecationWarning, warnmsg + ".*can't encode"):
+            my_struct = MyStruct(format='\u20ac')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+
+    def test_custom_struct_new(self):
+        # New way, no warnings:
+        class MyStruct(struct.Struct):
+            def __new__(cls, *args, **kwargs):
+                return super().__new__(cls, '>h')
+
+        my_struct = MyStruct('>h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct('<h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct(format='<h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
         my_struct = MyStruct()
         self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct(42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct('$')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct('\u20ac')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct('<h', 42)
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+
+    def test_custom_struct_new_and_init(self):
+        # New way, no warnings:
+        class MyStruct(struct.Struct):
+            def __new__(cls, newargs, initargs):
+                return super().__new__(cls, *newargs)
+            def __init__(self, newargs, initargs):
+                if initargs is not None:
+                    super().__init__(*initargs)
+
+        my_struct = MyStruct(('>h',), ('>h',))
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertRaises(TypeError):
+            MyStruct((), ())
+        with self.assertRaises(TypeError):
+            MyStruct(('>h',), ())
+        with self.assertRaises(TypeError):
+            MyStruct((), ('>h',))
+        with self.assertRaises(TypeError):
+            MyStruct((42,), ('>h',))
+        with self.assertRaises(TypeError):
+            with self.assertWarns(FutureWarning):
+                MyStruct(('>h',), (42,))
+        with self.assertRaises(struct.error):
+            MyStruct(('$',), ('>h',))
+        with self.assertRaises(struct.error):
+            with self.assertWarns(FutureWarning):
+                MyStruct(('>h',), ('$',))
+        with self.assertRaises(UnicodeEncodeError):
+            MyStruct(('\u20ac',), ('>h',))
+        with self.assertRaises(UnicodeEncodeError):
+            with self.assertWarns(FutureWarning):
+                MyStruct(('>h',), ('\u20ac',))
+        with self.assertWarns(FutureWarning):
+            my_struct = MyStruct(('>h',), ('<h',))
+        self.assertEqual(my_struct.pack(12345), b'\x39\x30')
+
+    def test_no_custom_struct_new_or_init(self):
+        class MyStruct(struct.Struct):
+            pass
+
+        my_struct = MyStruct('>h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        my_struct = MyStruct(format='>h')
+        self.assertEqual(my_struct.pack(12345), b'\x30\x39')
+        with self.assertRaises(TypeError):
+            MyStruct()
+        with self.assertRaises(TypeError):
+            MyStruct(42)
+        with self.assertRaises(struct.error):
+            MyStruct('$')
+        with self.assertRaises(UnicodeEncodeError):
+            MyStruct('\u20ac')
+        with self.assertRaises(TypeError):
+            MyStruct('>h', 42)
+        with self.assertRaises(TypeError):
+            MyStruct('>h', arg=42)
+        with self.assertRaises(TypeError):
+            MyStruct(arg=42)
+        with self.assertRaises(TypeError):
+            MyStruct('>h', format='>h')
 
     def test_repr(self):
         s = struct.Struct('=i2H')

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

@@ -0,0 +1,3 @@
+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.