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

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

これらの関数の一部は、文法の開始記号を引数に取ります。 利用できる開始
記号は "Py_eval_input"、"Py_file_input"、"Py_single_input"、
"Py_func_type_input" です。 説明は、それらを引数に取る関数の後にありま
す。

これらの関数の一部は FILE* 引数も受け取ります。 C ライブラリが異なると
"FILE" 構造体も異なり、互換性がない場合がある点に特に注意が必要です。
少なくとも Windows では、動的リンクされた拡張が実際に別のライブラリを
使うことがあります。 FILE* 引数を渡す場合は、Python ランタイムが使うの
と同じライブラリによって作成されたものだと確実に分かっている必要があり
ます。

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* の意味については、後述します。

   処理されない "SystemExit" が送出されると、"PyConfig.inspect" がゼロ
   である限り、この関数は "-1" を返さずにプロセスを終了します。

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_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)

   対話的なデバイスに関連付けられたファイルから、"flags" 引数に従って
   一つの文を読み込み、実行します。 利用者には "sys.ps1" と "sys.ps2"
   を使ってプロンプトを表示します。 "filename" は Python の "str" オブ
   ジェクトでなければなりません。

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

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

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

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

   "PyRun_InteractiveOneObject()" と同様ですが、"filename" は const
   char* で、*ファイルシステムのエンコーディングとエラーハンドラ* を使
   ってデコードされます。

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 で変更: この関数は メインインタープリタ からだけ呼
   び出されます。

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

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

   この関数は *スレッド状態がアタッチされていない* 状態で呼び出されま
   す。

   If this pointer is "NULL", "PyOS_Readline()" sets it to the default
   implementation, "PyOS_Readline()", before reading input.

   返す文字列はヌル終端されている必要があり、末尾の改行を読み取った場
   合はそれも含めます。 文字を一つも読み取る前にファイルの終わりに達し
   た場合は空文字列を返してください。 失敗または中断の場合は "NULL" を
   返します。 Python の例外が設定される場合もあります。

   "NULL" でない結果は、"PyMem_RawMalloc()" または
   "PyMem_RawRealloc()" で割り当てた文字列でなければなりません。

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

   バージョン 3.12 で変更: この関数は メインインタープリタ からだけ呼
   び出されます。

char *PyOS_Readline(FILE *sys_stdin, FILE *sys_stdout, const char *prompt)

   "prompt" が "NULL" でなければ表示し、"sys_stdin" から 1 行を読み取
   ります。 両方のストリームが端末で、呼び出し元が メインインタープリ
   タ の場合は "PyOS_ReadlineFunctionPointer" を使います。 それ以外の
   場合はデフォルトの実装を使い、"sys_stdout" をフラッシュして、C の標
   準エラーストリームに "prompt" を書き込みます。

   戻り値の文字列は "PyOS_ReadlineFunctionPointer" の規約に従いますが
   、呼び出し側は "PyMem_Free()" で解放する必要があります。 失敗または
   中断の場合は "NULL" を返します。 Python の例外が設定される場合もあ
   ります。

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)
    *戻り値: 新しい参照。*

   "str" の Python ソースコードを、オブジェクト "globals" と "locals"
   が指定するコンテキストで、"flags" が指定するコンパイラフラグを使っ
   て実行します。 "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)
    *戻り値: 新しい参照。*

   "str" 内の Python ソースコードを構文解析してコンパイルし、そのコー
   ドオブジェクトを返します。 開始記号は "start" で指定し、利用できる
   開始記号 のいずれかでなければなりません。 これによって、コンパイル
   できるコードを制限できます。 "filename" で指定されたファイル名はコ
   ードオブジェクトの作成に使われ、トレースバックや "SyntaxError" のメ
   ッセージに現れることがあります。 コードを構文解析またはコンパイルで
   きない場合は "NULL" を返します。

   整数 *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 を返します。

