はじめに

Python のアプリケーションプログラマー向けインターフェース (API) は、C と C++ のプログラマーに、Python インタープリタへのさまざまなレベルのアクセスを提供します。 C++ からも同様に使えますが、簡潔に Python/C API と呼びます。 Python/C API を使う主な理由は、根本的に異なる 2 つです。 1 つは、特定の目的のために 拡張モジュール を書くことです。 これは Python インタープリタを拡張する C のモジュールで、おそらく最も一般的な用途です。 もう 1 つは、より大きなアプリケーションの構成要素として Python を使うことです。 この技法は一般に、アプリケーションへの Python の 埋め込み (embedding) と呼ばれます。

拡張モジュールの作成は比較的わかりやすいプロセスで、 "手引書 (cookbook)" 的なアプローチでうまく実現できます。作業をある程度まで自動化してくれるツールもいくつかあります。一方、他のアプリケーションへの Python の埋め込みは、Python ができてから早い時期から行われてきましたが、拡張モジュールの作成に比べるとやや難解です。

多くの API 関数は、Python の埋め込みであるか拡張であるかに関わらず役立ちます; とはいえ、Python を埋め込んでいるほとんどのアプリケーションは、同時に自作の拡張モジュールも提供する必要が生じることになるでしょうから、Python を実際にアプリケーションに埋め込んでみる前に拡張モジュールの書き方に詳しくなっておくのはよい考えだと思います。

言語バージョン互換性

Pythonの C API は C11 や C++11 バージョンの C と C++ に互換性があります。

これは最低限のバージョンであり、C API はこれより新しい C/C++ の機能を必要としません。 コンパイラの「c11 モード」を有効にする必要は ありません。

コーディング基準

CPython に含める C コードを書いている場合は、 PEP 7 のガイドラインと基準に従わなければ なりません 。 このガイドラインは、コントリビュート対象の Python のバージョンに関係無く適用されます。 自身のサードパーティーのモジュールでは、それをいつか Python にコントリビュートするつもりでなければ、この慣習に従う必要はありません。

インクルードファイル

Python/C API を使うために必要な、関数、型およびマクロの全ての定義をインクルードするには、以下の行:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

をソースコードに記述します。この行を記述すると、標準ヘッダ: <stdio.h>, <string.h>, <errno.h>, <limits.h>, <assert.h>, <stdlib.h> を (利用できれば) インクルードします。

注釈

Python は、システムによっては標準ヘッダの定義に影響するようなプリプロセッサ定義を行っているので、 Python.h をいずれの標準ヘッダよりも前にインクルード せねばなりません 。

Python.h をインクルードする前に、常に PY_SSIZE_T_CLEAN を定義することが推奨されます。 このマクロの解説については 引数の解釈と値の構築 を参照してください。

Python.h で定義されている、ユーザから見える名前全て (Python.h がインクルードしている標準ヘッダの名前は除きます) には、接頭文字列 Py または _Py が付きます。_Py で始まる名前は Python 実装で内部使用するための名前で、拡張モジュールの作者は使ってはなりません。構造体のメンバには予約済みの接頭文字列はありません。

注釈

API のユーザは、Py や _Py で始まる名前を定義するコードを絶対に書いてはなりません。 後からコードを読む人を混乱させたり、将来の Python のバージョンで同じ名前が定義されて、ユーザの書いたコードの可搬性を危うくする可能性があります。

ヘッダファイル群は通常 Python と共にインストールされます。 Unixでは prefix/include/pythonversion/ および exec_prefix/include/pythonversion/ に置かれます。 prefix と exec_prefix は Python をビルドする際の configure スクリプトに与えたパラメタに対応し、 version は '%d.%d' % sys.version_info[:2] に対応します。 Windows では、ヘッダは prefix/include に置かれます。 prefix はインストーラに指定したインストールディレクトリです。

ヘッダをインクルードするには、各ヘッダの入ったディレクトリ (別々のディレクトリの場合は両方) を、コンパイラがインクルードファイルを検索するためのパスに入れます。親ディレクトリをサーチパスに入れて、 #include <pythonX.Y/Python.h> のようにしては なりません ; prefix 内のプラットフォームに依存しないヘッダは、 exec_prefix からプラットフォーム依存のヘッダをインクルードしているので、このような操作を行うと複数のプラットフォームでのビルドができなくなります。

C++ の利用者は、API がすべて C で定義されていても、ヘッダーファイルではエントリーポイントが適切に extern "C" として宣言されていることに注意してください。 そのため、C++ から API を使うのに特別な対応は必要ありません。

システムヘッダーのインクルード

Python.h は、いくつかの標準ヘッダーファイルをインクルードします。 C 拡張では、この暗黙のインクルードに依存せず、使う標準ヘッダーを自分でインクルードするべきです。 暗黙にインクルードされるのは次のヘッダーです。

  • <assert.h>

  • <intrin.h> (Windows)

  • <inttypes.h>

  • <limits.h>

  • <math.h>

  • <stdarg.h>

  • <string.h>

  • <wchar.h>

  • <sys/types.h> (存在する場合)

次のヘッダーは、3.13 以降の Limited API を使う場合を除き、後方互換性のためにインクルードされます。

  • <ctype.h>

  • <unistd.h> (POSIX)

次のヘッダーは、3.11 以降の Limited API を使う場合を除き、後方互換性のためにインクルードされます。

  • <errno.h>

  • <stdio.h>

  • <stdlib.h>

注釈

Python は、システムによっては標準ヘッダの定義に影響するようなプリプロセッサ定義を行っているので、 Python.h をいずれの標準ヘッダよりも前にインクルード せねばなりません 。

便利なマクロ

Python のヘッダーファイルでは、いくつかの便利なマクロが定義されています。 多くは、Py_RETURN_NONE や PyMODINIT_FUNC のように、用途に関連する箇所で定義されています。 ここでは、より汎用的なマクロを説明します。 すべてを網羅した一覧ではありません。

Py_CAN_START_THREADS

このマクロが定義されていれば、現在のシステムではスレッドを開始できます。

現在、CPython がサポートするすべてのシステム (PEP 11 を参照) は、一部の WebAssembly プラットフォームを除き、スレッドを開始できます。

Added in version 3.13.

Py_GETENV(s)

getenv(s) と同様ですが、コマンドラインで -E が指定された場合は NULL を返します (PyConfig.use_environment を参照)。

docstring のマクロ

PyDoc_STRVAR(name, str)

docstring に使える、名前が name の変数を作成します。 Python を docstring なしでビルドした場合 (--without-doc-strings)、値は空文字列になります。

以下はプログラム例です:

PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = {
    // ...
    {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
    // ...
}

PyDoc_VAR(name) = PyDoc_STR(str) に展開されます。

PyDoc_STR(str)

指定された文字列に展開されます。 docstring が無効な場合 (--without-doc-strings) は空文字列に展開されます。

以下はプログラム例です:

static PyMethodDef pysqlite_row_methods[] = {
    {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")},
    {NULL, NULL}
};
PyDoc_VAR(name)

指定された name を名前とする、静的な文字配列変数を宣言します。 static const char name[] に展開されます。

例えば:

PyDoc_VAR(python_doc) = PyDoc_STR(
   "東半球の熱帯・亜熱帯に生息するニシキヘビ科の属。"
   "獲物に巻き付いて締め付ける。");

汎用ユーティリティマクロ

以下は、Python に固有ではない一般的な処理のためのマクロです。

Py_UNUSED(arg)

コンパイラ警告を抑えるために関数定義の使用されない引数に使用してください。例えば: int func(int a, int Py_UNUSED(b)) { return a; } 。

Added in version 3.4.

Py_GCC_ATTRIBUTE(name)

GCC の属性 name を使います。 MSVC など、GCC の属性をサポートしないコンパイラには属性を見せません。

GCC では __attribute__((name)) に展開され、GCC の属性をサポートしないコンパイラでは何も展開されません。

数値ユーティリティ

Py_ABS(x)

x の絶対値を返します。

引数は複数回評価される可能性があります。 そのため、副作用のある式をこのマクロに直接渡さないでください。

例えば x が int 型の INT_MIN である場合など、結果を表現できない場合の動作は未定義です。

おおむね ((x) < 0 ? -(x) : (x)) に相当します。

Added in version 3.3.

Py_MAX(x, y)
Py_MIN(x, y)

それぞれ、引数のうち大きい方、小さい方を返します。

どの引数も複数回評価される可能性があります。 そのため、副作用のある式をこのマクロに直接渡さないでください。

Py_MAX は、おおむね (((x) > (y)) ? (x) : (y)) に相当します。

Added in version 3.3.

Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)

integer >> positions と似ていますが、必ず符号拡張を行います。 C の規格では、符号付き整数の右シフトで符号拡張を行うか、ゼロで埋めるかが定められていないためです。

integer は任意の符号付き整数型の値を指定します。 positions は右にシフトするビット数です。

integer と positions は、どちらも複数回評価される可能性があります。 そのため、関数呼び出しやその他の副作用がある操作を、このマクロに直接渡さないでください。 代わりに、結果を変数に保存してから渡してください。

type は使われず、後方互換性のためだけに残されています。 以前は、integer のキャストに使っていました。

バージョン 3.1 で変更: unsigned type が有効な型だけでなく、すべての符号付き整数型で使えるようになりました。 そのため、type は使われなくなりました。

Py_CHARMASK(c)

引数は、文字か、[-128, 127] または [0, 255] の範囲の整数でなければなりません。 このマクロは c を unsigned char にキャストして返します。

PY_BIG_ENDIAN
PY_LITTLE_ENDIAN

Python のビルド対象プラットフォームのバイト順を表す定数です。 どちらか一方だけが 1 で、もう一方は 0 です。

アサーションのユーティリティ

Py_UNREACHABLE()

設計上、到達することのないコードパスで使ってください。 例えば、可能な値をすべて case で網羅した switch 文の default: 節で使います。 assert(0) や abort() の呼び出しを置きたくなるような箇所で使ってください。

リリースモードでは、このマクロはコンパイラによるコードの最適化を助け、到達不能コードに関する警告を防ぎます。 例えば、GCC のリリースモードでは __builtin_unreachable() で実装されています。

デバッグモードと、対応していないコンパイラでは、Py_FatalError() の呼び出しに展開されます。

Py_UNREACHABLE() の用途の 1 つは、決して戻らないものの _Noreturn と宣言されていない関数の呼び出しの直後に置くことです。

発生する可能性が非常に低くても、例外的な状況で到達しうるコードパスには、このマクロを使ってはなりません。 例えば、メモリ不足の場合や、システムコールが想定範囲外の値を返した場合です。 そのような場合は、呼び出し元にエラーを報告する方が適切です。 呼び出し元に報告できない場合は、Py_FatalError() を使えます。

Added in version 3.7.

Py_SAFE_DOWNCAST(value, larger, smaller)

value を larger 型から smaller 型にキャストし、情報が失われなかったことを検証します。

Python のリリースビルドでは、おおむね ((smaller) value) と等価です (C++ では代わりに static_cast<smaller>(value) を使います)。

デバッグビルド (Py_DEBUG が定義されている場合) では、larger から smaller へのキャストで情報が失われていないことをアサートします。

value、larger、smaller は、式の中で複数回評価される可能性があります。 そのため、副作用のある式をこのマクロに直接渡さないでください。

Py_BUILD_ASSERT(cond)

コンパイル時の条件 cond をアサートする文です。 条件が偽の場合や、コンパイル時に評価できない場合は、ビルドに失敗します。

C23 以降では、おおむね static_assert(cond) に相当します。

例えば:

Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));

