# 超高水準レイヤ

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

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

  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)
  Part of the Stable ABI since version 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)
  Part of the 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)
  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 はそのファイルの名前でなければならず、 ファイルシステムのエンコーディングとエラーハンドラ でデコードされます。 closeit に真を指定した場合は、`PyRun_FileExFlags()` が処理を戻す前にファイルを閉じます。

PyObject *Py_CompileString(const char *str, const char *filename, int start)
  Return value: New reference. Part of the Stable ABI.

  下記の `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.

  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)
  Return value: New reference.

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

  Added in version 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
  Return value: New reference. Part of the 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)
  Return value: New reference. Part of the Stable ABI.

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

PyObject *PyEval_EvalFrame(PyFrameObject *f)
  Return value: New reference. Part of the Stable ABI.

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

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
  Return value: New reference. Part of the 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)」として扱われます。