Python

인터프리터 초기화 및 파이널리제이션

초기화 전에 인터프리터를 구성하는 방법에 대한 자세한 내용은 Python Initialization Configuration 를 참조하십시오.

파이썬 초기화 전

파이썬을 내장한 응용 프로그램에서는, 몇 가지 예외를 제외하고 다른 파이썬/C API 함수를 사용하기 전에 Py_Initialize() 함수를 호출해야 합니다.

다음 함수들은 파이썬이 초기화되기 전에 안전하게 호출될 수 있습니다:

참고

위에 나열된 일부 함수들과 유사해 보이지만, 다음 함수들은 인터프리터가 초기화되기 전에 호출해서는 안 됩니다: Py_EncodeLocale() 및 Py_RunMain().

인터프리터 초기화 및 종료

void Py_Initialize()
…의 일부 안정 ABI.

Python 인터프리터를 초기화합니다. Python을 내장하는 응용 프로그램에서는 다른 Python/C API 함수를 사용하기 전에 이 함수를 호출해야 합니다. 몇 가지 예외 사항은 Before Python Initialization 를 참조하십시오.

이 함수는 로드된 모듈 테이블(sys.modules)을 초기화하고, 핵심 모듈인 builtins, __main__, 그리고 sys 를 생성합니다. 또한 모듈 검색 경로(sys.path)를 초기화합니다. sys.argv 는 설정하지 않으므로 이를 위해서는 Python Initialization Configuration API를 사용하십시오. 이 함수는 처음으로 호출될 때만 동작하며, 두 번째 호출 시에는 아무 작업도 수행하지 않습니다(먼저 Py_FinalizeEx() 를 호출하지 않은 경우). 반환 값이 없으며, 초기화에 실패하면 치명적 오류가 발생합니다.

Python Initialization Configuration 를 사용자 정의하려면 Py_InitializeFromConfig() 를 사용하십시오.

참고

Windows에서 콘솔 모드를 O_TEXT 에서 O_BINARY 로 변경하며, 이는 C Runtime을 사용하는 다른 비(非) Python용 콘솔 사용에도 영향을 미칩니다.

void Py_InitializeEx(int initsigs)
…의 일부 안정 ABI.

initsigs 가 1 이면 이 함수는 Py_Initialize() 와 동일하게 작동합니다. initsigs 가 0 인 경우 신호 처리기(signal handler)의 초기화 등록을 건너뛰며, 이는 CPython이 더 큰 응용 프로그램의 일부로 내장될 때 유용할 수 있습니다.

Python Initialization Configuration 를 사용자 정의하려면 Py_InitializeFromConfig() 를 사용하십시오.

PyStatus Py_InitializeFromConfig(const PyConfig *config)

PyConfig를 사용한 초기화 에 설명된 대로 config 구성에서 Python을 초기화합니다.

인터프리터 사전 초기화, 실행 시간 구성 구조체 채우기 및 반환된 상태 구조체 쿼리에 대한 자세한 내용은 파이썬 초기화 구성 섹션을 참조하십시오.

버전 3.16.0a0 (unreleased)에서 변경: 명령줄 옵션으로 인해 Python을 종료해야 하는 경우, 해당 함수는 더 이상 종료 코드를 반환하지 않습니다. 대신, 해당 옵션은 Py_RunMain() 에서 처리됩니다.

int Py_IsInitialized()
…의 일부 안정 ABI.

Python 인터프리터가 초기화된 경우 참(0이 아닌 값)을 반환하고, 그렇지 않은 경우 거짓(0)을 반환합니다. Py_FinalizeEx() 가 호출된 후에는 Py_Initialize() 가 다시 호출될 때까지 거짓을 반환합니다.

버전 3.15에서 변경: 이 함수는 이제 site 모듈을 포함한 모든 초기화가 완료될 때까지 참을 반환하지 않습니다. 이전에는 Py_Initialize() 가 실행 중인 동안에도 참을 반환할 수 있었습니다.

int Py_IsFinalizing()
…의 일부 안정 ABI 버전 3.13 이후로.

메인 Python 인터프리터가 종료 중이면 참(0이 아닌 값)을 반환합니다. 그렇지 않으면 거짓(0)을 반환합니다.

Added in version 3.13.

int Py_FinalizeEx()
…의 일부 안정 ABI 버전 3.6 이후로.

