C拡張モジュール開発者必見！NumPyユーザガイドにおけるint PyModule_AddIntConstant() 関数のプログラミング

関数詳細

int PyModule_AddIntConstant(PyObject *m, const char *name, long value);

引数

value: 定数値 (整数)
name: 定数名 (文字列)
m: 定数を定義するモジュールオブジェクト

戻り値

成功した場合、0 を返します。失敗した場合、-1 を返します。

使い方

以下の例は、mymodule という名前のモジュールに MY_CONSTANT という名前で 10 という定数を定義する方法を示しています。

PyObject *mymodule_init(void)
{
    PyObject *m;

    m = PyModule_Create(&mymodule_module, NULL);
    if (m == NULL)
        return NULL;

    if (PyModule_AddIntConstant(m, "MY_CONSTANT", 10) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

このコードを実行すると、mymodule モジュールに MY_CONSTANT という名前の属性が作成され、その値は 10 になります。この属性は、Python コードから次のようにアクセスできます。

import mymodule

print(mymodule.MY_CONSTANT)

注意事項

同じ名前の定数がモジュール内に既に存在する場合、PyModule_AddIntConstant() は失敗します。
定数名は、Python の識別子規則に従う必要があります。
PyModule_AddIntConstant() は、32 ビット整数のみをサポートします。64 ビット整数定数を定義するには、PyModule_AddLongConstant() 関数を使用する必要があります。

NumPy ユーザガイドとの関連性

NumPy ユーザガイドでは、PyModule_AddIntConstant() 関数は、NumPy 拡張モジュール内で定数を定義するために使用する方法として紹介されています。この関数は、NumPy 固有の機能ではありませんが、NumPy 拡張モジュールの開発において一般的に使用されます。

例 1

この例は、mymodule という名前のモジュールに MY_CONSTANT1 と MY_CONSTANT2 という名前で 10 と 20 という 2 つの定数を定義する方法を示しています。

PyObject *mymodule_init(void)
{
    PyObject *m;

    m = PyModule_Create(&mymodule_module, NULL);
    if (m == NULL)
        return NULL;

    if (PyModule_AddIntConstant(m, "MY_CONSTANT1", 10) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    if (PyModule_AddIntConstant(m, "MY_CONSTANT2", 20) < 0) {
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

このコードを実行すると、mymodule モジュールに MY_CONSTANT1 と MY_CONSTANT2 という名前の 2 つの属性が作成され、それぞれの値は 10 と 20 になります。これらの属性は、Python コードから次のようにアクセスできます。

import mymodule

print(mymodule.MY_CONSTANT1)  # 10 を出力
print(mymodule.MY_CONSTANT2)  # 20 を出力

例 2

この例は、mymodule という名前のモジュールに MY_ENUM という名前の列挙型定数を定義する方法を示しています。

PyObject *mymodule_init(void)
{
    PyObject *m;
    PyObject *value;

    m = PyModule_Create(&mymodule_module, NULL);
    if (m == NULL)
        return NULL;

    value = PyInt_FromLong(1);
    if (value == NULL) {
        Py_DECREF(m);
        return NULL;
    }

    if (PyModule_AddIntConstant(m, "MY_ENUM_VALUE1", PyInt_AsLong(value)) < 0) {
        Py_DECREF(m);
        Py_DECREF(value);
        return NULL;
    }

    Py_DECREF(value);

    value = PyInt_FromLong(2);
    if (value == NULL) {
        Py_DECREF(m);
        return NULL;
    }

    if (PyModule_AddIntConstant(m, "MY_ENUM_VALUE2", PyInt_AsLong(value)) < 0) {
        Py_DECREF(m);
        Py_DECREF(value);
        return NULL;
    }

    Py_DECREF(value);

    return m;
}

このコードを実行すると、mymodule モジュールに MY_ENUM_VALUE1 と MY_ENUM_VALUE2 という名前の 2 つの属性が作成され、それぞれの値は 1 と 2 になります。これらの属性は、Python コードから次のようにアクセスできます。

import mymodule

print(mymodule.MY_ENUM_VALUE1)  # 1 を出力
print(mymodule.MY_ENUM_VALUE2)  # 2 を出力

同じ名前の定数がモジュール内に既に存在する場合、PyModule_AddIntConstant() は失敗します。
定数名は、Python の識別子規則に従う必要があります。
PyModule_AddIntConstant() 関数は、32 ビット整数のみをサポートします。64 ビット整数定数を定義するには、PyModule_AddLongConstant() 関数を使用する必要があります。

制限事項

柔軟性に欠けます。
エラー処理が組み込まれていません。
32 ビット整数のみをサポートします。

これらの制限を克服するために、int PyModule_AddIntConstant() の代替方法をいくつか検討することができます。

代替方法

PyObject_SetAttrString() 関数を使用する

この関数は、オブジェクトに属性を設定するために使用できます。整数定数を設定するには、次のように使用できます。

PyObject *m;
PyObject *value;

m = PyModule_Create(&mymodule_module, NULL);
if (m == NULL)
    return NULL;

value = PyInt_FromLong(10);
if (value == NULL) {
    Py_DECREF(m);
    return NULL;
}

if (PyObject_SetAttrString(m, "MY_CONSTANT", value) < 0) {
    Py_DECREF(m);
    Py_DECREF(value);
    return NULL;
}

Py_DECREF(value);

return m;

この方法は、PyModule_AddIntConstant() 関数よりも柔軟性に優れています。なぜなら、任意のオブジェクトに属性を設定できるからです。また、エラー処理を独自に実装することもできます。

PyModule_AddObject() 関数を使用する

この関数は、モジュールにオブジェクトを追加するために使用できます。整数定数を追加するには、次のように使用できます。

PyObject *m;
PyObject *value;

m = PyModule_Create(&mymodule_module, NULL);
if (m == NULL)
    return NULL;

value = PyInt_FromLong(10);
if (value == NULL) {
    Py_DECREF(m);
    return NULL;
}

if (PyModule_AddObject(m, "MY_CONSTANT", value) < 0) {
    Py_DECREF(m);
    Py_DECREF(value);
    return NULL;
}

Py_DECREF(value);

return m;

この方法は、PyModule_AddIntConstant() 関数と似ていますが、PyObject_SetAttrString() 関数よりも柔軟性に劣ります。なぜなら、モジュールにのみオブジェクトを追加できるからです。

カスタム属性記述子を実装する

この方法は、最も柔軟性と制御性が高いですが、最も複雑でもあります。カスタム属性記述子を実装するには、次の手順を実行する必要があります。

属性記述子構造体を定義する
構造体の __set__ メソッドを実装する
構造体の __get__ メソッドを実装する
構造体の __delete__ メソッドを実装する (オプション)
モジュールに属性記述子を登録する

カスタム属性記述子を使用すると、属性のアクセス、設定、削除を完全に制御できます。また、属性に独自のロジックを追加することもできます。