Python

C API 및 ABI 안정성

별도로 명시되지 않는 한, Python의 C API는 하위 호환성 정책인 PEP 387 의 적용을 받습니다. 대부분의 변경 사항은 소스 호환성을 유지하며(대개 새로운 API를 추가하는 방식), 기존 API를 변경하거나 제거하는 것은 서비스 중단 기간을 거친 후나 심각한 문제를 해결하기 위한 경우에만 수행됩니다.

CPython의 응용 프로그램 바이너리 인터페이스(ABI)는 마이너 버전 사이에서 전방 및 후방 호환성을 유지합니다(동일한 방식으로 컴파일된 경우에 한하며, 아래 플랫폼 고려 사항 참조). 따라서 Python 3.10.0용으로 컴파일된 코드는 3.10.8에서도 작동하고 그 반대도 마찬가지이지만, 3.9.x 및 3.11.x 버전에서는 별도로 컴파일해야 합니다.

안정성 기대치가 다른 두 단계의 C API가 있습니다.

  • 불안정 API 는 서비스 중단 기간 없이 마이너 버전에서 변경될 수 있습니다. 이름에 PyUnstable 접두사가 붙어 이를 표시합니다.

  • 제한된 API 는 여러 마이너 버전에 걸쳐 호환됩니다. Py_LIMITED_API 가 정의되면 Python.h 에서 이 부분 집합만 노출됩니다.

이들에 대한 자세한 내용은 아래에서 다룹니다.

_Py_InternalState 와 같이 언더스코어(_)로 시작하는 이름은 패치 릴리스에서도 예고 없이 변경될 수 있는 비공개(private) API입니다. 이 API를 사용해야 하는 경우, 본인의 사용 사례에 맞는 공개 API 추가를 논의하기 위해 CPython 개발자 에게 문의하십시오.

불안정한 C API

PyUnstable 접두사가 붙은 모든 API는 CPython 구현 세부 정보를 노출하며, 서비스 중단 경고 없이 매 마이너 릴리스(예: 3.9에서 3.10으로)마다 변경될 수 있습니다. 그러나 버그 수정 릴리스(예: 3.10.0에서 3.10.1로)에서는 변경되지 않습니다.

이 API는 일반적으로 디버거와 같은 특수한 로우레벨 도구를 위해 설계되었습니다.

이 API를 사용하는 프로젝트는 CPython 개발을 따르고 변경 사항에 적응하기 위해 추가적인 노력을 기울여야 합니다.

안정적인 응용 프로그램 바이너리 인터페이스

Python의 안정적(Stable) ABI 를 사용하면 재컴파일 없이도 여러 버전의 Python과 호환되는 확장 프로그램을 만들 수 있습니다.

참고

편의를 위해 이 문서에서는 확장 프로그램 을 다루고 있지만, Stable ABI는 Python 임베딩 등 모든 형태의 API 활용에 동일하게 적용됩니다.

두 종류의 안정적(Stable) ABI가 있습니다:

  • Python 3.2에서 도입된 abi3 는 CPython의 비-자유 스레딩 빌드와 호환됩니다.

  • Python 3.15에서 도입된 abi3t 는 CPython의 자유 스레딩 빌드와 호환됩니다. 이는 abi3 보다 더 엄격한 API 제한이 적용됩니다.

    Added in version 3.15: abi3t 는 PEP 803 에서 추가되었습니다.

확장 프로그램을 abi3 와 abi3t 모두에 대해 동시에 컴파일할 수 있으며, 이 경우 결과물은 자유 스레딩 및 비자유 스레딩 빌드 모두와 호환됩니다. 현재로서는 단독으로 abi3t 를 위해 컴파일하는 것과 비교해 불이익이 없습니다.

각 안정적(Stable) ABI는 Python 버전의 앞 두 자리를 사용하여 버전을 매깁니다. 예를 들어, Stable ABI 3.14는 Python 3.14에 해당합니다. Stable ABI 3.x용으로 컴파일된 확장은 Python 3.x 이상의 버전과 ABI 호환됩니다.

