インタープリタの初期化と終了処理

初期化前にインタープリタを設定する方法の詳細は、Python の初期化設定 を参照してください。

Python の初期化前

In an application embedding Python, the Py_Initialize() function must be called before using any other Python/C API functions; with the exception of a few functions.

次の関数は Python の初期化の前でも安全に呼び出せます:

• インタープリタを初期化する関数:

  • Py_Initialize()

  • Py_InitializeEx()

  • Py_InitializeFromConfig()

  • Py_BytesMain()

  • Py_Main()

  • Python 初期化設定 で説明するランタイムの事前初期化関数

• 設定関数:

  • PyImport_AppendInittab()

  • PyImport_ExtendInittab()

  • PyInitFrozenExtensions()

  • PyMem_SetAllocator()

  • PyMem_SetupDebugHooks()

  • PyObject_SetArenaAllocator()

  • Python 初期化設定 で説明する設定関数

• 情報取得の関数:

  • Py_IsInitialized()

  • PyMem_GetAllocator()

  • PyObject_GetArenaAllocator()

  • Py_GetBuildInfo()

  • Py_GetCompiler()

  • Py_GetCopyright()

  • Py_GetPlatform()

  • Py_GetVersion()

• ユーティリティ:

  • Py_DecodeLocale()

  • Python 初期化設定 で説明する状態の報告とユーティリティの関数

• メモリアロケータ:

  • PyMem_RawMalloc()

  • PyMem_RawRealloc()

  • PyMem_RawCalloc()

  • PyMem_RawFree()

• 同期:

  • PyMutex_Lock()

  • PyMutex_Unlock()

注釈

Despite their apparent similarity to some of the functions listed above, the following functions should not be called before the interpreter has been initialized: Py_EncodeLocale(), and Py_RunMain().

インタープリタの初期化と終了処理

void Py_Initialize()

次に属します: Stable ABI.

Python インタープリタを初期化します。 Python を組み込むアプリケーションでは、ほかの Python/C API 関数を使う前に呼び出す必要があります。 少数の例外については Python の初期化前 を参照してください。

This initializes the table of loaded modules (sys.modules), and creates the fundamental modules builtins, __main__ and sys. It also initializes the module search path (sys.path). It does not set sys.argv; use the Python Initialization Configuration API for that. This is a no-op when called for a second time (without calling Py_FinalizeEx() first). There is no return value; it is a fatal error if the initialization fails.

Python の初期化設定 をカスタマイズするには、Py_InitializeFromConfig() を使ってください。

注釈

Windows では O_TEXT から O_BINARY へコンソールモードが変更されますが、これはその C ランタイムを使っているコンソールでの Python 以外の使い勝手にも影響を及ぼします。

void Py_InitializeEx(int initsigs)

次に属します: Stable ABI.

initsigs が 1 の場合は Py_Initialize() と同じように動作します。 initsigs が 0 の場合は、シグナルハンドラーの初期化と登録を省略します。 これは、CPython をより大きなアプリケーションに組み込む場合に有用なことがあります。

Python の初期化設定 をカスタマイズするには、Py_InitializeFromConfig() を使ってください。

PyStatus Py_InitializeFromConfig(const PyConfig *config)

PyConfig による初期化 で説明するように、config の設定で Python を初期化します。

インタープリタの事前初期化、ランタイム設定構造体への値の設定、返される状態構造体の調べ方については、Python 初期化設定 を参照してください。

バージョン 3.16 で変更: The function no longer returns an exit code if a command line option wants to exit Python. Instead, the option is processed in Py_RunMain().

int Py_IsInitialized()

次に属します: Stable ABI.

Python インタプリタが初期化済みであれば真(非ゼロ)を、さもなければ偽(ゼロ)を返します。Py_FinalizeEx() を呼び出した後は、Py_Initialize() を再び呼び出すまで、この関数は偽を返します。

バージョン 3.15 で変更: site モジュールのインポートを含め、初期化が完全に終了するまでは真を返さなくなりました。 以前は、Py_Initialize() の実行中に真を返す場合がありました。

int Py_IsFinalizing()

次に属します: Stable ABI (バージョン 3.13 より).

メインの Python インタープリタが 終了処理中 なら真 (ゼロ以外) を返します。 それ以外の場合は偽 (ゼロ) を返します。

Added in version 3.13.

int Py_FinalizeEx()

次に属します: Stable ABI (バージョン 3.6 より).

Py_Initialize() と、その後の Python/C API 関数の使用による初期化をすべて元に戻します。 さらに、最後に Py_Initialize() を呼び出してから作成され、まだ破棄されていないサブインタープリタをすべて破棄します (以下の Py_NewInterpreter() を参照)。 再び Py_Initialize() を呼び出さずにもう一度呼び出しても、何も行いません。

Py_Initialize() の逆の処理なので、同じスレッドで同じインタープリタがアクティブな状態で呼び出す必要があります。 つまり、メインスレッドとメインインタープリタです。 Py_RunMain() の実行中には決して呼び出してはなりません。

通常の戻り値は 0 です。 終了処理中にバッファー内のデータの書き出しでエラーがあった場合は、-1 を返します。

Python は、Python インタープリタが確保したメモリをできる限り解放しようとします。 そのため、C 拡張は、以前に確保したすべての PyObject を適切に後始末してから、次の Py_Initialize() の呼び出しで使うようにしなければなりません。 そうしないと、脆弱性や不正な動作につながる可能性があります。

この関数が提供されている理由はいくつかあります。Python の埋め込みを行っているアプリケーションでは、アプリケーションを再起動することなく Python を再起動したいことがあります。また、動的ロード可能イブラリ (あるいは DLL) から Python インタプリタをロードするアプリケーションでは、DLL をアンロードする前に Python が確保したメモリを全て解放したいと考えるかもしれません。アプリケーション内で起きているメモリリークを追跡する際に、開発者は Python が確保したメモリをアプリケーションの終了前に解放させたいと思う場合もあります。

Bugs and caveats: The destruction of modules and objects in modules is done in random order; this may cause destructors (__del__() methods) to fail when they depend on other objects (even functions) or modules. Dynamically loaded extension modules loaded by Python are not unloaded. Small amounts of memory allocated by the Python interpreter may not be freed (if you find a leak, please report it). Memory tied up in circular references between objects is not freed. Interned strings will all be deallocated regardless of their reference count. Some memory allocated by extension modules may not be freed. Some extensions may not work properly if their initialization routine is called more than once; this can happen if an application calls Py_Initialize() and Py_FinalizeEx() more than once. Py_FinalizeEx() must not be called recursively from within itself. Therefore, it must not be called by any code that may be run as part of the interpreter shutdown process, such as atexit handlers, object finalizers, or any code that may be run while flushing the stdout and stderr files.

引数無しで 監査イベント cpython._PySys_ClearAuditHooks を送出します。

Added in version 3.6.

void Py_Finalize()

次に属します: Stable ABI.

この関数は Py_FinalizeEx() の後方互換性バージョンで、戻り値がありません。

int Py_BytesMain(int argc, char **argv)

次に属します: Stable ABI (バージョン 3.8 より).

Py_Main() と同様ですが、argv はバイト文字列の配列です。 これにより、呼び出し元のアプリケーションは、テキストのデコードを CPython ランタイムに任せられます。

Added in version 3.8.

int Py_Main(int argc, wchar_t **argv)

次に属します: Stable ABI.

標準インタープリタのメインプログラムです。 初期化から終了処理までの一連の処理に加え、環境変数とコマンドラインから設定を読み取り、コマンドライン に従って __main__ を実行する処理をまとめて行います。

より大きなアプリケーションに Python ランタイムを組み込むだけでなく、CPython の完全なコマンドラインインターフェースをサポートしたいプログラムのために提供されています。

argc と argv 引数は、C プログラムの main() 関数に渡すものに似ていますが、argv の各要素をあらかじめ Py_DecodeLocale() で wchar_t に変換する点が異なります。 引数リストの各要素が、渡された文字列とは別の文字列を指すように変更される可能性があることにも注意してください。 ただし、引数リストが指す文字列の内容は変更されません。

引数リストが有効な Python コマンドラインを表していない場合は 2 を返し、それ以外の場合は Py_RunMain() と同じ値を返します。

ランタイムの設定 の節で説明する CPython ランタイム設定 API を使うと、エラー処理を除いて、Py_Main はおおむね次の処理と等価です。

