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

See Python Initialization Configuration for details on how to configure the interpreter prior to initialization.

Before Python initialization

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 の初期化の前でも安全に呼び出せます:

• Functions that initialize the interpreter:

  • Py_Initialize()

  • Py_InitializeEx()

  • Py_InitializeFromConfig()

  • Py_BytesMain()

  • Py_Main()

  • the runtime pre-initialization functions covered in Python 初期化設定

• 設定関数:

  • PyImport_AppendInittab()

  • PyImport_ExtendInittab()

  • PyInitFrozenExtensions()

  • PyMem_SetAllocator()

  • PyMem_SetupDebugHooks()

  • PyObject_SetArenaAllocator()

  • the configuration functions covered in Python 初期化設定

• 情報取得の関数:

  • Py_IsInitialized()

  • PyMem_GetAllocator()

  • PyObject_GetArenaAllocator()

  • Py_GetBuildInfo()

  • Py_GetCompiler()

  • Py_GetCopyright()

  • Py_GetPlatform()

  • Py_GetVersion()

  • Py_IsInitialized()

• ユーティリティ:

  • Py_DecodeLocale()

  • the status reporting and utility functions covered in Python 初期化設定

• メモリアロケータ:

  • PyMem_RawMalloc()

  • PyMem_RawRealloc()

  • PyMem_RawCalloc()

  • PyMem_RawFree()

• Synchronization:

  • 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.

Initialize the Python interpreter. In an application embedding Python, this should be called before using any other Python/C API functions; see Before Python Initialization for the few exceptions.

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.

Use Py_InitializeFromConfig() to customize the Python Initialization Configuration.

注釈

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

void Py_InitializeEx(int initsigs)

次に属します: Stable ABI.

This function works like Py_Initialize() if initsigs is 1. If initsigs is 0, it skips initialization registration of signal handlers, which may be useful when CPython is embedded as part of a larger application.

Use Py_InitializeFromConfig() to customize the Python Initialization Configuration.

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Initialize Python from config configuration, as described in Initialization with PyConfig.

See the Python 初期化設定 section for details on pre-initializing the interpreter, populating the runtime configuration structure, and querying the returned status structure.

int Py_IsInitialized()

次に属します: Stable ABI.

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

バージョン 3.15 で変更: This function no longer returns true until initialization has fully completed, including import of the site module. Previously it could return true while Py_Initialize() was still running.

int Py_IsFinalizing()

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

Return true (non-zero) if the main Python interpreter is shutting down. Return false (zero) otherwise.

Added in version 3.13.

int Py_FinalizeEx()

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

Undo all initializations made by Py_Initialize() and subsequent use of Python/C API functions, and destroy all sub-interpreters (see Py_NewInterpreter() below) that were created and not yet destroyed since the last call to Py_Initialize(). This is a no-op when called for a second time (without calling Py_Initialize() again first).

Since this is the reverse of Py_Initialize(), it should be called in the same thread with the same interpreter active. That means the main thread and the main interpreter. This should never be called while Py_RunMain() is running.

Normally the return value is 0. If there were errors during finalization (flushing buffered data), -1 is returned.

Note that Python will do a best effort at freeing all memory allocated by the Python interpreter. Therefore, any C-Extension should make sure to correctly clean up all of the previously allocated PyObjects before using them in subsequent calls to Py_Initialize(). Otherwise it could introduce vulnerabilities and incorrect behavior.

この関数が提供されている理由はいくつかあります。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 より).

Similar to Py_Main() but argv is an array of bytes strings, allowing the calling application to delegate the text decoding step to the CPython runtime.

Added in version 3.8.

int Py_Main(int argc, wchar_t **argv)

次に属します: Stable ABI.

The main program for the standard interpreter, encapsulating a full initialization/finalization cycle, as well as additional behaviour to implement reading configurations settings from the environment and command line, and then executing __main__ in accordance with コマンドライン.

This is made available for programs which wish to support the full CPython command line interface, rather than just embedding a Python runtime in a larger application.

The argc and argv parameters are similar to those which are passed to a C program's main() function, except that the argv entries are first converted to wchar_t using Py_DecodeLocale(). It is also important to note that the argument list entries may be modified to point to strings other than those passed in (however, the contents of the strings pointed to by the argument list are not modified).

The return value is 2 if the argument list does not represent a valid Python command line, and otherwise the same as Py_RunMain().

In terms of the CPython runtime configuration APIs documented in the runtime configuration section (and without accounting for error handling), Py_Main is approximately equivalent to:

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

Py_RunMain();

In normal usage, an embedding application will call this function instead of calling Py_Initialize(), Py_InitializeEx() or Py_InitializeFromConfig() directly, and all settings will be applied as described elsewhere in this documentation. If this function is instead called after a preceding runtime initialization API call, then exactly which environmental and command line configuration settings will be updated is version dependent (as it depends on which settings correctly support being modified after they have already been set once when the runtime was first initialized).

int Py_RunMain(void)

Executes the main module in a fully configured CPython runtime.

Executes the command (PyConfig.run_command), the script (PyConfig.run_filename) or the module (PyConfig.run_module) specified on the command line or in the configuration. If none of these values are set, runs the interactive Python prompt (REPL) using the __main__ module's global namespace.

If PyConfig.inspect is not set (the default), the return value will be 0 if the interpreter exits normally (that is, without raising an exception), the exit status of an unhandled SystemExit, or 1 for any other unhandled exception.

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.

This function always finalizes the Python interpreter before it returns.

See Python Configuration for an example of a customized Python that always runs in isolated mode using Py_RunMain().

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

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

Register an atexit callback for the target interpreter interp. This is similar to Py_AtExit(), but takes an explicit interpreter and data pointer for the callback.

There must be an attached thread state for interp.

Added in version 3.13.

Cautions regarding interpreter finalization

In the late stage of interpreter shutdown, after attempting to wait for non-daemon threads to exit (though this can be interrupted by KeyboardInterrupt) and running the atexit functions, the runtime is marked as finalizing, meaning that Py_IsFinalizing() and sys.is_finalizing() return true. At this point, only the finalization thread (the thread that initiated finalization; this is typically the main thread) is allowed to attach a thread state.

Other threads that attempt to attach during finalization, either explicitly (such as via PyThreadState_Ensure() or Py_END_ALLOW_THREADS) or implicitly (such as in-between bytecode instructions), will enter a permanently blocked state. Generally, this is harmless, but this can result in deadlocks. For example, a thread may be permanently blocked while holding a lock, meaning that the finalization thread can never acquire that lock.

Prior to CPython 3.13, the thread would exit instead of hanging, which led to other issues (see the warning note at PyThread_exit_thread()).

Gross? Yes. Starting in Python 3.15, there are a number of C APIs that make it possible to avoid these issues by temporarily preventing finalization:

参考

PEP 788 explains the design, motivation and rationale for these APIs.

type PyInterpreterGuard

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

An opaque interpreter guard structure.

By holding an interpreter guard, the caller can ensure that the interpreter will not finalize until the guard is closed (through PyInterpreterGuard_Close()).

When a guard is held, a thread attempting to finalize the interpreter will block until the guard is closed before starting finalization. After finalization has started, threads are forever unable to acquire guards for that interpreter. This means that if you forget to close an interpreter guard, the process will permanently hang during finalization!

Holding a guard for an interpreter is similar to holding a strong reference to a Python object, except finalization does not happen automatically after all guards are released: it requires an explicit Py_EndInterpreter() call.

Added in version 3.15.

PyInterpreterGuard *PyInterpreterGuard_FromCurrent(void)

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

Create a finalization guard for the current interpreter. This will prevent finalization until the guard is closed.

例えば:

// Temporarily prevent finalization.
PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
if (guard == NULL) {
   // Finalization has already started or we're out of memory.
   return NULL;
}

Py_BEGIN_ALLOW_THREADS;
// Do some critical processing here. For example, we can safely acquire
// locks that might be acquired by the finalization thread.
Py_END_ALLOW_THREADS;

// Now that we're done with our critical processing, the interpreter is
// allowed to finalize again.
PyInterpreterGuard_Close(guard);

On success, this function returns a guard for the current interpreter; on failure, it returns NULL with an exception set.

This function will fail only if the current interpreter has already started finalizing, or if the process is out of memory.

The guard pointer returned by this function must be eventually closed with PyInterpreterGuard_Close(); failing to do so will result in the Python process infinitely hanging.

The caller must hold an attached thread state.

Added in version 3.15.

PyInterpreterGuard *PyInterpreterGuard_FromView(PyInterpreterView *view)

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

Create a finalization guard for an interpreter through a view.

On success, this function returns a guard to the interpreter represented by view. The view is still valid after calling this function. The guard must eventually be closed with PyInterpreterGuard_Close().

If the interpreter no longer exists, is already finalizing, or out of memory, then this function returns NULL without setting an exception.

The caller does not need to hold an attached thread state.

Added in version 3.15.

void PyInterpreterGuard_Close(PyInterpreterGuard *guard)

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

Close an interpreter guard, allowing the interpreter to start finalization if no other guards remain. If an interpreter guard is never closed, the interpreter will infinitely wait when trying to enter finalization!

After an interpreter guard is closed, it may not be used in PyThreadState_Ensure(). Doing so will result in undefined behavior.

This function cannot fail, and the caller doesn't need to hold an attached thread state.

Added in version 3.15.

Interpreter views

In some cases, it may be necessary to access an interpreter that may have been deleted. This can be done using interpreter views.

type PyInterpreterView

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

An opaque view of an interpreter.

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

Added in version 3.15.

PyInterpreterView *PyInterpreterView_FromCurrent(void)

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

Create a view to the current interpreter.

This function is generally meant to be used alongside PyInterpreterGuard_FromView() or PyThreadState_EnsureFromView().

On success, this function returns a view to the current interpreter; on failure, it returns NULL with an exception set.

The caller must hold an attached thread state.

Added in version 3.15.

void PyInterpreterView_Close(PyInterpreterView *view)

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

Close an interpreter view.

If an interpreter view is never closed, the view's memory will never be freed, but there are no other consequences. (In contrast, forgetting to close a guard will infinitely hang the main thread during finalization.)

This function cannot fail, and the caller doesn't need to hold an attached thread state.

Added in version 3.15.

PyInterpreterView *PyInterpreterView_FromMain(void)

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

Create a view for the main interpreter (the first and default interpreter in a Python process; see PyInterpreterState_Main()).

On success, this function returns a view to the main interpreter; on failure, it returns NULL without an exception set. Failure indicates that the process is out of memory.

Use this function when an interpreter pointer or view cannot be supplied by the caller, such as when a native threading library does not provide a void *arg parameter that could carry a PyInterpreterGuard or PyInterpreterView. In code that supports subinterpreters, prefer PyInterpreterView_FromCurrent() so the guard tracks the calling interpreter rather than the main one.

The caller does not need to hold an attached thread state.

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 として利用できます。

See also the Py_Version constant.

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.

Return information about the sequence number and build date and time of the current Python interpreter instance, for example

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

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