[3.13] gh-105733: Soft-deprecate ctypes.ARRAY, rather than hard-deprecating it. ...

gh-105733: Soft-deprecate ctypes.ARRAY, rather than hard-deprecating it. (GH-122281)

Soft-deprecate ctypes.ARRAY, rather than hard-deprecating it.

Partially reverts 2211454fe210637ed7fabda12690dac6cc9a8149
(cherry picked from commit 3833d27f985a62c4709dcd9dc73724fc19d46ebf)

Co-authored-by: Petr Viktorin <encukou@gmail.com>

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index d890d904ef4e6c5936fc22dbb6104627ef37fb4c..94c3071d044c68f950827454a5cd73447956fcb1 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -2621,6 +2621,15 @@ Arrays and pointers
    Array subclass constructors accept positional arguments, used to
    initialize the elements in order.
 
+.. function:: ARRAY(type, length)
+
+   Create an array.
+   Equivalent to ``type * length``, where *type* is a
+   :mod:`ctypes` data type and *length* an integer.
+
+   This function is :term:`soft deprecated` in favor of multiplication.
+   There are no plans to remove it.
+
 
 .. class:: _Pointer
 

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 3654cb42e47782c94e58a5e409ecbdc1c9408fd7..b53f419a59f0621b8c845cfd9129cd622ff4cbba 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -1482,8 +1482,8 @@ New Deprecations
   (Contributed by Hugo van Kemenade in :gh:`80480`.)
 
 * :mod:`ctypes`: Deprecate undocumented :func:`!ctypes.SetPointerType`
-  and :func:`!ctypes.ARRAY` functions.
-  Replace ``ctypes.ARRAY(item_type, size)`` with ``item_type * size``.
+  function. :term:`Soft-deprecate <soft deprecated>` the :func:`ctypes.ARRAY`
+  function in favor of multiplication.
   (Contributed by Victor Stinner in :gh:`105733`.)
 
 * :mod:`decimal`: Deprecate non-standard format specifier "N" for

diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py
index b7ee46d664ab08f4292c641ab1529300b9ff15ee..8261773cef9830a4fa23b6810493faf5f01c2e12 100644 (file)
--- a/Lib/ctypes/__init__.py
+++ b/Lib/ctypes/__init__.py
@@ -314,8 +314,6 @@ def SetPointerType(pointer, cls):
     del _pointer_type_cache[id(pointer)]
 
 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 6846773d7069ae7629df08092d8519d47bfe24f5..c80fdff5de685dfaa602b3b72e087b6d0450e7db 100644 (file)
--- a/Lib/test/test_ctypes/test_arrays.py
+++ b/Lib/test/test_ctypes/test_arrays.py
@@ -1,8 +1,7 @@
 import ctypes
 import sys
 import unittest
-import warnings
-from ctypes import (Structure, Array, sizeof, addressof,
+from ctypes import (Structure, Array, ARRAY, sizeof, addressof,
                     create_string_buffer, create_unicode_buffer,
                     c_char, c_wchar, c_byte, c_ubyte, c_short, c_ushort, c_int, c_uint,
                     c_long, c_ulonglong, c_float, c_double, c_longdouble)
@@ -17,13 +16,6 @@ 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_inheritance_hierarchy(self):
         self.assertEqual(Array.mro(), [Array, _CData, object])
@@ -275,10 +267,6 @@ 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/Misc/NEWS.d/next/Library/2024-07-25-15-41-14.gh-issue-105733.o3koJA.rst b/Misc/NEWS.d/next/Library/2024-07-25-15-41-14.gh-issue-105733.o3koJA.rst
new file mode 100644 (file)
index 0000000..60c5e69
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-07-25-15-41-14.gh-issue-105733.o3koJA.rst
@@ -0,0 +1,2 @@
+:func:`ctypes.ARRAY` is now :term:`soft deprecated`: it no longer emits deprecation
+warnings and is not scheduled for removal.