Estabilidad de la API en C

La API en C de Python está cubierta por la política de compatibilidad con versiones anteriores, PEP 387. Si bien la API en C cambiará con cada versión menor (por ejemplo de 3.9 a 3.10), la mayoría de los cambios serán compatibles con la fuente, típicamente sólo agregando una nueva API. El cambio de la API existente o la eliminación de la API sólo se realiza después de un período obsoleto o para arreglar problemas graves.

La interfaz binaria de aplicación (ABI) de CPython es compatible con versiones posteriores y anteriores tras una versión menor (si se compilan de la misma forma; ver Consideraciones de la plataforma a continuación). Por lo tanto, el código que se compila para Python 3.10.0 funcionará en la 3.10.8 y viceversa, pero tendrá que compilarse por separado para 3.9.x y 3.10.x.

Los nombres con el prefijo de un guión bajo, como _Py_InternalState, son API privadas que pueden cambiar incluso sin notificar en lanzamientos de parches.

Interfaz binaria de aplicación estable

En Python 3.2 se introdujo la API limitada, un subconjunto de la API en C de Python. Las extensiones que sólo usan la API limitada pueden compilarse una vez y funcionan con múltiples versiones de Python. El contenido de la API limitada es enumerado a continuación.

Para habilitar esto, Python proporciona una ABI estable: un conjunto de símbolos que permanecerá compatible en todas las versiones de Python 3.x. La ABI estable contiene símbolos expuestos en la API limitada, pero también otros - por ejemplo, funciones necesarias para soportar versiones anteriores de la API limitada.

(Para simplificar, este documento trata acerca de extensiones, pero la API limitada y la ABI estable funcionan de la misma forma para todos los usos de la API - por ejemplo, incrustar Python.)

Py_LIMITED_API

Se define esta macro antes de incluir Python.h para optar por usar sólo la API limitada y para seleccionar la versión de la API limitada.

Se define Py_LIMITED_API con el valor de PY_VERSION_HEX correspondiente a la versión más baja de Python que soporte su extensión. La extensión funcionará sin volver a compilarse con todas las versiones de Python 3 desde la especificada en adelante, y se puede usar la API limitada que se introdujo hasta esa versión.

En lugar de utilizar directamente la macro PY_VERSION_HEX, se codifica una versión menor mínima (por ejemplo, 0x030A0000 para Python 3.10) para tener estabilidad cuando se compila con futuras versiones de Python.

También se puede definir Py_LIMITED_API con 3. Esto funciona igual que 0x03020000 (Python 3.2, la función que introdujo la API limitada).

En Windows, las extensiones que usan la ABI estable deben estar vinculadas con python3.dll en lugar de una biblioteca específica de la versión como python39.dll.

En algunas plataformas, Python buscará y cargará archivos de bibliotecas compartidas con el nombre de la etiqueta abi3 (por ejemplo, mymodule.abi3.so). No comprueba si tales extensiones se ajustan a una ABI estable. El usuario (o sus herramientas de empaquetado) necesitan asegurarse que, por ejemplo, las extensiones que se crean con la API limitada 3.10+ no estén instaladas para versiones inferiores de Python.

Todas las funciones de la ABI estable se presentan como funciones en la biblioteca compartida de Python, no sólo como macros. Esto las hace utilizables desde lenguajes que no usan el preprocesador de C.

Alcance y rendimiento de la API limitada

El objetivo de la API limitada es permitir todo lo que es posible con la API completa en C, pero posiblemente con una penalización de rendimiento.

Por ejemplo, mientras PyList_GetItem() está disponible, su variante macro “insegura” PyList_GET_ITEM() no lo está. La macro puede ser más rápida porque puede confiar en los detalles de implementación específicos de la versión del objeto de lista.

Sin definirse Py_LIMITED_API, algunas funciones de la API en C están integradas o reemplazadas por macros. Definir Py_LIMITED_API desactiva esta integración, permitiendo estabilidad mientras que se mejoren las estructuras de datos de Python, pero posiblemente reduzca el rendimiento.

Al dejar fuera la definición de Py_LIMITED_API, es posible compilar una extensión de la API limitada con una ABI específica de la versión. Esto puede mejorar el rendimiento para esa versión de Python, pero limitará la compatibilidad. Compilar con Py_LIMITED_API producirá una extensión que se puede distribuir donde una versión específica no esté disponible - por ejemplo, para los prelanzamientos de una versión próxima de Python.

Advertencias de la API limitada

Tome en cuenta que compilar con Py_LIMITED_API no es una garantía completa de que el código se ajuste a la API limitada o a la ABI estable. Py_LIMITED_API sólo cubre definiciones, pero también una API incluye otros problemas, como la semántica esperada.

Un problema contra el que Py_LIMITED_API no protege es llamar una función con argumentos que son inválidos en una versión inferior de Python. Por ejemplo, se considera una función que empieza a aceptar NULL como un argumento. Ahora en Python 3.9, NULL selecciona un comportamiento predeterminado, pero en Python 3.8, el argumento se usará directamente, causando una desreferencia NULL y se detendrá. Un argumento similar funciona para campos de estructuras.

Otro problema es que algunos campos de estructura no se ocultan actualmente cuando se define Py_LIMITED_API, aunque son parte de la API limitada.

Por estas razones, recomendamos probar una extensión con todas las versiones menores de Python que soporte, y preferiblemente compilar con la versión más baja.

También recomendamos revisar la documentación de todas las API usadas para verificar si es parte explícitamente de la API limitada. Aunque se defina Py_LIMITED_API, algunas declaraciones privadas se exponen por razones técnicas (o incluso involuntariamente, como errores).

También tome en cuenta que la API limitada no necesariamente es estable: compilar con Py_LIMITED_API con Python 3.8 significa que la extensión se ejecutará con Python 3.12, pero no necesariamente compilará con Python 3.12. En particular, las partes de la API limitada se pueden quedar obsoletas y eliminarse, siempre que la ABI estable permanezca estable.

Consideraciones de la plataforma

La estabilidad de la ABI depende no sólo de Python, sino también del compilador que se usa, las bibliotecas de nivel inferior y las opciones del compilador. Para los fines de la ABI estable, estos detalles definen una “plataforma”. Generalmente dependen del tipo del sistema operativo y de la arquitectura del procesador

Es la responsabilidad de cada distribuidor particular de Python de asegurarse de que todas las versiones de Python en una plataforma particular se compilen de una forma que no rompa la ABI estable. Este es el caso de las versiones de Windows y macOS de python.org y muchos distribuidores de terceros.

Contenido de la API limitada

Actualmente, la API limitada incluye los siguientes elementos: