Python

C API 및 ABI 안정성

Unless documented otherwise, Python’s C API is covered by the Backwards Compatibility Policy, PEP 387. Most changes to it are source-compatible (typically by only adding new API). Changing existing API or removing API is only done after a deprecation period or to fix serious issues.

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

C API에는 서로 다른 안정성 기대치를 가진 두 가지 등급이 있습니다:

  • <unstable-c-api> 에서 불안정한 API`는 비사용 지원 중단 기간 없이 마이너 버전에서 변경될 수 있습니다. 이름에서는 PyUnstable 접두사로 표시됩니다.

  • <limited-c-api> 의 제한형 API`는 몇몇 마이너 버전에서 호환됩니다. Py_LIMITED_API 가 정의되면, Python.h 에서 이 서브셋만 노출됩니다.

이는 아래에서 더 자세히 논의합니다.

_Py_InternalState 와 같이 밑줄로 접두가 붙은 이름은 패치 릴리스에서도 예고 없이 변경될 수 있는 비공개 API입니다. 이 API를 사용해야 하는 경우, 사용 예를 위해 공개 API 추가를 논의하는 것이므로 CPython developers 에 연락하는 것을 고려해 보십시오.

불안정한 C API

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

이것은 일반적으로 디버거와 같은 전문적인, 낮은 수준의 도구용으로 의도된 것입니다.

이 API를 사용하는 프로젝트는 CPython 개발을 준수하고 변경 사항에 적응하기 위해 추가적인 노력을 기울일 것으로 예상됩니다.

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

Python’s Stable ABI allows extensions to be compatible with multiple versions of Python, without recompilation.

참고

간단하게 설명하기 위해, 이 문서는 확장 모듈 에 대해 이야기하지만, 안정 ABI는 Python 임베딩과 같이 API의 모든 사용처에서 동일하게 작동합니다.

두 가지 안정 ABI가 있습니다:

  • abi3, introduced in Python 3.2, is compatible with non-free-threaded builds of CPython.

  • abi3t, introduced in Python 3.15, is compatible with free-threaded builds of CPython. It has stricter API limitations than abi3.

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

확장 모듈은 동시에 두 abi3 와 abi3t 용으로 컴파일하는 것이 가능하며; 결과는 자유 스레드 및 비자유 스레드 Python 빌드와 모두 호환됩니다. 현재로서는 이는 abi3t 만 컴파일하는 것과 비교하여 단점이 없습니다.

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

Extensions that target a stable ABI must only use a limited subset of the C API. This subset is known as the Limited API; its contents are listed below.

Windows에서 안정 ABI를 사용하는 확장 모듈은 버전별 라이브러리(예: python39.dll) 대신 python3.dll 과 링크되어야 합니다. 이 라이브러리는 관련 심볼만 노출합니다.

On some platforms, Python will look for and load shared library files named with the abi3 or abi3t tag (for example, mymodule.abi3.so). Free-threaded interpreters only recognize the abi3t tag, while non-free-threaded ones will prefer abi3 but fall back to abi3t. Thus, extensions compatible with both ABIs should use the abi3t tag.

Python은 로드하는 확장 모듈이 호환되는 ABI를 갖는지 반드시 확인하지 않습니다. 확장 모듈 작성자는 Py_mod_abi 슬롯이나 PyABIInfo_Check() 함수를 사용하여 확인을 추가할 것을 권장하지만, 사용자(또는 패키징 도구)는 예를 들어 안정 ABI 3.10용으로 빌드된 확장 모듈이 이전 버전의 Python용으로 설치되지 않도록 보장하는 궁극적인 책임이 있습니다.

All functions in Stable ABI are present as functions in Python’s shared library, not solely as macros. This makes them usable in languages that don’t use the C preprocessor, including Python’s ctypes.

안정 ABI용으로 컴파일하기

참고

빌드 도구(예를 들어 meson-python, scikit-build-core, 또는 Setuptools)는 종종 매크로를 설정하고 이를 확장 파일 이름 및 기타 메타데이터와 동기화하는 메커니즘을 가지고 있습니다. 가능하다면, 이러한 메커니즘을 사용하는 것을 선호하며, 매크로를 수동으로 정의하는 것은 피하십시오.

이 섹션의 나머지 부분은 주로 도구 작성자를 위한 것이며, 확장 모듈을 수동으로 컴파일하는 사람들에게 관련이 있습니다.

더 보기

list of recommended tools in the Python Packaging User Guide

Stable ABI로 컴파일하려면, 확장 모듈이 지원해야 하는 가장 낮은 파이썬 버전에 맞춰 다음 매크로 중 하나 또는 모두를 Py_PACK_VERSION 형식으로 정의하십시오. 일반적으로는 컴파일하는 파이썬 헤더 버전보다는 특정 값을 선택하는 것이 좋습니다.

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

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만 노출합니다. 즉, Limited 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를 지정합니다. 이름 지정 방식이 다른 것은 하위 호환성 때문입니다.

역사적 참고 사항