Added in version 3.3.

Py_BUILD_ASSERT_EXPR(cond)

コンパイル時の条件 cond をアサートする式で、評価結果は 0 です。 条件が偽の場合や、コンパイル時に評価できない場合は、ビルドに失敗します。

例えば:

#define foo_to_char(foo) \
    ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))

Added in version 3.3.

型のサイズのユーティリティ

Py_ARRAY_LENGTH(array)

静的に確保された C の配列の長さを、コンパイル時に計算します。

array 引数は、コンパイル時にサイズが分かる C の配列でなければなりません。 ヒープに確保した配列など、サイズが不明な配列を渡すと、一部のコンパイラではコンパイルエラーになり、それ以外では誤った結果になります。

おおむね次の式と等価です。

sizeof(array) / sizeof((array)[0])
Py_MEMBER_SIZE(type, member)

構造体 type のメンバー member のサイズをバイト数で返します。

おおむね sizeof(((type *)NULL)->member) に相当します。

Added in version 3.6.

マクロ定義のユーティリティ

Py_FORCE_EXPANSION(X)

X と等価ですが、プリプロセッサーが X 内のマクロを強制的に展開するため、マクロでのトークンの連結に役立ちます。

Py_STRINGIFY(x)

x を C の文字列に変換します。 例えば Py_STRINGIFY(123) は "123" を返します。

Added in version 3.4.

宣言のユーティリティ

以下のマクロは宣言で使えます。 主に C API 自体を定義するためのもので、拡張の作者にとっての用途は限られます。 ほとんどは、C 言語で一般的な拡張機能の、コンパイラ固有の記法に展開されます。

Py_ALWAYS_INLINE

static inline 関数を常にインライン化するよう、コンパイラに要求します。 コンパイラはこれを無視して、インライン化しないと判断する場合もあります。

GCC の always_inline 属性と、MSVC の __forceinline に相当します。

It can be used to inline performance critical static inline functions when building Python in debug mode with function inlining disabled. For example, MSC disables function inlining when building in debug mode.

static inline 関数に無条件に Py_ALWAYS_INLINE を付けると、コードサイズの増加などによって、性能が悪化する場合があります。 通常、コストと利点の分析は、開発者よりもコンパイラの方が得意です。

Python が デバッグモードでビルドされている 場合 (Py_DEBUG マクロが定義されている場合)、Py_ALWAYS_INLINE マクロは何も行いません。

関数の戻り値の型の前に指定しなければなりません。 使用例を示します。

static inline Py_ALWAYS_INLINE int random(void) { return 4; }

Added in version 3.11.

Py_NO_INLINE

関数のインライン化を無効にします。 例えば、C のスタックの消費量を減らせるため、コードを大幅にインライン化する LTO+PGO ビルドで有用です (bpo-33720 を参照)。

GCC と MSVC の noinline 属性や指定に相当します。

使い方:

Py_NO_INLINE static int random(void) { return 4; }

Added in version 3.11.

Py_DEPRECATED(version)

特定の CPython バージョンで非推奨になった API を宣言するときに使ってください。 シンボル名の前に置かなければなりません。

以下はプログラム例です:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

バージョン 3.8 で変更: MSVC サポートが追加されました。

Py_LOCAL(type)

現在のファイル内でのみ使う関数に対し、高速な呼び出し規約を指定して、type を返す関数を宣言します。 意味上は static type と等価です。

Py_LOCAL_INLINE(type)

Py_LOCAL と等価ですが、さらに関数のインライン化を要求します。

Py_LOCAL_SYMBOL

