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

Python のアプリケーションプログラマ用インタフェース (Application
Programmer’s Interface, API) は、 Python インタプリタに対する様々なレ
ベルでのアクセス手段を C や C++ のプログラマに提供しています。この API
は通常 C++ からも全く同じように利用できるのですが、簡潔な呼び名にする
ために Python/C API と名づけられています。根本的に異なる二つの目的から
、 Python/C API が用いられます。第一は、特定用途の *拡張モジュール
(extention module)* 、すなわち Python インタプリタを拡張する C で書か
れたモジュールを記述する、という目的です。第二は、より大規模なアプリケ
ーション内で Python を構成要素 (component) として利用するという目的で
す; このテクニックは、一般的にはアプリケーションへの Python の埋め込み
(*embedding*) と呼びます。

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

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


インクルードファイル
====================

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

   #include "Python.h"

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

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

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

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

The header files are typically installed with Python.  On Unix, these
are located in the directories "*prefix*/include/pythonversion/" and
"*exec_prefix*/include/pythonversion/", where "prefix" and
"exec_prefix" are defined by the corresponding parameters to Python’s
**configure** script and *version* is "sys.version[:3]".  On Windows,
the headers are installed in "*prefix*/include", where "prefix" is the
installation directory specified to the installer.

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

API はすべて C 言語を使って定義していますが、ヘッダファイルはエントリ
ポイントを "extern "C"" で適切に宣言しているので、C++ ユーザは、なんの
問題もなく C++から API を利用できることに気づくはずです。


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

Python/C API 関数は、 "PyObject*" 型の一つ以上の引数と戻り値を持ちます
。この型は、任意の Python オブジェクトを表現する不透明 (opaque) なデー
タ型へのポインタです。 Python 言語は、全ての Python オブジェクト型をほ
とんどの状況 (例えば代入、スコープ規則 (scope rule)、引数渡し) で同様
に扱います。ほとんど全ての Python オブジェクトはヒープ (heap) 上に置か
れます: このため、 "PyObject" 型のオブジェクトは、自動記憶 (automatic)
としても静的記憶 (static) としても宣言できません。 "PyObject*" 型のポ
インタ変数のみ宣言できます。唯一の例外は、型オブジェクトです; 型オブジ
ェクトはメモリ解放 (deallocate) してはならないので、通常は静的記憶の
"PyTypeObject" オブジェクトにします。

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


参照カウント法
--------------

今日の計算機は有限の (しばしば非常に限られた) メモリサイズしか持たない
ので、参照カウントは重要な概念です; 参照カウントは、あるオブジェクトに
対して参照を行っている場所が何箇所あるかを数える値です。参照を行ってい
る場所とは、別のオブジェクトであったり、グローバルな (あるいは静的な)
C 変数であったり、何らかの C 関数内にあるローカルな変数だったりします
。あるオブジェクトの参照カウントがゼロになると、そのオブジェクトは解放
されます。そのオブジェクトに他のオブジェクトへの参照が入っていれば、他
のオブジェクトの参照カウントはデクリメントされます。デクリメントの結果
、他のオブジェクトの参照カウントがゼロになると、今度はそのオブジェクト
が解放される、といった具合に以後続きます。(言うまでもなく、互いを参照
しあうオブジェクトについて問題があります; 現状では、解決策は 「何もし
ない」 です。)

