超高水準レイヤ¶
この章の関数を使うとファイルまたはバッファにある Python ソースコードを実行できますが、より詳細なやり取りをインタプリタとすることはできないでしょう。
Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are Py_eval_input
,
Py_file_input
, and Py_single_input
. These are described
following the functions which accept them as parameters.
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)¶
- 次に属します: Stable ABI.
標準インタプリタのためのメインプログラム。Pythonを組み込むプログラムのためにこれを利用できるようにしています。 argc と argv 引数をCプログラムの
main()
関数 (ユーザのロケールに従って wchar_t に変換されます) へ渡されるものとまったく同じに作成すべきです。引数リストが変更される可能性があるという点に注意することは重要です。 (しかし、引数リストが指している文字列の内容は変更されません)。戻り値はインタプリタが(例外などではなく)普通に終了した時は0
に、例外で終了したときには1
に、引数リストが正しい Python コマンドラインが渡されなかったときは2
になります。Note that if an otherwise unhandled
SystemExit
is raised, this function will not return1
, but exit the process, as long asPyConfig.inspect
is zero.
-
int Py_BytesMain(int argc, char **argv)¶
- 次に属します: Stable ABI (バージョン 3.8 より).
Similar to
Py_Main()
but argv is an array of bytes strings.Added in version 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 の意味については、後述します。Note that if an otherwise unhandled
SystemExit
is raised, this function will not return-1
, but exit the process, as long asPyConfig.inspect
is zero.
-
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)¶
- 次に属します: Stable ABI.
int func(void)
というプロトタイプの関数へのポインタが設定できます。 この関数は、 Python のインタプリタのプロンプトがアイドル状態になりターミナルからのユーザの入力を待つようになったときに呼び出されます。 返り値は無視されます。 このフックを上書きすることで、 Python のソースコードの中でModules/_tkinter.c
がやっているように、インタプリタのプロンプトと他のイベントループを統合できます。バージョン 3.12 で変更: This function is only called from the main interpreter.
-
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()
でメモリ確保したものでなければなりません。バージョン 3.12 で変更: This function is only called from the main interpreter.
-
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)¶
- 戻り値: 新しい参照。
オブジェクトの globals と locals で指定されるコンテキストで、コンパイラフラグに flags を設定した状態で、 str にある Python ソースコードを実行します。 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)¶
- 戻り値: 新しい参照。
Parse and compile the Python source code in str, returning the resulting code object. The start token is given by start; this can be used to constrain the code which can be compiled and should be
Py_eval_input
,Py_file_input
, orPy_single_input
. The filename specified by filename is used to construct the code object and may appear in tracebacks orSyntaxError
exception messages. This returnsNULL
if the code cannot be parsed or compiled.整数 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 を返します。
-
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 の内容を変更できます。Whenever
PyCompilerFlags *flags
isNULL
,cf_flags
is treated as equal to0
, and any modification due tofrom __future__ import
is discarded.-
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 incf_flags
.
バージョン 3.8 で変更: Added cf_feature_version field.
-
int cf_flags¶