シンボルを共有ライブラリ内に限定して、非公開として宣言するマクロです。 対応するプラットフォームでは、シンボルがエクスポートされないようにします。

対応するバージョンの GCC/Clang では、__attribute__((visibility("hidden"))) に展開されます。

Py_EXPORTED_SYMBOL

シンボル (関数やデータ) をエクスポートすると宣言するマクロです。 Windows では __declspec(dllexport) に、対応するバージョンの GCC/Clang では __attribute__((visibility("default"))) に展開されます。 C API 自体の定義に使うものであり、拡張モジュールでは使うべきではありません。

Py_IMPORTED_SYMBOL

シンボルをインポートすると宣言するマクロです。 Windows では __declspec(dllimport) に展開されます。 C API 自体の定義に使うものであり、拡張モジュールでは使うべきではありません。

PyAPI_FUNC(type)

CPython が、C API の一部となる関数を宣言するために使うマクロです。 展開結果は、プラットフォームとビルド設定に依存します。 CPython の C API 自体を定義するためのものであり、拡張モジュールは自身のシンボルに使うべきではありません。

PyAPI_DATA(type)

CPython が、C API の一部となる公開グローバル変数を宣言するために使うマクロです。 展開結果は、プラットフォームとビルド設定に依存します。 CPython の C API 自体を定義するためのものであり、拡張モジュールは自身のシンボルに使うべきではありません。

古いマクロ

以下の 緩やかに非推奨となった マクロは、C11 以前の規格で標準化された機能のために使われていました。

Py_ALIGNED(num)

一部の GCC 系コンパイラで、num バイト境界へのアラインメントを指定します。 ほかのコンパイラでは何も行いません。

このマクロではなく、標準の alignas 指定子を使ってください。

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

PY_FORMAT_SIZE_T

size_t 用の printf() 書式修飾子です。 代わりに "z" を直接使ってください。

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

Py_LL(number)
Py_ULL(number)

number を、それぞれ long long または unsigned long long の整数リテラルとして使います。

それぞれ、number の後ろに LL または LLU を付けたものに展開されます。 ただし、一部の古いコンパイラでは、コンパイラ固有の接尾辞に展開されます。

C99 標準の接尾辞 LL と LLU を直接使うことを検討してください。

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

PY_LONG_LONG
PY_INT32_T
PY_UINT32_T
PY_INT64_T
PY_UINT64_T

それぞれ long long、int32_t、uint32_t、int64_t、uint64_t 型のエイリアスです。 以前は、これらの型にはコンパイラ固有の拡張が必要でした。

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

PY_LLONG_MIN
PY_LLONG_MAX
PY_ULLONG_MAX
PY_SIZE_MAX

それぞれ LLONG_MIN、LLONG_MAX、ULLONG_MAX、SIZE_MAX のエイリアスです。 代わりに、これらの標準の名前を使ってください。

必要なヘッダー <limits.h> は、Python.h で インクルードされます。

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

Py_MEMCPY(dest, src, n)

memcpy() のエイリアスです。

バージョン 3.14 で ソフト非推奨 <Soft deprecated>: 代わりに memcpy() を直接使ってください。

Py_UNICODE_SIZE

wchar_t 型のサイズです。 代わりに sizeof(wchar_t) または WCHAR_WIDTH/8 を使ってください。

後者に必要なヘッダー <limits.h> は、Python.h で インクルードされます。

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

Py_UNICODE_WIDE

wchar_t が Unicode 文字 (UCS-4) を保持できる場合に定義されます。 代わりに sizeof(wchar_t) >= 4 を使ってください。

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

Py_VA_COPY

C99 標準の va_copy 関数のエイリアスです。

以前は、va_list のコピーにコンパイラ固有の方法を使っていました。

バージョン 3.6 で変更: va_copy のエイリアスになりました。

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

オブジェクト、型および参照カウント

Python/C API 関数の多くは、PyObject* 型の引数を 1 つ以上受け取り、同じ型の値を返します。 この型は、任意の Python オブジェクトを表す不透明なデータ型へのポインターです。 Python 言語では、代入、スコープの規則、引数渡しなど、ほとんどの状況ですべての Python オブジェクト型を同じように扱います。 したがって、単一の C の型で表すのが適切です。 ほとんどすべての Python オブジェクトはヒープ上に置かれます。 PyObject 型の自動変数や静的変数を宣言することはなく、宣言するのは PyObject* 型のポインター変数だけです。 唯一の例外は型オブジェクトです。 型オブジェクトは解放してはならないため、通常は静的な PyTypeObject オブジェクトです。

全ての Python オブジェクトには (Python 整数型ですら) 型 (type) と参照カウント (reference count) があります。あるオブジェクトの型は、そのオブジェクトがどの種類のオブジェクトか (例えば整数、リスト、ユーザ定義関数、など; その他多数については 標準型の階層 で説明しています) を決定します。よく知られている型については、各々マクロが存在して、あるオブジェクトがその型かどうか調べられます; 例えば、 PyList_Check(a) は、 a で示されたオブジェクトが Python リスト型のとき (かつそのときに限り) 真値を返します。

参照カウント法

