bpo-29916: Include PyGetSetDef in C API extension documentation. (#83… · python/cpython@51ea806 (original) (raw)
`@@ -294,3 +294,43 @@ definition with the same method name.
`
294
294
`` read-only access. Using :c:macro:T_STRING for :attr:type implies
``
295
295
`` :c:macro:READONLY. Only :c:macro:T_OBJECT and :c:macro:T_OBJECT_EX
``
296
296
` members can be deleted. (They are set to NULL).
`
``
297
+
``
298
+
``
299
`+
.. c:type:: PyGetSetDef
`
``
300
+
``
301
`+
Structure to define property-like access for a type. See also description of
`
``
302
`` +
the :c:member:PyTypeObject.tp_getset slot.
``
``
303
+
``
304
`+
+-------------+------------------+-----------------------------------+
`
``
305
`+
| Field | C Type | Meaning |
`
``
306
`+
+=============+==================+===================================+
`
``
307
`+
| name | char * | attribute name |
`
``
308
`+
+-------------+------------------+-----------------------------------+
`
``
309
`+
| get | getter | C Function to get the attribute |
`
``
310
`+
+-------------+------------------+-----------------------------------+
`
``
311
`+
| set | setter | optional C function to set or |
`
``
312
`+
| | | delete the attribute, if omitted |
`
``
313
`+
| | | the attribute is readonly |
`
``
314
`+
+-------------+------------------+-----------------------------------+
`
``
315
`+
| doc | char * | optional docstring |
`
``
316
`+
+-------------+------------------+-----------------------------------+
`
``
317
`+
| closure | void * | optional function pointer, |
`
``
318
`+
| | | providing additional data for |
`
``
319
`+
| | | getter and setter |
`
``
320
`+
+-------------+------------------+-----------------------------------+
`
``
321
+
``
322
The ``get`` function takes one :c:type:`PyObject\*` parameter (the
``
323
instance) and a function pointer (the associated ``closure``)::
``
324
+
``
325
`+
typedef PyObject *(*getter)(PyObject *, void *);
`
``
326
+
``
327
`+
It should return a new reference on success or NULL with a set exception
`
``
328
`+
on failure.
`
``
329
+
``
330
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
``
331
the value to be set) and a function pointer (the associated ``closure``)::
``
332
+
``
333
`+
typedef int (*setter)(PyObject *, PyObject *, void *);
`
``
334
+
``
335
`+
In case the attribute should be deleted the second parameter is NULL.
`
``
336
Should return ``0`` on success or ``-1`` with a set exception on failure.