PyConfig config;
PyConfig_InitPythonConfig(&config);
PyConfig_SetArgv(&config, argc, argv);
Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

Py_RunMain();

通常、Python を組み込むアプリケーションは、Py_Initialize()、Py_InitializeEx()、Py_InitializeFromConfig() を直接呼び出す 代わりに この関数を呼び出します。 その場合、すべての設定はこのドキュメントのほかの箇所で説明されているとおりに適用されます。 先にランタイム初期化 API を呼び出した 後で この関数を呼び出す場合は、環境変数とコマンドラインのどの設定が更新されるかはバージョンに依存します。 ランタイムの最初の初期化で一度設定した値を、後から正しく変更できるかどうかが設定によって異なるためです。

int Py_FrozenMain(int argc, char **argv)

「凍結された」Python プログラムのメインプログラムです。 凍結されたプログラムとは、インタープリタとプログラムのモジュールのバイトコードを組み込んだ実行ファイルで、freeze ユーティリティなどで作成します (Tools/freeze を参照)。

インタープリタを初期化し、__main__ という名前の凍結モジュールをインポートして、インタープリタの終了処理を行います。 呼び出す前に、凍結モジュールを PyImport_FrozenModules に登録しておかなければなりません。 __main__ が登録されていなければ、致命的エラーになります。

argc and argv are byte strings like the arguments of a C program's main function, and are passed to the interpreter with PyConfig_SetBytesArgv(). Unlike Py_Main(), the arguments are not parsed as Python command line options (PyConfig.parse_argv is 0), so all of them are made available to the program in sys.argv. Apart from that, the interpreter uses the Python Configuration, so environment variables such as PYTHONPATH are honored. Warnings about the path configuration (PyConfig.pathconfig_warnings) are suppressed. If PYTHONINSPECT is set and standard input is a terminal, an interactive prompt is run after __main__ has finished, as with the -i option.

__main__ が未処理の例外なしで実行された場合は 0、それ以外の場合は 1 を返します。 インタープリタの終了処理が失敗した場合は 120 を返します (Py_FinalizeEx() を参照)。 未処理の SystemExit はプロセスを終了させます。 インタープリタを初期化できない場合は、Py_ExitStatusException() でプロセスを終了します。

Windows では、この関数は Python DLL からエクスポートされません。 代わりに freeze ユーティリティが、この関数に必要な Windows 固有のフックとともに Python/frozenmain.c をコンパイルして、凍結されたプログラムに組み込みます。

int Py_RunMain(void)

設定が完了した CPython ランタイムで、メインモジュールを実行します。

コマンドラインまたは設定で指定された、コマンド (PyConfig.run_command)、スクリプト (PyConfig.run_filename)、またはモジュール (PyConfig.run_module) を実行します。 どの値も設定されていなければ、__main__ モジュールのグローバル名前空間を使って、Python の対話プロンプト (REPL) を実行します。

PyConfig.inspect が設定されていない場合 (デフォルト)、インタープリタが例外を送出せず正常終了すれば 0 を返します。 未処理の SystemExit があればその終了ステータスを、それ以外の未処理の例外があれば 1 を返します。

If PyConfig.inspect is set (such as when the -i option is used), rather than returning when the interpreter exits, execution will instead resume in an interactive Python prompt (REPL) using the __main__ module's global namespace. If the interpreter exited with an exception, it is immediately raised in the REPL session. The function return value is then determined by the way the REPL session terminates: 0, 1, or the status of a SystemExit, as specified above.

この関数は、戻る前に必ず Python インタープリタの終了処理を行います。

Py_RunMain() を使って常に隔離モードで実行するようカスタマイズした Python の例は、Python の設定 を参照してください。

int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

対象のインタープリタ interp に atexit コールバックを登録します。 Py_AtExit() と似ていますが、インタープリタと、コールバックに渡すデータポインターを明示的に受け取ります。

interp の スレッド状態がアタッチされていなければなりません。

Added in version 3.13.

インタープリタの終了処理に関する注意

インタープリタの終了処理 の後半では、非デーモンスレッドの終了を待つ処理と atexit 関数の実行を終えた後、ランタイムが終了処理中と記録されます。 ただし、スレッドの終了を待つ処理は KeyboardInterrupt で中断される場合があります。 終了処理中と記録されると、Py_IsFinalizing() と sys.is_finalizing() が真を返します。 この時点では、終了処理を開始したスレッド (通常はメインスレッド) だけが、スレッド状態を アタッチ できます。