The reference count is important because today's computers have a finite (and often severely limited) memory size; it counts how many different places there are that have a strong reference to an object. Such a place could be another object, or a global (or static) C variable, or a local variable in some C function. When the last strong reference to an object is released (i.e. its reference count becomes zero), the object is deallocated. If it contains references to other objects, those references are released. Those other objects may be deallocated in turn, if there are no more references to them, and so on. (There's an obvious problem with objects that reference each other here; for now, the solution is "don't do that.")

Reference counts are always manipulated explicitly. The normal way is to use the macro Py_INCREF() to take a new reference to an object (i.e. increment its reference count by one), and Py_DECREF() to release that reference (i.e. decrement the reference count by one). The Py_DECREF() macro is considerably more complex than the incref one, since it must check whether the reference count becomes zero and then cause the object's deallocator to be called. The deallocator is a function pointer contained in the object's type structure. The type-specific deallocator takes care of releasing references for other objects contained in the object if this is a compound object type, such as a list, as well as performing any additional finalization that's needed. There's no chance that the reference count can overflow; at least as many bits are used to hold the reference count as there are distinct memory locations in virtual memory (assuming sizeof(Py_ssize_t) >= sizeof(void*)). Thus, the reference count increment is a simple operation.

オブジェクトへのポインターを格納するローカル変数すべてについて、強参照 を保持する (参照カウントを増やす) 必要はありません。 理論上は、変数がオブジェクトを指すようになったときに参照カウントを 1 増やし、変数がスコープを外れたときに 1 減らします。 しかし、この 2 つは相殺されるので、最終的な参照カウントは変わりません。 参照カウントを使う本当の理由は、変数がオブジェクトを指している間に、オブジェクトが解放されるのを防ぐことだけです。 少なくともその変数と同じ期間存続する別の参照があると分かっていれば、一時的に新しい 強参照 を取得する (参照カウントを増やす) 必要はありません。 重要な例は、Python から呼び出す拡張モジュールの C 関数に、引数として渡されるオブジェクトです。 呼び出しの仕組みによって、呼び出し中は各引数への参照が保持されることが保証されます。

ただし、よくある落とし穴として、リストから取り出したオブジェクトを、新しい参照を取得せずにしばらく保持することがあります。 別の操作がそのオブジェクトをリストから取り除いて参照を解放し、オブジェクト自体も解放してしまう可能性があります。 本当の危険は、無害に見える操作でも任意の Python コードを呼び出し、そのコードがこのような操作を行いうることです。 Py_DECREF() からユーザーのコードに制御が戻る経路があるため、ほとんどどの操作にも危険が潜んでいます。

安全な方法は、常に汎用の操作 (名前が PyObject_、PyNumber_、PySequence_、PyMapping_ で始まる関数) を使うことです。 これらの操作は、返すオブジェクトへの新しい 強参照 を必ず作成します (つまり、参照カウントを増やします)。 そのため、呼び出し元には、結果を使い終えたときに Py_DECREF() を呼び出す責任がありますが、これはすぐに習慣になります。

参照カウントの詳細

Python/C API の関数による参照カウントの扱いは、参照の所有権 で考えると最もよく説明できます。 所有権は参照に対するものであり、オブジェクトに対するものではありません (オブジェクトは所有されず、常に共有されます)。 「参照を所有する」とは、その参照が不要になったときに Py_DECREF を呼び出す責任を持つという意味です。 所有権は移すこともできます。 所有権を受け取ったコードには、不要になった参照を Py_DECREF() または Py_XDECREF() で解放する責任、あるいはその責任を通常は呼び出し元に引き継ぐ責任が生じます。 関数が呼び出し元に参照の所有権を渡すとき、呼び出し元は 新しい 参照を受け取るといいます。 所有権を移さない場合は、参照を 借用する といいます。 借用参照 に対しては、何もする必要はありません。

逆に、呼び出し元の関数がオブジェクトへの参照を渡す場合、呼び出される関数が参照を 盗む 場合と、盗まない場合の 2 通りがあります。

参照を盗む とは、関数に参照を渡したとき、その関数が参照を所有するようになることです。 新しい所有者は自身の判断で Py_DECREF() を使えるため、呼び出し元は呼び出し後にその参照を使ってはなりません。

参照を盗み取る関数はほとんどありません; 例外としてよく知られているのは、 PyList_SetItem() と PyTuple_SetItem() で、これらはシーケンスに入れる要素に対する参照を盗み取ります (しかし、要素の入る先のタプルやリストの参照は盗み取りません!)。これらの関数は、リストやタプルの中に新たに作成されたオブジェクトを入れていく際の常套的な書き方をしやすくするために、参照を盗み取るように設計されています; 例えば、 (1, 2, "three") というタプルを生成するコードは以下のようになります (とりあえず例外処理のことは忘れておきます; もっとよい書き方を後で示します):

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

ここで、 PyLong_FromLong() は新しい参照を返し、すぐに PyTuple_SetItem() に盗まれます。参照が盗まれた後もそのオブジェクトを利用したい場合は、参照盗む関数を呼び出す前に、 Py_INCREF() を利用してもう一つの参照を取得してください。

