diff options
author | Michael Seifert <michaelseifert04@yahoo.de> | 2017-09-15 16:25:27 (GMT) |
---|---|---|
committer | Serhiy Storchaka <storchaka@gmail.com> | 2017-09-15 16:25:27 (GMT) |
commit | da67e0d644bd3185efdaa4d15cc2ac0828ca83f9 (patch) | |
tree | dd85a181c16f77e5b37b596df881ac11e7b6e709 /Doc/c-api | |
parent | 11f0807a407551d498bb6bd8cc932636f75f1cd7 (diff) | |
download | cpython-da67e0d644bd3185efdaa4d15cc2ac0828ca83f9.zip cpython-da67e0d644bd3185efdaa4d15cc2ac0828ca83f9.tar.gz cpython-da67e0d644bd3185efdaa4d15cc2ac0828ca83f9.tar.bz2 |
bpo-29916: Include PyGetSetDef in C API extension documentation. (#831)
Diffstat (limited to 'Doc/c-api')
-rw-r--r-- | Doc/c-api/structures.rst | 40 | ||||
-rw-r--r-- | Doc/c-api/typeobj.rst | 15 |
2 files changed, 40 insertions, 15 deletions
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 67e4f9d..797b904 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -294,3 +294,43 @@ definition with the same method name. read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies :c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` members can be deleted. (They are set to *NULL*). + + +.. c:type:: PyGetSetDef + + Structure to define property-like access for a type. See also description of + the :c:member:`PyTypeObject.tp_getset` slot. + + +-------------+------------------+-----------------------------------+ + | Field | C Type | Meaning | + +=============+==================+===================================+ + | name | const char \* | attribute name | + +-------------+------------------+-----------------------------------+ + | get | getter | C Function to get the attribute | + +-------------+------------------+-----------------------------------+ + | set | setter | optional C function to set or | + | | | delete the attribute, if omitted | + | | | the attribute is readonly | + +-------------+------------------+-----------------------------------+ + | doc | const char \* | optional docstring | + +-------------+------------------+-----------------------------------+ + | closure | void \* | optional function pointer, | + | | | providing additional data for | + | | | getter and setter | + +-------------+------------------+-----------------------------------+ + + The ``get`` function takes one :c:type:`PyObject\*` parameter (the + instance) and a function pointer (the associated ``closure``):: + + typedef PyObject *(*getter)(PyObject *, void *); + + It should return a new reference on success or *NULL* with a set exception + on failure. + + ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and + the value to be set) and a function pointer (the associated ``closure``):: + + typedef int (*setter)(PyObject *, PyObject *, void *); + + In case the attribute should be deleted the second parameter is *NULL*. + Should return ``0`` on success or ``-1`` with a set exception on failure. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 2f0081a..0b4577f 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -719,21 +719,6 @@ type objects) *must* have the :attr:`ob_size` field. This field is not inherited by subtypes (computed attributes are inherited through a different mechanism). - .. XXX belongs elsewhere - - Docs for PyGetSetDef:: - - typedef PyObject *(*getter)(PyObject *, void *); - typedef int (*setter)(PyObject *, PyObject *, void *); - - typedef struct PyGetSetDef { - const char *name; /* attribute name */ - getter get; /* C function to get the attribute */ - setter set; /* C function to set or delete the attribute */ - const char *doc; /* optional doc string */ - void *closure; /* optional additional data for getter and setter */ - } PyGetSetDef; - .. c:member:: PyTypeObject* PyTypeObject.tp_base |