Py_Initialize() 및 이후의 Python/C API 함수 사용으로 수행된 모든 초기화 작업을 취소하고, 마지막 Py_Initialize() 호출 이후 생성되었으나 아직 파괴되지 않은 모든 하위 인터프리터(아래의 Py_NewInterpreter() 참조)를 제거합니다. 이 함수는 두 번째 호출 시(먼저 Py_Initialize() 를 호출하지 않은 경우) 아무 작업도 수행하지 않습니다.

이 함수는 Py_Initialize() 의 역과정이므로 동일한 스레드에서 동일한 인터프리터가 활성화된 상태로 호출되어야 합니다. 즉, 메인 스레드와 메인 인터프리터여야 합니다. 이 함수는 Py_RunMain() 이 실행되는 동안 절대로 호출되어서는 안 됩니다.

일반적으로 반환 값은 0 입니다. 종료 과정(버퍼된 데이터 플러시) 중 오류가 발생하면 -1 이 반환됩니다.

Python은 인터프리터에 의해 할당된 모든 메모리를 해제하기 위해 최선을 다합니다. 따라서 C 확장 모듈은 다음 Py_Initialize() 호출에서 이들을 사용하기 전에 이전에 할당된 모든 PyObject를 올바르게 정리해야 합니다. 그렇지 않으면 보안 취약점이나 잘못된 동작이 발생할 수 있습니다.

이 함수는 여러 가지 이유로 제공됩니다. 임베딩 애플리케이션은 애플리케이션 자체를 재시작하지 않고도 파이썬을 재시작하고 싶어 할 수 있습니다. 동적으로 로드 가능한 라이브러리(또는 DLL)에서 파이썬 인터프리터를 로드한 애플리케이션은 DLL을 언로드하기 전에 파이썬에 의해 할당된 모든 메모리를 해제하고 싶어 할 수도 있습니다. 애플리케이션의 메모리 누수를 추적하는 동안 개발자는 애플리케이션에서 나가기 전에 파이썬에 의해 할당된 모든 메모리를 해제하고자 할 수 있습니다.

버그 및 주의사항: 모듈 및 모듈 내 객체의 파괴는 무작위 순서로 수행됩니다. 이로 인해 다른 객체(함수 포함)나 모듈에 의존하는 소멸자(__del__() 메서드)가 실패할 수 있습니다. 파이썬에 의해 로드된 동적 확장 모듈은 언로드되지 않습니다. 파이썬 인터프리터에 의해 할당된 적은 양의 메모리는 해제되지 않을 수 있습니다(누수를 발견하면 보고해 주십시오). 객체 간의 순환 참조에 묶인 메모리는 해제되지 않습니다. 인턴된 문자열은 참조 횟수와 상관없이 모두 해제됩니다. 확장 모듈에 의해 할당된 일부 메모리는 해제되지 않을 수 있습니다. 초기화 루틴이 여러 번 호출되는 경우 일부 확장이 제대로 작동하지 않을 수 있으며, 이는 애플리케이션이 Py_Initialize() 및 Py_FinalizeEx() 를 여러 번 호출할 때 발생할 수 있습니다. Py_FinalizeEx() 는 자체 내에서 재귀적으로 호출되어서는 안 됩니다. 따라서 인터프리터 종료 과정의 일부로 실행될 수 있는 코드(예: atexit 핸들러, 객체 파이널라이저 또는 stdout 및 stderr 파일을 플러시하는 동안 실행될 수 있는 모든 코드)에 의해 호출되어서는 안 됩니다.

인자 없이 감사 이벤트 cpython._PySys_ClearAuditHooks 를 발생시킵니다.

Added in version 3.6.

void Py_Finalize()
…의 일부 안정 ABI.

이것은 반환 값을 무시하는 Py_FinalizeEx() 의 하위 호환 버전입니다.

int Py_BytesMain(int argc, char **argv)
…의 일부 안정 ABI 버전 3.8 이후로.

Py_Main() 과 유사하지만 argv 가 바이트 문자열 배열이므로 호출하는 애플리케이션이 텍스트 디코딩 단계를 CPython 런타임에 위임할 수 있습니다.

Added in version 3.8.

int Py_Main(int argc, wchar_t **argv)
…의 일부 안정 ABI.

표준 인터프리터를 위한 메인 프로그램으로, 전체 초기화/파이널리제이션 사이클을 캡슐화하며 환경 및 명령줄에서 구성 설정을 읽어온 후 명령 줄 에 따라 __main__ 을 실행하는 추가 동작을 포함합니다.