ちなみに、PyTuple_SetItem() はタプルの要素を設定する 唯一の 方法です。 タプルは不変のデータ型なので、PySequence_SetItem() と PyObject_SetItem() はこの操作を拒否します。 PyTuple_SetItem() は、自分で作成中のタプルに対してだけ使うべきです。

同じく、リストに値を入れていくコードは PyList_New() と PyList_SetItem() で書けます。

しかし実際には、タプルやリストを生成して値を入れる際には、上記のような方法はほとんど使いません。より汎用性のある関数、 Py_BuildValue() があり、ほとんどの主要なオブジェクトをフォーマット文字列 format string の指定に基づいて C の値から生成できます。例えば、上の二種類のコードブロックは、以下のように置き換えられます (エラーチェックにも配慮しています):

PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");

実際には、自分の関数に渡された引数のように、参照を借用しているだけの要素に対して、PyObject_SetItem() などを使う方がはるかに一般的です。 その場合、渡すだけのために新しい参照を取得してから「盗ませる」必要がないため、参照の扱いがずっと自然になります。 例えば、次の関数は、リスト (実際には任意の可変シーケンス) のすべての要素を指定した要素に設定します。

int
set_all(PyObject *target, PyObject *item)
{
    Py_ssize_t i, n;

    n = PyObject_Length(target);
    if (n < 0)
        return -1;
    for (i = 0; i < n; i++) {
        PyObject *index = PyLong_FromSsize_t(i);
        if (!index)
            return -1;
        if (PyObject_SetItem(target, index, item) < 0) {
            Py_DECREF(index);
            return -1;
        }
        Py_DECREF(index);
    }
    return 0;
}

関数の戻り値の場合には、状況は少し異なります。ほとんどの関数については、参照を渡してもその参照に対する所有権が変わることがない一方で、あるオブジェクトに対する参照を返すような多くの関数は、参照に対する所有権を呼び出し側に与えます。理由は簡単です: 多くの場合、関数が返すオブジェクトはその場で (on the fly) 生成されるため、呼び出し側が得る参照は生成されたオブジェクトに対する唯一の参照になるからです。従って、 PyObject_GetItem() や PySequence_GetItem() のように、オブジェクトに対する参照を返す汎用の関数は、常に新たな参照を返します (呼び出し側が参照の所有者になります)。

重要なのは、関数が返す参照の所有権を持てるかどうかは、どの関数を呼び出すかだけによる、と理解することです --- 関数呼び出し時の お飾り (関数に引数として渡したオブジェクトの型) は この問題には関係ありません! 従って、 PyList_GetItem() を使ってリスト内の要素を得た場合には、参照の所有者にはなりません --- が、同じ要素を同じリストから PySequence_GetItem() (図らずもこの関数は全く同じ引数をとります) を使って取り出すと、返されたオブジェクトに対する参照を得ます。

以下は、整数からなるリストに対して各要素の合計を計算する関数をどのようにして書けるかを示した例です; 一つは PyList_GetItem() を使っていて、もう一つは PySequence_GetItem() を使っています。

long
sum_list(PyObject *list)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;

    n = PyList_Size(list);
    if (n < 0)
        return -1; /* リストではない */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* 失敗しない */
        if (!PyLong_Check(item)) continue; /* 整数でないものを飛ばす */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* 整数が C の long に収まらないので終了する */
            return -1;
        total += value;
    }
    return total;
}

long
sum_sequence(PyObject *sequence)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n < 0)
        return -1; /* 長さを持たない */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* シーケンスでないか、別のエラー */
        if (PyLong_Check(item)) {
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* 整数が C の long に収まらないので終了する */
                return -1;
            total += value;
        }
        else {
            Py_DECREF(item); /* 所有する参照を解放する */
        }
    }
    return total;
}

型

他にも Python/C API において重要な役割を持つデータ型がいくつかあります; ほとんどは int, long, double, および char* といった、単なる C のデータ型です。また、モジュールで公開している関数を列挙する際に用いられる静的なテーブルや、新しいオブジェクト型におけるデータ属性を記述したり、複素数の値を記述したりするために構造体をいくつか使っています。これらの型については、その型を使う関数とともに説明してゆきます。

type Py_ssize_t
次に属します: Stable ABI.

sizeof(Py_ssize_t) == sizeof(size_t) を満たす符号付き整数型です。 C99 は、このような型を直接定義していません (size_t は符号なし整数型です)。 詳しくは PEP 353 を参照してください。

Py_INVALID_SIZE

無効なサイズを表す、値が -1 の Py_ssize_t 型の定数です。

PY_SSIZE_T_MAX
PY_SSIZE_T_MIN

それぞれ、Py_ssize_t 型の最大の正の値と最小の負の値です。

PY_DWORD_MAX

Windows の DWORD 型の最大値です。 すべてのプラットフォームで 0xffffffff に展開されます。

例外

Python プログラマは、特定のエラー処理が必要なときだけしか例外を扱う必要はありません; 処理しなかった例外は、処理の呼び出し側、そのまた呼び出し側、といった具合に、トップレベルのインタプリタ層まで自動的に伝播します。インタプリタ層は、スタックトレースバックと合わせて例外をユーザに報告します。

