summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/tuple.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api/tuple.rst')
-rw-r--r--Doc/c-api/tuple.rst100
1 files changed, 100 insertions, 0 deletions
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 3cbfe5b..184affb 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -108,3 +108,103 @@ Tuple Objects
.. c:function:: int PyTuple_ClearFreeList()
Clear the free list. Return the total number of freed items.
+
+
+Struct Sequence Objects
+-----------------------
+
+Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
+objects, i.e. a sequence whose items can also be accessed through attributes.
+To create a struct sequence, you first have to create a specific struct sequence
+type.
+
+.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
+
+ Create a new struct sequence type from the data in *desc*, described below. Instances
+ of the resulting type can be created with :c:func:`PyStructSequence_New`.
+
+
+.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
+
+ Initializes a struct sequence type *type* from *desc* in place.
+
+
+.. c:type:: PyStructSequence_Desc
+
+ Contains the meta information of a struct sequence type to create.
+
+ +-------------------+------------------------------+------------------------------------+
+ | Field | C Type | Meaning |
+ +===================+==============================+====================================+
+ | ``name`` | ``char *`` | name of the struct sequence type |
+ +-------------------+------------------------------+------------------------------------+
+ | ``doc`` | ``char *`` | pointer to docstring for the type |
+ | | | or NULL to omit |
+ +-------------------+------------------------------+------------------------------------+
+ | ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
+ | | | with field names of the new type |
+ +-------------------+------------------------------+------------------------------------+
+ | ``n_in_sequence`` | ``int`` | number of fields visible to the |
+ | | | Python side (if used as tuple) |
+ +-------------------+------------------------------+------------------------------------+
+
+
+.. c:type:: PyStructSequence_Field
+
+ Describes a field of a struct sequence. As a struct sequence is modeled as a
+ tuple, all fields are typed as :c:type:`PyObject\*`. The index in the
+ :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
+ field of the struct sequence is described.
+
+ +-----------+---------------+--------------------------------------+
+ | Field | C Type | Meaning |
+ +===========+===============+======================================+
+ | ``name`` | ``char *`` | name for the field or *NULL* to end |
+ | | | the list of named fields, set to |
+ | | | PyStructSequence_UnnamedField to |
+ | | | leave unnamed |
+ +-----------+---------------+--------------------------------------+
+ | ``doc`` | ``char *`` | field docstring or *NULL* to omit |
+ +-----------+---------------+--------------------------------------+
+
+
+.. c:var:: char* PyStructSequence_UnnamedField
+
+ Special value for a field name to leave it unnamed.
+
+
+.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
+
+ Creates an instance of *type*, which must have been created with
+ :c:func:`PyStructSequence_NewType`.
+
+
+.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
+
+ Return the object at position *pos* in the struct sequence pointed to by *p*.
+ No bounds checking is performed.
+
+
+.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+ Macro equivalent of :c:func:`PyStructSequence_GetItem`.
+
+
+.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+ Sets the field at index *pos* of the struct sequence *p* to value *o*. Like
+ :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
+ instances.
+
+ .. note::
+
+ This function "steals" a reference to *o*.
+
+
+.. c:function:: PyObject* PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
+
+ Macro equivalent of :c:func:`PyStructSequence_SetItem`.
+
+ .. note::
+
+ This function "steals" a reference to *o*.