Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
serhiy-storchaka merged 3 commits into from
Sep 15, 2017
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d715fe
bpo-29916: include PyGetSetDef in C API extension documentation.
MSeifert04 Mar 27, 2017
0fadfab
removed explicit documentation for getter and setter typedef
MSeifert04 Mar 27, 2017
a805713
Use 3-space indentation and remove periods in description column
MSeifert04 Sep 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions Doc/c-api/structures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 0 additions & 15 deletions Doc/c-api/typeobj.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down