gh-142083: Clarify documentation for array('u') typecode

Modules/arraymodule.c

@@ -2405,7 +2405,7 @@
 };
 
 static PyObject *
 array_repr(PyObject *op)
 {
     char typecode;
     PyObject *s, *v = NULL;
@@ -2433,7 +2433,7 @@
 }
 
 static PyObject*
 array_subscr(PyObject *op, PyObject *item)
 {
     arrayobject *self = arrayobject_CAST(op);
     array_state *state = find_array_state_by_type(Py_TYPE(self));
@@ -2497,7 +2497,7 @@
 }
 
 static int
 array_ass_subscr(PyObject *op, PyObject *item, PyObject *value)
 {
     Py_ssize_t start, stop, step, slicelength, needed;
     arrayobject *self = arrayobject_CAST(op);
@@ -2659,7 +2659,7 @@
 
 
 static int
 array_buffer_getbuf(PyObject *op, Py_buffer *view, int flags)
 {
     if (view == NULL) {
         PyErr_SetString(PyExc_BufferError,
@@ -2700,7 +2700,7 @@
 }
 
 static void
 array_buffer_relbuf(PyObject *op, Py_buffer *Py_UNUSED(view))
 {
     arrayobject *self = arrayobject_CAST(op);
     self->ob_exports--;
@@ -2875,13 +2875,13 @@
 }
 
 
 PyDoc_STRVAR(module_doc,
 "This module defines an object type which can efficiently represent\n\
 an array of basic values: characters, integers, floating-point\n\
 numbers.  Arrays are sequence types and behave very much like lists,\n\
 except that the type of objects stored in them is constrained.\n");
 
 PyDoc_STRVAR(arraytype_doc,
 "array(typecode [, initializer]) -> array\n\
 \n\
 Return a new array whose items are restricted by typecode, and\n\
@@ -2908,9 +2908,16 @@
     'f'         floating-point     4\n\
     'd'         floating-point     8\n\
 \n\
-NOTE: The 'u' typecode corresponds to Python's unicode character. On\n\
-narrow builds this is 2-bytes on wide builds this is 4-bytes.\n\
-\n\
+"NOTE: The 'u' typecode represents a Unicode character stored using the\n"
+"platform's C 'wchar_t' type. Since Python 3.9, array('u') uses wchar_t\n"
+"instead of the deprecated Py_UNICODE. The size of wchar_t is platform-\n"
+"dependent: typically 2 bytes on Windows (UTF-16) and 4 bytes on most\n"
+"Unix-like systems (UTF-32).\n"
+"\n"
+"The 'u' typecode has been deprecated since Python 3.3 and will be\n"
+"removed in Python 3.16. Please migrate to the 'w' typecode instead,\n"
+"which stores Unicode characters as Py_UCS4 (always 4 bytes).\n"
+"\n"
 NOTE: The 'q' and 'Q' type codes are only available if the platform\n\
 C compiler used to build Python supports 'long long', or, on Windows,\n\
 '__int64'.\n\
@@ -2938,7 +2945,7 @@
 \n\
 typecode -- the typecode character used to create the array\n\
 itemsize -- the length in bytes of one array item\n\
 ");
 
 static PyObject *array_iter(PyObject *op);
 
@@ -3278,4 +3285,4 @@
 PyInit_array(void)
 {
     return PyModuleDef_Init(&arraymodule);
 }