超高水準レイヤ

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

これらの関数のいくつかは引数として文法の開始記号を受け取ります。使用できる開始記号は Py_eval_inputPy_file_inputPy_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を組み込むプログラムのためにこれを利用できるようにしています。 argcargv 引数を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()closeit0 に、 flagsNULL にして単純化したインタフェースです。

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

下記の PyRun_AnyFileExFlags()closeit0 にして単純化したインターフェースです。

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

下記の PyRun_AnyFileExFlags()flagsNULL にして単純化したインタフェースです。

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

fp が対話的デバイス (コンソールや端末入力あるいは Unix 仮想端末) と関連づけられたファイルを参照している場合は、 PyRun_InteractiveLoop() の値を返します。それ以外の場合は、 PyRun_SimpleFile() の結果を返します。 filename はファイルシステムのエンコーディング (sys.getfilesystemencoding()) でデコードされます。 filenameNULL ならば、この関数はファイル名として "???" を使います。

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()closeit0 に、 flagsNULL にして単純化したインタフェースです。

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

下記の PyRun_SimpleFileExFlags()flagsNULL にして単純化したインタフェースです。

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Similar to PyRun_SimpleStringFlags(), but the Python source code is read from fp instead of an in-memory string. filename should be the name of the file, it is decoded from filesystem encoding and error handler. If closeit is true, the file is closed before PyRun_SimpleFileExFlags() returns.

注釈

On Windows, fp should be opened as binary mode (e.g. fopen(filename, "rb")). Otherwise, Python may not handle script file with LF line ending correctly.

int PyRun_InteractiveOne(FILE *fp, const char *filename)

下記の PyRun_InteractiveOneFlags()flagsNULL にして単純化したインタフェースです。

int PyRun_InteractiveOneFlags(FILE *fp, const char *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 is decoded from the filesystem encoding and error handler.

入力が正常に実行されたときは 0 を返します。例外が発生した場合は -1 を返します。パースエラーの場合はPythonの一部として配布されている errcode.h インクルードファイルにあるエラーコードを返します。 (Python.herrcode.h をインクルードしません。従って、 必要な場合はその都度インクルードしなければならないことに注意してください。)

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

下記の PyRun_InteractiveLoopFlags()flagsNULL にして単純化したインタフェースです。

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Read and execute statements from a file associated with an interactive device until EOF is reached. The user will be prompted using sys.ps1 and sys.ps2. filename is decoded from the filesystem encoding and error handler. Returns 0 at EOF or a negative number upon failure.

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行だけ読めます。 この関数は、文字列 promptNULL でない場合は 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()filenameNULL に、 flags0 にして単純化したインタフェースです。

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

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

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

Parse Python source code from str using the start token start according to the flags argument. The result can be used to create a code object which can be evaluated efficiently. This is useful if a code fragment must be evaluated many times. filename is decoded from the filesystem encoding and error handler.

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

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

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

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

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
Return value: New reference.

下記の PyRun_StringFlags()flagsNULL にして単純化したインタフェースです。

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
Return value: New reference.

オブジェクトの globalslocals で指定されるコンテキストで、コンパイラフラグに 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()closeit0 にし、 flagsNULL にして単純化したインタフェースです。

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
Return value: New reference.

下記の PyRun_FileExFlags()flagsNULL にして単純化したインタフェースです。

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
Return value: New reference.

下記の PyRun_FileExFlags()closeit0 にして単純化したインターフェースです。

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
Return value: New reference.

Similar to PyRun_StringFlags(), but the Python source code is read from fp instead of an in-memory string. filename should be the name of the file, it is decoded from the filesystem encoding and error handler. If closeit is true, the file is closed before PyRun_FileExFlags() returns.

PyObject *Py_CompileString(const char *str, const char *filename, int start)
Return value: New reference.

下記の Py_CompileStringFlags()flagsNULL にして単純化したインタフェースです。

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_inputPy_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.

Like Py_CompileStringObject(), but filename is a byte string decoded from the filesystem encoding and error handler.

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

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

type PyFrameObject

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

PyObject *PyEval_EvalFrame(PyFrameObject *f)
Return value: New reference.

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

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
Return value: New reference.

This is the main, unvarnished function of Python interpretation. The code object associated with the execution frame f is executed, interpreting bytecode and executing calls as needed. The additional throwflag parameter can mostly be ignored - if true, then it causes an exception to immediately be thrown; this is used for the throw() methods of generator objects.

バージョン 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__ importflags の内容を変更できます。

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

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