@@ -537,6 +537,9 @@ PyVarObject Slots
537537 initialized to zero. For :ref: `dynamically allocated type objects
538538 <heap-types>`, this field has a special internal meaning.
539539
540+ This field should be accessed using the :c:func: `Py_SIZE() ` and
541+ :c:func: `Py_SET_SIZE() ` macros.
542+
540543 **Inheritance: **
541544
542545 This field is not inherited by subtypes.
@@ -587,47 +590,86 @@ and :c:data:`PyType_Type` effectively act as defaults.)
587590
588591
589592.. c :member :: Py_ssize_t PyTypeObject.tp_basicsize
590- Py_ssize_t PyTypeObject.tp_itemsize
593+ Py_ssize_t PyTypeObject.tp_itemsize
591594
592595
593596
594597 There are two kinds of types: types with fixed-length instances have a zero
595- :c:member: `~PyTypeObject.tp_itemsize ` field, types with variable-length instances have a non-zero
596- :c:member: `~PyTypeObject.tp_itemsize ` field. For a type with fixed-length instances, all
597- instances have the same size, given in :c:member: `~PyTypeObject.tp_basicsize `.
598+ :c:member: `!tp_itemsize ` field, types with variable-length instances have a non-zero
599+ :c:member: `!tp_itemsize ` field. For a type with fixed-length instances, all
600+ instances have the same size, given in :c:member: `!tp_basicsize `.
601+ (Exceptions to this rule can be made using
602+ :c:func: `PyUnstable_Object_GC_NewWithExtraData `.)
598603
599604 For a type with variable-length instances, the instances must have an
600- :c:member: `~PyVarObject.ob_size ` field, and the instance size is :c:member: `~PyTypeObject.tp_basicsize ` plus N
601- times :c:member: `~PyTypeObject.tp_itemsize `, where N is the "length" of the object. The value of
602- N is typically stored in the instance's :c:member: `~PyVarObject.ob_size ` field. There are
603- exceptions: for example, ints use a negative :c:member: `~PyVarObject.ob_size ` to indicate a
604- negative number, and N is ``abs(ob_size) `` there. Also, the presence of an
605- :c:member: `~PyVarObject.ob_size ` field in the instance layout doesn't mean that the instance
606- structure is variable-length (for example, the structure for the list type has
607- fixed-length instances, yet those instances have a meaningful :c:member: `~PyVarObject.ob_size `
608- field).
609-
610- The basic size includes the fields in the instance declared by the macro
611- :c:macro: `PyObject_HEAD ` or :c:macro: `PyObject_VAR_HEAD ` (whichever is used to
612- declare the instance struct) and this in turn includes the :c:member: `~PyObject._ob_prev ` and
613- :c:member: `~PyObject._ob_next ` fields if they are present. This means that the only correct
614- way to get an initializer for the :c:member: `~PyTypeObject.tp_basicsize ` is to use the
615- ``sizeof `` operator on the struct used to declare the instance layout.
616- The basic size does not include the GC header size.
605+ :c:member: `~PyVarObject.ob_size ` field, and the instance size is
606+ :c:member: `!tp_basicsize ` plus N times :c:member: `!tp_itemsize `,
607+ where N is the "length" of the object.
608+
609+ Functions like :c:func: `PyObject_NewVar ` will take the value of N as an
610+ argument, and store in the instance's :c:member: `~PyVarObject.ob_size ` field.
611+ Note that the :c:member: `~PyVarObject.ob_size ` field may later be used for
612+ other purposes. For example, :py:type: `int ` instances use the bits of
613+ :c:member: `~PyVarObject.ob_size ` in an implementation-defined
614+ way; the underlying storage and its size should be acessed using
615+ :c:func: `PyLong_Export `.
616+
617+ .. note ::
617618
618- A note about alignment: if the variable items require a particular alignment,
619- this should be taken care of by the value of :c:member: `~PyTypeObject.tp_basicsize `. Example:
620- suppose a type implements an array of ``double ``. :c:member: `~PyTypeObject.tp_itemsize ` is
621- ``sizeof(double) ``. It is the programmer's responsibility that
622- :c:member: `~PyTypeObject.tp_basicsize ` is a multiple of ``sizeof(double) `` (assuming this is the
623- alignment requirement for ``double ``).
619+ The :c:member: `~PyVarObject.ob_size ` field should be accessed using
620+ the :c:func: `Py_SIZE() ` and :c:func: `Py_SET_SIZE() ` macros.
624621
625- For any type with variable-length instances, this field must not be ``NULL ``.
622+ Also, the presence of an :c:member: `~PyVarObject.ob_size ` field in the
623+ instance layout doesn't mean that the instance structure is variable-length.
624+ For example, the :py:type: `list ` type has fixed-length instances, yet those
625+ instances have a :c:member: `~PyVarObject.ob_size ` field.
626+ (As with :py:type: `int `, avoid reading lists' :c:member: `!ob_size ` directly.
627+ Call :c:func: `PyList_Size ` instead.)
628+
629+ The :c:member: `!tp_basicsize ` includes size needed for data of the type's
630+ :c:member: `~PyTypeObject.tp_base `, plus any extra data needed
631+ by each instance.
632+
633+ The correct way to set :c:member: `!tp_basicsize ` is to use the
634+ ``sizeof `` operator on the struct used to declare the instance layout.
635+ This struct must include the struct used to declare the base type.
636+ In other words, :c:member: `!tp_basicsize ` must be greater than or equal
637+ to the base's :c:member: `!tp_basicsize `.
638+
639+ Since every type is a subtype of :py:type: `object `, this struct must
640+ include :c:type: `PyObject ` or :c:type: `PyVarObject ` (depending on
641+ whether :c:member: `~PyVarObject.ob_size ` should be included). These are
642+ usually defined by the macro :c:macro: `PyObject_HEAD ` or
643+ :c:macro: `PyObject_VAR_HEAD `, respectively.
644+
645+ The basic size does not include the GC header size, as that header is not
646+ part of :c:macro: `PyObject_HEAD `.
647+
648+ For cases where struct used to declare the base type is unknown,
649+ see :c:member: `PyType_Spec.basicsize ` and :c:func: `PyType_FromMetaclass `.
650+
651+ Notes about alignment:
652+
653+ - :c:member: `!tp_basicsize ` must be a multiple of ``_Alignof(PyObject) ``.
654+ When using ``sizeof `` on a ``struct `` that includes
655+ :c:macro: `PyObject_HEAD `, as recommended, the compiler ensures this.
656+ When not using a C ``struct ``, or when using compiler
657+ extensions like ``__attribute__((packed)) ``, it is up to you.
658+ - If the variable items require a particular alignment,
659+ :c:member: `!tp_basicsize ` and :c:member: `!tp_itemsize ` must each be a
660+ multiple of that alignment.
661+ For example, if a type's variable part stores a ``double ``, it is
662+ your responsibility that both fields are a multiple of
663+ ``_Alignof(double) ``.
626664
627665 **Inheritance: **
628666
629- These fields are inherited separately by subtypes. If the base type has a
630- non-zero :c:member: `~PyTypeObject.tp_itemsize `, it is generally not safe to set
667+ These fields are inherited separately by subtypes.
668+ (That is, if the field is set to zero, :c:func: `PyType_Ready ` will copy
669+ the value from the base type, indicating that the instances do not
670+ need additional storage.)
671+
672+ If the base type has a non-zero :c:member: `~PyTypeObject.tp_itemsize `, it is generally not safe to set
631673 :c:member: `~PyTypeObject.tp_itemsize ` to a different non-zero value in a subtype (though this
632674 depends on the implementation of the base type).
633675
0 commit comments