3``으로도 ``Py_LIMITED_API``를 정의할 수 있습니다. 이것은 ``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`를 모두 정의하거나,

  • define only Py_LIMITED_API and:

    • on Windows, define Py_GIL_DISABLED;

    • 다른 시스템에서는 파이썬의 자유 스레딩 빌드 헤더를 사용하십시오.

Stable ABI 범위 및 성능

Stable ABI의 목표는 전체 C API로 가능한 모든 것을 허용하는 것이지만, 성능 저하가 있을 수 있습니다. 일반적으로 Stable ABI와의 호환성은 확장 모듈의 소스 코드 일부 변경을 요구합니다.

For example, while PyList_GetItem() is available, its “unsafe” macro variant PyList_GET_ITEM() is not. The macro can be faster because it can rely on version-specific implementation details of the list object.

또 다른 예로, Stable ABI용으로 컴파일할 때가 아닌 경우, 일부 C API 함수는 인라인되거나 매크로로 대체됩니다. Stable ABI용으로 컴파일하면 이러한 인라인 기능이 비활성화되어 안정성을 확보할 수 있지만, 성능이 저하될 수 있습니다.

Py_LIMITED_API 또는 Py_TARGET_ABI3T 정의를 생략하면, 특정 ABI용으로 Stable-ABI 호환 소스를 컴파일하는 것이 가능합니다. 그런 다음 성능이 빠를 수 있는 버전별 확장 기능을 Stable ABI용으로 컴파일된 버전과 함께 배포할 수 있습니다. (더 느리지만 더 호환성이 높은 대체 방안입니다.)

Stable ABI 주의사항

Stable ABI용으로 컴파일하는 것이 코드가 예상되는 파이썬 버전과 호환되리라는 완전한 보증은 아님에 유의하십시오. Stable ABI는 ABI 문제(누락된 심볼로 인한 링크 오류 또는 구조 레이아웃 또는 함수 시그니처 변경으로 인한 데이터 손상 등)를 방지합니다. 그러나 다른 파이썬 변경 사항은 확장 모듈의 동작 방식 을 변경할 수 있습니다.

Py_TARGET_ABI3T 및 Py_LIMITED_API 매크로가 막지 못하는 하나의 문제는, 더 낮은 파이썬 버전에서 무효한 인수를 사용하여 함수를 호출하는 것입니다. 예를 들어, 인수로 NULL``을 받기 시작하는 함수를 고려해 보세요. 파이썬 3.9에서는 ``NULL``이 이제 기본 동작을 선택하지만, 파이썬 3.8에서는 인수가 직접 사용되어 ``NULL 역참조 및 충돌을 일으킵니다. 유사한 인수는 구조체 필드에도 적용됩니다.

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

또한, 사용된 모든 API 문서를 검토하여 제한된 API의 일부인지 명시적으로 확인하는 것을 권장합니다. Py_LIMITED_API 를 정의했음에도 불구하고, 몇 가지 비공개 선언이 기술적인 이유로(또는 심지어 버그로 인해 의도치 않게) 노출됩니다.

또한, Py_LIMITED_API 로 3.8을 컴파일하는 것이 확장이 파이썬 3.12에서 로딩 되어야 함을 의미하고, 파이썬 3.12로 컴파일 되어야 함을 의미하지만, 동일한 소스 코드가 Py_LIMITED_API 가 3.12로 설정되었을 때 반드시 컴파일되는 것은 아니라는 점에 유의하십시오. 일반적으로, Stable ABI가 안정성을 유지하는 한, 제한된 API의 일부는 사용 중단되거나 제거될 수 있습니다.

플랫폼 고려 사항

ABI stability depends not only on Python, but also on the compiler used, lower-level libraries and compiler options. For the purposes of the Stable ABIs, these details define a “platform”. They usually depend on the OS type and processor architecture

각 특정 배포자의 파이썬이 특정 플랫폼의 모든 파이썬 버전을 Stable ABIs나 버전별 ABI를 깨뜨리지 않는 방식으로 빌드하는 것은 그 책임입니다. 이는 python.org 및 많은 제삼자 배포자의 Windows 및 macOS 릴리스에 해당합니다.

ABI 확인

Added in version 3.15.

파이썬은 ABI 호환성에 대한 기본적인 확인을 포함하고 있습니다.

This check is not comprehensive. It only guards against common cases of incompatible modules being installed for the wrong interpreter. It also does not take platform incompatibilities into account. It can only be done after an extension is successfully loaded.

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

대부분의 모듈은 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을 반환합니다.

If the ABI is incompatible, the raised exception will be 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

The major version of PyABIInfo. Can be set to:

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

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

uint8_t abiinfo_minor_version

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

uint16_t flags

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

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

Default flags, based on current values of macros such as Py_LIMITED_API and Py_GIL_DISABLED.

대안으로, 이 필드는 비트별 OR로 결합된 다음 플래그로 설정될 수 있습니다. 사용되지 않은 비트는 0으로 설정해야 합니다.

ABI 변형 – 다음 중 하나:

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

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

PyABIInfo_INTERNAL

특정 CPython 빌드에 종속된 ABI를 지정합니다. 내부 사용 전용입니다.

Free-스레딩 호환성 – 다음 중 하나:

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

CPython의 free-threaded builds 와 호환되는 ABI를 지정합니다. (즉, --disable-gil 로 컴파일된 것들, sys.abiflags 에 t 가 있는 경우)

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

CPython의 비-free-threaded 빌드와 호환되는 ABI를 지정합니다 ( --disable-gil 없이 컴파일된 것들).

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

CPython의 free-threaded 빌드와 비-free-threaded 빌드 모두와 호환되는 ABI를 지정합니다. 즉, abi3``와 ``abi3t 모두입니다.

uint32_t build_version

The version of the Python headers used to build the code, in the format used by 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) 를 사용하십시오.)

Otherwise, it should be set to PY_VERSION_HEX.

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

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

The value that should be used for this field, based on current values of macros such as Py_LIMITED_API, PY_VERSION_HEX and Py_GIL_DISABLED.

Added in version 3.15.

제한된 API 내용

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

분실물 보관소