ctypes: Add docstring for `ctypes.Array`

[tomasr8]

Documentation

The Array class from the ctypes module doesn't have a proper docstring:

from ctypes import Array
help(Array)

>>> Help on class Array in module _ctypes:
>>>
>>> class Array(_CData)
>>>  |  XXX to be provided   # !!
>>>  |

Though the class is documented in the docs so we could just reuse that description.

Feel free to pick up this issue :) If you're new to the C internals, here's a small guide to help you get started:

ctypes.Array is a class implemented in C defined in Modules/_ctypes/_ctypes.c. Here is the current docstring definition:

cpython/Modules/_ctypes/_ctypes.c

Lines 4816 to 4818 in 71a7c96

	Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
	PyDoc_STR("XXX to be provided"), /* tp_doc */
	(traverseproc)PyCData_traverse, /* tp_traverse */

To update the docstring, we could simply change the argument of PyDoc_STR(...) but if the docstring is longer it's better to use PyDoc_STRVAR to create a separate variable with the new docstring:

PyDoc_STRVAR(array_doc,
"Abstract base class for arrays.\n"
"\n"
"The recommended way to create ...");

then you substitute it back instead of PyDoc_STR:

Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */ 
- PyDoc_STR("XXX to be provided"),        /* tp_doc */ 
+ array_doc,                              /* tp_doc */ 
(traverseproc)PyCData_traverse, 

To test that it worked, rebuild python and check the docstring ;)

Linked PRs

• gh-107689: Add docstring to the ctypes array object #107697
• gh-107689: add docstrings to abstract classes #108882

[kostyafarber]

Can I work on this?

[tomasr8]

Can I work on this?

Go ahead!

[kostyafarber]

@tomasr8 we can close this now as it's been merged. Thanks!

[hugovk]

Does this need backporting (to 3.11)? Docs things usually are, I'm not sure about docstrings.

[tomasr8]

No idea what the general policy is, but searching for merged docstring PRs, I found a couple which did get backported (e.g. #103113)

[HarshKakran]

Hey! Is this issue still open?

[tomasr8]

Hey! Is this issue still open?

The PR was ctypes.Array has already been merged, but if you look through the ctypes module, there are more objects with missing docstrings (e.g. _CData). You might wanna have a look at those ;)