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

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


Python の初期化前
=================

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

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

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

  * "Py_Initialize()"

  * "Py_InitializeEx()"

  * "Py_InitializeFromConfig()"

  * "Py_BytesMain()"

  * "Py_Main()"

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

* 設定関数:

  * "PyImport_AppendInittab()"

  * "PyImport_ExtendInittab()"

  * "PyInitFrozenExtensions()"

  * "PyMem_SetAllocator()"

  * "PyMem_SetupDebugHooks()"

  * "PyObject_SetArenaAllocator()"

  * "Py_SetProgramName()"

  * "Py_SetPythonHome()"

  * 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()"

注釈:

  上に挙げた関数の一部と似ていても、"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 で削除.
