Debian Codegraph @

Doc/c-api/structures.rst

raw
1 .. highlight:: c
2
3 .. _common-structs:
4
5 Common Object Structures
6 ========================
7
8 There are a large number of structures which are used in the definition of
9 object types for Python. This section describes these structures and how they
10 are used.
11
12
13 Base object types and macros
14 ----------------------------
15
16 All Python objects ultimately share a small number of fields at the beginning
17 of the object's representation in memory. These are represented by the
18 :c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
19 by the expansions of some macros also used, whether directly or indirectly, in
20 the definition of all other Python objects. Additional macros can be found
21 under :ref:`reference counting <countingrefs>`.
22
23
24 .. c:type:: PyObject
25
26 All object types are extensions of this type. This is a type which
27 contains the information Python needs to treat a pointer to an object as an
28 object. In a normal "release" build, it contains only the object's
29 reference count and a pointer to the corresponding type object.
30 Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
31 to a Python object can be cast to a :c:expr:`PyObject*`.
32
33 The members must not be accessed directly; instead use macros such as
34 :c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`.
35
36 .. c:member:: Py_ssize_t ob_refcnt
37
38 The object's reference count, as returned by :c:macro:`Py_REFCNT`.
39 Do not use this field directly; instead use functions and macros such as
40 :c:macro:`!Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`.
41
42 The field type may be different from ``Py_ssize_t``, depending on
43 build configuration and platform.
44
45 .. c:member:: PyTypeObject* ob_type
46
47 The object's type.
48 Do not use this field directly; use :c:macro:`Py_TYPE` and
49 :c:func:`Py_SET_TYPE` instead.
50
51
52 .. c:type:: PyVarObject
53
54 An extension of :c:type:`PyObject` that adds the
55 :c:member:`~PyVarObject.ob_size` field.
56 This is intended for objects that have some notion of *length*.
57
58 As with :c:type:`!PyObject`, the members must not be accessed directly;
59 instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and
60 :c:macro:`Py_TYPE`.
61
62 .. c:member:: Py_ssize_t ob_size
63
64 A size field, whose contents should be considered an object's internal
65 implementation detail.
66
67 Do not use this field directly; use :c:macro:`Py_SIZE` instead.
68
69 Object creation functions such as :c:func:`PyObject_NewVar` will
70 generally set this field to the requested size (number of items).
71 After creation, arbitrary values can be stored in :c:member:`!ob_size`
72 using :c:macro:`Py_SET_SIZE`.
73
74 To get an object's publicly exposed length, as returned by
75 the Python function :py:func:`len`, use :c:func:`PyObject_Length`
76 instead.
77
78
79 .. c:macro:: PyObject_HEAD
80
81 This is a macro used when declaring new types which represent objects
82 without a varying length. The PyObject_HEAD macro expands to::
83
84 PyObject ob_base;
85
86 See documentation of :c:type:`PyObject` above.
87
88
89 .. c:macro:: PyObject_VAR_HEAD
90
91 This is a macro used when declaring new types which represent objects
92 with a length that varies from instance to instance.
93 The PyObject_VAR_HEAD macro expands to::
94
95 PyVarObject ob_base;
96
97 See documentation of :c:type:`PyVarObject` above.
98
99
100 .. c:var:: PyTypeObject PyBaseObject_Type
101
102 The base class of all other objects, the same as :class:`object` in Python.
103
104
105 .. c:function:: int Py_Is(PyObject *x, PyObject *y)
106
107 Test if the *x* object is the *y* object, the same as ``x is y`` in Python.
108
109 .. versionadded:: 3.10
110
111
112 .. c:function:: int Py_IsNone(PyObject *x)
113
114 Test if an object is the ``None`` singleton,
115 the same as ``x is None`` in Python.
116
117 .. versionadded:: 3.10
118
119
120 .. c:function:: int Py_IsTrue(PyObject *x)
121
122 Test if an object is the ``True`` singleton,
123 the same as ``x is True`` in Python.
124
125 .. versionadded:: 3.10
126
127
128 .. c:function:: int Py_IsFalse(PyObject *x)
129
130 Test if an object is the ``False`` singleton,
131 the same as ``x is False`` in Python.
132
133 .. versionadded:: 3.10
134
135
136 .. c:function:: PyTypeObject* Py_TYPE(PyObject *o)
137
138 Get the type of the Python object *o*.
139
140 The returned reference is :term:`borrowed <borrowed reference>` from *o*.
141 Do not release it with :c:func:`Py_DECREF` or similar.
142
143 .. versionchanged:: 3.11
144 :c:func:`Py_TYPE()` is changed to an inline static function.
145 The parameter type is no longer :c:expr:`const PyObject*`.
146
147
148 .. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
149
150 Return non-zero if the object *o* type is *type*. Return zero otherwise.
151 Equivalent to: ``Py_TYPE(o) == type``.
152
153 .. versionadded:: 3.9
154
155
156 .. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
157
158 Set the type of object *o* to *type*, without any checking or reference
159 counting.
160
161 This is a very low-level operation.
162 Consider instead setting the Python attribute :attr:`~object.__class__`
163 using :c:func:`PyObject_SetAttrString` or similar.
164
165 Note that assigning an incompatible type can lead to undefined behavior.
166
167 If *type* is a :ref:`heap type <heap-types>`, the caller must create a
168 new reference to it.
169 Similarly, if the old type of *o* is a heap type, the caller must release
170 a reference to that type.
171
172 .. versionadded:: 3.9
173
174
175 .. c:function:: Py_ssize_t Py_SIZE(PyVarObject *o)
176
177 Get the :c:member:`~PyVarObject.ob_size` field of *o*.
178
179 .. versionchanged:: 3.11
180 :c:func:`Py_SIZE()` is changed to an inline static function.
181 The parameter type is no longer :c:expr:`const PyVarObject*`.
182
183
184 .. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
185
186 Set the :c:member:`~PyVarObject.ob_size` field of *o* to *size*.
187
188 .. versionadded:: 3.9
189
190
191 .. c:macro:: PyObject_HEAD_INIT(type)
192
193 This is a macro which expands to initialization values for a new
194 :c:type:`PyObject` type. This macro expands to::
195
196 _PyObject_EXTRA_INIT
197 1, type,
198
199
200 .. c:macro:: PyVarObject_HEAD_INIT(type, size)
201
202 This is a macro which expands to initialization values for a new
203 :c:type:`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field.
204 This macro expands to::
205
206 _PyObject_EXTRA_INIT
207 1, type, size,
208
209
210 Implementing functions and methods
211 ----------------------------------
212
213 .. c:type:: PyCFunction
214
215 Type of the functions used to implement most Python callables in C.
216 Functions of this type take two :c:expr:`PyObject*` parameters and return
217 one such value. If the return value is ``NULL``, an exception shall have
218 been set. If not ``NULL``, the return value is interpreted as the return
219 value of the function as exposed in Python. The function must return a new
220 reference.
221
222 The function signature is::
223
224 PyObject *PyCFunction(PyObject *self,
225 PyObject *args);
226
227 .. c:type:: PyCFunctionWithKeywords
228
229 Type of the functions used to implement Python callables in C
230 with signature :ref:`METH_VARARGS | METH_KEYWORDS <METH_VARARGS-METH_KEYWORDS>`.
231 The function signature is::
232
233 PyObject *PyCFunctionWithKeywords(PyObject *self,
234 PyObject *args,
235 PyObject *kwargs);
236
237
238 .. c:type:: PyCFunctionFast
239
240 Type of the functions used to implement Python callables in C
241 with signature :c:macro:`METH_FASTCALL`.
242 The function signature is::
243
244 PyObject *PyCFunctionFast(PyObject *self,
245 PyObject *const *args,
246 Py_ssize_t nargs);
247
248 .. c:type:: PyCFunctionFastWithKeywords
249
250 Type of the functions used to implement Python callables in C
251 with signature :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>`.
252 The function signature is::
253
254 PyObject *PyCFunctionFastWithKeywords(PyObject *self,
255 PyObject *const *args,
256 Py_ssize_t nargs,
257 PyObject *kwnames);
258
259 .. c:type:: PyCMethod
260
261 Type of the functions used to implement Python callables in C
262 with signature :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`.
263 The function signature is::
264
265 PyObject *PyCMethod(PyObject *self,
266 PyTypeObject *defining_class,
267 PyObject *const *args,
268 Py_ssize_t nargs,
269 PyObject *kwnames)
270
271 .. versionadded:: 3.9
272
273
274 .. c:type:: PyMethodDef
275
276 Structure used to describe a method of an extension type. This structure has
277 four fields:
278
279 .. c:member:: const char *ml_name
280
281 Name of the method.
282
283 .. c:member:: PyCFunction ml_meth
284
285 Pointer to the C implementation.
286
287 .. c:member:: int ml_flags
288
289 Flags bits indicating how the call should be constructed.
290
291 .. c:member:: const char *ml_doc
292
293 Points to the contents of the docstring.
294
295 The :c:member:`~PyMethodDef.ml_meth` is a C function pointer.
296 The functions may be of different
297 types, but they always return :c:expr:`PyObject*`. If the function is not of
298 the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
299 Even though :c:type:`PyCFunction` defines the first parameter as
300 :c:expr:`PyObject*`, it is common that the method implementation uses the
301 specific C type of the *self* object.
302
303 The :c:member:`~PyMethodDef.ml_flags` field is a bitfield which can include
304 the following flags.
305 The individual flags indicate either a calling convention or a binding
306 convention.
307
308 There are these calling conventions:
309
310 .. c:macro:: METH_VARARGS
311
312 This is the typical calling convention, where the methods have the type
313 :c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values.
314 The first one is the *self* object for methods; for module functions, it is
315 the module object. The second parameter (often called *args*) is a tuple
316 object representing all arguments. This parameter is typically processed
317 using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
318
319
320 .. c:macro:: METH_KEYWORDS
321
322 Can only be used in certain combinations with other flags:
323 :ref:`METH_VARARGS | METH_KEYWORDS <METH_VARARGS-METH_KEYWORDS>`,
324 :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>` and
325 :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`.
326
327
328 .. _METH_VARARGS-METH_KEYWORDS:
329
330 :c:expr:`METH_VARARGS | METH_KEYWORDS`
331 Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
332 The function expects three parameters: *self*, *args*, *kwargs* where
333 *kwargs* is a dictionary of all the keyword arguments or possibly ``NULL``
334 if there are no keyword arguments. The parameters are typically processed
335 using :c:func:`PyArg_ParseTupleAndKeywords`.
336
337
338 .. c:macro:: METH_FASTCALL
339
340 Fast calling convention supporting only positional arguments.
341 The methods have the type :c:type:`PyCFunctionFast`.
342 The first parameter is *self*, the second parameter is a C array
343 of :c:expr:`PyObject*` values indicating the arguments and the third
344 parameter is the number of arguments (the length of the array).
345
346 .. versionadded:: 3.7
347
348 .. versionchanged:: 3.10
349
350 ``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`.
351
352
353 .. _METH_FASTCALL-METH_KEYWORDS:
354
355 :c:expr:`METH_FASTCALL | METH_KEYWORDS`
356 Extension of :c:macro:`METH_FASTCALL` supporting also keyword arguments,
357 with methods of type :c:type:`PyCFunctionFastWithKeywords`.
358 Keyword arguments are passed the same way as in the
359 :ref:`vectorcall protocol <vectorcall>`:
360 there is an additional fourth :c:expr:`PyObject*` parameter
361 which is a tuple representing the names of the keyword arguments
362 (which are guaranteed to be strings)
363 or possibly ``NULL`` if there are no keywords. The values of the keyword
364 arguments are stored in the *args* array, after the positional arguments.
365
366 .. versionadded:: 3.7
367
368
369 .. c:macro:: METH_METHOD
370
371 Can only be used in the combination with other flags:
372 :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`.
373
374
375 .. _METH_METHOD-METH_FASTCALL-METH_KEYWORDS:
376
377 :c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`
378 Extension of :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>`
379 supporting the *defining class*, that is,
380 the class that contains the method in question.
381 The defining class might be a superclass of ``Py_TYPE(self)``.
382
383 The method needs to be of type :c:type:`PyCMethod`, the same as for
384 ``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added after
385 ``self``.
386
387 .. versionadded:: 3.9
388
389
390 .. c:macro:: METH_NOARGS
391
392 Methods without parameters don't need to check whether arguments are given if
393 they are listed with the :c:macro:`METH_NOARGS` flag. They need to be of type
394 :c:type:`PyCFunction`. The first parameter is typically named *self* and will
395 hold a reference to the module or object instance. In all cases the second
396 parameter will be ``NULL``.
397
398 The function must have 2 parameters. Since the second parameter is unused,
399 :c:macro:`Py_UNUSED` can be used to prevent a compiler warning.
400
401
402 .. c:macro:: METH_O
403
404 Methods with a single object argument can be listed with the :c:macro:`METH_O`
405 flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
406 They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
407 :c:expr:`PyObject*` parameter representing the single argument.
408
409
410 These two constants are not used to indicate the calling convention but the
411 binding when used with methods of classes. These may not be used for functions
412 defined for modules. At most one of these flags may be set for any given
413 method.
414
415
416 .. c:macro:: METH_CLASS
417
418 .. index:: pair: built-in function; classmethod
419
420 The method will be passed the type object as the first parameter rather
421 than an instance of the type. This is used to create *class methods*,
422 similar to what is created when using the :func:`classmethod` built-in
423 function.
424
425
426 .. c:macro:: METH_STATIC
427
428 .. index:: pair: built-in function; staticmethod
429
430 The method will be passed ``NULL`` as the first parameter rather than an
431 instance of the type. This is used to create *static methods*, similar to
432 what is created when using the :func:`staticmethod` built-in function.
433
434 One other constant controls whether a method is loaded in place of another
435 definition with the same method name.
436
437
438 .. c:macro:: METH_COEXIST
439
440 The method will be loaded in place of existing definitions. Without
441 *METH_COEXIST*, the default is to skip repeated definitions. Since slot
442 wrappers are loaded before the method table, the existence of a
443 *sq_contains* slot, for example, would generate a wrapped method named
444 :meth:`~object.__contains__` and preclude the loading of a corresponding
445 PyCFunction with the same name. With the flag defined, the PyCFunction
446 will be loaded in place of the wrapper object and will co-exist with the
447 slot. This is helpful because calls to PyCFunctions are optimized more
448 than wrapper object calls.
449
450
451 .. c:var:: PyTypeObject PyCMethod_Type
452
453 The type object corresponding to Python C method objects. This is
454 available as :class:`types.BuiltinMethodType` in the Python layer.
455
456
457 .. c:function:: int PyCMethod_Check(PyObject *op)
458
459 Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type
460 or a subtype of it. This function always succeeds.
461
462
463 .. c:function:: int PyCMethod_CheckExact(PyObject *op)
464
465 This is the same as :c:func:`PyCMethod_Check`, but does not account for
466 subtypes.
467
468
469 .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
470
471 Turn *ml* into a Python :term:`callable` object.
472 The caller must ensure that *ml* outlives the :term:`callable`.
473 Typically, *ml* is defined as a static variable.
474
475 The *self* parameter will be passed as the *self* argument
476 to the C function in ``ml->ml_meth`` when invoked.
477 *self* can be ``NULL``.
478
479 The :term:`callable` object's ``__module__`` attribute
480 can be set from the given *module* argument.
481 *module* should be a Python string,
482 which will be used as name of the module the function is defined in.
483 If unavailable, it can be set to :const:`None` or ``NULL``.
484
485 .. seealso:: :attr:`function.__module__`
486
487 The *cls* parameter will be passed as the *defining_class*
488 argument to the C function.
489 Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``.
490
491 .. versionadded:: 3.9
492
493
494 .. c:var:: PyTypeObject PyCFunction_Type
495
496 The type object corresponding to Python C function objects. This is
497 available as :class:`types.BuiltinFunctionType` in the Python layer.
498
499
500 .. c:function:: int PyCFunction_Check(PyObject *op)
501
502 Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type
503 or a subtype of it. This function always succeeds.
504
505
506 .. c:function:: int PyCFunction_CheckExact(PyObject *op)
507
508 This is the same as :c:func:`PyCFunction_Check`, but does not account for
509 subtypes.
510
511
512 .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
513
514 Equivalent to ``PyCMethod_New(ml, self, module, NULL)``.
515
516
517 .. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self)
518
519 Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``.
520
521
522 .. c:function:: int PyCFunction_GetFlags(PyObject *func)
523
524 Get the function's flags on *func* as they were passed to
525 :c:member:`~PyMethodDef.ml_flags`.
526
527 If *func* is not a C function object, this fails with an exception.
528 *func* must not be ``NULL``.
529
530 This function returns the function's flags on success, and ``-1`` with an
531 exception set on failure.
532
533
534 .. c:function:: int PyCFunction_GET_FLAGS(PyObject *func)
535
536 This is the same as :c:func:`PyCFunction_GetFlags`, but without error
537 or type checking.
538
539
540 .. c:function:: PyCFunction PyCFunction_GetFunction(PyObject *func)
541
542 Get the function pointer on *func* as it was passed to
543 :c:member:`~PyMethodDef.ml_meth`.
544
545 If *func* is not a C function object, this fails with an exception.
546 *func* must not be ``NULL``.
547
548 This function returns the function pointer on success, and ``NULL`` with an
549 exception set on failure.
550
551
552 .. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func)
553
554 This is the same as :c:func:`PyCFunction_GetFunction`, but without error
555 or type checking.
556
557
558 .. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func)
559
560 Get the "self" object on *func*. This is the object that would be passed
561 to the first argument of a :c:type:`PyCFunction`. For C function objects
562 created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this
563 is the resulting module object.
564
565 If *func* is not a C function object, this fails with an exception.
566 *func* must not be ``NULL``.
567
568 This function returns a :term:`borrowed reference` to the "self" object
569 on success, and ``NULL`` with an exception set on failure.
570
571
572 .. c:function:: PyObject *PyCFunction_GET_SELF(PyObject *func)
573
574 This is the same as :c:func:`PyCFunction_GetSelf`, but without error or
575 type checking.
576
577
578 Accessing attributes of extension types
579 ---------------------------------------
580
581 .. c:type:: PyMemberDef
582
583 Structure which describes an attribute of a type which corresponds to a C
584 struct member.
585 When defining a class, put a NULL-terminated array of these
586 structures in the :c:member:`~PyTypeObject.tp_members` slot.
587
588 Its fields are, in order:
589
590 .. c:member:: const char* name
591
592 Name of the member.
593 A NULL value marks the end of a ``PyMemberDef[]`` array.
594
595 The string should be static, no copy is made of it.
596
597 .. c:member:: int type
598
599 The type of the member in the C struct.
600 See :ref:`PyMemberDef-types` for the possible values.
601
602 .. c:member:: Py_ssize_t offset
603
604 The offset in bytes that the member is located on the type’s object struct.
605
606 .. c:member:: int flags
607
608 Zero or more of the :ref:`PyMemberDef-flags`, combined using bitwise OR.
609
610 .. c:member:: const char* doc
611
612 The docstring, or NULL.
613 The string should be static, no copy is made of it.
614 Typically, it is defined using :c:macro:`PyDoc_STR`.
615
616 By default (when :c:member:`~PyMemberDef.flags` is ``0``), members allow
617 both read and write access.
618 Use the :c:macro:`Py_READONLY` flag for read-only access.
619 Certain types, like :c:macro:`Py_T_STRING`, imply :c:macro:`Py_READONLY`.
620 Only :c:macro:`Py_T_OBJECT_EX` (and legacy :c:macro:`T_OBJECT`) members can
621 be deleted.
622
623 .. _pymemberdef-offsets:
624
625 For heap-allocated types (created using :c:func:`PyType_FromSpec` or similar),
626 ``PyMemberDef`` may contain a definition for the special member
627 ``"__vectorcalloffset__"``, corresponding to
628 :c:member:`~PyTypeObject.tp_vectorcall_offset` in type objects.
629 This member must be defined with ``Py_T_PYSSIZET``, and either
630 ``Py_READONLY`` or ``Py_READONLY | Py_RELATIVE_OFFSET``. For example::
631
632 static PyMemberDef spam_type_members[] = {
633 {"__vectorcalloffset__", Py_T_PYSSIZET,
634 offsetof(Spam_object, vectorcall), Py_READONLY},
635 {NULL} /* Sentinel */
636 };
637
638 (You may need to ``#include <stddef.h>`` for :c:func:`!offsetof`.)
639
640 The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and
641 :c:member:`~PyTypeObject.tp_weaklistoffset` can be defined similarly using
642 ``"__dictoffset__"`` and ``"__weaklistoffset__"`` members, but extensions
643 are strongly encouraged to use :c:macro:`Py_TPFLAGS_MANAGED_DICT` and
644 :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead.
645
646 .. versionchanged:: 3.12
647
648 ``PyMemberDef`` is always available.
649 Previously, it required including ``"structmember.h"``.
650
651 .. versionchanged:: 3.14
652
653 :c:macro:`Py_RELATIVE_OFFSET` is now allowed for
654 ``"__vectorcalloffset__"``, ``"__dictoffset__"`` and
655 ``"__weaklistoffset__"``.
656
657 .. c:function:: PyObject* PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)
658
659 Get an attribute belonging to the object at address *obj_addr*. The
660 attribute is described by ``PyMemberDef`` *m*. Returns ``NULL``
661 on error.
662
663 .. versionchanged:: 3.12
664
665 ``PyMember_GetOne`` is always available.
666 Previously, it required including ``"structmember.h"``.
667
668 .. c:function:: int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
669
670 Set an attribute belonging to the object at address *obj_addr* to object *o*.
671 The attribute to set is described by ``PyMemberDef`` *m*. Returns ``0``
672 if successful and a negative value on failure.
673
674 .. versionchanged:: 3.12
675
676 ``PyMember_SetOne`` is always available.
677 Previously, it required including ``"structmember.h"``.
678
679 .. _PyMemberDef-flags:
680
681 Member flags
682 ^^^^^^^^^^^^
683
684 The following flags can be used with :c:member:`PyMemberDef.flags`:
685
686 .. c:macro:: Py_READONLY
687
688 Not writable.
689
690 .. c:macro:: Py_AUDIT_READ
691
692 Emit an ``object.__getattr__`` :ref:`audit event <audit-events>`
693 before reading.
694
695 .. c:macro:: Py_RELATIVE_OFFSET
696
697 Indicates that the :c:member:`~PyMemberDef.offset` of this ``PyMemberDef``
698 entry indicates an offset from the subclass-specific data, rather than
699 from ``PyObject``.
700
701 Can only be used as part of the :c:data:`Py_tp_members`
702 :c:type:`slot <PyType_Slot>` when creating a class using negative
703 :c:member:`~PyType_Spec.basicsize`.
704 It is mandatory in that case.
705 When setting :c:member:`~PyTypeObject.tp_members` from the slot during
706 class creation, Python clears the flag and sets
707 :c:member:`PyMemberDef.offset` to the offset from the ``PyObject`` struct.
708
709 .. index::
710 single: READ_RESTRICTED (C macro)
711 single: WRITE_RESTRICTED (C macro)
712 single: RESTRICTED (C macro)
713
714 .. versionchanged:: 3.10
715
716 The :c:macro:`!RESTRICTED`, :c:macro:`!READ_RESTRICTED` and
717 :c:macro:`!WRITE_RESTRICTED` macros available with
718 ``#include "structmember.h"`` are deprecated.
719 :c:macro:`!READ_RESTRICTED` and :c:macro:`!RESTRICTED` are equivalent to
720 :c:macro:`Py_AUDIT_READ`; :c:macro:`!WRITE_RESTRICTED` does nothing.
721
722 .. index::
723 single: READONLY (C macro)
724
725 .. versionchanged:: 3.12
726
727 The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`.
728 The :c:macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix.
729 The new names are now always available.
730 Previously, these required ``#include "structmember.h"``.
731 The header is still available and it provides the old names.
732
733 .. _PyMemberDef-types:
734
735 Member types
736 ^^^^^^^^^^^^
737
738 :c:member:`PyMemberDef.type` can be one of the following macros corresponding
739 to various C types.
740 When the member is accessed in Python, it will be converted to the
741 equivalent Python type.
742 When it is set from Python, it will be converted back to the C type.
743 If that is not possible, an exception such as :exc:`TypeError` or
744 :exc:`ValueError` is raised.
745
746 Unless marked (D), attributes defined this way cannot be deleted
747 using e.g. :keyword:`del` or :py:func:`delattr`.
748
749 ================================ ============================= ======================
750 Macro name C type Python type
751 ================================ ============================= ======================
752 .. c:macro:: Py_T_BYTE :c:expr:`char` :py:class:`int`
753 .. c:macro:: Py_T_SHORT :c:expr:`short` :py:class:`int`
754 .. c:macro:: Py_T_INT :c:expr:`int` :py:class:`int`
755 .. c:macro:: Py_T_LONG :c:expr:`long` :py:class:`int`
756 .. c:macro:: Py_T_LONGLONG :c:expr:`long long` :py:class:`int`
757 .. c:macro:: Py_T_UBYTE :c:expr:`unsigned char` :py:class:`int`
758 .. c:macro:: Py_T_UINT :c:expr:`unsigned int` :py:class:`int`
759 .. c:macro:: Py_T_USHORT :c:expr:`unsigned short` :py:class:`int`
760 .. c:macro:: Py_T_ULONG :c:expr:`unsigned long` :py:class:`int`
761 .. c:macro:: Py_T_ULONGLONG :c:expr:`unsigned long long` :py:class:`int`
762 .. c:macro:: Py_T_PYSSIZET :c:expr:`Py_ssize_t` :py:class:`int`
763 .. c:macro:: Py_T_FLOAT :c:expr:`float` :py:class:`float`
764 .. c:macro:: Py_T_DOUBLE :c:expr:`double` :py:class:`float`
765 .. c:macro:: Py_T_BOOL :c:expr:`char` :py:class:`bool`
766 (written as 0 or 1)
767 .. c:macro:: Py_T_STRING :c:expr:`const char *` (*) :py:class:`str` (RO)
768 .. c:macro:: Py_T_STRING_INPLACE :c:expr:`const char[]` (*) :py:class:`str` (RO)
769 .. c:macro:: Py_T_CHAR :c:expr:`char` (0-127) :py:class:`str` (**)
770 .. c:macro:: Py_T_OBJECT_EX :c:expr:`PyObject *` :py:class:`object` (D)
771 ================================ ============================= ======================
772
773 (*): Zero-terminated, UTF8-encoded C string.
774 With :c:macro:`!Py_T_STRING` the C representation is a pointer;
775 with :c:macro:`!Py_T_STRING_INPLACE` the string is stored directly
776 in the structure.
777
778 (**): String of length 1. Only ASCII is accepted.
779
780 (RO): Implies :c:macro:`Py_READONLY`.
781
782 (D): Can be deleted, in which case the pointer is set to ``NULL``.
783 Reading a ``NULL`` pointer raises :py:exc:`AttributeError`.
784
785 .. index::
786 single: T_BYTE (C macro)
787 single: T_SHORT (C macro)
788 single: T_INT (C macro)
789 single: T_LONG (C macro)
790 single: T_LONGLONG (C macro)
791 single: T_UBYTE (C macro)
792 single: T_USHORT (C macro)
793 single: T_UINT (C macro)
794 single: T_ULONG (C macro)
795 single: T_ULONGULONG (C macro)
796 single: T_PYSSIZET (C macro)
797 single: T_FLOAT (C macro)
798 single: T_DOUBLE (C macro)
799 single: T_BOOL (C macro)
800 single: T_CHAR (C macro)
801 single: T_STRING (C macro)
802 single: T_STRING_INPLACE (C macro)
803 single: T_OBJECT_EX (C macro)
804 single: structmember.h
805
806 .. versionadded:: 3.12
807
808 In previous versions, the macros were only available with
809 ``#include "structmember.h"`` and were named without the ``Py_`` prefix
810 (e.g. as ``T_INT``).
811 The header is still available and contains the old names, along with
812 the following deprecated types:
813
814 .. c:macro:: T_OBJECT
815
816 Like ``Py_T_OBJECT_EX``, but ``NULL`` is converted to ``None``.
817 This results in surprising behavior in Python: deleting the attribute
818 effectively sets it to ``None``.
819
820 .. c:macro:: T_NONE
821
822 Always ``None``. Must be used with :c:macro:`Py_READONLY`.
823
824 Defining Getters and Setters
825 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
826
827 .. c:type:: PyGetSetDef
828
829 Structure to define property-like access for a type. See also description of
830 the :c:member:`PyTypeObject.tp_getset` slot.
831
832 .. c:member:: const char* name
833
834 attribute name
835
836 .. c:member:: getter get
837
838 C function to get the attribute.
839
840 .. c:member:: setter set
841
842 Optional C function to set or delete the attribute.
843 If ``NULL``, the attribute is read-only.
844
845 .. c:member:: const char* doc
846
847 optional docstring
848
849 .. c:member:: void* closure
850
851 Optional user data pointer, providing additional data for getter and setter.
852
853 .. c:type:: PyObject *(*getter)(PyObject *, void *)
854
855 The ``get`` function takes one :c:expr:`PyObject*` parameter (the
856 instance) and a user data pointer (the associated ``closure``):
857
858 It should return a new reference on success or ``NULL`` with a set exception
859 on failure.
860
861 .. c:type:: int (*setter)(PyObject *, PyObject *, void *)
862
863 ``set`` functions take two :c:expr:`PyObject*` parameters (the instance and
864 the value to be set) and a user data pointer (the associated ``closure``):
865
866 In case the attribute should be deleted the second parameter is ``NULL``.
867 Should return ``0`` on success or ``-1`` with a set exception on failure.