ctypes: Add docstring for ctypes.Array

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

Can I work on this?

Can I work on this?

Go ahead!

gh-107689: Add docstring to `ctypes.Array` (#107697)

@tomasr8

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

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

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

Hey! Is this issue still open?

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 ;)

Navigation Menu

Repository navigation

ctypes: Add docstring for `ctypes.Array` #107689

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

ctypes: Add docstring for ctypes.Array #107689

Description

Documentation

Linked PRs

Activity

kostyafarber commented on Aug 6, 2023

tomasr8 commented on Aug 6, 2023

kostyafarber commented on Aug 10, 2023

hugovk commented on Aug 10, 2023

tomasr8 commented on Aug 10, 2023

HarshKakran commented on Aug 23, 2023

tomasr8 commented on Aug 23, 2023

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

ctypes: Add docstring for `ctypes.Array` #107689