Документация Python неофициальный перевод
Содержание страницы

Стабильность C API и ABIC API and ABI Stability

Если не указано иное, C API Python подпадает под политику обратной совместимости PEP 387. Большинство изменений в нём совместимы на уровне исходного кода (как правило, только за счёт добавления нового API). Изменение существующего API или его удаление производится только после периода устаревания или для исправления серьёзных проблем.

Двоичный интерфейс приложений (ABI) CPython совместим вперёд и назад в пределах одного минорного выпуска (при условии одинаковой компиляции; см. Особенности платформ ниже). Таким образом, код, скомпилированный для 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, являются закрытым API, который может изменяться без уведомления даже в патч-релизах. Если вам необходимо использовать этот API, рассмотрите возможность обращения к разработчикам CPython для обсуждения добавления публичного API для вашего сценария использования.

Нестабильный C APIUnstable C API

Любой API, имя которого начинается с префикса PyUnstable, раскрывает детали реализации CPython и может меняться в каждом минорном выпуске (например, с 3.9 до 3.10) без каких-либо предупреждений об устаревании. Однако он не будет меняться в исправляющем выпуске (например, с 3.10.0 до 3.10.1).

Он в основном предназначен для специализированных низкоуровневых инструментов, таких как отладчики.

Ожидается, что проекты, использующие этот API, будут следить за разработкой CPython и прилагать дополнительные усилия для адаптации к изменениям.

Стабильные двоичные интерфейсы приложенийStable Application Binary Interfaces

Стабильный ABI Python позволяет расширениям быть совместимыми с несколькими версиями Python без перекомпиляции.

Примечание

Для простоты в этом документе говорится о расширениях, но Stable ABI работает одинаково для всех случаев использования API – например, для встраивания Python.

Существует два стабильных ABI:

  • abi3, представленный в Python 3.2, совместим с не-свободно-поточными сборками CPython.

  • abi3t, представленный в Python 3.15, совместим с свободно-поточными сборками CPython. Он имеет более строгие ограничения API, чем abi3.

    Добавлено в версии 3.15: abi3t был добавлен в PEP 803

Расширение может быть скомпилировано одновременно как для обоих abi3, так и для abi3t; результат будет совместим как со свободно-поточными, так и с не-свободно-поточными сборками Python. В настоящее время это не имеет недостатков по сравнению с компиляцией только для abi3t.

Каждый стабильный ABI версионируется с использованием первых двух чисел версии Python. Например, Stable ABI 3.14 соответствует Python 3.14. Расширение, скомпилированное для Stable ABI 3.x, совместимо по ABI с Python 3.x и выше.

Расширения, нацеленные на стабильный ABI, должны использовать только ограниченное подмножество C API. Это подмножество известно как Ограниченный API; его содержимое перечислено ниже.

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

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

Python не обязательно проверяет, что загружаемые им расширения имеют совместимый ABI. Авторам расширений рекомендуется добавить проверку с помощью слота Py_mod_abi или функции PyABIInfo_Check(), но конечный пользователь (или его инструмент сборки пакетов) несёт ответственность за то, чтобы, например, расширения, собранные для Stable ABI 3.10, не были установлены для более низких версий Python.

Все функции в Stable ABI присутствуют как функции в разделяемой библиотеке Python, а не только как макросы. Это делает их доступными в языках, которые не используют препроцессор C, включая ctypes Python.

Компиляция для стабильного ABICompiling for Stable ABI

Примечание

Инструменты сборки (такие как, например, meson-python, scikit-build-core или Setuptools) часто имеют механизм для установки макросов и их синхронизации с именами файлов расширений и другими метаданными. Если такой механизм существует, предпочтительнее использовать его, а не определять макросы вручную.

Оставшаяся часть раздела в основном предназначена для разработчиков инструментов и тех, кто компилирует расширения вручную.

См. также

список рекомендуемых инструментов в Python Packaging User Guide

Чтобы скомпилировать для Stable ABI, определите один или оба следующих макроса, указав самую старую версию Python, которую должно поддерживать ваше расширение, в формате Py_PACK_VERSION. Обычно выбирают конкретное значение, а не версию заголовочных файлов Python, с которыми выполняется компиляция.