안정적인 ABI를 목표로 하는 확장은 C API의 제한된 부분 집합만 사용해야 합니다. 이 집합은 제한된 API(Limited API) 라고 알려져 있으며, 포함 내용은 아래에 나열되어 있습니다.

Windows에서 안정적(Stable) ABI를 사용하는 확장은 python39.dll 과 같은 버전 특정 라이브러리가 아닌 python3.dll 에 링크되어야 합니다. 이 라이브러리는 관련 심볼만 노출합니다.

일부 플랫폼에서 Python은 abi3 또는 abi3t 태그가 붙은 이름의 공유 라이브러리 파일(예: mymodule.abi3.so)을 찾아 로드합니다. 자유 스레딩 인터프리터는 abi3t 태그만 인식하고, 비자유 스레딩 인터프리터는 abi3``를 선호하되 실패 시 ``abi3t``로 대체(fallback)합니다. 따라서 두 ABI 모두와 호환되는 확장은 ``abi3t 태그를 사용해야 합니다.

Python은 로드하는 확장이 호환되는 ABI를 가졌는지 반드시 확인하지 않습니다. 확장 프로그램 제작자는 Py_mod_abi 슬롯이나 PyABIInfo_Check() 함수를 사용하여 검사 기능을 추가하는 것을 권장하며, 사용자(또는 패키징 도구)는 예를 들어 Stable ABI 3.10용으로 빌드된 확장이 낮은 버전의 Python에 설치되지 않도록 보장할 책임이 있습니다.

Stable ABI의 모든 함수는 단순히 매크로가 아니라 Python 공유 라이브러리의 실제 함수로 존재합니다. 이를 통해 Python의 ctypes 를 포함하여 C 전처리기를 사용하지 않는 언어에서도 사용할 수 있습니다.

Stable ABI용 컴파일

참고

빌드 도구(예: meson-python, scikit-build-core 또는 Setuptools)는 종종 매크로를 설정하고 이를 확장 프로그램 파일명 및 기타 메타데이터와 동기화하는 기능을 제공합니다. 그러한 기능이 있는 경우 수동으로 매크로를 정의하는 대신 해당 기능을 사용하는 것을 권장합니다.

이 섹션의 나머지 부분은 주로 도구 제작자와 확장 프로그램을 수동으로 컴파일하는 사용자에게 해당됩니다.

더 보기

list of recommended tools in the Python Packaging User Guide

Stable ABI용으로 컴파일하려면 다음 매크로 중 하나 또는 둘 모두를 확장 프로그램이 지원해야 하는 가장 낮은 Python 버전에 대해 Py_PACK_VERSION 형식으로 정의하십시오. 일반적으로 컴파일에 사용되는 Python 헤더 버전이 아니라 특정 값을 선택해야 합니다.

매크로는 Python.h 를 포함하기 전에 정의되어야 합니다. 이 시점에서는 Py_PACK_VERSION 을 사용할 수 없으므로 숫자 값을 직접 사용해야 합니다. 참고용으로 최근 몇몇 Python 버전의 값은 다음과 같습니다.

0x30b0000  /* Py_PACK_VERSION(3,11) */
0x30c0000  /* Py_PACK_VERSION(3,12) */
0x30d0000  /* Py_PACK_VERSION(3,13) */
0x30e0000  /* Py_PACK_VERSION(3,14) */
0x30f0000  /* Py_PACK_VERSION(3,15) */
0x3100000  /* Py_PACK_VERSION(3,16) */

매크로 중 하나가 정의된 경우, Python.h 는 해당 Stable ABI와 호환되는 API만 노출합니다(즉, 제한된 API 및 컴파일러에게는 보여야 하지만 직접 사용해서는 안 되는 몇몇 정의). 두 매크로 모두 정의된 경우, Python.h 은 두 Stable ABI 모두와 호환되는 API만 노출합니다.

Py_LIMITED_API

Target abi3, that is, non-free-threaded builds of CPython. See above for common information.

Py_TARGET_ABI3T

Target abi3t, that is, free-threaded builds of CPython. See above for common information.