이 기능은 단순히 더 큰 애플리케이션에 파이썬 런타임을 내장하는 대신 전체 CPython 명령줄 인터페이스를 지원하려는 프로그램을 위해 제공됩니다.

argc 및 argv 매개변수는 C 프로그램의 main() 함수에 전달되는 것과 유사하지만, 차이점은 argv 항목이 먼저 Py_DecodeLocale() 를 사용하여 wchar_t 로 변환된다는 것입니다. 또한 인자 목록의 항목이 입력된 것과 다른 문자열을 가리키도록 변경될 수 있음에 유의하십시오(단, 인자 목록이 가리키는 문자열의 내용은 변경되지 않습니다).

인수 목록이 유효한 파이썬 명령줄을 나타내지 않으면 반환 값은 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();

일반적인 사용 사례에서 임베딩 애플리케이션은 Py_Initialize(), Py_InitializeEx() 또는 Py_InitializeFromConfig() 를 직접 호출하는 대신 이 함수를 호출하며, 모든 설정은 본 문서의 다른 부분에 설명된 대로 적용됩니다. 만약 이전 런타임 초기화 API 호출 후에 이 함수가 호출되는 경우, 어떤 환경 및 명령줄 구성 설정이 업데이트될지는 버전에 따라 다릅니다(이는 런타임이 처음 초기화될 때 한 번 설정된 후 수정되는 것을 지원하는 설정에 따라 달라지기 때문입니다).

int Py_RunMain(void)

완전히 구성된 CPython 런타임에서 메인 모듈을 실행합니다.

명령 줄이나 구성에서 지정된 명령 (PyConfig.run_command), 스크립트 (PyConfig.run_filename) 또는 모듈 (PyConfig.run_module)을 실행합니다. 이러한 값이 모두 설정되지 않은 경우, __main__ 모듈의 전역 네임스페이스를 사용하는 대화형 파이썬 프롬프트(REPL)를 실행합니다.

PyConfig.inspect 가 설정되지 않은 경우(기본값), 인터프리터가 정상적으로 종료되면(즉, 예외를 발생시키지 않음) 반환 값은 0 이며, 처리되지 않은 SystemExit 의 경우 종료 상태를, 그 외 모든 처리되지 않은 예외에 대해서는 1 을 반환합니다.

PyConfig.inspect 가 설정된 경우(예를 들어 -i 옵션을 사용하는 경우), 인터프리터 종료 시 반환하는 대신 __main__ 모듈의 전역 네임스페이스를 사용하여 대화형 파이썬 프롬프트(REPL)에서 실행을 재개합니다. 인터프리터가 예외와 함께 종료된 경우, 해당 예외는 REPL 세션에서 즉시 발생됩니다. 함수 반환 값은 위에 명시된 대로 REPL 세션 이 종료되는 방식에 따라 0, 1 또는 SystemExit 의 상태로 결정됩니다.

이 함수는 반환하기 전에 항상 파이썬 인터프리터를 파이널리제이션합니다.

Py_RunMain() 을 사용하여 항상 격리 모드에서 실행되는 사용자 정의 파이썬의 예는 파이썬 구성 를 참조하십시오.

int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)
이것은 불안정 API. 마이너 릴리스에서 예고 없이 변경될 수 있습니다.

대상 인터프리터 interp 에 대한 atexit 콜백을 등록합니다. 이는 Py_AtExit() 와 유사하지만, 콜백을 위해 명시적인 인터프리터 및 데이터 포인터를 받습니다.

interp 에 attached thread state 가 존재해야 합니다.

Added in version 3.13.

인터프리터 파이널리제이션 관련 주의사항

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.

파이널리제이션 중에 명시적으로(예: PyThreadState_Ensure() 또는 Py_END_ALLOW_THREADS 를 통한 경우)나 암시적으로(예: 바이트코드 명령 사이 등) 연결을 시도하는 다른 스레드는 영구적으로 차단된 상태 에 빠지게 됩니다. 일반적으로 이는 무해하지만, 데드락을 초래할 수 있습니다. 예를 들어, 어떤 스레드가 잠금을 보유한 채 영구적으로 차단되면 파이널리제이션 스레드가 해당 잠금을 절대 획득할 수 없게 됩니다.

