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

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

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

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

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

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

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

Ограниченный 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 предотвращает проблемы с ABI, такие как ошибки компоновщика из-за отсутствующих символов или повреждение данных вследствие изменения структуры структур или сигнатур функций. Однако другие изменения в Python могут повлиять на поведение расширений. Подробности см. в политике обратной совместимости Python (PEP 387).

Стабильный 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.

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

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

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

Состав Ограниченного API

В настоящее время Ограниченный API включает следующие элементы:

PY_VECTORCALL_ARGUMENTS_OFFSET
PyAIter_Check()
PyArg_Parse()
PyArg_ParseTuple()
PyArg_ParseTupleAndKeywords()
PyArg_UnpackTuple()
PyArg_VaParse()
PyArg_VaParseTupleAndKeywords()
PyArg_ValidateKeywordArguments()
PyBaseObject_Type
PyBool_FromLong()
PyBool_Type
PyBuffer_FillContiguousStrides()
PyBuffer_FillInfo()
PyBuffer_FromContiguous()
PyBuffer_GetPointer()
PyBuffer_IsContiguous()
PyBuffer_Release()
PyBuffer_SizeFromFormat()
PyBuffer_ToContiguous()
PyByteArrayIter_Type
PyByteArray_AsString()
PyByteArray_Concat()
PyByteArray_FromObject()
PyByteArray_FromStringAndSize()
PyByteArray_Resize()
PyByteArray_Size()
PyByteArray_Type
PyBytesIter_Type
PyBytes_AsString()
PyBytes_AsStringAndSize()
PyBytes_Concat()
PyBytes_ConcatAndDel()
PyBytes_DecodeEscape()
PyBytes_FromFormat()
PyBytes_FromFormatV()
PyBytes_FromObject()
PyBytes_FromString()
PyBytes_FromStringAndSize()
PyBytes_Repr()
PyBytes_Size()
PyBytes_Type
PyCFunction
PyCFunctionWithKeywords
PyCFunction_Call()
PyCFunction_GetFlags()
PyCFunction_GetFunction()
PyCFunction_GetSelf()
PyCFunction_New()
PyCFunction_NewEx()
PyCFunction_Type
PyCMethod_New()
PyCallIter_New()
PyCallIter_Type
PyCallable_Check()
PyCapsule_Destructor
PyCapsule_GetContext()
PyCapsule_GetDestructor()
PyCapsule_GetName()
PyCapsule_GetPointer()
PyCapsule_Import()
PyCapsule_IsValid()
PyCapsule_New()
PyCapsule_SetContext()
PyCapsule_SetDestructor()
PyCapsule_SetName()
PyCapsule_SetPointer()
PyCapsule_Type
PyClassMethodDescr_Type
PyCodec_BackslashReplaceErrors()
PyCodec_Decode()
PyCodec_Decoder()
PyCodec_Encode()
PyCodec_Encoder()
PyCodec_IgnoreErrors()
PyCodec_IncrementalDecoder()
PyCodec_IncrementalEncoder()
PyCodec_KnownEncoding()
PyCodec_LookupError()
PyCodec_NameReplaceErrors()
PyCodec_Register()
PyCodec_RegisterError()
PyCodec_ReplaceErrors()
PyCodec_StreamReader()
PyCodec_StreamWriter()
PyCodec_StrictErrors()
PyCodec_Unregister()
PyCodec_XMLCharRefReplaceErrors()
PyComplex_FromDoubles()
PyComplex_ImagAsDouble()
PyComplex_RealAsDouble()
PyComplex_Type
PyDescr_NewClassMethod()
PyDescr_NewGetSet()
PyDescr_NewMember()
PyDescr_NewMethod()
PyDictItems_Type
PyDictIterItem_Type
PyDictIterKey_Type
PyDictIterValue_Type
PyDictKeys_Type
PyDictProxy_New()
PyDictProxy_Type
PyDictRevIterItem_Type
PyDictRevIterKey_Type
PyDictRevIterValue_Type
PyDictValues_Type
PyDict_Clear()
PyDict_Contains()
PyDict_Copy()
PyDict_DelItem()
PyDict_DelItemString()
PyDict_GetItem()
PyDict_GetItemString()
PyDict_GetItemWithError()
PyDict_Items()
PyDict_Keys()
PyDict_Merge()
PyDict_MergeFromSeq2()
PyDict_New()
PyDict_Next()
PyDict_SetItem()
PyDict_SetItemString()
PyDict_Size()
PyDict_Type
PyDict_Update()
PyDict_Values()
PyEllipsis_Type
PyEnum_Type
PyErr_BadArgument()
PyErr_BadInternalCall()
PyErr_CheckSignals()
PyErr_Clear()
PyErr_Display()
PyErr_DisplayException()
PyErr_ExceptionMatches()
PyErr_Fetch()
PyErr_Format()
PyErr_FormatV()
PyErr_GetExcInfo()
PyErr_GetHandledException()
PyErr_GetRaisedException()
PyErr_GivenExceptionMatches()
PyErr_NewException()
PyErr_NewExceptionWithDoc()
PyErr_NoMemory()
PyErr_NormalizeException()
PyErr_Occurred()
PyErr_Print()
PyErr_PrintEx()
PyErr_ProgramText()
PyErr_ResourceWarning()
PyErr_Restore()
PyErr_SetExcFromWindowsErr()
PyErr_SetExcFromWindowsErrWithFilename()
PyErr_SetExcFromWindowsErrWithFilenameObject()
PyErr_SetExcFromWindowsErrWithFilenameObjects()
PyErr_SetExcInfo()
PyErr_SetFromErrno()
PyErr_SetFromErrnoWithFilename()
PyErr_SetFromErrnoWithFilenameObject()
PyErr_SetFromErrnoWithFilenameObjects()
PyErr_SetFromWindowsErr()
PyErr_SetFromWindowsErrWithFilename()
PyErr_SetHandledException()
PyErr_SetImportError()
PyErr_SetImportErrorSubclass()
PyErr_SetInterrupt()
PyErr_SetInterruptEx()
PyErr_SetNone()
PyErr_SetObject()
PyErr_SetRaisedException()
PyErr_SetString()
PyErr_SyntaxLocation()
PyErr_SyntaxLocationEx()
PyErr_WarnEx()
PyErr_WarnExplicit()
PyErr_WarnFormat()
PyErr_WriteUnraisable()
PyEval_AcquireLock()
PyEval_AcquireThread()
PyEval_CallFunction()
PyEval_CallMethod()
PyEval_CallObjectWithKeywords()
PyEval_EvalCode()
PyEval_EvalCodeEx()
PyEval_EvalFrame()
PyEval_EvalFrameEx()
PyEval_GetBuiltins()
PyEval_GetFrame()
PyEval_GetFuncDesc()
PyEval_GetFuncName()
PyEval_GetGlobals()
PyEval_GetLocals()
PyEval_InitThreads()
PyEval_ReleaseLock()
PyEval_ReleaseThread()
PyEval_RestoreThread()
PyEval_SaveThread()
PyEval_ThreadsInitialized()
PyExc_ArithmeticError
PyExc_AssertionError
PyExc_AttributeError
PyExc_BaseException
PyExc_BaseExceptionGroup
PyExc_BlockingIOError
PyExc_BrokenPipeError
PyExc_BufferError
PyExc_BytesWarning
PyExc_ChildProcessError
PyExc_ConnectionAbortedError
PyExc_ConnectionError
PyExc_ConnectionRefusedError
PyExc_ConnectionResetError
PyExc_DeprecationWarning
PyExc_EOFError
PyExc_EncodingWarning
PyExc_EnvironmentError
PyExc_Exception
PyExc_FileExistsError
PyExc_FileNotFoundError
PyExc_FloatingPointError
PyExc_FutureWarning
PyExc_GeneratorExit
PyExc_IOError
PyExc_ImportError
PyExc_ImportWarning
PyExc_IndentationError
PyExc_IndexError
PyExc_InterruptedError
PyExc_IsADirectoryError
PyExc_KeyError
PyExc_KeyboardInterrupt
PyExc_LookupError
PyExc_MemoryError
PyExc_ModuleNotFoundError
PyExc_NameError
PyExc_NotADirectoryError
PyExc_NotImplementedError
PyExc_OSError
PyExc_OverflowError
PyExc_PendingDeprecationWarning
PyExc_PermissionError
PyExc_ProcessLookupError
PyExc_RecursionError
PyExc_ReferenceError
PyExc_ResourceWarning
PyExc_RuntimeError
PyExc_RuntimeWarning
PyExc_StopAsyncIteration
PyExc_StopIteration
PyExc_SyntaxError
PyExc_SyntaxWarning
PyExc_SystemError
PyExc_SystemExit
PyExc_TabError
PyExc_TimeoutError
PyExc_TypeError
PyExc_UnboundLocalError
PyExc_UnicodeDecodeError
PyExc_UnicodeEncodeError
PyExc_UnicodeError
PyExc_UnicodeTranslateError
PyExc_UnicodeWarning
PyExc_UserWarning
PyExc_ValueError
PyExc_Warning
PyExc_WindowsError
PyExc_ZeroDivisionError
PyExceptionClass_Name()
PyException_GetArgs()
PyException_GetCause()
PyException_GetContext()
PyException_GetTraceback()
PyException_SetArgs()
PyException_SetCause()
PyException_SetContext()
PyException_SetTraceback()
PyFile_FromFd()
PyFile_GetLine()
PyFile_WriteObject()
PyFile_WriteString()
PyFilter_Type
PyFloat_AsDouble()
PyFloat_FromDouble()
PyFloat_FromString()
PyFloat_GetInfo()
PyFloat_GetMax()
PyFloat_GetMin()
PyFloat_Type
PyFrameObject
PyFrame_GetCode()
PyFrame_GetLineNumber()
PyFrozenSet_New()
PyFrozenSet_Type
PyGC_Collect()
PyGC_Disable()
PyGC_Enable()
PyGC_IsEnabled()
PyGILState_Ensure()
PyGILState_GetThisThreadState()
PyGILState_Release()
PyGILState_STATE
PyGetSetDef
PyGetSetDescr_Type
PyImport_AddModule()
PyImport_AddModuleObject()
PyImport_AppendInittab()
PyImport_ExecCodeModule()
PyImport_ExecCodeModuleEx()
PyImport_ExecCodeModuleObject()