# 超高水準レイヤ

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

これらの関数のいくつかは引数として文法の開始記号を受け取ります。使用できる開始記号は `Py_eval_input` と `Py_file_input` 、 `Py_single_input` です。開始記号の説明はこれらを引数として取る関数の後にあります。

これらの関数のいくつかが `FILE*` 引数をとることにも注意してください。注意深く扱う必要がある特別な問題の1つは、異なるCライブラリの `FILE` 構造体は異なっていて互換性がない可能性があるということです。実際に(少なくとも)Windowsでは、動的リンクされる拡張が異なるライブラリを使うことが可能であり、したがって、 `FILE*` 引数がPythonランタイムが使っているライブラリと同じライブラリによって作成されたことが確かならば、単にこれらの関数へ渡すだけということに注意すべきです。

int `Py_Main`(int argc, wchar_t **argv)
  Part of the Stable ABI.

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

  `Py_InspectFlag` が設定されていない場合、未処理の `SystemExit` 例外が発生すると、この関数は `1` を返すのではなくプロセスを exit することに気をつけてください。

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.

  バージョン 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 の意味については、後述します。

  `Py_InspectFlag` が設定されていない場合、未処理の `SystemExit` 例外が発生すると、この関数は `1` を返すのではなくプロセスを exit することに気をつけてください。

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` がやっているように、インタプリタのプロンプトと他のイベントループを統合できます。

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

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.

  str 内の Python ソースコードをパースしてコンパイルし、作られたコードオブジェクトを返します。開始トークンは start によって与えられます。これはコンパイル可能なコードを制限するために使うことができ、 `Py_eval_input` 、 `Py_file_input` もしくは `Py_single_input` であるべきです。 filename で指定されるファイル名はコードオブジェクトを構築するために使われ、トレースバックあるいは `SyntaxError` 例外メッセージに出てくる可能性があります。コードがパースできなかったりコンパイルできなかったりした場合に、これは `NULL` を返します。

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

  バージョン 3.4 で追加.

PyObject *`Py_CompileStringExFlags`(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
  Return value: New reference.

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

  バージョン 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.

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

type `PyFrameObject`
  Part of the Limited API (as an opaque struct).

  フレームオブジェクトを表現するために使われるオブジェクトのC構造体。 この型のフィールドはいつでも変更され得ます。

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 の内容を変更できます。

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

  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)」として扱われます。