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

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

Python の初期化前

Python を組み込むアプリケーションでは、一部の関数と グローバルな設定変数 を除き、ほかの Python/C API を使う前に Py_Initialize() を呼び出さなければなりません。

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

注釈

上に挙げた関数の一部と似ていても、Py_EncodeLocale()、PyEval_InitThreads()、Py_RunMain() は、インタープリタの初期化前に 呼び出してはなりません。

グローバルな設定変数

Python には、様々な機能やオプションを制御するグローバルな設定のための変数があります。 デフォルトでは、これらのフラグは コマンドラインオプション で制御されます。

オプションでフラグがセットされると、フラグの値はそのオプションがセットされた回数になります。 例えば、 -b では Py_BytesWarningFlag が 1 に設定され、 -bb では Py_BytesWarningFlag が 2 に設定されます。

int Py_BytesWarningFlag

この API は後方互換性のために残されています。 代わりに PyConfig.bytes_warning を設定してください。 Python の初期化設定 を参照してください。

bytes または bytearray を str と比較した場合、または、 bytes を int と比較した場合に警告を発生させます。 2 以上の値を設定している場合は、エラーを発生させます。

-b オプションで設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_DebugFlag

この API は後方互換性のために残されています。 代わりに PyConfig.parser_debug を設定してください。 Python の初期化設定 を参照してください。

パーサーのデバッグ出力を有効にします。(専門家専用です。コンパイルオプションに依存します)。

-d オプションと PYTHONDEBUG 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_DontWriteBytecodeFlag

この API は後方互換性のために残されています。 代わりに PyConfig.write_bytecode を設定してください。 Python の初期化設定 を参照してください。

非ゼロに設定した場合、Python はソースモジュールのインポート時に .pyc ファイルの作成を試みません。

-B オプションと PYTHONDONTWRITEBYTECODE 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_FrozenFlag

この API は後方互換性のために残されています。 代わりに PyConfig.pathconfig_warnings を設定してください。 Python の初期化設定 を参照してください。

_freeze_module プログラムと frozenmain プログラムが使用する非公開フラグです。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_HashRandomizationFlag

この API は後方互換性のために残されています。 代わりに PyConfig.hash_seed と PyConfig.use_hash_seed を設定してください。 Python の初期化設定 を参照してください。

PYTHONHASHSEED 環境変数が空でない文字列に設定された場合に、 1 が設定されます。

フラグがゼロでない場合、 PYTHONHASHSEED 環境変数を読みシークレットハッシュシードを初期化します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_IgnoreEnvironmentFlag

この API は後方互換性のために残されています。 代わりに PyConfig.use_environment を設定してください。 Python の初期化設定 を参照してください。

PYTHONPATH や PYTHONHOME など、設定されているすべての PYTHON* 環境変数を無視します。

-E オプションと -I オプションで設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_InspectFlag

この API は後方互換性のために残されています。 代わりに PyConfig.inspect を設定してください。 Python の初期化設定 を参照してください。

最初の引数にスクリプトを指定した場合や -c オプションを使った場合は、sys.stdin が端末でなくても、スクリプトやコマンドの実行後に対話モードに入ります。

-i オプションと PYTHONINSPECT 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_InteractiveFlag

この API は後方互換性のために残されています。 代わりに PyConfig.interactive を設定してください。 Python の初期化設定 を参照してください。

-i オプションで設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_IsolatedFlag

この API は後方互換性のために残されています。 代わりに PyConfig.isolated を設定してください。 Python の初期化設定 を参照してください。

Python を隔離モードで実行します。 隔離モードでは sys.path はスクリプトのディレクトリやユーザのサイトパッケージのディレクトリを含みません。

-I オプションで設定します。

Added in version 3.4.

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_LegacyWindowsFSEncodingFlag

この API は後方互換性のために残されています。 代わりに PyPreConfig.legacy_windows_fs_encoding を設定してください。 Python の初期化設定 を参照してください。

フラグがゼロ以外の場合は、ファイルシステムエンコーディングとエラーハンドラー として、UTF-8 と surrogatepass エラーハンドラーの代わりに、mbcs と replace エラーハンドラーを使います。

PYTHONLEGACYWINDOWSFSENCODING 環境変数が空でない文字列に設定された場合に、 1 に設定されます。

より詳しくは PEP 529 を参照してください。

利用可能な環境: Windows.

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_LegacyWindowsStdioFlag

この API は後方互換性のために残されています。 代わりに PyConfig.legacy_windows_stdio を設定してください。 Python の初期化設定 を参照してください。

フラグがゼロ以外の場合は、sys の標準ストリームに io._WindowsConsoleIO の代わりに io.FileIO を使います。

PYTHONLEGACYWINDOWSSTDIO 環境変数が空でない文字列に設定された場合に、 1 に設定されます。

より詳しくは PEP 528 を参照してください。

利用可能な環境: Windows.

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_NoSiteFlag

この API は後方互換性のために残されています。 代わりに PyConfig.site_import を設定してください。 Python の初期化設定 を参照してください。

site モジュールの import と、そのモジュールが行なっていた site ごとの sys.path への操作を無効にします。後で site を明示的に import しても、これらの操作は実行されません (実行したい場合は、 site.main() を呼び出してください)。

-S オプションで設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_NoUserSiteDirectory

この API は後方互換性のために残されています。 代わりに PyConfig.user_site_directory を設定してください。 Python の初期化設定 を参照してください。

ユーザのサイトパッケージのディレクトリ を sys.path に追加しません。

-s オプション、 -I 、 PYTHONNOUSERSITE 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_OptimizeFlag

この API は後方互換性のために残されています。 代わりに PyConfig.optimization_level を設定してください。 Python の初期化設定 を参照してください。

-O オプションと PYTHONOPTIMIZE 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_QuietFlag

この API は後方互換性のために残されています。 代わりに PyConfig.quiet を設定してください。 Python の初期化設定 を参照してください。

インタラクティブモードでも copyright とバージョンのメッセージを表示しません。

-q オプションで設定します。

Added in version 3.2.

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_UnbufferedStdioFlag

この API は後方互換性のために残されています。 代わりに PyConfig.buffered_stdio を設定してください。 Python の初期化設定 を参照してください。

標準出力と標準エラーをバッファリングしないように強制します。

-u オプションと PYTHONUNBUFFERED 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

int Py_VerboseFlag

この API は後方互換性のために残されています。 代わりに PyConfig.verbose を設定してください。 Python の初期化設定 を参照してください。

モジュールが初期化されるたびにメッセージを出力し、それがどこ (ファイル名やビルトインモジュール) からロードされたのかを表示します。 値が 2 以上の場合は、モジュールを検索するときにチェックしたファイルごとにメッセージを出力します。また、終了時のモジュールクリーンアップに関する情報も提供します。

-v オプションと PYTHONVERBOSE 環境変数で設定します。

バージョン 3.12 で非推奨、バージョン 3.15 で削除.

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

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 初期化設定 を参照してください。

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 より).

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

This is a thread-safe way to access an interpreter that may be finalizing or already destroyed.

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.

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

void Py_SetProgramName(const wchar_t *name)
次に属します: Stable ABI.

この API は後方互換性のために残されています。 代わりに PyConfig.program_name を設定してください。 Python の初期化設定 を参照してください。

この関数を使う場合は、最初の Py_Initialize() の呼び出しより前に呼び出してください。 プログラムの main() 関数に渡された argv[0] 引数をワイド文字に変換した値を、インタープリタに知らせます。 以下に示す一部の関数は、これを使ってインタープリタの実行ファイルからの相対位置にある Python ランタイムライブラリを探します。 デフォルト値は 'python' です。 引数は、静的な記憶領域に置かれた、ゼロ終端のワイド文字列を指す必要があります。 その内容は、プログラムの実行中に変わってはなりません。 Python インタープリタのコードが、この記憶領域の内容を変更することはありません。

バイト文字列をデコードして wchar_t* 文字列を取得するには、Py_DecodeLocale() を使ってください。