ところが、 C プログラマの場合、エラーチェックは常に明示的に行わねばなりません。 Python/C API の全ての関数は、関数のドキュメントで明確に説明がない限り例外を発行する可能性があります。一般的な話として、ある関数が何らかのエラーに遭遇すると、関数は例外を設定して、関数内における参照の所有権を全て放棄し、エラー値 (error indicator) を返します。ドキュメントに書かれてない場合、このエラー値は関数の戻り値の型によって、 NULL か -1 のどちらかになります。いくつかの関数ではブール型で真/偽を返し、偽はエラーを示します。きわめて少数の関数では明確なエラー指標を返さなかったり、あいまいな戻り値を返したりするので、 PyErr_Occurred() で明示的にエラーテストを行う必要があります。これらの例外は常に明示的にドキュメント化されます。

例外状態は、スレッドごとの記憶領域で管理されます。 スレッドを使わないアプリケーションでは、グローバルな記憶領域を使うことに相当します。 スレッドは、例外が発生しているか、していないかの 2 つの状態のいずれかを取ります。 PyErr_Occurred() でこれを調べられます。 例外が発生していれば、その例外の型オブジェクトへの借用参照を返し、それ以外の場合は NULL を返します。 例外状態を設定する関数はいくつかあり、PyErr_SetString() が最もよく使われますが、最も汎用的な関数というわけではありません。 PyErr_Clear() は例外状態を消去します。

完全な例外状態は、例外の型、対応する例外の値、トレースバックの 3 つのオブジェクトからなり、いずれも NULL になりえます。 これらは Python の sys.exc_info() の結果と同じ意味を持ちますが、同じものではありません。 Python 側のオブジェクトは、Python の try ... except 文で現在処理している最後の例外を表します。 一方、C レベルの例外状態が存在するのは、例外が C 関数の間で受け渡され、Python バイトコードインタープリタのメインループに到達するまでの間だけです。 メインループが、例外を sys.exc_info() などに移す処理を行います。

Python 1.5 以降、Python コードから例外状態にアクセスするには、スレッドセーフな sys.exc_info() の呼び出しを推奨します。 この関数は、Python コードから使う、スレッドごとの例外状態を返します。 また、両方の例外状態へのアクセス方法の意味が変更され、例外を捕捉する関数が、呼び出し元の例外状態を保つためにスレッドの例外状態を保存・復元するようになりました。 これにより、無害に見える関数が処理中の例外を上書きすることで生じる、例外処理コードのよくあるバグを防ぎます。 トレースバック内のスタックフレームが参照するオブジェクトの寿命が、不必要に延びることも減らします。

一般に、何らかの処理を別の関数に任せる関数は、呼び出し先が例外を送出したかを調べ、送出していれば、その例外状態を自身の呼び出し元に伝えるべきです。 所有しているオブジェクトへの参照を解放し、エラーを示す値を返します。 ただし、別の例外を設定しては なりません。 そうすると、直前に送出された例外を上書きし、エラーの正確な原因に関する重要な情報を失ってしまいます。

例外を検出して呼び出し元に伝える単純な例は、上の sum_sequence() に示されています。 この例では、エラーを検出したときに所有する参照の後始末をする必要がありません。 次の関数では、エラー時の後始末の例を示します。 まず、Python の良さを思い出せるように、同じ処理を Python で書いたコードを示します。

def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1

以下は対応するコードを C で完璧に書いたものです:

int
incr_item(PyObject *dict, PyObject *key)
{
    /* Py_XDECREF のため、すべてのオブジェクトを NULL で初期化する */
    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
    int rv = -1; /* 戻り値を -1 (失敗) で初期化する */

    item = PyObject_GetItem(dict, key);
    if (item == NULL) {
        /* KeyError のみ処理する: */
        if (!PyErr_ExceptionMatches(PyExc_KeyError))
            goto error;

        /* エラーを消去してゼロを使う: */
        PyErr_Clear();
        item = PyLong_FromLong(0L);
        if (item == NULL)
            goto error;
    }
    const_one = PyLong_FromLong(1L);
    if (const_one == NULL)
        goto error;

    incremented_item = PyNumber_Add(item, const_one);
    if (incremented_item == NULL)
        goto error;

    if (PyObject_SetItem(dict, key, incremented_item) < 0)
        goto error;
    rv = 0; /* 成功 */
    /* 続いて後始末のコードを実行する */

 error:
    /* 成功と失敗の両方で使う後始末のコード */

    /* NULL 参照を無視するため Py_XDECREF() を使う */
    Py_XDECREF(item);
    Py_XDECREF(const_one);
    Py_XDECREF(incremented_item);

    return rv; /* エラーなら -1、成功なら 0 */
}

