May 20, 2025 · May 20, 2025
diff --git a/.gitattributes b/.gitattributes
 *.icobinary
 *.jpgbinary
 *.pckbinary
 *.pdfbinary
 *.pngbinary
 *.psdbinary
 *.tarbinary
 **/clinic/*.cpp.hgenerated
 **/clinic/*.h.hgenerated
 *_db.hgenerated
 Doc/c-api/lifecycle.dot.svggenerated
 Doc/data/stable_abi.datgenerated
 Doc/library/token-list.incgenerated
 Include/internal/pycore_ast.hgenerated
diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst

   Initialize a newly allocated object *op* with its type and initial
   reference.  Returns the initialized object.  Other fields of the object are
   not affected.
   not initialized.  Despite its name, this function is unrelated to the
   object's:meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init`
   slot).  Specifically, this function does **not** call the object's
   :meth:`!__init__` method.

   In general, consider this function to be a low-level routine. Use
   :c:member:`~PyTypeObject.tp_alloc` where possible.
   For implementing :c:member:`!tp_alloc` for your type, prefer
   :c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.

   .. note::

      This function only initializes the object's memory corresponding to the
      initial :c:type:`PyObject` structure.  It does not zero the rest.


 .. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)

   This does everything:c:func:`PyObject_Init` does, and also initializes the
   length information for a variable-size object.

   ..note::

      This function only initializes some of the object's memory.  It does not
      zero the rest.


 ..c:macro:: PyObject_New(TYPE, typeobj)

   Allocate a new Python object using the C structure type *TYPE*
   and the Python type object *typeobj* (``PyTypeObject*``).
   Fields not defined by the Python object header are not initialized.
   The caller will own the only reference to the object
   (i.e. its reference count will be one).
   The size of the memory allocation is determined from the
   :c:member:`~PyTypeObject.tp_basicsize` field of the type object.
   Allocates a new Python object using the C structure type *TYPE* and the
   Python type object *typeobj* (``PyTypeObject*``) by calling
   :c:func:`PyObject_Malloc` to allocate memory and initializing it like
   :c:func:`PyObject_Init`.  The caller will own the only reference to the
   object (i.e. its reference count will be one).

   Avoid calling this directly to allocate memory for an object; call the type's
   :c:member:`~PyTypeObject.tp_alloc` slot instead.

   When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
 :c:func:`PyType_GenericAlloc` is preferred over a custom function that
   simply calls this macro.

   This macro does not call:c:member:`~PyTypeObject.tp_alloc`,
 :c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
   :c:member:`~PyTypeObject.tp_init` (:meth:`~object.__init__`).

   This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
   :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.

   Memory allocated by this macro must be freed with:c:func:`PyObject_Free`
   (usually called via the object's:c:member:`~PyTypeObject.tp_free` slot).

   .. note::

      The returned memory is not guaranteed to have been completely zeroed
      before it was initialized.

   .. note::

      This macro does not construct a fully initialized object of the given
      type; it merely allocates memory and prepares itfor further
      initialization by :c:member:`~PyTypeObject.tp_init`.  To construct a
      fully initialized object, call *typeobj* instead.  For example::

         PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);

   Note that this function is unsuitable if *typeobj* has
   :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
   use :c:func:`PyObject_GC_New` instead.
   ..seealso::

      *:c:func:`PyObject_Free`
      *:c:macro:`PyObject_GC_New`
      *:c:func:`PyType_GenericAlloc`
      *:c:member:`~PyTypeObject.tp_alloc`


 ..c:macro:: PyObject_NewVar(TYPE, typeobj, size)

   Allocate a new Python object using the C structure type *TYPE* and the
   Python type object *typeobj* (``PyTypeObject*``).
   Fields not defined by the Python object header
   are not initialized.  The allocated memory allows for the *TYPE* structure
   plus *size* (``Py_ssize_t``) fields of the size
   given by the :c:member:`~PyTypeObject.tp_itemsize` field of
   *typeobj*.  This is useful for implementing objects like tuples, which are
   able to determine their size at construction time.  Embedding the array of
   fields into the same allocation decreases the number of allocations,
   improving the memory management efficiency.

   Note that this function is unsuitable if *typeobj* has
   :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
   use :c:func:`PyObject_GC_NewVar` instead.
   Like:c:macro:`PyObject_New` except:

   * It allocates enough memory for the *TYPE* structure plus *size*
     (``Py_ssize_t``) fields of the size given by the
 :c:member:`~PyTypeObject.tp_itemsize` field of *typeobj*.
   * The memory is initialized like:c:func:`PyObject_InitVar`.

   This is useful for implementing objects like tuples, which are able to
   determine their size at construction time.  Embedding the array of fields
   into the same allocation decreases the number of allocations, improving the
   memory management efficiency.

   Avoid calling this directly to allocate memory for an object; call the type's
 :c:member:`~PyTypeObject.tp_alloc` slot instead.

   When populating a type's:c:member:`~PyTypeObject.tp_alloc` slot,
 :c:func:`PyType_GenericAlloc` is preferred over a custom function that
   simply calls this macro.

   This cannot be used for objects with:c:macro:`Py_TPFLAGS_HAVE_GC` set in
 :c:member:`~PyTypeObject.tp_flags`; use:c:macro:`PyObject_GC_NewVar`
   instead.

   Memory allocated by this function must be freed with:c:func:`PyObject_Free`
   (usually called via the object's:c:member:`~PyTypeObject.tp_free` slot).

   ..note::

      The returned memory is not guaranteed to have been completely zeroed
      before it was initialized.

   ..note::

      This macro does not construct a fully initialized object of the given
      type; it merely allocates memory and prepares it for further
      initialization by:c:member:`~PyTypeObject.tp_init`.  To construct a
      fully initialized object, call *typeobj* instead.  For example::

         PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);

   ..seealso::

      *:c:func:`PyObject_Free`
      *:c:macro:`PyObject_GC_NewVar`
      *:c:func:`PyType_GenericAlloc`
      *:c:member:`~PyTypeObject.tp_alloc`


 ..c:function::voidPyObject_Del(void *op)
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
   Analogous to:c:macro:`PyObject_New` but for container objects with the
 :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.

   Do not call this directly to allocate memory for an object; call the type's
 :c:member:`~PyTypeObject.tp_alloc` slot instead.

   When populating a type's:c:member:`~PyTypeObject.tp_alloc` slot,
 :c:func:`PyType_GenericAlloc` is preferred over a custom function that
   simply calls this macro.

   Memory allocated by this macro must be freed with
 :c:func:`PyObject_GC_Del` (usually called via the object's
 :c:member:`~PyTypeObject.tp_free` slot).

   ..seealso::

      *:c:func:`PyObject_GC_Del`
      *:c:macro:`PyObject_New`
      *:c:func:`PyType_GenericAlloc`
      *:c:member:`~PyTypeObject.tp_alloc`


 ..c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)

   Analogous to:c:macro:`PyObject_NewVar` but for container objects with the
 :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.

   Do not call this directly to allocate memory for an object; call the type's
 :c:member:`~PyTypeObject.tp_alloc` slot instead.

   When populating a type's:c:member:`~PyTypeObject.tp_alloc` slot,
 :c:func:`PyType_GenericAlloc` is preferred over a custom function that
   simply calls this macro.

   Memory allocated by this macro must be freed with
 :c:func:`PyObject_GC_Del` (usually called via the object's
 :c:member:`~PyTypeObject.tp_free` slot).

   ..seealso::

      *:c:func:`PyObject_GC_Del`
      *:c:macro:`PyObject_NewVar`
      *:c:func:`PyType_GenericAlloc`
      *:c:member:`~PyTypeObject.tp_alloc`


 ..c:function:: PyObject*PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)

   Analogous to:c:macro:`PyObject_GC_New` but allocates *extra_size*
   The extra data will be deallocated with the object, but otherwise it is
   not managed by Python.

   Memory allocated by this function must be freed with
   :c:func:`PyObject_GC_Del` (usually called via the object's
 :c:member:`~PyTypeObject.tp_free` slot).

   .. warning::
      The function is marked as unstable because thefinal mechanism
      for reserving extra data after an instance is not yet decided.
   Releases memory allocated to an object using:c:macro:`PyObject_GC_New` or
 :c:macro:`PyObject_GC_NewVar`.

   Do not call this directly to free an object's memory; call the type's
 :c:member:`~PyTypeObject.tp_free` slot instead.

   Do not use this for memory allocated by:c:macro:`PyObject_New`,
 :c:macro:`PyObject_NewVar`, or related allocation functions; use
 :c:func:`PyObject_Free` instead.

   ..seealso::

      *:c:func:`PyObject_Free` is the non-GC equivalent of this function.
      *:c:macro:`PyObject_GC_New`
      *:c:macro:`PyObject_GC_NewVar`
      *:c:func:`PyType_GenericAlloc`
      *:c:member:`~PyTypeObject.tp_free`


 ..c:function::voidPyObject_GC_UnTrack(void *op)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,6 +10,7 @@
		*.icobinary
		*.jpgbinary
		*.pckbinary
		*.pdfbinary
		*.pngbinary
		*.psdbinary
		*.tarbinary
Expand DownExpand Up		@@ -67,6 +68,7 @@ PCbuild/readme.txt dos
		*/clinic/.cpp.hgenerated
		*/clinic/.h.hgenerated
		*_db.hgenerated
		Doc/c-api/lifecycle.dot.svggenerated
		Doc/data/stable_abi.datgenerated
		Doc/library/token-list.incgenerated
		Include/internal/pycore_ast.hgenerated
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,46 +16,128 @@ Allocating Objects on the Heap

		Initialize a newly allocated object op with its type and initial
		reference. Returns the initialized object. Other fields of the object are
		not affected.
		not initialized. Despite its name, this function is unrelated to the
		object's:meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init`
		slot). Specifically, this function does not call the object's
		:meth:`!__init__` method.

		In general, consider this function to be a low-level routine. Use
		:c:member:`~PyTypeObject.tp_alloc` where possible.
		For implementing :c:member:`!tp_alloc` for your type, prefer
		:c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.

		.. note::

		This function only initializes the object's memory corresponding to the
		initial :c:type:`PyObject` structure. It does not zero the rest.


		.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject op, PyTypeObject type, Py_ssize_t size)

		This does everything:c:func:`PyObject_Init` does, and also initializes the
		length information for a variable-size object.

		..note::

		This function only initializes some of the object's memory. It does not
		zero the rest.


		..c:macro:: PyObject_New(TYPE, typeobj)

		Allocate a new Python object using the C structure type TYPE
		and the Python type object typeobj (``PyTypeObject*``).
		Fields not defined by the Python object header are not initialized.
		The caller will own the only reference to the object
		(i.e. its reference count will be one).
		The size of the memory allocation is determined from the
		:c:member:`~PyTypeObject.tp_basicsize` field of the type object.
		Allocates a new Python object using the C structure type TYPE and the
		Python type object typeobj (``PyTypeObject*``) by calling
		:c:func:`PyObject_Malloc` to allocate memory and initializing it like
		:c:func:`PyObject_Init`. The caller will own the only reference to the
		object (i.e. its reference count will be one).

		Avoid calling this directly to allocate memory for an object; call the type's
		:c:member:`~PyTypeObject.tp_alloc` slot instead.

		When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
		:c:func:`PyType_GenericAlloc` is preferred over a custom function that
		simply calls this macro.

		This macro does not call:c:member:`~PyTypeObject.tp_alloc`,
		:c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
		:c:member:`~PyTypeObject.tp_init` (:meth:`~object.__init__`).

		This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
		:c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.

		Memory allocated by this macro must be freed with:c:func:`PyObject_Free`
		(usually called via the object's:c:member:`~PyTypeObject.tp_free` slot).

		.. note::

		The returned memory is not guaranteed to have been completely zeroed
		before it was initialized.

		.. note::

		This macro does not construct a fully initialized object of the given
		type; it merely allocates memory and prepares itfor further
		initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
		fully initialized object, call typeobj instead. For example::

		PyObject foo = PyObject_CallNoArgs((PyObject )&PyFoo_Type);

		Note that this function is unsuitable if typeobj has
		:c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
		use :c:func:`PyObject_GC_New` instead.
		..seealso::

		*:c:func:`PyObject_Free`
		*:c:macro:`PyObject_GC_New`
		*:c:func:`PyType_GenericAlloc`
		*:c:member:`~PyTypeObject.tp_alloc`


		..c:macro:: PyObject_NewVar(TYPE, typeobj, size)

		Allocate a new Python object using the C structure type TYPE and the
		Python type object typeobj (``PyTypeObject*``).
		Fields not defined by the Python object header
		are not initialized. The allocated memory allows for the TYPE structure
		plus size (``Py_ssize_t``) fields of the size
		given by the :c:member:`~PyTypeObject.tp_itemsize` field of
		typeobj. This is useful for implementing objects like tuples, which are
		able to determine their size at construction time. Embedding the array of
		fields into the same allocation decreases the number of allocations,
		improving the memory management efficiency.

		Note that this function is unsuitable if typeobj has
		:c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
		use :c:func:`PyObject_GC_NewVar` instead.
		Like:c:macro:`PyObject_New` except:

		* It allocates enough memory for the TYPE structure plus size
		(``Py_ssize_t``) fields of the size given by the
		:c:member:`~PyTypeObject.tp_itemsize` field of typeobj.
		* The memory is initialized like:c:func:`PyObject_InitVar`.

		This is useful for implementing objects like tuples, which are able to
		determine their size at construction time. Embedding the array of fields
		into the same allocation decreases the number of allocations, improving the
		memory management efficiency.

		Avoid calling this directly to allocate memory for an object; call the type's
		:c:member:`~PyTypeObject.tp_alloc` slot instead.

		When populating a type's:c:member:`~PyTypeObject.tp_alloc` slot,
		:c:func:`PyType_GenericAlloc` is preferred over a custom function that
		simply calls this macro.

		This cannot be used for objects with:c:macro:`Py_TPFLAGS_HAVE_GC` set in
		:c:member:`~PyTypeObject.tp_flags`; use:c:macro:`PyObject_GC_NewVar`
		instead.

		Memory allocated by this function must be freed with:c:func:`PyObject_Free`
		(usually called via the object's:c:member:`~PyTypeObject.tp_free` slot).

		..note::

		The returned memory is not guaranteed to have been completely zeroed
		before it was initialized.

		..note::

		This macro does not construct a fully initialized object of the given
		type; it merely allocates memory and prepares it for further
		initialization by:c:member:`~PyTypeObject.tp_init`. To construct a
		fully initialized object, call typeobj instead. For example::

		PyObject list_instance = PyObject_CallNoArgs((PyObject )&PyList_Type);

		..seealso::

		*:c:func:`PyObject_Free`
		*:c:macro:`PyObject_GC_NewVar`
		*:c:func:`PyType_GenericAlloc`
		*:c:member:`~PyTypeObject.tp_alloc`


		..c:function::voidPyObject_Del(void *op)
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -57,11 +57,49 @@ rules:
		Analogous to:c:macro:`PyObject_New` but for container objects with the
		:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.

		Do not call this directly to allocate memory for an object; call the type's
		:c:member:`~PyTypeObject.tp_alloc` slot instead.

		When populating a type's:c:member:`~PyTypeObject.tp_alloc` slot,
		:c:func:`PyType_GenericAlloc` is preferred over a custom function that
		simply calls this macro.

		Memory allocated by this macro must be freed with
		:c:func:`PyObject_GC_Del` (usually called via the object's
		:c:member:`~PyTypeObject.tp_free` slot).

		..seealso::

		*:c:func:`PyObject_GC_Del`
		*:c:macro:`PyObject_New`
		*:c:func:`PyType_GenericAlloc`
		*:c:member:`~PyTypeObject.tp_alloc`


		..c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)

		Analogous to:c:macro:`PyObject_NewVar` but for container objects with the
		:c:macro:`Py_TPFLAGS_HAVE_GC` flag set.

		Do not call this directly to allocate memory for an object; call the type's
		:c:member:`~PyTypeObject.tp_alloc` slot instead.

		When populating a type's:c:member:`~PyTypeObject.tp_alloc` slot,
		:c:func:`PyType_GenericAlloc` is preferred over a custom function that
		simply calls this macro.

		Memory allocated by this macro must be freed with
		:c:func:`PyObject_GC_Del` (usually called via the object's
		:c:member:`~PyTypeObject.tp_free` slot).

		..seealso::

		*:c:func:`PyObject_GC_Del`
		*:c:macro:`PyObject_NewVar`
		*:c:func:`PyType_GenericAlloc`
		*:c:member:`~PyTypeObject.tp_alloc`


		..c:function:: PyObjectPyUnstable_Object_GC_NewWithExtraData(PyTypeObject type, size_t extra_size)

		Analogous to:c:macro:`PyObject_GC_New` but allocates extra_size
Expand All		@@ -73,6 +111,10 @@ rules:
		The extra data will be deallocated with the object, but otherwise it is
		not managed by Python.

		Memory allocated by this function must be freed with
		:c:func:`PyObject_GC_Del` (usually called via the object's
		:c:member:`~PyTypeObject.tp_free` slot).

		.. warning::
		The function is marked as unstable because thefinal mechanism
		for reserving extra data after an instance is not yet decided.
Expand DownExpand Up		@@ -136,6 +178,21 @@ rules:
		Releases memory allocated to an object using:c:macro:`PyObject_GC_New` or
		:c:macro:`PyObject_GC_NewVar`.

		Do not call this directly to free an object's memory; call the type's
		:c:member:`~PyTypeObject.tp_free` slot instead.

		Do not use this for memory allocated by:c:macro:`PyObject_New`,
		:c:macro:`PyObject_NewVar`, or related allocation functions; use
		:c:func:`PyObject_Free` instead.

		..seealso::

		*:c:func:`PyObject_Free` is the non-GC equivalent of this function.
		*:c:macro:`PyObject_GC_New`
		*:c:macro:`PyObject_GC_NewVar`
		*:c:func:`PyType_GenericAlloc`
		*:c:member:`~PyTypeObject.tp_free`


		..c:function::voidPyObject_GC_UnTrack(void *op)

Expand Down