Стабильность 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). Он не проверяет, соответствуют ли такие расширения Стабильному 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 останется стабильным.