なんとこの例は C で goto 文を使うお勧めの方法まで示していますね! この例では、特定の例外を処理するために PyErr_ExceptionMatches() および PyErr_Clear() をどう使うかを示しています。また、所有権を持っている参照で、値が NULL になるかもしれないものを捨てるために Py_XDECREF() をどう使うかも示しています (関数名に 'X' が付いていることに注意してください; Py_DECREF() は NULL 参照に出くわすとクラッシュします)。正しく動作させるためには、所有権を持つ参照を保持するための変数を NULL で初期化することが重要です; 同様に、あらかじめ戻り値を定義する際には値を -1 (失敗) で初期化しておいて、最後の関数呼び出しまでうまくいった場合にのみ 0 (成功) に設定します。

Python の埋め込み

Python インタプリタの埋め込みを行う人 (いわば拡張モジュールの書き手の対極) が気にかけなければならない重要なタスクは、Python インタプリタの初期化処理 (initialization)、そしておそらくは終了処理 (finalization) です。インタプリタのほとんどの機能は、インタプリタの起動後しか使えません。

基本的な初期化処理を行う関数は Py_Initialize() です。この関数はロード済みのモジュールからなるテーブルを作成し、土台となるモジュール builtins, __main__, および sys を作成します。また、モジュール検索パス (sys.path) の初期化も行います。

Py_Initialize() does not set the "script argument list" (sys.argv). If this variable is needed by Python code that will be executed later, setting PyConfig.argv and PyConfig.parse_argv must be set: see Python Initialization Configuration.

ほとんどのシステムでは (特に Unix と Windows は、詳細がわずかに異なりはしますが)、 Py_Initialize() は標準の Python インタプリタ実行形式の場所に対する推定結果に基づいて、 Python のライブラリが Python インタプリタ実行形式からの相対パスで見つかるという仮定の下にモジュール検索パスを計算します。とりわけこの検索では、シェルコマンド検索パス (環境変数 PATH) 上に見つかった python という名前の実行ファイルの置かれているディレクトリの親ディレクトリからの相対で、 lib/pythonX.Y という名前のディレクトリを探します。

例えば、 Python 実行形式が /usr/local/bin/python で見つかったとすると、ライブラリが /usr/local/lib/pythonX.Y にあるものと仮定します。 (実際には、このパスは "フォールバック (fallback)" のライブラリ位置でもあり、 python が PATH 上に無い場合に使われます。) ユーザは PYTHONHOME を設定することでこの動作をオーバーライドしたり、 PYTHONPATH を設定して追加のディレクトリを標準モジュール検索パスの前に挿入したりできます。

Python を組み込むアプリケーションは、Py_InitializeFromConfig() を呼び出す 前に PyConfig.program_name を設定することで、検索先を指定できます。 この場合も PYTHONHOME の指定が優先され、PYTHONPATH は標準のパスの前に挿入されます。

たまに、 Python を初期化前の状態にもどしたいことがあります。例えば、あるアプリケーションでは実行を最初からやりなおし (start over) させる (Py_Initialize() をもう一度呼び出させる) ようにしたいかもしれません。あるいは、アプリケーションが Python を一旦使い終えて、Python が確保したメモリを解放させたいかもしれません。 Py_FinalizeEx() を使うとこうした処理を実現できます。また、関数 Py_IsInitialized() は、Python が現在初期化済みの状態にある場合に真を返します。これらの関数についてのさらなる情報は、後の章で説明します。 Py_FinalizeEx() がPythonインタプリタに確保された全てのメモリを 解放するわけではない ことに注意してください。例えば、拡張モジュールによって確保されたメモリは、現在のところ解放する事ができません。

デバッグ版ビルド (Debugging Builds)

インタプリタと拡張モジュールに対しての追加チェックをするためのいくつかのマクロを有効にしてPythonをビルドすることができます。これらのチェックは、実行時に大きなオーバーヘッドを生じる傾向があります。なので、デフォルトでは有効にされていません。

Pythonデバッグ版ビルドの全ての種類のリストが、Pythonソース配布(source distribution)の中の Misc/SpecialBuilds.txt にあります。参照カウントのトレース、メモリアロケータのデバッグ、インタプリタのメインループの低レベルプロファイリングが利用可能です。よく使われるビルドについてのみ、この節の残りの部分で説明します。

Py_DEBUG

Py_DEBUG マクロを定義してインタープリタをコンパイルすると、一般に Python のデバッグビルド と呼ばれるものができます。

Unix では、./configure コマンドに --with-pydebug を追加して Py_DEBUG を有効にできます。 これにより、コンパイラの最適化も無効になります。

Windows では、例えば PCbuild/build.bat に -d を渡すなどしてデバッグビルドを選ぶと、Py_DEBUG が自動的に有効になります。 さらに、Python 固有ではない _DEBUG マクロがコンパイラによって定義されている場合も、Py_DEBUG が暗黙に有効になります。

以下で説明する参照カウントのデバッグに加え、追加の検査を行います。 詳しくは Python のデバッグビルド を参照してください。

Defining Py_TRACE_REFS enables reference tracing (see the configure --with-trace-refs option). When defined, a circular doubly linked list of active objects is maintained by adding two extra fields to every PyObject. Total allocations are tracked as well. Upon exit, all existing references are printed. (In interactive mode this happens after every statement run by the interpreter.)

より詳しい情報については、Pythonのソース配布(source distribution)の中の Misc/SpecialBuilds.txt を参照してください。