超高水準レイヤ

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