終了処理中にほかのスレッドがアタッチしようとすると、永久にブロックされた状態 になります。 これは、PyThreadState_Ensure() や Py_END_ALLOW_THREADS などで明示的にアタッチする場合も、バイトコード命令の間などで暗黙にアタッチする場合も同じです。 通常は問題ありませんが、デッドロックを引き起こすことがあります。 例えば、ロックを保持したまま永久にブロックされると、終了処理を行うスレッドがそのロックを取得できなくなります。

CPython 3.13 より前は、停止したままになる代わりにスレッドが終了していましたが、別の問題を引き起こしていました (PyThread_exit_thread() の警告を参照)。

望ましくない動作ですが、Python 3.15 以降では、一時的に終了処理を防ぐことで、これらの問題を避けるための C API がいくつか用意されています。

参考

これらの API の設計、動機、根拠は PEP 788 で説明されています。

type PyInterpreterGuard

次に属します: Stable ABI (不透明な構造体として) (バージョン 3.15 より).

インタープリタのガードを表す不透明な構造体です。

インタープリタのガードを保持すると、PyInterpreterGuard_Close() でガードを閉じるまで、そのインタープリタの終了処理が行われないことを保証できます。

ガードが保持されている場合、インタープリタの終了処理を行おうとするスレッドは、ガードが閉じられるまでブロックしてから終了処理を開始します。 終了処理が始まると、スレッドはそのインタープリタのガードを二度と取得できなくなります。 つまり、インタープリタのガードを閉じ忘れると、プロセスは終了処理で 永久に停止したままになります。

インタープリタのガードを保持することは、Python オブジェクトへの 強参照 を保持することに似ています。 ただし、すべてのガードを解放しても終了処理は自動的には行われず、明示的に Py_EndInterpreter() を呼び出す必要があります。

Added in version 3.15.

PyInterpreterGuard *PyInterpreterGuard_FromCurrent(void)

次に属します: Stable ABI (バージョン 3.15 より).

現在のインタープリタの終了処理を防ぐガードを作成します。 ガードを閉じるまで終了処理を防ぎます。

例えば:

// 一時的に終了処理を防ぐ。
PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
if (guard == NULL) {
   // 終了処理がすでに始まっているか、メモリが不足している。
   return NULL;
}

Py_BEGIN_ALLOW_THREADS;
// ここで重要な処理を行う。
// 例えば、終了処理を行うスレッドも取得しうるロックを安全に取得できる。
Py_END_ALLOW_THREADS;

// 重要な処理が終わったので、インタープリタの終了処理を再び許可する。
PyInterpreterGuard_Close(guard);

成功時は現在のインタープリタのガードを返します。 失敗時は例外を設定して NULL を返します。

失敗するのは、現在のインタープリタがすでに終了処理を開始している場合と、プロセスのメモリが不足している場合だけです。

この関数が返したガードのポインターは、必ず PyInterpreterGuard_Close() で閉じなければなりません。 閉じないと、Python プロセスが無期限に停止したままになります。

呼び出し元には スレッド状態がアタッチされていなければなりません。

Added in version 3.15.

PyInterpreterGuard *PyInterpreterGuard_FromView(PyInterpreterView *view)

次に属します: Stable ABI (バージョン 3.15 より).

ビューを通じて、インタープリタの終了処理を防ぐガードを作成します。

成功時は、view が表すインタープリタのガードを返します。 呼び出し後もビューは有効です。 ガードは必ず PyInterpreterGuard_Close() で閉じなければなりません。

インタープリタがすでに存在しない場合、終了処理中の場合、またはメモリが不足している場合は、例外を設定せずに NULL を返します。

呼び出し元に スレッド状態がアタッチされている 必要はありません。

Added in version 3.15.

void PyInterpreterGuard_Close(PyInterpreterGuard *guard)

次に属します: Stable ABI (バージョン 3.15 より).

インタープリタのガードを閉じます。 ほかのガードが残っていなければ、インタープリタが終了処理を開始できるようになります。 ガードを閉じないままにすると、インタープリタは終了処理を開始しようとしたときに無期限に待ち続けます。

