超高水準レイヤ¶
この章の関数を使うとファイルまたはバッファにある 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)¶ 標準インタプリタのためのメインプログラム。Pythonを組み込むプログラムのためにこれを利用できるようにしています。 argc と argv 引数をCプログラムの
main()
関数 (ユーザのロケールに従って wchar_t に変換されます) へ渡されるものとまったく同じに作成すべきです。引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。戻り値はインタプリタが(例外などではなく)普通に終了した時は0
に、例外で終了したときには1
に、引数リストが正しい Python コマンドラインが渡されなかったときは2
になります。Py_InspectFlag
が設定されていない場合、未処理のSystemExit
例外が発生すると、この関数は1
を返すのではなくプロセスを exit することに気をつけてください。
-
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 ならば、この関数はファイル名として"???"
を使います。
-
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 はそのファイルの名前でなければならず、ファイルシステムのエンコーディング (sys.getfilesystemencoding()
) でデコードされます。 closeit に真を指定した場合は、PyRun_SimpleFileExFlags が処理を戻す前にファイルを閉じます。
-
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)¶ Read and execute statements from a file associated with an interactive device until EOF is reached. The user will be prompted using
sys.ps1
andsys.ps2
. filename is decoded from the filesystem encoding (sys.getfilesystemencoding()
). Returns0
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行だけ読めます。 この関数は、文字列 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
にして単純化したインタフェースです。
-
struct _node*
PyParser_SimpleParseStringFlags
(const char *str, int start, int flags)¶ 下記の
PyParser_SimpleParseStringFlagsFilename()
の filename を NULL にして単純化したインタフェースです。
-
struct _node*
PyParser_SimpleParseStringFlagsFilename
(const char *str, const char *filename, int start, int flags)¶ 開始トークン start を使って str に含まれる Python ソースコードを flags 引数に従ってパースします。効率的に評価可能なコードオブジェ クトを作成するためにその結果を使うことができます。コード断片を何度も評価しなければならない場合に役に立ちます。 filename はファイルシステムエンコーディング (
sys.getfilesystemencoding()
) でデコードされます。
-
struct _node*
PyParser_SimpleParseFile
(FILE *fp, const char *filename, int start)¶ 下記の
PyRun_SimpleParseFileFlags()
の flags を0
にして単純化したインタフェースです。
-
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()
の 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)¶ 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)¶ 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 **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *kwdefs, PyObject *closure)¶ 与えられた特定の環境で、コンパイル済みのコードオブジェクトを評価します。この環境はグローバル変数の辞書と、ローカル変数のマッピングオブジェクト、引数の配列、キーワードとデフォルト値、keyword-only 引数のデフォルト値の辞書と、セルのクロージャタプルで構成されます。
-
PyFrameObject
¶ フレームオブジェクトを表現するために使われるオブジェクトのC構造体。 この型のフィールドはいつでも変更され得ます。
-
PyObject*
PyEval_EvalFrame
(PyFrameObject *f)¶ 実行フレームを評価します。これは
PyEval_EvalFrameEx()
に対するシンプルなインタフェースで、後方互換性のためのものです。
-
PyObject*
PyEval_EvalFrameEx
(PyFrameObject *f, int throwflag)¶ Python のインタープリタの主要な、直接的な関数です。 この関数には 2000 行ほどあります。 実行フレーム 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
による変更は無視されます。struct PyCompilerFlags { int cf_flags; }