Макросы должны быть определены до включения Python.h. Поскольку Py_PACK_VERSION на этом этапе недоступен, необходимо напрямую использовать числовое значение. Для справки приведены значения для нескольких последних версий Python:

0x30a0000  /* Py_PACK_VERSION(3,10) */
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) */

Когда определён один из макросов, Python.h будет предоставлять только API, совместимый с заданным Stable ABI – то есть Limited API плюс некоторые определения, которые должны быть видны компилятору, но не должны использоваться напрямую. Когда определены оба, Python.h будет предоставлять API, совместимый с обоими Stable ABI.

Py_LIMITED_API

Целевой abi3, то есть сборки CPython без свободной многопоточности. Общие сведения см. в выше.

Py_TARGET_ABI3T

Целевой abi3t, то есть сборки CPython со свободной многопоточностью. Общие сведения см. в выше.

Добавлено в версии 3.15.

Оба макроса задают целевой ABI; разный стиль именования обусловлен обратной совместимостью.

Историческая справка

Можно также определить Py_LIMITED_API как 3. Это работает так же, как 0x03020000 (Python 3.2 – версия, в которой появился Stable ABI).

Когда определены оба, Python.h может переопределить Py_LIMITED_API в соответствии с Py_TARGET_ABI3T, а может и не переопределить.

В сборке со свободной многопоточностью – то есть когда определён Py_GIL_DISABLED – Py_TARGET_ABI3T по умолчанию принимает значение Py_LIMITED_API. Это означает, что есть два способа сборки для обоих abi3 и abi3t:

  • определить оба Py_LIMITED_API и Py_TARGET_ABI3T, или

  • определить только Py_LIMITED_API и:

    • в Windows определить Py_GIL_DISABLED;

    • в других системах использовать заголовочные файлы сборки Python со свободной многопоточностью.

Область применения Stable ABI и производительностьStable ABI Scope and Performance

Цель Stable ABI – разрешить всё, что возможно с полным C API, но, возможно, с потерей производительности. В целом совместимость со Stable ABI потребует некоторых изменений в исходном коде расширения.

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

Другой пример: при компиляции не для Stable ABI некоторые функции C API встраиваются или заменяются макросами. Компиляция для Stable ABI отключает такое встраивание, обеспечивая стабильность по мере улучшения структур данных Python, но возможно снижая производительность.

Если не определять Py_LIMITED_API или Py_TARGET_ABI3T, можно скомпилировать совместимый со Stable ABI исходный код для версионного ABI. Тогда можно распространять потенциально более быстрое версионное расширение вместе с версией, скомпилированной для Stable ABI – более медленным, но более совместимым запасным вариантом.

Предостережения о Stable ABIStable ABI Caveats

Обратите внимание: компиляция для Stable ABI не является полной гарантией совместимости кода с ожидаемыми версиями Python. Stable ABI предотвращает проблемы с ABI, такие как ошибки компоновки из-за отсутствия символов или повреждение данных из-за изменений в структуре или сигнатурах функций. Однако другие изменения в Python могут изменить поведение расширений.

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

По этим причинам мы рекомендуем тестировать расширение со всеми поддерживаемыми минорными версиями Python.

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

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

Особенности платформPlatform Considerations

Стабильность ABI зависит не только от Python, но и от используемого компилятора, низкоуровневых библиотек и параметров компиляции. Для целей стабильных ABI эти детали определяют «платформу». Обычно они зависят от типа ОС и архитектуры процессора.

Ответственность каждого конкретного распространителя Python – обеспечить, чтобы все версии Python на определённой платформе были собраны таким образом, чтобы не нарушать стабильные ABI или версионные ABI. Это справедливо для выпусков Windows и macOS от python.org и многих сторонних распространителей.

Проверка ABIABI Checking

Добавлено в версии 3.15.

Python включает элементарную проверку совместимости ABI.

Эта проверка не является всеобъемлющей. Она лишь защищает от распространённых случаев установки несовместимых модулей для неподходящего интерпретатора. Она также не учитывает несовместимости платформ. Она может быть выполнена только после успешной загрузки расширения.

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

Большинство модулей могут использовать эту проверку через слот 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)
Часть Stable ABI начиная с версии 3.15.