インタープリタのガードを閉じた後は、PyThreadState_Ensure() に使ってはなりません。 使った場合の動作は未定義です。

この関数は失敗せず、呼び出し元に スレッド状態がアタッチされている 必要もありません。

Added in version 3.15.

インタープリタのビュー

すでに削除されている可能性のあるインタープリタにアクセスする必要がある場合があります。 インタープリタのビューを使うことで、これを行えます。

type PyInterpreterView

次に属します: Stable ABI (不透明な構造体として) (バージョン 3.15 より).

インタープリタの不透明なビューです。

終了処理中や破棄済みの可能性があるインタープリタに、スレッドセーフにアクセスするための手段です。

Added in version 3.15.

PyInterpreterView *PyInterpreterView_FromCurrent(void)

次に属します: Stable ABI (バージョン 3.15 より).

現在のインタープリタのビューを作成します。

通常、PyInterpreterGuard_FromView() または PyThreadState_EnsureFromView() と組み合わせて使うための関数です。

成功時は現在のインタープリタのビューを返します。 失敗時は例外を設定して NULL を返します。

呼び出し元には スレッド状態がアタッチされていなければなりません。

Added in version 3.15.

void PyInterpreterView_Close(PyInterpreterView *view)

次に属します: Stable ABI (バージョン 3.15 より).

インタープリタのビューを閉じます。

インタープリタのビューを閉じないままにすると、ビューのメモリが解放されなくなりますが、それ以外の影響はありません。 一方、ガードを閉じ忘れると、終了処理中にメインスレッドが無期限に停止したままになります。

この関数は失敗せず、呼び出し元に スレッド状態がアタッチされている 必要もありません。

Added in version 3.15.

PyInterpreterView *PyInterpreterView_FromMain(void)

次に属します: Stable ABI (バージョン 3.15 より).

メインインタープリタのビューを作成します。 メインインタープリタは Python プロセスで最初に作成される、デフォルトのインタープリタです (PyInterpreterState_Main() を参照)。

成功時はメインインタープリタのビューを返します。 失敗時は例外を設定せずに NULL を返します。 失敗は、プロセスのメモリ不足を示します。

ネイティブのスレッドライブラリに、PyInterpreterGuard や PyInterpreterView を渡せる void *arg 引数がない場合など、呼び出し元がインタープリタのポインターやビューを渡せないときに使ってください。 サブインタープリタに対応するコードでは、メインインタープリタではなく呼び出し元のインタープリタをガードで追跡できるよう、PyInterpreterView_FromCurrent() を優先してください。

呼び出し元に スレッド状態がアタッチされている 必要はありません。

Added in version 3.15.

プロセスワイドのパラメータ

const char *Py_GetVersion()

次に属します: Stable ABI.

Python インタプリタのバージョンを返します。バージョンは、次のような形式の文字列です

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

第一ワード (最初のスペース文字まで) は、現在の Python のバージョンです; 最初の文字は、ピリオドで区切られたメジャーバージョンとマイナーバージョンです。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version として利用できます。

Py_Version 定数も参照してください。

const char *Py_GetPlatform()

次に属します: Stable ABI.

現在のプラットフォームの識別子を返します。 Unix では、オペレーティングシステムの「正式な」名前を小文字に変換し、メジャーリビジョン番号を付けたものです。 例えば、SunOS 5.x とも呼ばれる Solaris 2.x では 'sunos5' になります。 macOS では 'darwin'、Windows では 'win32' です。 返される文字列は静的な記憶領域を指しているため、呼び出し元で変更してはいけません。 この値は Python のコードから sys.platform として参照できます。

const char *Py_GetCopyright()

次に属します: Stable ABI.

現在の Python バージョンに対する公式の著作権表示文字列を返します。例えば

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.copyright として利用できます。

const char *Py_GetCompiler()

次に属します: Stable ABI.

現在使っているバージョンの Python をビルドする際に用いたコンパイラを示す文字列を、角括弧で囲った文字列を返します。例えば:

"[GCC 2.7.2.2]"

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。

const char *Py_GetBuildInfo()

次に属します: Stable ABI.

現在の Python インタープリタのビルド番号と、ビルドした日時の情報を返します。 例えば次のような値です。

"#67, Aug  1 1997, 22:34:28"

関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は Python コードからは sys.version の一部として取り出せます。