Стабильность C API

Ограниченный C API

В Python 3.2 был представлен Ограниченный API — подмножество C API Python. Расширения, использующие только Ограниченный API, можно скомпилировать один раз и загружать в нескольких версиях Python. Состав Ограниченного API перечислен ниже.

Py_LIMITED_API

Определите этот макрос перед подключением Python.h, чтобы использовать только Ограниченный API и выбрать его версию.

Задайте для Py_LIMITED_API значение PY_VERSION_HEX, соответствующее самой ранней версии Python, которую поддерживает ваше расширение. Расширение будет совместимо на уровне ABI со всеми выпусками Python 3, начиная с указанного, и сможет использовать Ограниченный API, представленный вплоть до этой версии.

Вместо непосредственного использования макроса PY_VERSION_HEX укажите минимальную версию с определённым младшим номером (например, 0x030A0000 для Python 3.10), чтобы обеспечить стабильность при компиляции с будущими версиями Python.

Также можно определить Py_LIMITED_API как 3. Это работает так же, как 0x03020000 (Python 3.2 — версия, в которой был представлен Ограниченный API).

Стабильный ABI

Для этого Python предоставляет Стабильный ABI: набор символов, которые будут сохранять совместимость ABI во всех версиях Python 3.x.

Стабильный ABI содержит символы, предоставляемые в Ограниченном API, а также другие символы — например, функции, необходимые для поддержки более старых версий Ограниченного API.

В Windows расширения, использующие Стабильный ABI, следует компоновать с python3.dll, а не с библиотекой для конкретной версии, такой как python39.dll.

На некоторых платформах Python ищет и загружает файлы общих библиотек с тегом abi3 в имени (например, mymodule.abi3.so). Python не проверяет, соответствуют ли такие расширения Стабильному ABI. Пользователь (или его инструменты упаковки) должен убедиться, что, например, расширения, собранные с Ограниченным API 3.10+, не устанавливаются для более старых версий Python.

Все функции Стабильного ABI присутствуют в общей библиотеке Python именно как функции, а не только как макросы. Благодаря этому их можно использовать из языков, в которых не применяется препроцессор C.

Область применения и производительность Ограниченного API

Цель Ограниченного API — предоставить всё, что возможно с полным C API, хотя, возможно, и с потерей производительности.

Например, PyList_GetItem() доступна, а её «небезопасный» вариант в виде макроса PyList_GET_ITEM() — нет. Макрос может работать быстрее, поскольку использует специфичные для версии детали реализации объекта списка.

Если Py_LIMITED_API не определён, некоторые функции C API встраиваются в код или заменяются макросами. Определение Py_LIMITED_API отключает такое встраивание, обеспечивая стабильность по мере улучшения структур данных Python, но может снизить производительность.

Если не определять Py_LIMITED_API, можно скомпилировать расширение для Ограниченного API с ABI, специфичным для конкретной версии. Это может повысить производительность для этой версии Python, но ограничит совместимость. В таком случае компиляция с Py_LIMITED_API позволит получить расширение, которое можно распространять там, где расширение для конкретной версии недоступно, — например, для предварительных выпусков будущей версии Python.

Ограничения Ограниченного API

Обратите внимание, что компиляция с Py_LIMITED_API не гарантирует полностью, что код соответствует Ограниченному API или Стабильному ABI. Py_LIMITED_API охватывает только определения, но API включает и другие аспекты, например ожидаемую семантику.

Одна из проблем, от которых Py_LIMITED_API не защищает, — вызов функции с аргументами, недопустимыми в более старой версии Python. Например, рассмотрим функцию, которая начинает принимать NULL в качестве аргумента. В Python 3.9 NULL теперь выбирает поведение по умолчанию, но в Python 3.8 аргумент будет использоваться напрямую, что приведёт к разыменованию NULL и аварийному завершению. Аналогичная ситуация возможна с полями структур.

Ещё одна проблема заключается в том, что некоторые поля структур в настоящее время не скрываются при определённом Py_LIMITED_API, несмотря на то что они входят в Ограниченный API.

По этим причинам мы рекомендуем тестировать расширение во всех поддерживаемых им выпусках Python с разным младшим номером версии и, по возможности, собирать его с использованием самой ранней из этих версий.

Мы также рекомендуем изучить документацию по всему используемому API и проверить, входит ли он явно в Ограниченный API. Даже при определённом Py_LIMITED_API по техническим причинам (или даже непреднамеренно, из-за ошибок) могут предоставляться некоторые закрытые объявления.

Также обратите внимание, что Ограниченный API не обязательно стабилен: если скомпилировать с Py_LIMITED_API в Python 3.8, расширение будет работать в Python 3.12, но не обязательно будет компилироваться в Python 3.12. В частности, некоторые части Ограниченного API могут быть объявлены устаревшими и удалены при условии, что Стабильный ABI останется стабильным.