バージョン 3.11 で非推奨、バージョン 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では、オペレーティングシステムの "公式の" 名前を小文字に変換し、後ろにメジャーリビジョン番号を付けた構成になっています。例えば Solaris 2.x は、SunOS 5.x, としても知られていますが、'sunos5' になります。macOS では 'darwin' です。Windows では 'win' です。関数が返す文字列ポインタは静的な記憶領域を返します; 関数の呼び出し側はこの値を変更できません。この値は 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 の一部として取り出せます。

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
次に属します: Stable ABI.

この API は後方互換性のために残されています。 代わりに PyConfig.argv と PyConfig.parse_argv と PyConfig.safe_path を設定してください。 Python の初期化設定 を参照してください。

argc および argv に基づいて sys.argv を設定します。これらの引数はプログラムの main() に渡した引数に似ていますが、最初の要素が Python インタプリタの宿主となっている実行形式の名前ではなく、実行されるスクリプト名を参照しなければならない点が違います。実行するスクリプトがない場合、 argv の最初の要素は空文字列にしてもかまいません。この関数が sys.argv の初期化に失敗した場合、致命的エラーを Py_FatalError() で知らせます。

updatepath が 0 の場合、ここまでの動作がこの関数がすることの全てです。 updatepath が 0 でない場合、この関数は sys.path を以下のアルゴリズムに基づいて修正します:

  • 存在するスクリプトの名前が argv[0] に渡された場合、そのスクリプトがある場所の絶対パスを sys.path の先頭に追加します。

  • それ以外の場合 (argc が 0 だったり、 argv[0] が存在するファイル名を指していない場合)、 sys.path の先頭に空の文字列を追加します。 これは現在の作業ディレクトリ (".") を先頭に追加するのと同じです。

バイト文字列をデコードして wchar_t* 文字列を取得するには、Py_DecodeLocale() を使ってください。

Python の初期化設定 の PyConfig.orig_argv と PyConfig.argv メンバーも参照してください。

注釈

単一のスクリプトを実行する以外の目的で Python インタープリタを組み込むアプリケーションでは、updatepath に 0 を渡し、必要なら sys.path を自分で更新することを推奨します。 CVE 2008-5983 を参照してください。

3.1.3 より前のバージョンでは、 PySys_SetArgv() の呼び出しが完了した後に sys.path の先頭の要素を取り出すことで、同じ効果が得られます。例えばこのように使います:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

Added in version 3.1.3.

バージョン 3.11 で非推奨、バージョン 3.15 で削除.

void PySys_SetArgv(int argc, wchar_t **argv)
次に属します: Stable ABI.

この API は後方互換性のために残されています。 代わりに PyConfig.argv と PyConfig.parse_argv を設定してください。 Python の初期化設定 を参照してください。

この関数は、 python インタプリタが -I オプション付きで実行されている場合を除き PySys_SetArgvEx() の updatepath に 1 を設定したのと同じように動作します。

バイト文字列をデコードして wchar_t* 文字列を取得するには、Py_DecodeLocale() を使ってください。

Python の初期化設定 の PyConfig.orig_argv と PyConfig.argv メンバーも参照してください。

バージョン 3.4 で変更: updatepath の値は -I オプションに依存します。

バージョン 3.11 で非推奨、バージョン 3.15 で削除.

void Py_SetPythonHome(const wchar_t *home)
次に属します: Stable ABI.

この API は後方互換性のために残されています。 代わりに PyConfig.home を設定してください。 Python の初期化設定 を参照してください。

Python の標準ライブラリがある、デフォルトの "home" ディレクトリを設定します。引数の文字列の意味については PYTHONHOME を参照してください。

引数は静的なストレージに置かれてプログラム実行中に書き換えられないようなゼロ終端の文字列であるべきです。Python インタプリタはこのストレージの内容を変更しません。

バイト文字列をデコードして wchar_t* 文字列を取得するには、Py_DecodeLocale() を使ってください。

バージョン 3.11 で非推奨、バージョン 3.15 で削除.