From 5d715fefe6cd936a6b0cff25bc6eee2eff5e2e81 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Mon, 27 Mar 2017 04:01:19 +0200 Subject: [PATCH 1/3] bpo-29916: include PyGetSetDef in C API extension documentation. --- Doc/c-api/structures.rst | 49 ++++++++++++++++++++++++++++++++++++++++ Doc/c-api/typeobj.rst | 15 ------------ 2 files changed, 49 insertions(+), 15 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 67e4f9d4b9d1a7..2253c0f136e2cb 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -294,3 +294,52 @@ 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 | :c:type:`getter` | C Function to get the attribute | + +-------------+------------------+-----------------------------------+ + | set | :c:type:`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. | + +-------------+------------------+-----------------------------------+ + + +.. c:type:: getter + + Type of functions used to implement attribute get functions in C. + Functions of this type take one :c:type:`PyObject\*` parameter (the + instance) and a function pointer (the associated ``closure``):: + + typedef PyObject *(*getter)(PyObject *, void *); + + Should return a new reference on success or *NULL* with a set exception on + failure. + + +.. c:type:: setter + + Type of functions used to implement attribute set functions in C. + Functions of this type 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 2f0081aa3db3b8..0b4577f5b950a9 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 From 0fadfabf060fbdb8fa1663b9badccf1c42203fc4 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Mon, 27 Mar 2017 17:02:12 +0200 Subject: [PATCH 2/3] removed explicit documentation for getter and setter typedef --- Doc/c-api/structures.rst | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 2253c0f136e2cb..55cacaaf4d7897 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -306,9 +306,9 @@ definition with the same method name. +=============+==================+===================================+ | name | const char \* | attribute name. | +-------------+------------------+-----------------------------------+ - | get | :c:type:`getter` | C Function to get the attribute | + | get | getter | C Function to get the attribute | +-------------+------------------+-----------------------------------+ - | set | :c:type:`setter` | optional C function to set or | + | set | setter | optional C function to set or | | | | delete the attribute. If omitted | | | | the attribute is readonly. | +-------------+------------------+-----------------------------------+ @@ -319,25 +319,16 @@ definition with the same method name. | | | getter and setter. | +-------------+------------------+-----------------------------------+ - -.. c:type:: getter - - Type of functions used to implement attribute get functions in C. - Functions of this type take one :c:type:`PyObject\*` parameter (the + The ``get`` function takes one :c:type:`PyObject\*` parameter (the instance) and a function pointer (the associated ``closure``):: typedef PyObject *(*getter)(PyObject *, void *); - Should return a new reference on success or *NULL* with a set exception on - failure. - - -.. c:type:: setter + It should return a new reference on success or *NULL* with a set exception + on failure. - Type of functions used to implement attribute set functions in C. - Functions of this type take two :c:type:`PyObject\*` parameters (the - instance and the value to be set) and a function pointer - (the associated ``closure``):: + ``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 *); From a8057139713dbcc32d23cb1e35ad5f7483d132a9 Mon Sep 17 00:00:00 2001 From: Michael Seifert Date: Fri, 15 Sep 2017 17:44:18 +0200 Subject: [PATCH 3/3] Use 3-space indentation and remove periods in description column --- Doc/c-api/structures.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 55cacaaf4d7897..797b9045fa8edc 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -304,25 +304,25 @@ definition with the same method name. +-------------+------------------+-----------------------------------+ | Field | C Type | Meaning | +=============+==================+===================================+ - | name | const char \* | attribute name. | + | 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. | + | | | 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. | + | | | 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 *); + typedef PyObject *(*getter)(PyObject *, void *); It should return a new reference on success or *NULL* with a set exception on failure. @@ -330,7 +330,7 @@ definition with the same method name. ``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 *); + 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.