@@ -16,46 +16,128 @@ Allocating Objects on the Heap
1616
1717 Initialize a newly allocated object *op * with its type and initial
1818 reference. Returns the initialized object. Other fields of the object are
19- not affected.
19+ not initialized. Despite its name, this function is unrelated to the
20+ object's:meth: `~object.__init__ ` method (:c:member: `~PyTypeObject.tp_init `
21+ slot). Specifically, this function does **not** call the object's
22+ :meth:`!__init__` method.
23+
24+ In general, consider this function to be a low-level routine. Use
25+ :c:member:`~PyTypeObject.tp_alloc` where possible.
26+ For implementing :c:member:`!tp_alloc` for your type, prefer
27+ :c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.
28+
29+ .. note::
30+
31+ This function only initializes the object's memory corresponding to the
32+ initial :c:type:`PyObject` structure. It does not zero the rest.
2033
2134
2235.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
2336
2437 This does everything:c:func: `PyObject_Init ` does, and also initializes the
2538 length information for a variable-size object.
2639
40+ ..note ::
41+
42+ This function only initializes some of the object's memory. It does not
43+ zero the rest.
44+
2745
2846..c :macro :: PyObject_New(TYPE, typeobj)
2947
30- TYPE *
31- and the Python type object *typeobj * (``PyTypeObject* ``).
32- Fields not defined by the Python object header are not initialized.
33- The caller will own the only reference to the object
34- (i.e. its reference count will be one).
35- The size of the memory allocation is determined from the
36- :c:member:`~PyTypeObject.tp_basicsize` field of the type object.
48+ TYPE * and the
49+ Python type object *typeobj * (``PyTypeObject* ``) by calling
50+ :c:func:`PyObject_Malloc` to allocate memory and initializing it like
51+ :c:func:`PyObject_Init`. The caller will own the only reference to the
52+ object (i.e. its reference count will be one).
53+
54+ Avoid calling this directly to allocate memory for an object; call the type' s
55+ :c:member:`~PyTypeObject.tp_alloc` slot instead.
56+
57+ When populating a type' s :c:member:`~PyTypeObject.tp_alloc` slot,
58+ :c:func: `PyType_GenericAlloc ` is preferred over a custom function that
59+ simply calls this macro.
60+
61+ This macro does not call:c:member: `~PyTypeObject.tp_alloc `,
62+ :c:member: `~PyTypeObject.tp_new ` (:meth: `~object.__new__ `), or
63+ :c:member:`~PyTypeObject.tp_init` (:meth: `~object.__init__ `).
64+
65+ This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
66+ :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.
67+
68+ :c:func: `PyObject_Free `
69+ (usually called via the object's:c:member: `~PyTypeObject.tp_free ` slot).
70+
71+ .. note::
72+
73+ The returned memory is not guaranteed to have been completely zeroed
74+ before it was initialized.
75+
76+ .. note::
77+
78+ This macro does not construct a fully initialized object of the given
79+ type; it merely allocates memory and prepares itfor further
80+ initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
81+ fully initialized object, call *typeobj* instead. For example::
82+
83+ PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);
3784
38- Note that this function is unsuitable if *typeobj* has
39- :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
40- use :c:func:`PyObject_GC_New` instead.
85+ seealso ::
86+
87+ *:c:func: `PyObject_Free `
88+ *:c:macro: `PyObject_GC_New `
89+ *:c:func: `PyType_GenericAlloc `
90+ *:c:member: `~PyTypeObject.tp_alloc `
4191
4292
4393..c :macro :: PyObject_NewVar(TYPE, typeobj, size)
4494
45- Allocate a new Python object using the C structure type *TYPE* and the
46- Python type object *typeobj* (``PyTypeObject* ``).
47- Fields not defined by the Python object header
48- are not initialized. The allocated memory allows for the *TYPE* structure
49- plus *size* (``Py_ssize_t ``) fields of the size
50- given by the :c:member:`~PyTypeObject.tp_itemsize` field of
51- *typeobj*. This is useful for implementing objects like tuples, which are
52- able to determine their size at construction time. Embedding the array of
53- fields into the same allocation decreases the number of allocations,
54- improving the memory management efficiency.
55-
56- Note that this function is unsuitable if *typeobj* has
57- :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
58- use :c:func:`PyObject_GC_NewVar` instead.
95+ :c:macro: `PyObject_New ` except:
96+
97+ * It allocates enough memory for the *TYPE * structure plus *size *
98+ (``Py_ssize_t ``) fields of the size given by the
99+ :c:member: `~PyTypeObject.tp_itemsize ` field of *typeobj *.
100+ * The memory is initialized like:c:func: `PyObject_InitVar `.
101+
102+ This is useful for implementing objects like tuples, which are able to
103+ determine their size at construction time. Embedding the array of fields
104+ into the same allocation decreases the number of allocations, improving the
105+ memory management efficiency.
106+
107+ Avoid calling this directly to allocate memory for an object; call the type's
108+ :c:member: `~PyTypeObject.tp_alloc ` slot instead.
109+
110+ When populating a type's:c:member: `~PyTypeObject.tp_alloc ` slot,
111+ :c:func: `PyType_GenericAlloc ` is preferred over a custom function that
112+ simply calls this macro.
113+
114+ This cannot be used for objects with:c:macro: `Py_TPFLAGS_HAVE_GC ` set in
115+ :c:member: `~PyTypeObject.tp_flags `; use:c:macro: `PyObject_GC_NewVar `
116+ instead.
117+
118+ Memory allocated by this function must be freed with:c:func: `PyObject_Free `
119+ (usually called via the object's:c:member: `~PyTypeObject.tp_free ` slot).
120+
121+ ..note ::
122+
123+ The returned memory is not guaranteed to have been completely zeroed
124+ before it was initialized.
125+
126+ ..note ::
127+
128+ This macro does not construct a fully initialized object of the given
129+ type; it merely allocates memory and prepares it for further
130+ initialization by:c:member: `~PyTypeObject.tp_init `. To construct a
131+ fully initialized object, call *typeobj * instead. For example::
132+
133+ PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);
134+
135+ ..seealso ::
136+
137+ *:c:func: `PyObject_Free `
138+ *:c:macro: `PyObject_GC_NewVar `
139+ *:c:func: `PyType_GenericAlloc `
140+ *:c:member: `~PyTypeObject.tp_alloc `
59141
60142
61143..c :function ::void PyObject_Del (void *op)