CPython 3.13 이전에는 스레드가 멈추는 대신 종료되었으며, 이는 다른 문제를 야기했습니다(PyThread_exit_thread() 의 경고 문구 참조).

심각한 문제인가요? 네. 파이썬 3.15부터는 파이널리제이션을 일시적으로 방지하여 이러한 문제를 피할 수 있게 하는 여러 C API가 제공됩니다.

더 보기

PEP 788 은 이들 API의 설계, 동기 및 근거를 설명합니다.

type PyInterpreterGuard
…의 일부 안정 ABI (불투명 구조체로) 버전 3.15 이후로.

불투명한 인터프리터 가드 구조체입니다.

인터프리터 가드를 보유함으로써 호출자는 가드가 닫힐 때까지( PyInterpreterGuard_Close() 를 통해) 인터프리터가 파이널리제이션되지 않도록 보장할 수 있습니다.

가드가 유지되는 동안 인터프리터를 파이널리제이션하려는 스레드는 가드가 닫힐 때까지 차단된 상태로 대기하며 그 이후에 파이널리제이션을 시작합니다. 파이널리제이션이 시작되면, 다른 스레드들은 해당 인터프리터에 대한 가드를 영원히 획득할 수 없습니다. 즉, 인터프리터 가드를 닫는 것을 잊으면 파이널리제이션 중에 프로세스가 영구적으로 멈출(hang) 수 있습니다!

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)
…의 일부 안정 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() 를 사용하여 닫아야 합니다. 그렇지 않으면 파이썬 프로세스가 무한히 대기하게 됩니다.

The caller must hold an attached thread state.

Added in version 3.15.

PyInterpreterGuard *PyInterpreterGuard_FromView(PyInterpreterView *view)
…의 일부 안정 ABI 버전 3.15 이후로.

뷰(view)를 통해 인터프리터에 대한 파이널리제이션 가드를 생성합니다.

성공하면 이 함수는 view 가 나타내는 인터프리터에 대한 가드를 반환합니다. 뷰는 이 함수를 호출한 후에도 유효합니다. 가드는 반드시 PyInterpreterGuard_Close() 로 닫혀야 합니다.

인터프리터가 더 이상 존재하지 않거나 파이널리제이션 중이거나 메모리가 부족한 경우, 이 함수는 예외를 설정하지 않고 NULL 을 반환합니다.

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

Added in version 3.15.

void PyInterpreterGuard_Close(PyInterpreterGuard *guard)
…의 일부 안정 ABI 버전 3.15 이후로.

인터프리터 가드를 닫습니다. 다른 가드가 남아 있지 않은 상태에서 이 가드를 닫으면 인터프리터가 파이널리제이션을 시작할 수 있습니다. 만약 인터프리터 가드를 닫지 않으면, 인터프리터가 파이널리제이션에 진입하려고 할 때 무한히 대기하게 됩니다!

인터프리터 가드가 닫힌 후에는 PyThreadState_Ensure() 에서 사용할 수 없습니다. 그렇게 하면 정의되지 않은 동작이 발생합니다.

이 함수는 실패할 수 없으며, 호출자가 attached thread state 를 보유할 필요가 없습니다.

Added in version 3.15.

인터프리터 뷰

어떤 경우에는 이미 삭제된 인터프리터에 접근해야 할 수도 있습니다. 이는 인터프리터 뷰를 사용하여 수행할 수 있습니다.

type PyInterpreterView
…의 일부 안정 ABI (불투명 구조체로) 버전 3.15 이후로.

인터프리터의 불투명(opaque) 뷰입니다.

이는 파이널리제이션 중이거나 이미 파괴된 인터프리터에 접근하는 스레드 안전한(thread-safe) 방법입니다.

Added in version 3.15.

PyInterpreterView *PyInterpreterView_FromCurrent(void)
…의 일부 안정 ABI 버전 3.15 이후로.

현재 인터프리터에 대한 뷰를 생성합니다.

이 함수는 일반적으로 PyInterpreterGuard_FromView() 또는 PyThreadState_EnsureFromView() 와 함께 사용되도록 설계되었습니다.

성공 시 이 함수는 현재 인터프리터에 대한 뷰를 반환하며, 실패 시 예외를 설정하고 NULL 을 반환합니다.

The caller must hold an attached thread state.

Added in version 3.15.

void PyInterpreterView_Close(PyInterpreterView *view)
…의 일부 안정 ABI 버전 3.15 이후로.