Проверяет, что переданный info совместим с текущим запущенным интерпретатором.

Возвращает 0 при успехе. В случае неудачи возбуждает исключение и возвращает -1.

Если ABI несовместим, возбуждённое исключение будет ImportError.

Аргумент module_name может быть NULL или указывать на NUL-терминированную строку в кодировке UTF-8, используемую для сообщений об ошибках.

Обратите внимание: если info описывает ABI, используемый текущим кодом (как определено PyABIInfo_VAR, например), использование любого другого API Python C может привести к крахам. В частности, небезопасно исследовать возбуждённое исключение.

Добавлено в версии 3.15.

PyABIInfo_VAR(NAME)
Часть Stable ABI начиная с версии 3.15.

Определяет статическую переменную PyABIInfo с заданным NAME, которая описывает ABI, который будет использоваться текущим кодом. Этот макрос раскрывается в:

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

Добавлено в версии 3.15.

type PyABIInfo
Часть Stable ABI (включая все члены) начиная с версии 3.15.
uint8_t abiinfo_major_version

Главная версия PyABIInfo. Может быть установлена в:

  • 0 для пропуска всех проверок, или

  • 1 для указания этой версии PyABIInfo.

uint8_t abiinfo_minor_version

Минорная версия PyABIInfo. Должна быть установлена в 0; бо́льшие значения зарезервированы для обратно совместимых будущих версий PyABIInfo.

uint16_t flags

Это поле обычно устанавливается в следующий макрос:

PyABIInfo_DEFAULT_FLAGS
Часть Stable ABI начиная с версии 3.15.

Флаги по умолчанию, основанные на текущих значениях макросов, таких как Py_LIMITED_API и Py_GIL_DISABLED.

В качестве альтернативы поле может быть установлено в следующие флаги, объединённые поразрядным ИЛИ. Неиспользуемые биты должны быть установлены в ноль.

Вариант ABI – один из:

PyABIInfo_STABLE
Часть Stable ABI начиная с версии 3.15.

Указывает, что используется стабильный ABI.

PyABIInfo_INTERNAL

Указывает ABI, специфичный для конкретной сборки CPython. Только для внутреннего использования.

Совместимость со свободной многопоточностью – один из:

PyABIInfo_FREETHREADED
Часть Stable ABI начиная с версии 3.15.

Указывает ABI, совместимый с сборками со свободными потоками CPython. (То есть сборками, скомпилированными с --disable-gil; с t в sys.abiflags)

PyABIInfo_GIL
Часть Stable ABI начиная с версии 3.15.

Указывает ABI, совместимый со сборками CPython без свободных потоков (то есть сборками, скомпилированными без --disable-gil).

PyABIInfo_FREETHREADING_AGNOSTIC
Часть Stable ABI начиная с версии 3.15.

Указывает ABI, совместимый как со сборками со свободными потоками, так и со сборками без свободных потоков CPython, то есть как с abi3, так и с abi3t.

uint32_t build_version

Версия заголовочных файлов Python, использованных для сборки кода, в формате, используемом в PY_VERSION_HEX.

Это поле можно установить в 0, чтобы пропустить любые проверки, связанные с этим полем. Эта опция предназначена в основном для проектов, которые не используют заголовочные файлы CPython напрямую и не эмулируют какую-либо конкретную их версию.

uint32_t abi_version

Версия ABI.

Для Stable ABI это поле должно быть установлено в значение Py_LIMITED_API или Py_TARGET_ABI3T. Если оба определены, используйте меньшее значение. (Если Py_LIMITED_API равно 3; используйте Py_PACK_VERSION(3, 2) вместо 3.)

В противном случае, его следует установить в PY_VERSION_HEX.

Его также можно установить в 0, чтобы пропустить любые проверки, связанные с этим полем.

PyABIInfo_DEFAULT_ABI_VERSION
Часть Stable ABI начиная с версии 3.15.

Значение, которое следует использовать для этого поля, на основе текущих значений макросов, таких как Py_LIMITED_API, PY_VERSION_HEX и Py_GIL_DISABLED.

Добавлено в версии 3.15.

Содержание Limited APIContents of Limited API

Это окончательный список Limited API для Python 3.15: