はじめに
********

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/python*X.Y*" という名
前のディレクトリを探します。

例えば、 Python 実行形式が "/usr/local/bin/python" で見つかったとする
と、ライブラリが "/usr/local/lib/python*X.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" を参照してください。


おすすめのサードパーティツール
==============================

以下のサードパーティーツールは、Python 用の C、C++、Rust 拡張を、より
簡単かつ高度な方法で作成できるようにします。

* Cython

* cffi

* HPy

* nanobind (C++)

* Numba

* pybind11 (C++)

* PyO3 (Rust)

* SWIG

これらのツールを使うと、特定の CPython バージョンに強く依存したコード
や、参照カウントの誤りを避けられ、CPython API の扱いよりも自分のコード
に集中できます。 一般に、ツールを更新することで Python の新しいバージ
ョンに対応でき、より新しく効率的な API が自動的に使われることもよくあ
ります。 1 つのソースから、Python のほかの実装向けにコンパイルできるツ
ールもあります。

これらのプロジェクトのサポートは Python の保守担当者とは別の人々が行っ
ているため、問題は各プロジェクトに直接報告する必要があります。 上の一
覧は古くなる可能性があるので、そのプロジェクトの保守とサポートが続いて
いることを確認してください。

参考:

  Python Packaging User Guide: Binary Extensions
     Python Packaging User Guideはバイナリ拡張の作成が簡単になる便利な
     ツールをカバーしているだけではなく、まず始めになぜ拡張モジュール
     を作ることが望ましいかの様々な理由について議論しています。