Added in version 3.15.

두 매크로 모두 대상 ABI를 지정합니다. 명칭 스타일이 다른 것은 하위 호환성 때문입니다.

역사적 참고

또한 Py_LIMITED_API 를 3 으로 정의할 수도 있습니다. 이는 0x03020000 (Stable ABI가 도입된 버전인 Python 3.2)과 동일하게 작동합니다.

두 매크로가 모두 정의된 경우, Python.h 는 Py_LIMITED_API 를 Py_TARGET_ABI3T 와 일치하도록 재정의할 수도 있고 아닐 수도 있습니다.

On a free-threaded build – that is, when Py_GIL_DISABLED is defined – Py_TARGET_ABI3T defaults to the value of Py_LIMITED_API. This means that there are two ways to build for both abi3 and abi3t:

  • Py_LIMITED_API`와 :c:macro:!Py_TARGET_ABI3T`를 모두 정의하거나,

  • Py_LIMITED_API 만 정의하고:

    • Windows의 경우, Py_GIL_DISABLED 를 정의합니다.

    • 기타 시스템의 경우, Python 자유 스레딩 빌드용 헤더를 사용하십시오.

Stable ABI 범위 및 성능

Stable ABI의 목표는 전체 C API로 가능한 모든 것을 허용하되 성능 저하가 따를 수 있음을 인정하는 것입니다. 일반적으로 Stable ABI 호환성을 확보하려면 확장 프로그램 소스 코드의 일부 변경이 필요합니다.

예를 들어, PyList_GetItem() 은 사용 가능하지만, 그 “안전하지 않은” 매크로 변형인 PyList_GET_ITEM() 은 사용할 수 없습니다. 해당 매크로는 리스트 객체의 버전에 따른 구현 세부 사항을 활용할 수 있어 더 빠를 수 있기 때문입니다.

또 다른 예로, Stable ABI를 위해 컴파일하지 않을 때는 일부 C API 함수가 인라인화되거나 매크로로 대체됩니다. Stable ABI용으로 컴파일하면 이러한 인라인화가 비활성화되어 Python 데이터 구조가 개선됨에 따라 안정성을 확보할 수 있지만 성능은 저하될 수 있습니다.

Py_LIMITED_API 또는 Py_TARGET_ABI3T 정의를 생략함으로써 특정 버전용 ABI에 호환되는 소스를 컴파일할 수 있습니다. 이렇게 하면 더 빠를 수 있는 특정 버전 전용 확장과, 속도는 느리지만 더 호환성이 좋은 Stable ABI용으로 빌드된 버전을 함께 배포할 수 있습니다.

Stable ABI 주의 사항

Stable ABI용으로 컴파일하는 것이 예상되는 Python 버전들과의 호환성을 완전히 보장하는 것은 아니라는 점에 유의하십시오. Stable ABI는 누락된 심볼로 인한 링커 오류나 구조 레이아웃 또는 함수 시그니처 변경으로 인한 데이터 손상과 같은 ABI 문제를 방지합니다. 그러나 Python의 다른 변화로 인해 확장 프로그램의 동작 이 변경될 수 있습니다.

Py_TARGET_ABI3T 및 Py_LIMITED_API 매크로가 방어하지 못하는 한 가지 문제는 낮은 파이썬 버전에서 유효하지 않은 인자로 함수를 호출하는 경우입니다. 예를 들어, 어떤 인자에 대해 NULL``을 허용하기 시작한 함수를 생각해 보십시오. 파이썬 3.9에서는 ``NULL``이 기본 동작을 선택하지만, 파이썬 3.8에서는 해당 인자가 직접 사용되어 ``NULL 참조 오류가 발생하고 충돌하게 됩니다. 유사한 원리가 구조체의 필드에도 적용됩니다.

이러한 이유로, 확장 모듈을 지원하는 모든 마이너 파이썬 버전에서 테스트할 것을 권장합니다.

