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

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

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

Partially reverts 2211454
(cherry picked from commit 3833d27)

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

Author: miss-islington

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
 

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

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
 
 ################################################################

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 @@
           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 @@ 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()

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.