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

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 9e69b3dc51a1ac3754bad22360f4ddf2b7c1e962..c2f928e16aa90ce7dcee76ebe89deb850227dbfe 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -2688,6 +2688,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 0854631c832ef4b9eb5ee44d4074dabc436bffcf..fbf19d1c9598e12092cec0ea66a7ea504c41ac26 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -1494,8 +1494,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 721522caeeac92ab2fc8225f60a8dde8a56f2c5e..cb3a61287bfe5d21d99fdbfbeab2cd28e809514a 100644 (file)
--- a/Lib/ctypes/__init__.py
+++ b/Lib/ctypes/__init__.py
@@ -324,8 +324,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.