mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-12-14 04:17:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

bpo-29916: Include PyGetSetDef in C API extension documentation. (#831)

Browse Source
This commit is contained in:
Michael Seifert 2017-09-15 18:25:27 +02:00 committed by Serhiy Storchaka
parent 11f0807a40
commit da67e0d644
2 changed files with 40 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
Doc/c-api/structures.rst
View File

@ -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.

15
Doc/c-api/typeobj.rst
View File

@ -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