ctypes: wrong exception message in docs

[kamilturek]

Documentation

The ctypes docs say that the message of the ArgumentError for the presented example should be as follows:

In fact, it looks like this:

>>> strchr = libc.strchr
>>> strchr.restype = c_char_p
>>> strchr.argtypes = [c_char_p, c_char]
>>> 
>>> strchr(b"abcdef", b"def")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ctypes.ArgumentError: argument 2: TypeError: wrong type

I will prepare a PR.

• PR: gh-99266: fix wrong exception message in ctypes docs #99267

• PR: gh-99266: ctypes: Preserve a more detailed exception in _SimpleCData.from_param #99760

[eryksun]

Note that the better error message from the c_set() set function gets cleared by PyCSimpleType_from_param() before it looks for an _as_parameter_ attribute on the object. We're left with the less useful message "wrong type". The original exception could be saved and then restored if the object doesn't have an _as_parameter_ attribute.

c_set():

cpython/Modules/_ctypes/cfield.c

Lines 1114 to 1137 in 2eee9d9

	static PyObject *
	c_set(void *ptr, PyObject *value, Py_ssize_t size)
	{
	if (PyBytes_Check(value) && PyBytes_GET_SIZE(value) == 1) {
	*(char *)ptr = PyBytes_AS_STRING(value)[0];
	_RET(value);
	}
	if (PyByteArray_Check(value) && PyByteArray_GET_SIZE(value) == 1) {
	*(char *)ptr = PyByteArray_AS_STRING(value)[0];
	_RET(value);
	}
	if (PyLong_Check(value))
	{
	long longval = PyLong_AsLong(value);
	if (longval < 0 || longval >= 256)
	goto error;
	*(char *)ptr = (char)longval;
	_RET(value);
	}
	error:
	PyErr_Format(PyExc_TypeError,
	"one character bytes, bytearray or integer expected");
	return NULL;
	}

PyCSimpleType_from_param():

cpython/Modules/_ctypes/_ctypes.c

Lines 2208 to 2274 in 2eee9d9

	/*
	* This is a *class method*.
	* Convert a parameter into something that ConvParam can handle.
	*/
	static PyObject *
	PyCSimpleType_from_param(PyObject *type, PyObject *value)
	{
	StgDictObject *dict;
	const char *fmt;
	PyCArgObject *parg;
	struct fielddesc *fd;
	PyObject *as_parameter;
	int res;
	/* If the value is already an instance of the requested type,
	we can use it as is */
	res = PyObject_IsInstance(value, type);
	if (res == -1)
	return NULL;
	if (res) {
	Py_INCREF(value);
	return value;
	}
	dict = PyType_stgdict(type);
	if (!dict) {
	PyErr_SetString(PyExc_TypeError,
	"abstract class");
	return NULL;
	}
	/* I think we can rely on this being a one-character string */
	fmt = PyUnicode_AsUTF8(dict->proto);
	assert(fmt);
	fd = _ctypes_get_fielddesc(fmt);
	assert(fd);
	parg = PyCArgObject_new();
	if (parg == NULL)
	return NULL;
	parg->tag = fmt[0];
	parg->pffi_type = fd->pffi_type;
	parg->obj = fd->setfunc(&parg->value, value, 0);
	if (parg->obj)
	return (PyObject *)parg;
	PyErr_Clear();
	Py_DECREF(parg);
	if (_PyObject_LookupAttr(value, &_Py_ID(_as_parameter_), &as_parameter) < 0) {
	return NULL;
	}
	if (as_parameter) {
	if (_Py_EnterRecursiveCall("while processing _as_parameter_")) {
	Py_DECREF(as_parameter);
	return NULL;
	}
	value = PyCSimpleType_from_param(type, as_parameter);
	_Py_LeaveRecursiveCall();
	Py_DECREF(as_parameter);
	return value;
	}
	PyErr_SetString(PyExc_TypeError,
	"wrong type");
	return NULL;
	}

Actually, I don't see why it doesn't first check for an _as_parameter_ attribute on value, and I don't see why it needs to recursively call PyCSimpleType_from_param().

[kamilturek]

As per the docs, _as_parameter_ can return another object with the _as_parameter_ attribute. I believe that's why the recursion is needed.

The from_param() class method receives the Python object passed to the function call, it should do a typecheck or whatever is needed to make sure this object is acceptable, and then return the object itself, its as_parameter attribute, or whatever you want to pass as the C function argument in this case. Again, the result should be an integer, string, bytes, a ctypes instance, or an object with an as_parameter attribute.

https://docs.python.org/3/library/ctypes.html

[kamilturek]

@eryksun I followed your suggestion of saving and restoring the exception. I opened a PR.