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

この章の関数を使うとファイルまたはバッファにある 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 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.

   The available compiler flags are accessible as macros:

   PyCF_ALLOW_TOP_LEVEL_AWAIT
   PyCF_ONLY_AST
   PyCF_OPTIMIZED_AST
   PyCF_TYPE_COMMENTS

      See compiler flags in documentation of the "ast" Python module,
      which exports these constants under the same names.

   The ""PyCF"" flags above can be combined with ""CO_FUTURE"" flags
   such as "CO_FUTURE_ANNOTATIONS" to enable features normally
   selectable using future statements. See Code Object Flags for a
   complete list.
