gh-105733: Deprecate ctypes SetPointerType() and ARRAY() (#105734)

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index e6504b0152acc2f0aca1a57c1d790060008d32ff..97bc1587d5052af8470e9a274ececd3477d71876 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -140,6 +140,12 @@ Deprecated
   Use the ``'w'`` format code instead.
   (contributed by Hugo van Kemenade in :gh:`80480`)
 
+* :mod:`ctypes`: Deprecate undocumented :func:`!ctypes.SetPointerType`
+  and :func:`!ctypes.ARRAY` functions.
+  Replace ``ctypes.SetPointerType(item_type, size)`` with ``item_type * size``.
+  (Contributed by Victor Stinner in :gh:`105733`.)
+
+
 Removed
 =======
 

diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py
index 95353bab26cc71a3ae9a741c51338776c64e77a2..141142a57dcb3e22d406758cab9ec3a8c41d2bd8 100644 (file)
--- a/Lib/ctypes/__init__.py
+++ b/Lib/ctypes/__init__.py
@@ -302,8 +302,9 @@ def create_unicode_buffer(init, size=None):
     raise TypeError(init)
 
 
-# XXX Deprecated
 def SetPointerType(pointer, cls):
+    import warnings
+    warnings._deprecated("ctypes.SetPointerType", remove=(3, 15))
     if _pointer_type_cache.get(cls, None) is not None:
         raise RuntimeError("This type already exists in the cache")
     if id(pointer) not in _pointer_type_cache:
@@ -312,8 +313,9 @@ def SetPointerType(pointer, cls):
     _pointer_type_cache[cls] = pointer
     del _pointer_type_cache[id(pointer)]
 
-# XXX Deprecated
 def ARRAY(typ, len):
+    import warnings
+    warnings._deprecated("ctypes.ARRAY", remove=(3, 15))
     return typ * len
 
 ################################################################

diff --git a/Lib/test/test_ctypes/test_arrays.py b/Lib/test/test_ctypes/test_arrays.py
index 415a5785a9c1bb6a37c419699d2528a4d1908624..473083870ca6e5944ee45527692ba3510b4b2bc5 100644 (file)
--- a/Lib/test/test_ctypes/test_arrays.py
+++ b/Lib/test/test_ctypes/test_arrays.py
@@ -1,7 +1,9 @@
-import unittest
-from test.support import bigmemtest, _2G
+import ctypes
 import sys
+import unittest
+import warnings
 from ctypes import *
+from test.support import bigmemtest, _2G
 
 from test.test_ctypes import need_symbol
 
@@ -10,6 +12,14 @@ formats = "bBhHiIlLqQfd"
 formats = c_byte, c_ubyte, c_short, c_ushort, c_int, c_uint, \
           c_long, c_ulonglong, c_float, c_double, c_longdouble
 
+
+def ARRAY(*args):
+    # ignore DeprecationWarning in tests
+    with warnings.catch_warnings():
+        warnings.simplefilter('ignore', DeprecationWarning)
+        return ctypes.ARRAY(*args)
+
+
 class ArrayTestCase(unittest.TestCase):
     def test_simple(self):
         # create classes holding simple numeric types, and check
@@ -234,5 +244,10 @@ class ArrayTestCase(unittest.TestCase):
     def test_large_array(self, size):
         c_char * size
 
+    def test_deprecation(self):
+        with self.assertWarns(DeprecationWarning):
+            CharArray = ctypes.ARRAY(c_char, 3)
+
+
 if __name__ == '__main__':
     unittest.main()

diff --git a/Lib/test/test_ctypes/test_incomplete.py b/Lib/test/test_ctypes/test_incomplete.py
index 00c430ef53cfa8d3c055aed71d01db5f8c310a16..0b53c15f1f99863bdd79f7922e782aff51b7b767 100644 (file)
--- a/Lib/test/test_ctypes/test_incomplete.py
+++ b/Lib/test/test_ctypes/test_incomplete.py
@@ -1,4 +1,6 @@
+import ctypes
 import unittest
+import warnings
 from ctypes import *
 
 ################################################################
@@ -6,7 +8,11 @@ from ctypes import *
 # The incomplete pointer example from the tutorial
 #
 
-class MyTestCase(unittest.TestCase):
+class TestSetPointerType(unittest.TestCase):
+
+    def tearDown(self):
+        # to not leak references, we must clean _pointer_type_cache
+        ctypes._reset_cache()
 
     def test_incomplete_example(self):
         lpcell = POINTER("cell")
@@ -14,7 +20,9 @@ class MyTestCase(unittest.TestCase):
             _fields_ = [("name", c_char_p),
                         ("next", lpcell)]
 
-        SetPointerType(lpcell, cell)
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore', DeprecationWarning)
+            ctypes.SetPointerType(lpcell, cell)
 
         c1 = cell()
         c1.name = b"foo"
@@ -32,9 +40,14 @@ class MyTestCase(unittest.TestCase):
             p = p.next[0]
         self.assertEqual(result, [b"foo", b"bar"] * 4)
 
-        # to not leak references, we must clean _pointer_type_cache
-        from ctypes import _pointer_type_cache
-        del _pointer_type_cache[cell]
+    def test_deprecation(self):
+        lpcell = POINTER("cell")
+        class cell(Structure):
+            _fields_ = [("name", c_char_p),
+                        ("next", lpcell)]
+
+        with self.assertWarns(DeprecationWarning):
+            ctypes.SetPointerType(lpcell, cell)
 
 ################################################################
 

diff --git a/Misc/NEWS.d/next/Library/2023-06-13-19-38-12.gh-issue-105733.WOp0mG.rst b/Misc/NEWS.d/next/Library/2023-06-13-19-38-12.gh-issue-105733.WOp0mG.rst
new file mode 100644 (file)
index 0000000..20f2ba2
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2023-06-13-19-38-12.gh-issue-105733.WOp0mG.rst
@@ -0,0 +1,2 @@
+:mod:`ctypes`: Deprecate undocumented :func:`!ctypes.SetPointerType` and
+:func:`!ctypes.ARRAY` functions. Patch by Victor Stinner.