Allocating Objects on the Heap

PyObject*_PyObject_New(PyTypeObject*type)
Return value: New reference.
PyVarObject*_PyObject_NewVar(PyTypeObject*type,Py_ssize_tsize)
Return value: New reference.
PyObject*PyObject_Init(PyObject*op,PyTypeObject*type)
Return value: Borrowed reference. Part of theStable ABI.

Initialize a newly allocated objectop with its type and initialreference. Returns the initialized object. Other fields of the object arenot initialized. Despite its name, this function is unrelated to theobject’s__init__() method (tp_initslot). Specifically, this function doesnot call the object’s__init__() method.

In general, consider this function to be a low-level routine. Usetp_alloc where possible.For implementingtp_alloc for your type, preferPyType_GenericAlloc() orPyObject_New().

Note

This function only initializes the object’s memory corresponding to theinitialPyObject structure. It does not zero the rest.

PyVarObject*PyObject_InitVar(PyVarObject*op,PyTypeObject*type,Py_ssize_tsize)
Return value: Borrowed reference. Part of theStable ABI.

This does everythingPyObject_Init() does, and also initializes thelength information for a variable-size object.

Note

This function only initializes some of the object’s memory. It does notzero the rest.

PyObject_New(TYPE,typeobj)

Allocates a new Python object using the C structure typeTYPE and thePython type objecttypeobj (PyTypeObject*) by callingPyObject_Malloc() to allocate memory and initializing it likePyObject_Init(). The caller will own the only reference to theobject (i.e. its reference count will be one).

Avoid calling this directly to allocate memory for an object; call the type’stp_alloc slot instead.

When populating a type’stp_alloc slot,PyType_GenericAlloc() is preferred over a custom function thatsimply calls this macro.

This macro does not calltp_alloc,tp_new (__new__()), ortp_init (__init__()).

This cannot be used for objects withPy_TPFLAGS_HAVE_GC set intp_flags; usePyObject_GC_New instead.

Memory allocated by this macro must be freed withPyObject_Free()(usually called via the object’stp_free slot).

Note

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

Note

This macro does not construct a fully initialized object of the giventype; it merely allocates memory and prepares it for furtherinitialization bytp_init. To construct afully initialized object, calltypeobj instead. For example:

PyObject*foo=PyObject_CallNoArgs((PyObject*)&PyFoo_Type);
PyObject_NewVar(TYPE,typeobj,size)

LikePyObject_New except:

  • It allocates enough memory for theTYPE structure plussize(Py_ssize_t) fields of the size given by thetp_itemsize field oftypeobj.

  • The memory is initialized likePyObject_InitVar().

This is useful for implementing objects like tuples, which are able todetermine their size at construction time. Embedding the array of fieldsinto the same allocation decreases the number of allocations, improving thememory management efficiency.

Avoid calling this directly to allocate memory for an object; call the type’stp_alloc slot instead.

When populating a type’stp_alloc slot,PyType_GenericAlloc() is preferred over a custom function thatsimply calls this macro.

This cannot be used for objects withPy_TPFLAGS_HAVE_GC set intp_flags; usePyObject_GC_NewVarinstead.

Memory allocated by this function must be freed withPyObject_Free()(usually called via the object’stp_free slot).

Note

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

Note

This macro does not construct a fully initialized object of the giventype; it merely allocates memory and prepares it for furtherinitialization bytp_init. To construct afully initialized object, calltypeobj instead. For example:

PyObject*list_instance=PyObject_CallNoArgs((PyObject*)&PyList_Type);
voidPyObject_Del(void*op)

Same asPyObject_Free().

PyObject_Py_NoneStruct

Object which is visible in Python asNone. This should only be accessedusing thePy_None macro, which evaluates to a pointer to thisobject.

See also

Module Objects

To allocate and create extension modules.