또한 사용되는 모든 API의 문서를 검토하여 해당 API가 명시적으로 제한된 API(Limited API)에 포함되는지 확인하는 것을 권장합니다. Py_LIMITED_API 가 정의된 경우라도 기술적인 이유(또는 버그로 인한 의도치 않은 경우)로 인해 몇몇 비공개 선언이 노출될 수 있습니다.

또한 Py_LIMITED_API 3.8을 사용하여 컴파일하는 것은 확장 모듈이 파이썬 3.12에서 로드 되어야 하며, 파이썬 3.12로 컴파일 되어야 함을 의미하지만, 동일한 소스가 Py_LIMITED_API 가 3.12로 설정된 상태에서 반드시 컴파일된다는 것을 의미하지는 않습니다. 일반적으로 Stable ABI가 안정적으로 유지되는 한, Limited API의 일부는 폐기되거나 삭제될 수 있습니다.

플랫폼 고려 사항

ABI 안정성은 파이썬뿐만 아니라 사용된 컴파일러, 하위 수준 라이브러리 및 컴파일러 옵션에 따라 달라집니다. Stable ABIs 의 목적에서 이러한 세부 정보는 “플랫폼”을 정의합니다. 이는 일반적으로 OS 유형과 프로세서 아키텍처에 따라 결정됩니다.

특정 플랫폼의 모든 파이썬 버전이 Stable ABI 또는 버전별 ABI를 깨뜨리지 않는 방식으로 빌드되도록 보장하는 것은 각 파이썬 배포자의 책임입니다. 이는 python.org 의 Windows 및 macOS 릴리스와 많은 제3자 배포자의 경우에 해당합니다.

ABI 확인

Added in version 3.15.

파이썬은 ABI 호환성에 대한 기본적인 검사를 포함합니다.

이 검사는 포괄적이지 않습니다. 이는 잘못된 인터프리터에 호환되지 않는 모듈이 설치되는 일반적인 경우를 방지할 뿐입니다. 또한 platform incompatibilities 는 고려하지 않습니다. 이 검사는 확장 모듈이 성공적으로 로드된 후에만 수행될 수 있습니다.

이러한 제한 사항에도 불구하고, 감지 가능한 호환성 문제가 충돌을 일으키는 대신 예외를 발생시키도록 확장 모듈에서 이 메커니즘을 사용하는 것을 권장합니다.

대부분의 모듈은 다음과 같이 Py_mod_abi 슬롯과 PyABIInfo_VAR 매크로를 통해 이 검사를 사용할 수 있습니다.

PyABIInfo_VAR(abi_info);

static PyModuleDef_Slot mymodule_slots[] = {
   {Py_mod_abi, &abi_info},
   ...
};

고급 사용 사례에 대한 전체 API는 아래에 설명되어 있습니다.

int PyABIInfo_Check(PyABIInfo *info, const char *module_name)
…의 일부 안정 ABI 버전 3.15 이후로.

주어진 info 가 현재 실행 중인 인터프리터와 호환되는지 확인합니다.

성공 시 0을 반환합니다. 실패 시 예외를 발생시키고 -1을 반환합니다.

ABI가 호환되지 않으면 발생하는 예외는 ImportError 입니다.

module_name 인자는 NULL 이거나 오류 메시제에 사용되는 NUL로 끝나는 UTF-8 인코딩 문자열을 가리킬 수 있습니다.

info 가 현재 코드가 사용하는 ABI를 설명하는 경우(예를 들어, PyABIInfo_VAR 에 의해 정의된 경우), 다른 파이썬 C API를 사용하면 충돌이 발생할 수 있음에 유의하십시오. 특히, 발생한 예외를 조사하는 것은 안전하지 않습니다.

Added in version 3.15.

PyABIInfo_VAR(NAME)
…의 일부 안정 ABI 버전 3.15 이후로.

현재 코드가 사용할 ABI를 설명하는 주어진 NAME 의 정적 PyABIInfo 변수를 정의합니다. 이 매크로는 다음과 같이 확장됩니다.

static PyABIInfo NAME = {
    1, 0,
    PyABIInfo_DEFAULT_FLAGS,
    PY_VERSION_HEX,
    PyABIInfo_DEFAULT_ABI_VERSION
}

