bpo-34626: Document creating heap types from the C-API (GH-9154) · python/cpython@f1e17e9 (original) (raw)
`@@ -95,18 +95,6 @@ Type Objects
`
95
95
``` from a type's base class. Return 0 on success, or return -1 and sets an
`96`
`96`
` exception on error.
`
`97`
`97`
``
`98`
``
`-
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
`
`99`
``
`-`
`100`
``
`-
Creates and returns a heap type object from the *spec* passed to the function.
`
`101`
``
`-`
`102`
``
`-
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
`
`103`
``
`-`
`104`
``
`-
Creates and returns a heap type object from the *spec*. In addition to that,
`
`105`
``
`-
the created heap type contains all types contained by the *bases* tuple as base
`
`106`
``
`-
types. This allows the caller to reference other heap types as base types.
`
`107`
``
`-`
`108`
``
`-
.. versionadded:: 3.3
`
`109`
``
`-`
`110`
`98`
`.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
`
`111`
`99`
``
`112`
`100`
` Return the function pointer stored in the given slot. If the
`
`@@ -115,4 +103,107 @@ Type Objects
`
`115`
`103`
` Callers will typically cast the result pointer into the appropriate
`
`116`
`104`
` function type.
`
`117`
`105`
``
``
`106`
`` +
See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument.
``
``
`107`
`+`
``
`108`
`+
An exception is raised if *type* is not a heap type.
`
``
`109`
`+`
`118`
`110`
` .. versionadded:: 3.4
`
``
`111`
`+`
``
`112`
`+`
``
`113`
`+
Creating Heap-Allocated Types
`
``
`114`
`+
.............................
`
``
`115`
`+`
``
`116`
`+
The following functions and structs are used to create
`
``
`117`
`` +
:ref:`heap types <heap-types>`.
``
``
`118`
`+`
``
`119`
`+
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
`
``
`120`
`+`
``
`121`
`+
Creates and returns a heap type object from the *spec*.
`
``
`122`
`+`
``
`123`
`+
If *bases* is a tuple, the created heap type contains all types contained
`
``
`124`
`+
in it as base types.
`
``
`125`
`+`
``
`126`
`+
If *bases* is *NULL*, the *Py_tp_base* slot is used instead.
`
``
`127`
`` +
If that also is *NULL*, the new type derives from :class:`object`.
``
``
`128`
`+`
``
`129`
`` +
This function calls :c:func:`PyType_Ready` on the new type.
``
``
`130`
`+`
``
`131`
`+
.. versionadded:: 3.3
`
``
`132`
`+`
``
`133`
`+
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
`
``
`134`
`+`
``
`135`
``` +
Equivalent to ``PyType_FromSpecWithBases(spec, NULL)``.
``
136
+
``
137
`+
.. c:type:: PyType_Spec
`
``
138
+
``
139
`+
Structure defining a type's behavior.
`
``
140
+
``
141
`+
.. c:member:: const char* PyType_Spec.name
`
``
142
+
``
143
`` +
Name of the type, used to set :c:member:PyTypeObject.tp_name.
``
``
144
+
``
145
`+
.. c:member:: const char* PyType_Spec.doc
`
``
146
+
``
147
`` +
Type docstring, used to set :c:member:PyTypeObject.tp_doc.
``
``
148
+
``
149
`+
.. c:member:: int PyType_Spec.basicsize
`
``
150
`+
.. c:member:: int PyType_Spec.itemsize
`
``
151
+
``
152
`+
Size of the instance in bytes, used to set
`
``
153
`` +
:c:member:PyTypeObject.tp_basicsize and
``
``
154
`` +
:c:member:PyTypeObject.tp_itemsize.
``
``
155
+
``
156
`+
.. c:member:: int PyType_Spec.flags
`
``
157
+
``
158
`` +
Type flags, used to set :c:member:PyTypeObject.tp_flags.
``
``
159
+
``
160
If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set,
``
161
`` +
:c:func:PyType_FromSpecWithBases sets it automatically.
``
``
162
+
``
163
`+
.. c:member:: PyType_Slot *PyType_Spec.slots
`
``
164
+
``
165
`` +
Array of :c:type:PyType_Slot structures.
``
``
166
Terminated by the special slot value ``{0, NULL}``.
``
167
+
``
168
`+
.. c:type:: PyType_Slot
`
``
169
+
``
170
`+
Structure defining optional functionality of a type, containing a slot ID
`
``
171
`+
and a value pointer.
`
``
172
+
``
173
`+
.. c:member:: int PyType_Slot.slot
`
``
174
+
``
175
`+
A slot ID.
`
``
176
+
``
177
`+
Slot IDs are named like the field names of the structures
`
``
178
`` +
:c:type:PyTypeObject, :c:type:PyNumberMethods,
``
``
179
`` +
:c:type:PySequenceMethods, :c:type:PyMappingMethods and
``
``
180
:c:type:`PyAsyncMethods` with an added ``Py_`` prefix.
``
181
`+
For example, use:
`
``
182
+
``
183
* ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc`
``
184
* ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
``
185
* ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
``
186
+
``
187
`+
The following fields cannot be set using PyType_Spec and PyType_Slot:
`
``
188
+
``
189
`` +
- :c:member:
~PyTypeObject.tp_dict
``
``
190
`` +
- :c:member:
~PyTypeObject.tp_mro
``
``
191
`` +
- :c:member:
~PyTypeObject.tp_cache
``
``
192
`` +
- :c:member:
~PyTypeObject.tp_subclasses
``
``
193
`` +
- :c:member:
~PyTypeObject.tp_weaklist
``
``
194
`` +
- :c:member:
~PyTypeObject.tp_print
``
``
195
`` +
- :c:member:
~PyTypeObject.tp_weaklistoffset
``
``
196
`` +
- :c:member:
~PyTypeObject.tp_dictoffset
``
``
197
`` +
- :c:member:
~PyBufferProcs.bf_getbuffer
``
``
198
`` +
- :c:member:
~PyBufferProcs.bf_releasebuffer
``
``
199
+
``
200
`` +
Setting :c:data:Py_tp_bases may be problematic on some platforms.
``
``
201
`+
To avoid issues, use the bases argument of
`
``
202
`` +
:py:func:PyType_FromSpecWithBases instead.
``
``
203
+
``
204
`+
.. c:member:: void *PyType_Slot.pfunc
`
``
205
+
``
206
`+
The desired value of the slot. In most cases, this is a pointer
`
``
207
`+
to a function.
`
``
208
+
``
209
`+
May not be NULL.
`