ヒープ上でのオブジェクトの割り当て
**********************************

PyObject *_PyObject_New(PyTypeObject *type)
    *戻り値: 新しい参照。*

PyVarObject *_PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
    *戻り値: 新しい参照。*

PyObject *PyObject_Init(PyObject *op, PyTypeObject *type)
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

   新しく割り当てたオブジェクト *op* の型と初期の参照を設定し、初期化
   したオブジェクトを返します。 オブジェクトの他のフィールドは初期化し
   ません。 名前に反して、この関数はオブジェクトの "__init__()" メソッ
   ド ("tp_init" スロット) とは無関係です。 特に、この関数はオブジェク
   トの "__init__()" メソッドを呼び出し **ません**。

   一般に、この関数は低レベルのルーチンとして扱ってください。 可能な場
   合は "tp_alloc" を使ってください。 自分の型の "tp_alloc" を実装する
   場合は、"PyType_GenericAlloc()" または "PyObject_New()" を優先して
   ください。

   注釈:

     この関数が初期化するのは、オブジェクトのメモリのうち先頭の
     "PyObject" 構造体に対応する部分だけです。 残りの部分をゼロで埋め
     ることはありません。

PyVarObject *PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
    *戻り値: 借用参照。** 次に属します: Stable ABI.*

   "PyObject_Init()" の全ての処理を行い、可変サイズオブジェクトの場合
   には長さ情報も初期化します。

   注釈:

     この関数が初期化するのは、オブジェクトのメモリの一部だけです。 残
     りの部分をゼロで埋めることはありません。

PyObject_New(TYPE, typeobj)

   C の構造体型 *TYPE* と Python の型オブジェクト *typeobj*
   ("PyTypeObject*") を使って、新しい Python オブジェクトを割り当てま
   す。 "PyObject_Malloc()" を呼び出してメモリを割り当て、
   "PyObject_Init()" と同じように初期化します。 呼び出し側がオブジェク
   トへの唯一の参照を所有します (つまり参照カウントは 1 になります)。

   オブジェクトのメモリを割り当てるためにこれを直接呼び出すのは避け、
   代わりに型の "tp_alloc" スロットを呼び出してください。

   型の "tp_alloc" スロットには、このマクロを呼び出すだけの独自の関数
   よりも "PyType_GenericAlloc()" を設定することが推奨されます。

   このマクロは "tp_alloc"、"tp_new" ("__new__()")、"tp_init"
   ("__init__()") を呼び出しません。

   "tp_flags" に "Py_TPFLAGS_HAVE_GC" が設定されたオブジェクトには使え
   ません。 代わりに "PyObject_GC_New" を使ってください。

   このマクロで割り当てたメモリは "PyObject_Free()" で解放しなければな
   りません (通常はオブジェクトの "tp_free" スロットを介して呼び出しま
   す)。

   注釈:

     返されるメモリが初期化前にすべてゼロで埋められているとは限りませ
     ん。

   注釈:

     このマクロは指定された型の完全に初期化されたオブジェクトを構築す
     るものではありません。 メモリを割り当て、"tp_init" によるさらなる
     初期化の準備をするだけです。 完全に初期化されたオブジェクトを構築
     するには、代わりに *typeobj* を呼び出してください。 例えば次のよ
     うにします。

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

   参考:

     * "PyObject_Free()"

     * "PyObject_GC_New"

     * "PyType_GenericAlloc()"

     * "tp_alloc"

PyObject_NewVar(TYPE, typeobj, size)

   "PyObject_New" と同じですが、次の点が異なります。

   * *TYPE* 構造体に加え、*typeobj* の "tp_itemsize" フィールドが指定
     するサイズのフィールド *size* 個分 ("Py_ssize_t") のメモリを割り
     当てます。

   * メモリは "PyObject_InitVar()" と同じように初期化されます。

   これはタプルのように構築時にサイズを決定できるオブジェクトの実装に
   役立ちます。 フィールドの配列を同じ割り当て領域に埋め込むことで、割
   り当て回数を減らし、メモリ管理の効率を高められます。

   オブジェクトのメモリを割り当てるためにこれを直接呼び出すのは避け、
   代わりに型の "tp_alloc" スロットを呼び出してください。

   型の "tp_alloc" スロットには、このマクロを呼び出すだけの独自の関数
   よりも "PyType_GenericAlloc()" を設定することが推奨されます。

   "tp_flags" に "Py_TPFLAGS_HAVE_GC" が設定されたオブジェクトには使え
   ません。 代わりに "PyObject_GC_NewVar" を使ってください。

   この関数で割り当てたメモリは "PyObject_Free()" で解放しなければなり
   ません (通常はオブジェクトの "tp_free" スロットを介して呼び出します
   )。

   注釈:

     返されるメモリが初期化前にすべてゼロで埋められているとは限りませ
     ん。

   注釈:

     このマクロは指定された型の完全に初期化されたオブジェクトを構築す
     るものではありません。 メモリを割り当て、"tp_init" によるさらなる
     初期化の準備をするだけです。 完全に初期化されたオブジェクトを構築
     するには、代わりに *typeobj* を呼び出してください。 例えば次のよ
     うにします。

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

   参考:

     * "PyObject_Free()"

     * "PyObject_GC_NewVar"

     * "PyType_GenericAlloc()"

     * "tp_alloc"

PyObject _Py_NoneStruct

   Python からは "None" に見えるオブジェクトです。この値へのアクセスは
   、このオブジェクトへのポインタを評価する "Py_None" マクロを使わなけ
   ればなりません。

参考:

  モジュールオブジェクト (module object)
     拡張モジュールのアロケートと生成。


緩やかに非推奨となった別名
==========================

バージョン 3.15 で ソフト非推奨 <Soft deprecated>.

これらは既存の関数やマクロの別名です。 後方互換性のためだけに残されて
います。

+----------------------------------------------------+----------------------------------------------------+
| 緩やかに非推奨となった別名                         | 関数                                               |
|====================================================|====================================================|
| PyObject_NEW(type, typeobj)                        | "PyObject_New"                                     |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_NEW_VAR(type, typeobj, n)                 | "PyObject_NewVar"                                  |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_INIT(op, typeobj)                         | "PyObject_Init()"                                  |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_INIT_VAR(op, typeobj, n)                  | "PyObject_InitVar()"                               |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_MALLOC(n)                                 | "PyObject_Malloc()"                                |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_REALLOC(p, n)                             | "PyObject_Realloc()"                               |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_FREE(p)                                   | "PyObject_Free()"                                  |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_DEL(p)                                    | "PyObject_Free()"                                  |
+----------------------------------------------------+----------------------------------------------------+
| PyObject_Del(p)                                    | "PyObject_Free()"                                  |
+----------------------------------------------------+----------------------------------------------------+
