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

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 のバージョンで同じ名前が定義されて、ユーザの書いたコードの
可搬性を危うくする可能性があります。

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

ヘッダをインクルードするには、各ヘッダの入ったディレクトリ (別々のディ
レクトリの場合は両方) を、コンパイラがインクルードファイルを検索するた
めのパスに入れます。親ディレクトリをサーチパスに入れて、 "#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()" を呼び出して decref する役割を担います
--- あるいは、その役割を (通常はコードを呼び出した元に) 受け渡します。
ある関数が、関数の呼び出し側に対して参照の所有権を渡すと、呼び出し側は
*新たな* 参照 (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"));

ここで、 "PyInt_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)
   {
       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 において重要な役割を持つデータ型は、 "PyObject" 型の他に
もいくつかあります; ほとんどは "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()" は例外状態情報を消し去る関数です。

完全な例外状態情報は、3 つのオブジェクト: 例外の型、例外の値、そしてト
レースバック、からなります  (どのオブジェクトも *NULL* を取り得ます)。
これらの情報は、 Python オブジェクトの   "sys.exc_type",
"sys.exc_value", および "sys.exc_traceback" と同じ意味を持ちます; とは
いえ、 C と Python の例外状態情報は全く同じではありません: Python にお
ける例外オブジェクトは、Python の "try" ...  "except" 文で最近処理した
オブジェクトを表す一方、 C レベルの例外状態情報が存続するのは、渡され
た例外情報を "sys.exc_type" その他に転送するよう取り計らう Python のバ
イトコードインタプリタのメインループに到達するまで、例外が関数の間で受
け渡しされている間だけです。

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)
です。インタプリタのほとんどの機能は、インタプリタの起動後しか使えませ
ん。

基本的な初期化処理を行う関数は "Py_Initialize()" です。この関数はロー
ド済みのモジュールからなるテーブルを作成し、土台となるモジュール
"__builtin__", "__main__",  "sys" , "exceptions" を作成します。また、
モジュール検索パス ("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" で定義されています)。

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


デバッグ版ビルド (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()" メソッドが追加されます。

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

* 初期化されていない数に対する参照を検出するために、長整数のストレー
  ジ が特定の妥当でないパターンで初期化されます。

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

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

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

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

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

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