struct PyCompilerFlags

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

   "PyCompilerFlags *flags" が "NULL" の場合、"cf_flags" は "0" として
   扱われ、"from __future__ import" による変更は破棄されます。

   int cf_flags

      コンパイラフラグ。

   int cf_feature_version

      "cf_feature_version" は Python のマイナーバージョンです。
      "PY_MINOR_VERSION" に初期化してください。

      このフィールドはデフォルトでは無視されます。 "cf_flags" に
      "PyCF_ONLY_AST" フラグが設定されている場合に限って使います。

   バージョン 3.8 で変更: "cf_feature_version" フィールドを追加しまし
   た。

   利用できるコンパイラフラグはマクロとして公開されています。

   PyCF_ALLOW_TOP_LEVEL_AWAIT
   PyCF_ONLY_AST
   PyCF_OPTIMIZED_AST
   PyCF_TYPE_COMMENTS

      "ast" Python モジュールのドキュメントの コンパイラフラグ を参照
      してください。 このモジュールは同じ名前で定数をエクスポートして
      います。

   -[ 低レベルのフラグ ]-

   以下のフラグとマスクは、標準ライブラリや対話的インタープリタの限ら
   れた用途に使います。 標準ライブラリ以外のコードで必要になることはほ
   とんどありません。 実装の詳細とみなされ、いつでも変更される可能性が
   あります。

   PyCF_ALLOW_INCOMPLETE_INPUT

      このフラグはコンパイラと "codeop" モジュールの間のプライベートな
      インターフェースです。 使わないでください。 動作はサポートされて
      おらず、予告なく変更される可能性があります。

      このフラグを設定すると、インデントされたブロックの途中や閉じてい
      ない文字列リテラルなど、さらに入力が必要な位置でソースが終わった
      ためにコンパイルに失敗した場合、"SyntaxError" のサブクラスである
      未公開の "_IncompleteInputError" を送出します。 "codeop" モジュ
      ールは、このフラグを "PyCF_DONT_IMPLY_DEDENT" と併せて設定し、入
      力が未完成なのか、実際に構文エラーがあるのかを区別します。 これ
      により、対話的インタープリタはエラーを報告せずに次の行の入力を求
      めるべき場合を判断できます。

      Added in version 3.11.

   PyCF_DONT_IMPLY_DEDENT

      デフォルトでは、"Py_single_input" を開始記号としてコンパイルする
      と、ソースの末尾で未終了のインデントブロックを暗黙に閉じます。
      このフラグを設定すると、ソースの最終行が改行で終わる場合だけブロ
      ックを閉じ、それ以外の場合は "SyntaxError" でコンパイルが失敗し
      ます。

         PyCompilerFlags flags = {
             .cf_flags = 0,
             .cf_feature_version = PY_MINOR_VERSION,
         };
         const char *source = "if a:\n    pass";

         /* "if" ブロックは暗黙に閉じられる。
            コードオブジェクトを返す: */
         Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

         /* このフラグを使うと、最終行が改行で終わらないため
            SyntaxError で失敗する: */
         flags.cf_flags = PyCF_DONT_IMPLY_DEDENT;
         Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

      "codeop" モジュールは、このフラグで対話的入力が未完成かどうかを
      検出します。 インデントされたブロック内でまだ入力中なら、ソース
      はまだ改行で終わらないためコンパイルに失敗し、利用者に次の行の入
      力を求めます。

   PyCF_IGNORE_COOKIE

      ソースに **PEP 263** のエンコーディング宣言 ("coding cookie") が
      あっても無視し、UTF-8 として読み取ります。

         PyCompilerFlags flags = {
             .cf_flags = 0,
             .cf_feature_version = PY_MINOR_VERSION,
         };
         const char *source = "# coding: latin-1\ns = '\xe9'\n";

         /* エンコーディング宣言に従い、バイト 0xE9 を Latin-1 として
            デコードする。s を "é" に設定するコードオブジェクトを返す: */
         Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

         /* このフラグを使うとエンコーディング宣言を無視する。0xE9 は
            有効な UTF-8 ではないため、コンパイルは SyntaxError で失敗する: */
         flags.cf_flags = PyCF_IGNORE_COOKIE;
         Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

      組み込み関数 "compile()"、"eval()"、"exec()" は、ソースが "str"
      オブジェクトの場合にこのフラグを設定します。 UTF-8 にエンコード
      したテキストをパーサに渡すためです。

   PyCF_SOURCE_IS_UTF8

      ソースが UTF-8 エンコードであると分かっていることを示します。 組
      み込み関数 "compile()"、"eval()"、"exec()" はこのフラグを設定し
      ますが、現在は効果がありません。

   上記の「"PyCF"」フラグは、"CO_FUTURE_ANNOTATIONS" などの「
   "CO_FUTURE"」フラグと組み合わせ、通常 future 文 で選択する機能を有
   効にできます。 全一覧は コードオブジェクトのフラグ を参照してくださ
   い。

   以下のマスクは複数のフラグを組み合わせたものです。

   PyCF_MASK

      通常 future 文 で有効にする機能を選ぶ、すべての "CO_FUTURE" フラ
      グ (コードオブジェクトのフラグ を参照) のビットマスクです。
      "PyCompilerFlags *flags" 引数を使ってコンパイルしたコードに
      "from __future__ import" 文が含まれる場合、インポートされた機能
      のフラグが "flags" に追加され、同じコンテキストで後から実行する
      コードに引き継がれます。

   PyCF_MASK_OBSOLETE

      新しいコードでこのマスクを使わないでください。 フラグを
      "compile()" に渡す古いコードが動作し続けるためだけに残されていま
      す。

      もはや効果のない、廃止された future 機能のフラグのビットマスクで
      す。

   PyCF_COMPILE_MASK

      "PyCF_ONLY_AST" など、ソースのコンパイル方法を変えるすべての
      "PyCF" フラグのビットマスクです。 組み込み関数 "compile()" は、
      "flags" 引数の検証にこのマスクを使います。


利用できる開始記号
==================

int Py_eval_input

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

int Py_file_input

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

int Py_single_input

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

int Py_func_type_input

   関数型に対する Python 文法の開始記号で、"Py_CompileString()" と一緒
   に使います。 **PEP 484** の「シグネチャ型コメント」を構文解析するた
   めに使います。

   "PyCF_ONLY_AST" フラグの設定が必要です。

   参考:

     * "ast.FunctionType"

     * **PEP 484**

   Added in version 3.8.


スタックへの影響
================

参考: "dis.stack_effect()"

PY_INVALID_STACK_EFFECT

   無効なスタックへの影響を表す番兵値。

   現在は "INT_MAX" と同等です。

   Added in version 3.8.

int PyCompile_OpcodeStackEffect(int opcode, int oparg)

   *opcode* と引数 *oparg* がスタックに与える影響を計算します。

   成功した場合はスタックへの影響を返し、失敗した場合は
   "PY_INVALID_STACK_EFFECT" を返します。

   Added in version 3.4.

int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)

   "PyCompile_OpcodeStackEffect()" と同様ですが、"jump" がゼロの場合は
   ジャンプしたときのスタックへの影響を含めません。

   If *jump* is "0", this will not include the stack effect of
   jumping, but if *jump* is "1" or "-1", this will include it.

   成功した場合はスタックへの影響を返し、失敗した場合は
   "PY_INVALID_STACK_EFFECT" を返します。

   Added in version 3.8.