参照カウントは、常に明示的なやり方で操作されます。通常の方法では、
"Py_INCREF()" マクロでオブジェクトの参照を 1 インクリメントし、
"Py_DECREF()" マクロで 1 デクリメントします。 "Py_DECREF()" マクロは、
incref よりもかなり複雑です。というのは、 Py_DECREF マクロは参照カウン
トがゼロになったかどうかを調べて、なった場合にはオブジェクトのメモリ解
放関数 (deallocator) を呼び出さなければならないからです。メモリ解放関
数とは、オブジェクトの型を定義している構造体内にある関数へのポインタで
す。型固有のメモリ解放関数は、その型が複合オブジェクト (compound
object) 型である場合には、オブジェクト内の他のオブジェクトに対する参照
カウントをデクリメントするよう気を配るとともに、その他の必要なファイナ
ライズ (finalize) 処理を実行します。参照カウントがオーバフローすること
はありません; というのも、仮想メモリ空間には、("sizeof(Py_ssize_t) >=
sizeof(void*)" と仮定した場合) 少なくとも参照カウントの記憶に使われる
ビット数と同じだけのメモリ上の位置があるからです。従って、参照カウント
のインクリメントは単純な操作になります。

オブジェクトへのポインタが入っているローカルな変数全てについて、オブジ
ェクトの参照カウントを必ずインクリメントしなければならないわけではあり
ません。理論上は、オブジェクトの参照カウントは、オブジェクトを指し示す
変数が生成されたときに 1 増やされ、その変数がスコープから出て行った際
に 1 減らされます。しかしこの場合、二つの操作は互いに相殺するので、結
果的に参照カウントは変化しません。参照カウントを使う真の意義とは、手持
ちの何らかの変数がオブジェクトを指している間はオブジェクトがデアロケー
トされないようにすることにあります。オブジェクトに対して、一つでも別の
参照が行われていて、その参照が手持ちの変数と同じ間維持されるのなら、参
照カウントを一時的に増やす必要はありません。参照カウント操作の必要性が
浮き彫りになる重要な局面とは、Python から呼び出された拡張モジュール内
の C 関数にオブジェクトを引数として渡すときです; 呼び出しメカニズムは
、呼び出しの間全ての引数に対する参照を保証します。

しかしながら、よく陥る過ちとして、あるオブジェクトをリストから得たとき
に、参照カウントをインクリメントせずにしばらく放っておくというのがあり
ます。他の操作がオブジェクトをリストから除去してしまい、参照カウントが
デクリメントされてデアロケートされてしまうことが考えられます。本当に危
険なのは、まったく無害そうにみえる操作が、上記の動作を引き起こす何らか
の Python コードを呼び出しかねないということです; "Py_DECREF()" からユ
ーザへ制御を戻せるようなコードパスが存在するため、ほとんど全ての操作が
潜在的に危険をはらむことになります。

安全に参照カウントを操作するアプローチは、汎用の操作 (関数名が
"PyObject_", "PyNumber_", "PySequence_", および  "PyMapping_" で始まる
関数) の利用です。これらの操作は常に戻り値となるオブジェクトの参照カウ
ントをインクリメントします。ユーザには戻り値が不要になったら
"Py_DECREF()" を呼ぶ責任が残されています; とはいえ、すぐにその習慣は身
に付くでしょう。


参照カウントの詳細
~~~~~~~~~~~~~~~~~~

Python/C API の各関数における参照カウントの振る舞いは、説明するには、
*参照の所有権 (ownership of references)* という言葉でうまく説明できま
す。所有権は参照に対するもので、オブジェクトに対するものではありません
(オブジェクトは誰にも所有されず、常に共有されています)。ある 「参照の
所有」 は、その参照が必要なくなった時点で Py_DECREF を呼び出す役割を担
うことを意味します。所有権は委譲でき、あるコードが委譲によって所有権を
得ると、今度はそのコードが参照が必要なくなった際に最終的に
"Py_DECREF()" や "Py_XDECREF()" を呼び出して、参照カウンタを1つ減らす
役割を担います — あるいは、その役割を (通常はコードを呼び出した元に)
受け渡します。ある関数が、関数の呼び出し側に対して参照の所有権を渡すと
、呼び出し側は *新たな* 参照 (new reference) を得る、と言います。所有
権が渡されない場合、呼び出し側は参照を *借りる* (borrow) といいます。
借りた参照に対しては、何もする必要はありません。

逆に、ある関数呼び出しで、あるオブジェクトへの参照を呼び出される関数に
渡す際には、二つの可能性: 関数がオブジェクトへの参照を *盗み取る*
(steal) 場合と、そうでない場合があります。*参照を盗む* とは、関数に参
照を渡したときに、参照の所有者がその関数になったと仮定し、関数の呼び出
し元には所有権がなくなるということです。

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

   PyObject *t;

   t = PyTuple_New(3);
   PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
   PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
   PyTuple_SetItem(t, 2, PyString_FromString("three"));

Here, "PyInt_FromLong()" returns a new reference which is immediately
stolen by "PyTuple_SetItem()".  When you want to keep using an object
although the reference to it will be stolen, use "Py_INCREF()" to grab
another reference before calling the reference-stealing function.

ちなみに、 "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)
   {
       int i, n;

       n = PyObject_Length(target);
       if (n < 0)
           return -1;
       for (i = 0; i < n; i++) {
           PyObject *index = PyInt_FromLong(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)
   {
       int i, n;
       long total = 0;
       PyObject *item;

       n = PyList_Size(list);
       if (n < 0)
           return -1; /* Not a list */
       for (i = 0; i < n; i++) {
           item = PyList_GetItem(list, i); /* Can't fail */
           if (!PyInt_Check(item)) continue; /* Skip non-integers */
           total += PyInt_AsLong(item);
       }
       return total;
   }

   long
   sum_sequence(PyObject *sequence)
   {
       int i, n;
       long total = 0;
       PyObject *item;
       n = PySequence_Length(sequence);
       if (n < 0)
           return -1; /* Has no length */
       for (i = 0; i < n; i++) {
           item = PySequence_GetItem(sequence, i);
           if (item == NULL)
               return -1; /* Not a sequence, or other failure */
           if (PyInt_Check(item))
               total += PyInt_AsLong(item);
           Py_DECREF(item); /* Discard reference ownership */
       }
       return total;
   }


型
--

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


例外
====

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

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

例外時の状態情報 (exception state)は、スレッド単位に用意された記憶領域
(per-thread storage) 内で管理されます (この記憶領域は、スレッドを使わ
ないアプリケーションではグローバルな記憶領域と同じです)。一つのスレッ
ドは二つの状態のどちらか: 例外が発生したか、まだ発生していないか、をと
ります。関数 "PyErr_Occurred()" を使うと、この状態を調べられます: この
関数は例外が発生した際にはその例外型オブジェクトに対する借用参照
(borrowed reference) を返し、そうでないときには *NULL* を返します。例
外状態を設定する関数は数多くあります: "PyErr_SetString()" はもっともよ
く知られている (が、もっとも汎用性のない) 例外を設定するための関数で、
"PyErr_Clear()" は例外状態情報を消し去る関数です。

The full exception state consists of three objects (all of which can
be *NULL*): the exception type, the corresponding exception  value,
and the traceback.  These have the same meanings as the Python
objects "sys.exc_type", "sys.exc_value", and "sys.exc_traceback";
however, they are not the same: the Python objects represent the last
exception being handled by a Python  "try" … "except" statement, while
the C level exception state only exists while an exception is being
passed on between C functions until it reaches the Python bytecode
interpreter’s  main loop, which takes care of transferring it to
"sys.exc_type" and friends.

Python 1.5 からは、Python で書かれたコードから例外状態情報にアクセスす
る方法として、推奨されていてスレッドセーフな方法は "sys.exc_info()" に
なっているので注意してください。この関数は Python コードの実行されてい
るスレッドにおける例外状態情報を返します。また、これらの例外状態情報に
対するアクセス手段は、両方とも意味づけ (semantics) が変更され、ある関
数が例外を捕捉すると、その関数を実行しているスレッドの例外状態情報を保
存して、呼び出し側の例外状態情報を維持するようになりました。この変更に
よって、無害そうに見える関数が現在扱っている例外を上書きすることで引き
起こされる、例外処理コードでよくおきていたバグを抑止しています; また、
トレースバック内のスタックフレームで参照されているオブジェクトがしばし
ば不必要に寿命を永らえていたのをなくしています。

一般的な原理として、ある関数が別の関数を呼び出して何らかの作業をさせる
とき、呼び出し先の関数が例外を送出していないか調べなくてはならず、もし
送出していれば、その例外状態情報は呼び出し側に渡されなければなりません
。呼び出し元の関数はオブジェクト参照の所有権をすべて放棄し、エラー指標
を返さなくてはなりませんが、余計に例外を設定する必要は *ありません* —
そんなことをすれば、たった今送出されたばかりの例外を上書きしてしまい、
エラーの原因そのものに関する重要な情報を失うことになります。

例外を検出して渡す例は、上の "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)
   {
       /* Objects all initialized to NULL for Py_XDECREF */
       PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
       int rv = -1; /* Return value initialized to -1 (failure) */

       item = PyObject_GetItem(dict, key);
       if (item == NULL) {
           /* Handle KeyError only: */
           if (!PyErr_ExceptionMatches(PyExc_KeyError))
               goto error;

           /* Clear the error and use zero: */
           PyErr_Clear();
           item = PyInt_FromLong(0L);
           if (item == NULL)
               goto error;
       }
       const_one = PyInt_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; /* Success */
       /* Continue with cleanup code */

    error:
       /* Cleanup code, shared by success and failure path */

       /* Use Py_XDECREF() to ignore NULL references */
       Py_XDECREF(item);
       Py_XDECREF(const_one);
       Py_XDECREF(incremented_item);

       return rv; /* -1 for error, 0 for success */
   }

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


Python の埋め込み
=================

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

The basic initialization function is "Py_Initialize()". This
initializes the table of loaded modules, and creates the fundamental
modules "__builtin__", "__main__", "sys", and "exceptions".  It also
initializes the module search path ("sys.path").

"Py_Initialize()" の中では、 「スクリプトへの引数リスト」 (script
argument list, "sys.argv" のこと) を設定しません。この変数が後に実行さ
れる Python コード中で必要なら、 "Py_Initialize()" の後で
"PySys_SetArgvEx(argc, argv, updatepath)" を呼び出して明示的に設定しな
ければなりません。

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

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

埋め込みを行うアプリケーションでは、 "Py_Initialize()" を呼び出す *前
に* "Py_SetProgramName(file)"  を呼び出すことで、上記の検索を操作でき
ます。この埋め込みアプリケーションでの設定は依然として "PYTHONHOME"
でオーバライドでき、標準のモジュール検索パスの前には以前として
"PYTHONPATH" が挿入されるので注意してください。アプリケーションでモジ
ュール検索パスを完全に制御したいのなら、独自に "Py_GetPath()",
"Py_GetPrefix()", "Py_GetExecPrefix()",  および
"Py_GetProgramFullPath()"  の実装を提供しなければなりません (これらは
全て "Modules/getpath.c" で定義されています)。

Sometimes, it is desirable to 「uninitialize」 Python.  For instance,
the application may want to start over (make another call to
"Py_Initialize()") or the application is simply done with its  use of
Python and wants to free memory allocated by Python.  This can be
accomplished by calling "Py_Finalize()".  The function
"Py_IsInitialized()" returns true if Python is currently in the
initialized state.  More information about these functions is given in
a later chapter. Notice that "Py_Finalize()" does *not* free all
memory allocated by the Python interpreter, e.g. memory allocated by
extension modules currently cannot be released.


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

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

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

インタプリタを "Py_DEBUG" マクロを有効にしてコンパイルすると、一般的に
「デバッグビルド」といわれるPythonができます。 Unix では、
"./configure" コマンドに "--with-pydebug" を追加することで、
"Py_DEBUG" が有効になります。その場合、暗黙的にPython専用ではない
"_DEBUG" も有効になります。 Unix ビルドでは、 "Py_DEBUG" が有効な場合
、コンパイラの最適化が無効になります。

あとで説明する参照カウントデバッグの他に、以下の追加チェックも有効にな
ります:

* object allocator に対する追加チェック。

* パーサーとコンパイラに対する追加チェック。

* 情報損失のために、大きい型から小さい型へのダウンキャストに対するチ
  ェ ック。

* 辞書(dict)と集合(set)の実装に対する、いくつもの assertion の追加。
  加 えて、集合オブジェクトに "test_c_api()" メソッドが追加されます。

* フレームを作成する時の、引数の健全性チェック。

* The storage for long ints is initialized with a known invalid
  pattern to catch reference to uninitialized digits.

* 低レベルトレースと追加例外チェックがVM runtimeに追加されます。

* メモリアリーナ(memory arena)の実装に対する追加チェック。

* threadモジュールに対する追加デバッグ機能.

ここで言及されていない追加チェックもあるでしょう。

"Py_TRACE_REFS" を宣言すると、参照トレースが有効になります。全ての
"PyObject" に二つのフィールドを追加することで、使用中のオブジェクトの
循環二重連結リストが管理されます。全ての割り当て(allocation)がトレース
されます。終了時に、全ての残っているオブジェクトが表示されます。 (イン
タラクティブモードでは、インタプリタによる文の実行のたびに表示されます
) Py_TRACE_REFS は "Py_DEBUG" によって暗黙的に有効になります。

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