# 超高水準レイヤ

この章の関数を使うとファイルまたはバッファにある 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`, `Py_single_input`, and `Py_func_type_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_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)

  Read and execute a single statement from a file associated with an interactive device according to the flags argument. The user will be prompted using `sys.ps1` and `sys.ps2`. filename must be a Python `str` object.

  入力が正常に実行されたときは `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)

  Similar to `PyRun_InteractiveOneObject()`, but filename is a const char*, which is decoded from the filesystem encoding and error handler.

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.

  Can be set to point to a function with the prototype `int func(void)`. The function will be called when Python's interpreter prompt is about to become idle and wait for user input from the terminal. The return value is ignored. Overriding this hook can be used to integrate the interpreter's prompt with other event loops, as done in `Modules/_tkinter.c` in the Python source code.

  バージョン 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)
  戻り値: 新しい参照。

  Execute Python source code from str in the context specified by the objects globals and locals with the compiler flags specified by flags. globals must be a dictionary; locals can be any object that implements the mapping protocol. The parameter start specifies the start symbol and must be one of the available start symbols.

  コードを実行した結果を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 symbol is given by start; this can be used to constrain the code which can be compiled and should be available start symbols. 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 を返します。

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.

  Low-level flags

  The following flags and masks serve narrow needs of the standard library and interactive interpreters. Code outside the standard library rarely has a reason to use them. They are considered implementation details and may change at any time.

  PyCF_ALLOW_INCOMPLETE_INPUT

    This flag is a private interface between the compiler and the `codeop` module. Do not use it; its behavior is unsupported and may change without warning.

    With this flag set, when compilation fails because the source text ends where more input is expected, for example in the middle of an indented block or an unterminated string literal, the error raised is the undocumented `_IncompleteInputError`, a subclass of `SyntaxError`. The `codeop` module sets this flag, together with `PyCF_DONT_IMPLY_DEDENT`, to tell input that is incomplete apart from input with a real syntax error, so that interactive interpreters know when to prompt for another line instead of reporting an error.

    Added in version 3.11.

  PyCF_DONT_IMPLY_DEDENT

    By default, when compiling with the `Py_single_input` start symbol, reaching the end of the source text implicitly closes any open indented blocks. With this flag set, open blocks are only closed if the last line of the source ends with a newline; otherwise, compilation fails with a `SyntaxError`:

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

        /* The "if" block is closed implicitly;
           this returns a code object: */
        Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

        /* With the flag, this fails with a SyntaxError,
           because the last line does not end with a newline: */
        flags.cf_flags = PyCF_DONT_IMPLY_DEDENT;
        Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

    The `codeop` module uses this flag to detect incomplete interactive input. While the user is still typing inside an indented block, the source does not yet end with a newline, so it fails to compile and the user is prompted for another line.

  PyCF_IGNORE_COOKIE

    Read the source text as UTF-8, ignoring its PEP 263 encoding declaration ("coding cookie"), if any:

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

        /* The coding cookie is honored: byte 0xE9 is decoded as
           Latin-1, and this returns a code object that sets s to "é": */
        Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

        /* With the flag, the cookie is ignored and compilation fails
           with a SyntaxError, because 0xE9 is not valid UTF-8: */
        flags.cf_flags = PyCF_IGNORE_COOKIE;
        Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

    The `compile()`, `eval()` and `exec()` built-in functions set this flag when the source is a `str` object, because they pass the text to the parser encoded as UTF-8.

  PyCF_SOURCE_IS_UTF8

    Mark the source text as known to be UTF-8 encoded. The `compile()`, `eval()` and `exec()` built-in functions set this flag, but it currently has no effect.

  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.

  The following masks combine several flags:

  PyCF_MASK

    Bitmask of all `CO_FUTURE` flags (see Code Object Flags), which select features normally enabled by future statements. When code compiled with a `PyCompilerFlags *flags` argument contains a `from __future__ import` statement, the flag for the imported feature is added to flags, so that code executed later in the same context inherits it.

  PyCF_MASK_OBSOLETE

    Do not use this mask in new code. It is kept only so that old code passing its flags to `compile()` keeps working.

    Bitmask of flags for obsolete future features that no longer have any effect.

  PyCF_COMPILE_MASK

    Bitmask of all `PyCF` flags that change how the source is compiled, such as `PyCF_ONLY_AST`. The `compile()` built-in function uses this mask to validate its flags argument.

## Available start symbols

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

  The start symbol from the Python grammar for a function type; for use with `Py_CompileString()`. This is used to parse "signature type comments" from PEP 484.

  This requires the `PyCF_ONLY_AST` flag to be set.

  参考

  - `ast.FunctionType`

  - PEP 484

  Added in version 3.8.

## Stack Effects

参考

`dis.stack_effect()`

PY_INVALID_STACK_EFFECT

  Sentinel value representing an invalid stack effect.

  This is currently equivalent to `INT_MAX`.

  Added in version 3.8.

int PyCompile_OpcodeStackEffect(int opcode, int oparg)

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

  On success, this function returns the stack effect; on failure, this returns `PY_INVALID_STACK_EFFECT`.

  Added in version 3.4.

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

  Similar to `PyCompile_OpcodeStackEffect()`, but don't include the stack effect of jumping if jump is zero.

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

  On success, this function returns the stack effect; on failure, this returns `PY_INVALID_STACK_EFFECT`.

  Added in version 3.8.