summaryrefslogtreecommitdiffstats
path: root/Doc/c-api
diff options
context:
space:
mode:
authorMichael Seifert <michaelseifert04@yahoo.de>2017-09-15 16:25:27 (GMT)
committerSerhiy Storchaka <storchaka@gmail.com>2017-09-15 16:25:27 (GMT)
commitda67e0d644bd3185efdaa4d15cc2ac0828ca83f9 (patch)
treedd85a181c16f77e5b37b596df881ac11e7b6e709 /Doc/c-api
parent11f0807a407551d498bb6bd8cc932636f75f1cd7 (diff)
downloadcpython-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.rst40
-rw-r--r--Doc/c-api/typeobj.rst15
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