超高水準レイヤ
**************

この章の関数を使うとファイルまたはバッファにある Python ソースコードを
実行できますが、より詳細なやり取りをインタプリタとすることはできないで
しょう。

これらの関数のいくつかは引数として文法の開始記号を受け取ります。使用で
きる開始記号は "Py_eval_input" と "Py_file_input" 、 "Py_single_input"
です。開始記号の説明はこれらを引数として取る関数の後にあります。

これらの関数のいくつかが "FILE*" 引数をとることにも注意してください。
注意深く扱う必要がある特別な問題の1つは、異なるCライブラリの "FILE" 構
造体は異なっていて互換性がない可能性があるということです。実際に(少な
くとも)Windowsでは、動的リンクされる拡張が異なるライブラリを使うことが
可能であり、したがって、 "FILE*" 引数がPythonランタイムが使っているラ
イブラリと同じライブラリによって作成されたことが確かならば、単にこれら
の関数へ渡すだけということに注意すべきです。

int Py_Main(int argc, wchar_t **argv)

   標準インタプリタのためのメインプログラム。Pythonを組み込むプログラ
   ムのためにこれを利用できるようにしています。 *argc* と *argv* 引数
   をCプログラムの "main()" 関数 (ユーザのロケールに従って wchar_t に
   変換されます) へ渡されるものとまったく同じに作成すべきです。引数リ
   ストが変更される可能性があるという点に注意することは重要です。 (し
   かし、引数リストが指している文字列の内容は変更されません)。戻り値は
   インタプリタが(例外などではなく)普通に終了した時は "0" に、例外で終
   了したときには "1" に、引数リストが正しい Python コマンドラインが渡
   されなかったときは "2" になります。

   "Py_InspectFlag" が設定されていない場合、未処理の "SystemExit" 例外
   が発生すると、この関数は "1" を返すのではなくプロセスを exit するこ
   とに気をつけてください。

int PyRun_AnyFile(FILE *fp, const char *filename)

   下記の "PyRun_AnyFileExFlags()" の *closeit* を "0" に、 *flags* を
   "NULL" にして単純化したインタフェースです。

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

   下記の "PyRun_AnyFileExFlags()" の *closeit* を "0" にして単純化し
   たインタフェースです。

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

   下記の "PyRun_AnyFileExFlags()" の *flags* を "NULL" にして単純化し
   たインタフェースです。

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

   *fp* が対話的デバイス (コンソールや端末入力あるいは Unix 仮想端末)
   と関連づけられたファイルを参照している場合は、
   "PyRun_InteractiveLoop()" の値を返します。それ以外の場合は、
   "PyRun_SimpleFile()" の結果を返します。 *filename* はファイルシステ
   ムのエンコーディング ("sys.getfilesystemencoding()") でデコードされ
   ます。 *filename* が "NULL" ならば、この関数はファイル名として
   ""???"" を使います。

int PyRun_SimpleString(const char *command)

   This is a simplified interface to "PyRun_SimpleStringFlags()"
   below, leaving the "PyCompilerFlags"* argument set to "NULL".

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

   "__main__" モジュールの中で *flags* に従って *command* に含まれる
   Python ソースコードを実行します。 "__main__" がまだ存在しない場合は
   作成されます。正常終了の場合は "0" を返し、また例外が発生した場合は
   "-1" を返します。エラーがあっても、例外情報を得る方法はありません。
   *flags* の意味については、後述します。

   "Py_InspectFlag" が設定されていない場合、未処理の "SystemExit" 例外
   が発生すると、この関数は "1" を返すのではなくプロセスを exit するこ
   とに気をつけてください。

int PyRun_SimpleFile(FILE *fp, const char *filename)

   下記の "PyRun_SimpleFileExFlags()" の *closeit* を "0" に、 *flags*
   を "NULL" にして単純化したインタフェースです。

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

   下記の "PyRun_SimpleFileExFlags()" の *flags* を "NULL" にして単純
   化したインタフェースです。

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

   "PyRun_SimpleStringFlags()" と似ていますが、Pythonソースコードをメ
   モリ内の文字列ではなく *fp* から読み込みます。 *filename* はそのフ
   ァイルの名前でなければならず、ファイルシステムのエンコーディング
   ("sys.getfilesystemencoding()") でデコードされます。 *closeit* に真
   を指定した場合は、PyRun_SimpleFileExFlags が処理を戻す前にファイル
   を閉じます。

   注釈:

     Windowsでは、 *fp* はバイナリモードで開くべきです (例えば
     "fopen(filename, "rb")")。 そうしない場合は、 Python は行末が LF
     のスクリプトを正しく扱えないでしょう。

