超高水準レイヤ

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

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

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)

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

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

int Py_BytesMain(int argc, char **argv)

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)

If fp refers to a file associated with an interactive device (console or terminal input or Unix pseudo-terminal), return the value of PyRun_InteractiveLoop(), otherwise return the result of PyRun_SimpleFile(). filename is decoded from the filesystem encoding (sys.getfilesystemencoding()). If filename is NULL, this function uses "???" as the filename. If closeit is true, the file is closed before PyRun_SimpleFileExFlags() returns.

int PyRun_SimpleString(const char *command)

This is a simplified interface to PyRun_SimpleStringFlags() below, leaving the PyCompilerFlags* argument set to 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 はそのファイルの名前でなければならず、ファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。 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 はファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。

入力が正常に実行されたときは 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 はファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。 EOFに達すると 0 を返すか、失敗したら負の数を返します。

int (*PyOS_InputHook)(void)

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

struct _node* PyParser_SimpleParseString(const char *str, int start)

下記の PyParser_SimpleParseStringFlagsFilename() の filename を NULL に、 flags を 0 にして単純化したインターフェースです。

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseStringFlags(const char *str, int start, int flags)

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

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)

開始トークン start を使って str に含まれる Python ソースコードを flags 引数に従ってパースします。効率的に評価可能なコードオブジェ クトを作成するためにその結果を使うことができます。コード断片を何度も評価しなければならない場合に役に立ちます。 filename はファイルシステムエンコーディング (sys.getfilesystemencoding()) でデコードされます。

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

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

Deprecated since version 3.9, will be removed in version 3.10.

struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

PyParser_SimpleParseStringFlagsFilename() に似ていますが、 Pythonソースコードをメモリ内の文字列ではなく fp から読み込みます。 filename はそのファイルの名前でなけれななりません。

Deprecated since version 3.9, will be removed in version 3.10.

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 はそのファイルの名前でなければならず、ファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。もし closeit を真にすると、 PyRun_FileExFlags() が処理を戻す前にファイルを閉じます。

PyObject* Py_CompileString(const char *str, const char *filename, int start)

Return value: New reference.

下記の 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 はファイルシステムのエンコーディングでデコード (os.fsdecode()) されたバイト文字列です。

バージョン 3.2 で追加.

PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

Return value: New reference.

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.

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

PyFrameObject

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

PyObject* PyEval_EvalFrame(PyFrameObject *f)

Return value: New reference.

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

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Return value: New reference.

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