[Python-checkins] gh-105733: Deprecate ctypes SetPointerType() and ARRAY() (#105734)

[vstinner]

https://github.com/python/cpython/commit/2211454fe210637ed7fabda12690dac6cc9a8149
commit: 2211454fe210637ed7fabda12690dac6cc9a8149
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2023-06-13T18:16:26Z
summary:

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

files:
A Misc/NEWS.d/next/Library/2023-06-13-19-38-12.gh-issue-105733.WOp0mG.rst
M Doc/whatsnew/3.13.rst
M Lib/ctypes/__init__.py
M Lib/test/test_ctypes/test_arrays.py
M Lib/test/test_ctypes/test_incomplete.py

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index e6504b0152acc..97bc1587d5052 100644
--- 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 95353bab26cc7..141142a57dcb3 100644
--- 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 415a5785a9c1b..473083870ca6e 100644
--- 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 = 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 @@ def test_bpo36504_signed_int_overflow(self):
     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 00c430ef53cfa..0b53c15f1f998 100644
--- 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 @@
 # 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 cell(Structure):
             _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 cell(Structure):
             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
index 0000000000000..20f2ba2bcc5cb
--- /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.