python · erlend-aasland · Aug 8, 2023 · Aug 5, 2023 · Aug 5, 2023 · Aug 5, 2023
diff --git a/Misc/NEWS.d/next/Core and Builtins/2023-08-05-15-45-07.gh-issue-107659.QgtQ5M.rst b/Misc/NEWS.d/next/Core and Builtins/2023-08-05-15-45-07.gh-issue-107659.QgtQ5M.rst
@@ -0,0 +1 @@
+Add docstrings for :func:`ctypes.pointer` and :func:`ctypes.POINTER`.
diff --git a/Modules/_ctypes/callproc.c b/Modules/_ctypes/callproc.c
@@ -54,6 +54,11 @@
 
  */
 
+/*[clinic input]
+module _ctypes
+[clinic start generated code]*/
+/*[clinic end generated code: output=da39a3ee5e6b4b0d input=476a19c49b31a75c]*/
+
 #ifndef Py_BUILD_CORE_BUILTIN
 #  define Py_BUILD_CORE_MODULE 1
 #endif
@@ -98,6 +103,7 @@
 
 #include "pycore_runtime.h"         // _PyRuntime
 #include "pycore_global_objects.h"  // _Py_ID()
+#include "clinic/callproc.c.h"
 
 #define CTYPES_CAPSULE_NAME_PYMEM "_ctypes pymem"
 
@@ -1893,8 +1899,21 @@ unpickle(PyObject *self, PyObject *args)
     return NULL;
 }
 
+/*[clinic input]
+_ctypes.POINTER as create_pointer_type
+
+    type as cls: object
+    /
+
+Creates and returns a new ctypes pointer type.
+
+Pointer types are cached and reused internally, so calling this function
+repeatedly is cheap. 'type' must be a ctypes type.
+[clinic start generated code]*/
+
 static PyObject *
-POINTER(PyObject *self, PyObject *cls)
+create_pointer_type(PyObject *module, PyObject *cls)
+/*[clinic end generated code: output=98c3547ab6f4f40b input=ccb867693e635dea]*/
 {
     PyObject *result;
     PyTypeObject *typ;
@@ -1944,23 +1963,37 @@ POINTER(PyObject *self, PyObject *cls)
     return result;
 }
 
+/*[clinic input]
+_ctypes.pointer as create_pointer_inst
+
+    obj: object
+    /
+
+Creates a new pointer instance, pointing to 'obj'.
+
+The returned object is of the type POINTER(type(obj)). Note that if you just
+want to pass a pointer to an object to a foreign function call,
+you should use byref(obj) which is much faster.
+[clinic start generated code]*/
+
 static PyObject *
-pointer(PyObject *self, PyObject *arg)
+create_pointer_inst(PyObject *module, PyObject *obj)
+/*[clinic end generated code: output=1039888809db21a2 input=925d2ec210c75c47]*/
 {
     PyObject *result;
     PyObject *typ;
 
-    typ = PyDict_GetItemWithError(_ctypes_ptrtype_cache, (PyObject *)Py_TYPE(arg));
+    typ = PyDict_GetItemWithError(_ctypes_ptrtype_cache, (PyObject *)Py_TYPE(obj));
     if (typ) {
-        return PyObject_CallOneArg(typ, arg);
+        return PyObject_CallOneArg(typ, obj);
     }
     else if (PyErr_Occurred()) {
         return NULL;
     }
-    typ = POINTER(NULL, (PyObject *)Py_TYPE(arg));
+    typ = create_pointer_type(NULL, (PyObject *)Py_TYPE(obj));
     if (typ == NULL)
         return NULL;
-    result = PyObject_CallOneArg(typ, arg);
+    result = PyObject_CallOneArg(typ, obj);
     Py_DECREF(typ);
     return result;
 }
@@ -1997,8 +2030,8 @@ buffer_info(PyObject *self, PyObject *arg)
 PyMethodDef _ctypes_module_methods[] = {
     {"get_errno", get_errno, METH_NOARGS},
     {"set_errno", set_errno, METH_VARARGS},
-    {"POINTER", POINTER, METH_O },
-    {"pointer", pointer, METH_O },
+    CREATE_POINTER_TYPE_METHODDEF
+    CREATE_POINTER_INST_METHODDEF
     {"_unpickle", unpickle, METH_VARARGS },
     {"buffer_info", buffer_info, METH_O, "Return buffer interface information"},
     {"resize", resize, METH_VARARGS, "Resize the memory buffer of a ctypes instance"},

diff --git a/Modules/_ctypes/clinic/callproc.c.h b/Modules/_ctypes/clinic/callproc.c.h
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add docstrings for :func:`ctypes.pointer` and :func:`ctypes.POINTER`.