Added in version 3.15.

type PyABIInfo
…의 일부 안정 ABI (모든 멤버 포함) 버전 3.15 이후로.
uint8_t abiinfo_major_version

PyABIInfo 의 메이저 버전입니다. 다음과 같이 설정할 수 있습니다.

  • 모든 검사를 건너뛰려면 0, 또는

  • 이 버전의 PyABIInfo 를 지정하려면 1 을 사용합니다.

uint8_t abiinfo_minor_version

PyABIInfo 의 마이너 버전입니다. 반드시 0 으로 설정해야 하며, 더 큰 값은 하위 호환성이 있는 미래의 PyABIInfo 버전을 위해 예약되어 있습니다.

uint16_t flags

이 필드는 일반적으로 다음 매크로와 같이 설정됩니다.

PyABIInfo_DEFAULT_FLAGS
…의 일부 안정 ABI 버전 3.15 이후로.

Py_LIMITED_API 및 Py_GIL_DISABLED 와 같은 매크로의 현재 값에 기반한 기본 플래그입니다.

대신, 이 필드를 비트 논리합(OR)으로 결합된 다음 플래그들로 설정할 수 있습니다. 사용하지 않는 비트는 0으로 설정해야 합니다.

ABI 변체 — 다음 중 하나:

PyABIInfo_STABLE
…의 일부 안정 ABI 버전 3.15 이후로.

Stable ABI가 사용됨을 지정합니다.

PyABIInfo_INTERNAL

특정 CPython 빌드에 특화된 ABI를 지정합니다. 내부용으로만 사용됩니다.

프리 스레딩 호환성 — 다음 중 하나:

PyABIInfo_FREETHREADED
…의 일부 안정 ABI 버전 3.15 이후로.

CPython의 free-threaded builds 와 호환되는 ABI를 지정합니다. (즉, --disable-gil 옵션으로 컴파일되었으며, sys.abiflags 에 t 가 포함된 경우입니다.)

PyABIInfo_GIL
…의 일부 안정 ABI 버전 3.15 이후로.

CPython의 프리 스레딩이 아닌 빌드(즉, --disable-gil 없이 컴파일된 경우)와 호환되는 ABI를 지정합니다.

PyABIInfo_FREETHREADING_AGNOSTIC
…의 일부 안정 ABI 버전 3.15 이후로.

CPython의 프리 스레딩 및 프리 스레딩이 아닌 빌드 모두와 호환되는, 즉 abi3 및 abi3t 를 모두 지원하는 ABI를 지정합니다.

uint32_t build_version

PY_VERSION_HEX 가 사용하는 형식으로 코드 빌드에 사용된 파이썬 헤더 버전입니다.

이 필드와 관련된 모든 검사를 건너뛰려면 0 으로 설정할 수 있습니다. 이 옵션은 주로 CPython 헤더를 직접 사용하지 않고 특정 버전을 에뮬레이트하지 않는 프로젝트를 위한 것입니다.

uint32_t abi_version

ABI 버전입니다.

Stable ABI의 경우, 이 필드는 Py_LIMITED_API 또는 Py_TARGET_ABI3T 값이어야 합니다. 둘 다 정의된 경우 더 작은 값을 사용합니다. (Py_LIMITED_API 가 3 인 경우, 3 대신 Py_PACK_VERSION(3, 2) 를 사용하십시오.)

그렇지 않은 경우, PY_VERSION_HEX 로 설정해야 합니다.

이 필드와 관련된 모든 검사를 건너뛰려면 0 으로 설정할 수 있습니다.

PyABIInfo_DEFAULT_ABI_VERSION
…의 일부 안정 ABI 버전 3.15 이후로.

Py_LIMITED_API, PY_VERSION_HEX, Py_GIL_DISABLED 와 같은 매크로의 현재 값에 기반하여 이 필드에 사용되어야 할 값입니다.

Added in version 3.15.

제한된 API(Limited API) 내용

This is the definitive list of Limited API for Python 3.16:

분실물 보관소