인터프리터 뷰를 닫습니다.

인터프리터 뷰를 닫지 않으면 뷰의 메모리가 해제되지 않지만 다른 문제는 발생하지 않습니다. (이와 대조적으로, 가드를 닫지 않으면 파이널리제이션 동안 메인 스레드가 무한히 멈추게 됩니다.)

이 함수는 실패할 수 없으며, 호출자가 attached thread state 를 보유할 필요가 없습니다.

Added in version 3.15.

PyInterpreterView *PyInterpreterView_FromMain(void)
…의 일부 안정 ABI 버전 3.15 이후로.

메인 인터프리터(파이썬 프로세스에서 첫 번째이자 기본인 인터프리터; PyInterpreterState_Main() 참조)에 대한 뷰를 생성합니다.

성공 시 이 함수는 메인 인터프리터에 대한 뷰를 반환하며, 실패 시 예외 없이 NULL 을 반환합니다. 실패는 프로세스의 메모리가 부족함을 나타냅니다.

호출자가 인터프리터 포인터나 뷰를 제공할 수 없는 경우(예: 네이티브 스레딩 라이브러리가 PyInterpreterGuard 또는 PyInterpreterView 를 담을 수 있는 void *arg 매개변수를 제공하지 않는 경우) 이 함수를 사용하십시오. 서브 인터프리터를 지원하는 코드에서는 가드가 메인 인터프리터 대신 호출된 인터프리터를 추적할 수 있도록 PyInterpreterView_FromCurrent() 를 사용하는 것을 권장합니다.

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

Added in version 3.15.

프로세스 전체 매개변수

const char *Py_GetVersion()
…의 일부 안정 ABI.

이 파이썬 인터프리터의 버전을 반환합니다. 이 문자열은 다음과 같은 형식을 갖습니다.

"3.15.0rc2 (3.15.0~rc2-1.fc44.x86_64, Sep  3 2026, 00:00:00) [GCC 16.2.1 20260819 (Red Hat 16.2.1-2)]"

첫 번째 단어(첫 번째 공백 문자까지)는 현재 파이썬 버전이며, 첫 부분은 점으로 구분된 메이저 및 마이너 버전입니다. 반환된 문자열은 정적 저장소를 가리키므로 호출자가 그 값을 수정해서는 안 됩니다. 이 값은 파이썬 코드에서 sys.version 으로 사용할 수 있습니다.

Py_Version 상수를 참조하십시오.

const char *Py_GetPlatform()
…의 일부 안정 ABI.

현재 플랫폼의 식별자를 반환합니다. Unix에서 이는 운영체제의 “공식” 이름을 소문자로 변환하고 메이저 리비전 번호를 붙여 구성됩니다. 예를 들어, SunOS 5.x로도 알려진 Solaris 2.x의 경우 값은 'sunos5' 입니다. macOS에서는 'darwin' 이며, Windows에서는 'win' 입니다. 반환된 문자열은 정적 저장소를 가리키므로 호출자가 값을 수정해서 안 됩니다. 이 값은 파이썬 코드에서 sys.platform 으로 사용할 수 있습니다.

const char *Py_GetCopyright()
…의 일부 안정 ABI.

현재 파이썬 버전에 대한 공식 저작권 문구(예를 들어)

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

반환된 문자열은 정적 저장소를 가리키므로 호출자가 값을 수정해서는 안 됩니다. 이 값은 파이썬 코드에서 sys.copyright 로 사용할 수 있습니다.

const char *Py_GetCompiler()
…의 일부 안정 ABI.

현재 파이썬 버전을 빌드하는 데 사용된 컴파일러를 대괄호 안에 표시하여 반환합니다. 예를 들어:

"[GCC 2.7.2.2]"

반환된 문자열은 정적 저장소를 가리키므로 호출자가 값을 수정해서는 안 됩니다. 이 값은 파이썬 코드에서 변수 sys.version 의 일부로 제공됩니다.

const char *Py_GetBuildInfo()
…의 일부 안정 ABI.

현재 파이썬 인터프리터 인스턴스의 시퀀스 번호와 빌드 날짜 및 시간에 대한 정보를 반환합니다. 예를 들어

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

반환된 문자열은 정적 저장소를 가리키므로 호출자가 값을 수정해서는 안 됩니다. 이 값은 파이썬 코드에서 변수 sys.version 의 일부로 제공됩니다.

분실물 보관소