int PyRun_InteractiveOne(FILE *fp, const char *filename)

   下記の "PyRun_InteractiveOneFlags()" の *flags* を "NULL" にして単
   純化したインタフェースです。

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

   対話的デバイスに関連付けられたファイルから文を一つ読み込み、
   *flags* に従って実行します。 "sys.ps1" と "sys.ps2" を使って、ユー
   ザにプロンプトを表示します。 *filename* はファイルシステムのエンコ
   ーディング ("sys.getfilesystemencoding()") でデコードされます。

   入力が正常に実行されたときは "0" を返します。例外が発生した場合は
   "-1" を返します。パースエラーの場合はPythonの一部として配布されてい
   る "errcode.h" インクルードファイルにあるエラーコードを返します。
   ("Python.h" は "errcode.h" をインクルードしません。従って、 必要な
   場合はその都度インクルードしなければならないことに注意してください
   。)

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

   下記の "PyRun_InteractiveLoopFlags()" の *flags* を "NULL" にして単
   純化したインタフェースです。

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

   対話的デバイスに関連付けられたファイルから EOF に達するまで文を読み
   込み実行します。 "sys.ps1" と "sys.ps2" を使って、ユーザにプロンプ
   トを表示します。 *filename* はファイルシステムのエンコーディング
   ("sys.getfilesystemencoding()") でデコードされます。 EOFに達すると
   "0" を返すか、失敗したら負の数を返します。

int (*PyOS_InputHook)(void)

   "int func(void)" というプロトタイプの関数へのポインタが設定できます
   。 この関数は、 Python のインタプリタのプロンプトがアイドル状態にな
   りターミナルからのユーザの入力を待つようになったときに呼び出されま
   す。 返り値は無視されます。 このフックを上書きすることで、 Python
   のソースコードの中で "Modules/_tkinter.c" がやっているように、イン
   タプリタのプロンプトと他のイベントループを統合できます。

char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)

   "char *func(FILE *stdin, FILE *stdout, char *prompt)" というプロト
   タイプの関数へのポインタが設定でき、デフォルトの関数を上書きするこ
   とでインタプリタのプロンプトへの入力を1行だけ読めます。 この関数は
   、文字列 *prompt* が "NULL" でない場合は *prompt* を出力し、与えら
   れた標準入力ファイルから入力を1行読み、結果の文字列を返すという動作
   が期待されています。 例えば、 "readline" モジュールはこのフックを設
   定して、行編集機能やタブ補完機能を提供しています。

   返り値は "PyMem_RawMalloc()" または "PyMem_RawRealloc()" でメモリ確
   保した文字列、あるいはエラーが起きた場合には "NULL" でなければなり
   ません。

   バージョン 3.4 で変更: 返り値は、 "PyMem_Malloc()" や
   "PyMem_Realloc()" ではなく、 "PyMem_RawMalloc()" または
   "PyMem_RawRealloc()" でメモリ確保したものでなければなりません。

struct _node* PyParser_SimpleParseString(const char *str, int start)

   下記の "PyParser_SimpleParseStringFlagsFilename()" の *filename* を
   "NULL" に、 *flags* を "0" にして単純化したインタフェースです。

struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)

   下記の "PyParser_SimpleParseStringFlagsFilename()" の *filename* を
   "NULL" にして単純化したインタフェースです。

struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)

   開始トークン *start* を使って *str* に含まれる Python ソースコード
   を *flags* 引数に従ってパースします。効率的に評価可能なコードオブジ
   ェ クトを作成するためにその結果を使うことができます。コード断片を何
   度も評価しなければならない場合に役に立ちます。 *filename* はファイ
   ルシステムエンコーディング ("sys.getfilesystemencoding()") でデコー
   ドされます。

struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

   下記の "PyRun_SimpleParseFileFlags()" の *flags* を "0" にして単純
   化したインタフェースです。

struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

   "PyParser_SimpleParseStringFlagsFilename()" に似ていますが、 Python
   ソースコードをメモリ内の文字列ではなく *fp* から読み込みます。
   *filename* はそのファイルの名前でなけれななりません。

PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
    *Return value: New reference.*

   下記の "PyRun_StringFlags()" の *flags* を "NULL" にして単純化した
   インタフェースです。

PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *Return value: New reference.*

   オブジェクトの *globals* と *locals* で指定されるコンテキストで、コ
   ンパイラフラグに *flags* を設定した状態で、 *str* にある Python ソ
   ースコードを実行します。 *globals* は辞書でなければなりません;
   *locals* はマッピングプロトコルを実装したオブジェクトなら何でも構い
   ません。 引数 *start* はソースコードをパースするために使われるべき
   開始トークンを指定します。

   コードを実行した結果をPythonオブジェクトとして返します。または、例
   外が発生したならば "NULL" を返します。

PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
    *Return value: New reference.*

   下記の "PyRun_FileExFlags()" の *closeit* を "0" にし、 *flags* を
   "NULL" にして単純化したインタフェースです。

PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
    *Return value: New reference.*

   下記の "PyRun_FileExFlags()" の *flags* を "NULL" にして単純化した
   インタフェースです。

PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *Return value: New reference.*

   下記の "PyRun_FileExFlags()" の *closeit* を "0" にして単純化したイ
   ンタフェースです。

PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
    *Return value: New reference.*

   "PyRun_StringFlags()" と似ていますが、Pythonソースコードをメモリ内
   の文字列ではなく *fp* から読み込みます。 *filename* はそのファイル
   の名前でなければならず、ファイルシステムのエンコーディング
   ("sys.getfilesystemencoding()") でデコードされます。もし *closeit*
   を真にすると、 "PyRun_FileExFlags()" が処理を戻す前にファイルを閉じ
   ます。

PyObject* Py_CompileString(const char *str, const char *filename, int start)
    *Return value: New reference.*

   下記の "Py_CompileStringFlags()" の *flags* を "NULL" にして単純化
   したインタフェースです。

PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
    *Return value: New reference.*

   下記の "Py_CompileStringExFlags()" の *optimize* を "-1" にして単純
   化したインタフェースです。

PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
    *Return value: New reference.*

   *str* 内の Python ソースコードをパースしてコンパイルし、作られたコ
   ードオブジェクトを返します。開始トークンは *start* によって与えられ
   ます。これはコンパイル可能なコードを制限するために使うことができ、
   "Py_eval_input" 、 "Py_file_input" もしくは "Py_single_input" であ
   るべきです。 *filename* で指定されるファイル名はコードオブジェクト
   を構築するために使われ、トレースバックあるいは "SyntaxError" 例外メ
   ッセージに出てくる可能性があります。コードがパースできなかったりコ
   ンパイルできなかったりした場合に、これは "NULL" を返します。

   整数 *optimize* は、コンパイラの最適化レベルを指定します;  "-1" は
   、インタプリタの "-O" オプションで与えられるのと同じ最適化レベルを
   選びます。明示的なレベルは、 "0" (最適化なし、 "__debug__" は真)、
   "1" (assert は取り除かれ、 "__debug__" は偽)、 "2" (docstring も取
   り除かれる) です。

   バージョン 3.4 で追加.

PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
    *Return value: New reference.*

   "Py_CompileStringObject()" と似ていますが、 *filename* はファイルシ
   ステムのエンコーディングでデコード ("os.fsdecode()") されたバイト文
   字列です。

   バージョン 3.2 で追加.

PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
    *Return value: New reference.*

   "PyEval_EvalCodeEx()" のシンプルなインタフェースで、コードオブジェ
   クトと、グローバル変数とローカル変数だけを受け取ります。 他の引数に
   は "NULL" が渡されます。

PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)
    *Return value: New reference.*

   与えられた特定の環境で、コンパイル済みのコードオブジェクトを評価し
   ます。この環境はグローバル変数の辞書と、ローカル変数のマッピングオ
   ブジェクト、引数の配列、キーワードとデフォルト値、キーワード専用 引
   数のデフォルト値の辞書と、セルのクロージャタプルで構成されます。

PyFrameObject

   フレームオブジェクトを表現するために使われるオブジェクトのC構造体。
   この型のフィールドはいつでも変更され得ます。

PyObject* PyEval_EvalFrame(PyFrameObject *f)
    *Return value: New reference.*

   実行フレームを評価します。これは "PyEval_EvalFrameEx()" に対するシ
   ンプルなインタフェースで、後方互換性のためのものです。

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
    *Return value: New reference.*

   Python のインタープリタの主要な、直接的な関数です。 この関数には
   2000 行ほどあります。 実行フレーム *f* に関連付けられたコードオブジ
   ェクトを実行します。 バイトコードを解釈して、必要に応じて呼び出しを
   実行します。 追加の *throwflag* 引数はほとんど無視できます。 - もし
   true なら、 すぐに例外を発生させます。これはジェネレータオブジェク
   トの "throw()" メソッドで利用されます。

   バージョン 3.4 で変更: アクティブな例外を黙って捨てないことを保証す
   るのに便利なように、この関数はデバッグアサーションを含むようになり
   ました。

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

   現在の評価フレームのフラグを変更します。成功したら true を、失敗し
   たら false を返します。

int Py_eval_input

   単独の式に対するPython文法の開始記号で、 "Py_CompileString()" と一
   緒に使います。

int Py_file_input

   ファイルあるいは他のソースから読み込まれた文の並びに対するPython文
   法の開始記号で、 "Py_CompileString()" と一緒に使います。これは任意
   の長さのPythonソースコードをコンパイルするときに使う記号です。

int Py_single_input

   単一の文に対するPython文法の開始記号で、 "Py_CompileString()" と一
   緒に使います。これは対話式のインタプリタループのための記号です。

struct PyCompilerFlags

   コンパイラフラグを収めておくための構造体です。コードをコンパイルす
   るだけの場合、この構造体が "int flags" として渡されます。コードを実
   行する場合には "PyCompilerFlags *flags" として渡されます。この場合
   、"from __future__ import" は *flags* の内容を変更できます。

   Whenever "PyCompilerFlags *flags" is "NULL", "cf_flags" is treated
   as equal to "0", and any modification due to "from __future__
   import" is discarded.

      struct PyCompilerFlags {
          int cf_flags;
      }

int CO_FUTURE_DIVISION

   このビットを *flags* にセットすると、除算演算子 "/" は **PEP 238**
   による「真の除算 (true division)」として扱われます。
