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

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

Several of these functions accept a start symbol from the grammar as a
parameter.  The available start symbols are "Py_eval_input",
"Py_file_input", and "Py_single_input".  These are described following
the functions which accept them as parameters.

Note also that several of these functions take FILE* parameters.  One
particular issue which needs to be handled carefully is that the
"FILE" structure for different C libraries can be different and
incompatible.  Under Windows (at least), it is possible for
dynamically linked extensions to actually use different libraries, so
care should be taken that FILE* parameters are only passed to these
functions if it is certain that they were created by the same library
that the Python runtime is using.

int Py_Main(int argc, wchar_t **argv)
    * 次に属します: Stable ABI.*

   The main program for the standard interpreter.  This is made
   available for programs which embed Python.  The *argc* and *argv*
   parameters should be prepared exactly as those which are passed to
   a C program's "main()" function (converted to wchar_t according to
   the user's locale).  It is important to note that the argument list
   may be modified (but the contents of the strings pointed to by the
   argument list are not). The return value will be "0" if the
   interpreter exits normally (i.e., without an exception), "1" if the
   interpreter exits due to an exception, or "2" if the parameter list
   does not represent a valid Python command line.

   Note that if an otherwise unhandled "SystemExit" is raised, this
   function will not return "1", but exit the process, as long as
   "PyConfig.inspect" is zero.

int Py_BytesMain(int argc, char **argv)
    * 次に属します: Stable ABI (バージョン 3.8 より).*

   Similar to "Py_Main()" but *argv* is an array of bytes strings.

   Added in version 3.8.

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" ならば、この関数はファイル名として
   ""???"" を使います。*closeit* が真なら、ファイルは
   "PyRun_SimpleFileExFlags()" が処理を戻す前に閉じられます。

int PyRun_SimpleString(const char *command)

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

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

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

   Note that if an otherwise unhandled "SystemExit" is raised, this
   function will not return "-1", but exit the process, as long as
   "PyConfig.inspect" is zero.

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* はそのフ
   ァイルの名前でなければならず、 *ファイルシステムのエンコーディング
   とエラーハンドラ* でデコードされます。 *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* は *ファイルシステムのエン
   コーディングとエラーハンドラ* でデコードされます。

   入力が正常に実行されたときは "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* は *ファイルシステムのエンコーディング
   とエラーハンドラ* でデコードされます。 EOFに達すると "0" を返すか、
   失敗したら負の数を返します。

int (*PyOS_InputHook)(void)
    * 次に属します: Stable ABI.*

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

   バージョン 3.12 で変更: This function is only called from the main
   interpreter.

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()" でメモリ確保したものでなければなりません。

   バージョン 3.12 で変更: This function is only called from the main
   interpreter.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
    *戻り値: 新しい参照。*

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

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *戻り値: 新しい参照。*

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

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

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
    *戻り値: 新しい参照。*

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

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
    *戻り値: 新しい参照。*

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

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *戻り値: 新しい参照。*

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

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
    *戻り値: 新しい参照。*

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

PyObject *Py_CompileString(const char *str, const char *filename, int start)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
    *戻り値: 新しい参照。*

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

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
    *戻り値: 新しい参照。*

   Parse and compile the Python source code in *str*, returning the
   resulting code object.  The start token is given by *start*; this
   can be used to constrain the code which can be compiled and should
   be "Py_eval_input", "Py_file_input", or "Py_single_input".  The
   filename specified by *filename* is used to construct the code
   object and may appear in tracebacks or "SyntaxError" exception
   messages.  This returns "NULL" if the code cannot be parsed or
   compiled.

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

   Added in version 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
    *戻り値: 新しい参照。*

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

   Added in version 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "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)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyEval_EvalFrame(PyFrameObject *f)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Python のインタープリタの主要な、直接的な関数です。実行フレーム *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.

   int cf_flags

      コンパイラフラグ。

   int cf_feature_version

      *cf_feature_version* is the minor Python version. It should be
      initialized to "PY_MINOR_VERSION".

      The field is ignored by default, it is used if and only if
      "PyCF_ONLY_AST" flag is set in "cf_flags".

   バージョン 3.8 で変更: Added *cf_feature_version* field.

int CO_FUTURE_DIVISION

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