The Python/C API

Versión 3.11.0

Guido van Rossum and the Python development team

noviembre 15, 2022

Python Software Foundation

Email: [email protected]
 Índice general

1 Introducción 3
1.1 Estándares de codificación . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Archivos de cabecera (Include) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Macros útiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Objetos, tipos y conteos de referencias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4.1 Conteo de Referencias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4.2 Tipos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5 Excepciones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.6 Integración de Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.7 Depuración de compilaciones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 Estabilidad de la API en C 15
2.1 Interfaz binaria de aplicación estable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.1 Alcance y rendimiento de la API limitada . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.2 Advertencias de la API limitada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2 Consideraciones de la plataforma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3 Contenido de la API limitada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3 La capa de muy alto nivel 41

4 Conteo de referencias 47

5 Manejo de excepciones 49
5.1 Impresión y limpieza . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.2 Lanzando excepciones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.3 Emitir advertencias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.4 Consultando el indicador de error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.5 Manejo de señal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.6 Clases de Excepción . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.7 Objetos Excepción . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.8 Objetos Unicode de Excepción . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.9 Control de Recursión . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.10 Excepciones Estándar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.11 Categorías de advertencia estándar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

6 Utilidades 63
6.1 Utilidades del sistema operativo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.2 Funciones del Sistema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.3 Control de procesos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.4 Importando Módulos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.5 Soporte de empaquetado (marshalling) de datos . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

i
 6.6 Analizando argumentos y construyendo valores . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.6.1 Analizando argumentos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.6.2 Construyendo valores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.7 Conversión y formato de cadenas de caracteres . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.8 Reflexión . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.9 Registro de códec y funciones de soporte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.9.1 API de búsqueda de códec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.9.2 API de registro para controladores de errores de codificación Unicode . . . . . . . . . . . 84

7 Capa de objetos abstractos 85

7.1 Protocolo de objeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
7.2 Protocolo de llamada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.2.1 El protocolo tp_call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.2.2 El protocolo vectorcall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.2.3 API para invocar objetos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.2.4 API de soporte de llamadas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.3 Protocolo de números . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.4 Protocolo de secuencia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.5 Protocolo de mapeo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.6 Protocolo iterador . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.7 Protocolo Búfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
7.7.1 Estructura de búfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.7.2 Tipos de solicitud búfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
7.7.3 Arreglos complejos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
7.7.4 Funciones relacionadas a búfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.8 Protocolo de búfer antiguo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

8 Capa de objetos concretos 111

8.1 Objetos fundamentales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
8.1.1 Objetos Tipos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
8.1.2 El objeto None . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
8.2 Objetos numéricos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
8.2.1 Objetos Enteros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
8.2.2 Objetos Booleanos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
8.2.3 Objetos de punto flotante . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
8.2.4 Pack functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
8.2.5 Unpack functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
8.2.6 Objetos de números complejos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
8.3 Objetos de secuencia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
8.3.1 Objetos Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
8.3.2 Objetos de arreglos de bytes (bytearrays) . . . . . . . . . . . . . . . . . . . . . . . . . . 124
8.3.3 Objetos y códecs Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
8.3.4 Objetos Tuplas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
8.3.5 Objetos de secuencia de estructura . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
8.3.6 Objetos lista . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
8.4 Objetos contenedor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
8.4.1 Objetos Diccionarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
8.4.2 Objetos Conjunto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
8.5 Objetos de función . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
8.5.1 Objetos función . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
8.5.2 Objetos de método de instancia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
8.5.3 Objetos método . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
8.5.4 Objetos Celda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
8.5.5 Objetos Código . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
8.6 Otros objetos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
8.6.1 Objetos archivo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
8.6.2 Objetos Modulo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.6.3 Objetos iteradores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

ii
 8.6.4 Objetos descriptores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
8.6.5 Objeto rebanada (slice) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.6.6 Objeto Elipsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
8.6.7 Objetos de vista de memoria (MemoryView) . . . . . . . . . . . . . . . . . . . . . . . . 167
8.6.8 Objetos de referencia débil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
8.6.9 Cápsulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
8.6.10 Objetos Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
8.6.11 Objetos Generadores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
8.6.12 Objetos corrutina . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.6.13 Objetos de variables de contexto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.6.14 Objetos DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
8.6.15 Objetos para indicaciones de tipado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

9 Inicialización, Finalización e Hilos 179

9.1 Antes de la inicialización de Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
9.2 Variables de configuración global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
9.3 Inicializando y finalizando el intérprete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
9.4 Parámetros de todo el proceso . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
9.5 Estado del hilo y el bloqueo global del intérprete . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
9.5.1 Liberando el GIL del código de extensión . . . . . . . . . . . . . . . . . . . . . . . . . . 188
9.5.2 Hilos creados sin Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
9.5.3 Precauciones sobre fork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.5.4 API de alto nivel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.5.5 API de bajo nivel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
9.6 Soporte de subinterprete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
9.6.1 Errores y advertencias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
9.7 Notificaciones asincrónicas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
9.8 Perfilado y Rastreo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
9.9 Soporte avanzado del depurador . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
9.10 Soporte de almacenamiento local de hilo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
9.10.1 API de almacenamiento específico de hilo (TSS, Thread Specific Storage) . . . . . . . . . 199
9.10.2 API de almacenamiento local de hilos (TLS, Thread Local Storage) . . . . . . . . . . . . 200

10 Configuración de inicialización de Python 203

10.1 Ejemplo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
10.2 PyWideStringList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
10.3 PyStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
10.4 PyPreConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
10.5 Preinicialización de Python con PyPreConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
10.6 PyConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
10.7 Inicialización con PyConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
10.8 Configuración aislada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
10.9 Configuración de Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
10.10 Configuración de la ruta de Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
10.11 Py_RunMain() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
10.12 Py_GetArgcArgv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
10.13 API Provisional Privada de Inicialización Multifásica . . . . . . . . . . . . . . . . . . . . . . . . 223

11 Gestión de la memoria 225

11.1 Visión general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
11.2 Dominios del asignador . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
11.3 Interfaz de memoria sin procesar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
11.4 Interfaz de memoria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
11.5 Asignadores de objetos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
11.6 Asignadores de memoria predeterminados . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
11.7 Personalizar asignadores de memoria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
11.8 Configurar enlaces para detectar errores en las funciones del asignador de memoria de Python . . . 232
11.9 El asignador pymalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
11.9.1 Personalizar asignador de arena de pymalloc . . . . . . . . . . . . . . . . . . . . . . . . 233

iii
 11.10 tracemalloc C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
11.11 Ejemplos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

12 Soporte de implementación de objetos 237

12.1 Asignación de objetos en el montículo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
12.2 Estructuras de objetos comunes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
12.2.1 Tipos objeto base y macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
12.2.2 Implementando funciones y métodos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
12.2.3 Acceder a atributos de tipos de extensión . . . . . . . . . . . . . . . . . . . . . . . . . . 242
12.3 Objetos Tipo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
12.3.1 Referencia rápida . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
12.3.2 Definición de PyTypeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
12.3.3 Ranuras (Slots) PyObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
12.3.4 Ranuras PyVarObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
12.3.5 Ranuras PyTypeObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
12.3.6 Tipos estáticos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
12.3.7 Tipos Heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
12.4 Estructuras de Objetos de Números . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
12.5 Estructuras de Objetos Mapeo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
12.6 Estructuras de objetos secuencia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
12.7 Estructuras de Objetos Búfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
12.8 Estructuras de objetos asíncronos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
12.9 Tipo Ranura typedefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
12.10 Ejemplos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
12.11 Apoyo a la recolección de basura cíclica . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
12.11.1 Controlar el estado del recolector de basura . . . . . . . . . . . . . . . . . . . . . . . . . 281

13 Versiones de API y ABI 283

A Glosario 285

B Acerca de estos documentos 299

B.1 Contribuidores de la documentación de Python . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

C Historia y Licencia 301

C.1 Historia del software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
C.2 Términos y condiciones para acceder o usar Python . . . . . . . . . . . . . . . . . . . . . . . . . 302
C.2.1 ACUERDO DE LICENCIA DE PSF PARA PYTHON | lanzamiento | . . . . . . . . . . 302
C.2.2 ACUERDO DE LICENCIA DE BEOPEN.COM PARA PYTHON 2.0 . . . . . . . . . . 303
C.2.3 ACUERDO DE LICENCIA CNRI PARA PYTHON 1.6.1 . . . . . . . . . . . . . . . . 304
C.2.4 ACUERDO DE LICENCIA CWI PARA PYTHON 0.9.0 HASTA 1.2 . . . . . . . . . . 305
C.2.5 LICENCIA BSD DE CLÁUSULA CERO PARA CÓDIGO EN EL PYTHON | lanza-
miento | DOCUMENTACIÓN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
C.3 Licencias y reconocimientos para software incorporado . . . . . . . . . . . . . . . . . . . . . . . 306
C.3.1 Mersenne Twister . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
C.3.2 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
C.3.3 Servicios de socket asincrónicos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
C.3.4 Gestión de cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
C.3.5 Seguimiento de ejecución . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
C.3.6 funciones UUencode y UUdecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
C.3.7 Llamadas a procedimientos remotos XML . . . . . . . . . . . . . . . . . . . . . . . . . 309
C.3.8 test_epoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
C.3.9 Seleccionar kqueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
C.3.10 SipHash24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
C.3.11 strtod y dtoa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
C.3.12 OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
C.3.13 expat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
C.3.14 libffi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
C.3.15 zlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

iv
 C.3.16 cfuhash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
C.3.17 libmpdec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
C.3.18 Conjunto de pruebas W3C C14N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
C.3.19 Audioop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

D Derechos de autor 319

Índice 321

v
vi
 The Python/C API, Versión 3.11.0

Este manual documenta la API utilizada por los programadores de C y C ++ que desean escribir módulos de extensión
o incorporar Python. Es un complemento de extending-index, que describe los principios generales de la escritura de
extensión pero no documenta las funciones API en detalle.

Índice general 1
The Python/C API, Versión 3.11.0

2 Índice general
 CAPÍTULO 1

Introducción

La interfaz del programador de aplicaciones (API) con Python brinda a los programadores de C y C++ acceso al
intérprete de Python en una variedad de niveles. La API es igualmente utilizable desde C++, pero por brevedad
generalmente se conoce como la API Python/C. Hay dos razones fundamentalmente diferentes para usar la API
Python/C. La primera razón es escribir módulos de extensión para propósitos específicos; Estos son módulos C que
extienden el intérprete de Python. Este es probablemente el uso más común. La segunda razón es usar Python co-
mo componente en una aplicación más grande; Esta técnica se conoce generalmente como integración (embedding)
Python en una aplicación.
Escribir un módulo de extensión es un proceso relativamente bien entendido, donde un enfoque de «libro de cocina»
(cookbook) funciona bien. Hay varias herramientas que automatizan el proceso hasta cierto punto. Si bien las personas
han integrado Python en otras aplicaciones desde su existencia temprana, el proceso de integrar Python es menos
sencillo que escribir una extensión.
Muchas funciones API son útiles independientemente de si está integrando o extendiendo Python; Además, la mayoría
de las aplicaciones que integran Python también necesitarán proporcionar una extensión personalizada, por lo que
probablemente sea una buena idea familiarizarse con la escritura de una extensión antes de intentar integrar Python
en una aplicación real.

1.1 Estándares de codificación

Si está escribiendo código C para su inclusión en CPython, debe seguir las pautas y estándares definidos en PEP
7. Estas pautas se aplican independientemente de la versión de Python a la que esté contribuyendo. Seguir estas
convenciones no es necesario para sus propios módulos de extensión de terceros, a menos que eventualmente espere
contribuir con ellos a Python.

3
The Python/C API, Versión 3.11.0

1.2 Archivos de cabecera (Include)

Todas las definiciones de función, tipo y macro necesarias para usar la API Python/C se incluyen en su código
mediante la siguiente línea:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

Esto implica la inclusión de los siguientes archivos de encabezado estándar: <stdio.h>, <string.h>, <errno.
h>, <limits.h>, <assert.h> y <stdlib.h> (si está disponible).

Nota: Dado que Python puede definir algunas definiciones de preprocesador que afectan los encabezados estándar
en algunos sistemas, debe incluir Python.h antes de incluir encabezados estándar.
Se recomienda definir siempre PY_SSIZE_T_CLEAN antes de incluir Python.h. Consulte Analizando argumen-
tos y construyendo valores para obtener una descripción de este macro.

Todos los nombres visibles del usuario definidos por Python.h (excepto los definidos por los encabezados estándar
incluidos) tienen uno de los prefijos Py o _Py. Los nombres que comienzan con _Py son para uso interno de la
implementación de Python y no deben ser utilizados por escritores de extensiones. Los nombres de miembros de
estructura no tienen un prefijo reservado.

Nota: El código de usuario nunca debe definir nombres que comiencen con Py o _Py. Esto confunde al lector y
pone en peligro la portabilidad del código de usuario para futuras versiones de Python, que pueden definir nombres
adicionales que comienzan con uno de estos prefijos.

Los archivos de encabezado generalmente se instalan con Python. En Unix, estos se encuentran en los directorios
prefix/include/pythonversion/ y exec_prefix/include/pythonversion/, donde prefix
y exec_prefix están definidos por los parámetros correspondientes al programa de Python configure y version
es '%d.%d' % sys.version_info[:2]. En Windows, los encabezados se instalan en prefix/include,
donde prefix es el directorio de instalación especificado para el instalador.
Para incluir los encabezados, coloque ambos directorios (si son diferentes) en la ruta de búsqueda de su compilador
para incluir. No coloque los directorios principales en la ruta de búsqueda y luego use #include <pythonX.
Y/Python.h>; esto se romperá en las compilaciones multiplataforma ya que los encabezados independientes de la
plataforma bajo prefix incluyen los encabezados específicos de la plataforma de exec_prefix.
Los usuarios de C++ deben tener en cuenta que aunque la API se define completamente usando C, los archivos de
encabezado declaran correctamente que los puntos de entrada son extern "C". Como resultado, no es necesario
hacer nada especial para usar la API desde C++.

1.3 Macros útiles

Varias macros útiles se definen en los archivos de encabezado de Python. Muchos se definen más cerca de donde son
útiles (por ejemplo Py_RETURN_NONE). Otros de una utilidad más general se definen aquí. Esto no es necesaria-
mente una lista completa.
Py_ABS(x)
Retorna el valor absoluto de x.
Nuevo en la versión 3.3.
Py_ALWAYS_INLINE
Ask the compiler to always inline a static inline function. The compiler can ignore it and decides to not inline
the function.

4 Capítulo 1. Introducción
 The Python/C API, Versión 3.11.0

It can be used to inline performance critical static inline functions when building Python in debug mode with
function inlining disabled. For example, MSC disables function inlining when building in debug mode.
Marking blindly a static inline function with Py_ALWAYS_INLINE can result in worse performances (due
to increased code size for example). The compiler is usually smarter than the developer for the cost/benefit
analysis.
If Python is built in debug mode (if the Py_DEBUG macro is defined), the Py_ALWAYS_INLINE macro
does nothing.
It must be specified before the function return type. Usage:

static inline Py_ALWAYS_INLINE int random(void) { return 4; }

Nuevo en la versión 3.11.

Py_CHARMASK(c)
El argumento debe ser un carácter o un número entero en el rango [-128, 127] o [0, 255]. Este macro retorna
la conversión c a un unsigned char.
Py_DEPRECATED(version)
Use esto para declaraciones obsoletas. El macro debe colocarse antes del nombre del símbolo.
Ejemplo:

Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);

Distinto en la versión 3.8: Soporte para MSVC fue agregado.

Py_GETENV(s)
Al igual que getenv(s), pero retorna NULL si: la opción -E se pasó en la línea de comando (es decir, si se
establece Py_IgnoreEnvironmentFlag).
Py_MAX(x, y)
Retorna el valor máximo entre x e y.
Nuevo en la versión 3.3.
Py_MEMBER_SIZE(type, member)
Retorna el tamaño de una estructura (type) member en bytes.
Nuevo en la versión 3.6.
Py_MIN(x, y)
Retorna el valor mínimo entre x e y.
Nuevo en la versión 3.3.
Py_NO_INLINE
Disable inlining on a function. For example, it reduces the C stack consumption: useful on LTO+PGO builds
which heavily inline code (see bpo-33720).
Usage:

Py_NO_INLINE static int random(void) { return 4; }

Nuevo en la versión 3.11.

Py_STRINGIFY(x)
Convierte x en una cadena de caracteres C. Por ejemplo, Py_STRINGIFY(123) retorna "123".
Nuevo en la versión 3.4.

1.3. Macros útiles 5

The Python/C API, Versión 3.11.0

Py_UNREACHABLE()
Use esto cuando tenga una ruta de código a la que no se pueda acceder por diseño. Por ejemplo, en la cláusula
default: en una declaración switch para la cual todos los valores posibles están cubiertos en declaraciones
case. Use esto en lugares donde podría tener la tentación de poner una llamada assert(0) o abort().
En el modo de lanzamiento, la macro ayuda al compilador a optimizar el código y evita una advertencia sobre
el código inalcanzable. Por ejemplo, la macro se implementa con __builtin_unreachable() en GCC
en modo de lanzamiento.
Un uso de Py_UNREACHABLE() es seguir una llamada a una función que nunca retorna pero que no está
declarada _Py_NO_RETURN.
Si una ruta de código es un código muy poco probable pero se puede acceder en casos excepcionales, esta
macro no debe utilizarse. Por ejemplo, en condiciones de poca memoria o si una llamada al sistema retorna un
valor fuera del rango esperado. En este caso, es mejor informar el error a la persona que llama. Si no se puede
informar del error a la persona que llama, se puede utilizar Py_FatalError().
Nuevo en la versión 3.7.
Py_UNUSED(arg)
Use esto para argumentos no utilizados en una definición de función para silenciar las advertencias del com-
pilador. Ejemplo: int func(int a, int Py_UNUSED(b)) {return a; }.
Nuevo en la versión 3.4.
PyDoc_STRVAR(name, str)
Crea una variable con el nombre name que se puede usar en docstrings. Si Python se construye sin docstrings,
el valor estará vacío.
Utilice PyDoc_STRVAR para que los docstrings admitan la construcción de Python sin docstrings, como se
especifica en PEP 7.
Ejemplo:

PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = {

// ...
{"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
// ...
}

PyDoc_STR(str)
Crea un docstring para la cadena de caracteres de entrada dada o una cadena vacía si los docstrings están
deshabilitados.
Utilice PyDoc_STR al especificar docstrings para admitir la construcción de Python sin docstrings, como se
especifica en PEP 7.
Ejemplo:

static PyMethodDef pysqlite_row_methods[] = {

{"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
PyDoc_STR("Returns the keys of the row.")},
{NULL, NULL}
};

6 Capítulo 1. Introducción
 The Python/C API, Versión 3.11.0

1.4 Objetos, tipos y conteos de referencias

Most Python/C API functions have one or more arguments as well as a return value of type PyObject*. This type
is a pointer to an opaque data type representing an arbitrary Python object. Since all Python object types are treated
the same way by the Python language in most situations (e.g., assignments, scope rules, and argument passing), it
is only fitting that they should be represented by a single C type. Almost all Python objects live on the heap: you
never declare an automatic or static variable of type PyObject, only pointer variables of type PyObject* can
be declared. The sole exception are the type objects; since these must never be deallocated, they are typically static
PyTypeObject objects.
Todos los objetos de Python (incluso los enteros de Python) tienen un tipo (type) y un conteo de referencia (reference
count). El tipo de un objeto determina qué tipo de objeto es (por ejemplo, un número entero, una lista o una función
definida por el usuario; hay muchos más como se explica en types). Para cada uno de los tipos conocidos hay un
macro para verificar si un objeto es de ese tipo; por ejemplo, PyList_Check(a) es verdadero si (y solo si) el
objeto al que apunta a es una lista de Python.

1.4.1 Conteo de Referencias

El conteo de referencia es importante porque las computadoras de hoy tienen un tamaño de memoria finito (y a
menudo muy limitado); cuenta cuántos lugares diferentes hay los cuales tienen una referencia a un objeto. Tal lugar
podría ser otro objeto, o una variable C global (o estática), o una variable local en alguna función C. Cuando el
recuento de referencia de un objeto se convierte en cero, el objeto se desasigna. Si contiene referencias a otros objetos,
su recuento de referencias se reduce. Esos otros objetos pueden ser desasignados a su vez, si esta disminución hace
que su recuento de referencia sea cero, y así sucesivamente. (Hay un problema obvio con los objetos que se refieren
entre sí aquí; por ahora, la solución es «no hagas eso»).
Los conteos de referencias siempre se manipulan explícitamente. La forma normal es usar el macro Py_INCREF()
para incrementar el conteo de referencia de un objeto en uno, y Py_DECREF() para disminuirlo en uno. El macro
Py_DECREF() es considerablemente más compleja que la incref, ya que debe verificar si el recuento de referencia
se convierte en cero y luego hacer que se llame al desasignador (deallocator) del objeto. El desasignador es un puntero
de función contenido en la estructura de tipo del objeto. El desasignador específico del tipo se encarga de disminuir
los recuentos de referencia para otros objetos contenidos en el objeto si este es un tipo de objeto compuesto, como
una lista, así como realizar cualquier finalización adicional que sea necesaria. No hay posibilidad de que el conteo de
referencia se desborde; se utilizan al menos tantos bits para contener el recuento de referencia como ubicaciones de
memoria distintas en la memoria virtual (suponiendo sizeof(Py_ssize_t) >= sizeof(void*)). Por lo
tanto, el incremento del recuento de referencia es una operación simple.
No es necesario incrementar el conteo de referencia de un objeto para cada variable local que contiene un puntero a
un objeto. En teoría, el conteo de referencia del objeto aumenta en uno cuando se hace que la variable apunte hacia
él y disminuye en uno cuando la variable se sale del alcance. Sin embargo, estos dos se cancelan entre sí, por lo que
al final el recuento de referencias no ha cambiado. La única razón real para usar el recuento de referencia es evitar
que el objeto pierda su asignación mientras nuestra variable lo apunte. Si sabemos que hay al menos otra referencia
al objeto que vive al menos tanto como nuestra variable, no hay necesidad de incrementar el recuento de referencias
temporalmente. Una situación importante donde esto surge es en los objetos que se pasan como argumentos a las
funciones de C en un módulo de extensión que se llama desde Python; El mecanismo de llamada garantiza mantener
una referencia a cada argumento durante la duración de la llamada.
Sin embargo, una trampa común es extraer un objeto de una lista y mantenerlo por un tiempo sin incrementar su
conteo de referencia. Es posible que alguna otra operación elimine el objeto de la lista, disminuya su conteo de
referencias y posiblemente lo desasigne. El peligro real es que las operaciones de aspecto inocente pueden invocar
código arbitrario de Python que podría hacer esto; hay una ruta de código que permite que el control vuelva al usuario
desde a Py_DECREF(), por lo que casi cualquier operación es potencialmente peligrosa.
Un enfoque seguro es utilizar siempre las operaciones genéricas (funciones cuyo nombre comienza con PyObject_,
PyNumber_, PySequence_ o PyMapping_). Estas operaciones siempre incrementan el recuento de referencia
del objeto que retornan. Esto deja a la persona que llama con la responsabilidad de llamar Py_DECREF() cuando
hayan terminado con el resultado; Esto pronto se convierte en una segunda naturaleza.

1.4. Objetos, tipos y conteos de referencias 7

The Python/C API, Versión 3.11.0

Detalles del conteo de referencia

El comportamiento del conteo de referencias de funciones en la API de Python/C se explica mejor en términos de
propiedad de las referencias. La propiedad pertenece a referencias, nunca a objetos (los objetos no son propiedad:
siempre se comparten). «Poseer una referencia» significa ser responsable de llamar a Py_DECREF cuando ya no se
necesita la referencia. La propiedad también se puede transferir, lo que significa que el código que recibe la propiedad
de la referencia se hace responsable de eventualmente disminuirla llamando a Py_DECREF() o Py_XDECREF()
cuando ya no es necesario — o transmitiendo esta responsabilidad (generalmente a la persona que llama). Cuando una
función transfiere la propiedad de una referencia a su llamador, se dice que el que llama recibe una nueva referencia.
Cuando no se transfiere ninguna propiedad, se dice que la persona que llama toma prestada la referencia. No es
necesario hacer nada para obtener una referencia prestada.
Por el contrario, cuando una función de llamada pasa una referencia a un objeto, hay dos posibilidades: la función roba
una referencia al objeto, o no lo hace. Robar una referencia significa que cuando pasa una referencia a una función,
esa función asume que ahora posee esa referencia, y usted ya no es responsable de ella.
Pocas funciones roban referencias; las dos excepciones notables son PyList_SetItem() y
PyTuple_SetItem(), que roban una referencia al elemento (¡pero no a la tupla o lista en la que se colo-
ca el elemento!). Estas funciones fueron diseñadas para robar una referencia debido a un idioma común para
poblar una tupla o lista con objetos recién creados; por ejemplo, el código para crear la tupla (1, 2, "tres")
podría verse así (olvidando el manejo de errores por el momento; una mejor manera de codificar esto se muestra a
continuación):
PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

Aquí PyLong_FromLong() retorna una nueva referencia que es inmediatamente robada por
PyTuple_SetItem(). Cuando quiera seguir usando un objeto aunque se le robe la referencia, use
Py_INCREF() para tomar otra referencia antes de llamar a la función de robo de referencias.
Por cierto, PyTuple_SetItem() es la única forma de establecer elementos de tupla;
PySequence_SetItem() y PyObject_SetItem() se niegan a hacer esto ya que las tuplas son un
tipo de datos inmutable. Solo debe usar PyTuple_SetItem() para las tuplas que está creando usted mismo.
El código equivalente para llenar una lista se puede escribir usando PyList_New() y PyList_SetItem().
Sin embargo, en la práctica, rara vez utilizará estas formas de crear y completar una tupla o lista. Hay una función
genérica, Py_BuildValue(), que puede crear los objetos más comunes a partir de valores C, dirigidos por un
una cadena de caracteres de formato (format string). Por ejemplo, los dos bloques de código anteriores podrían
reemplazarse por lo siguiente (que también se ocupa de la comprobación de errores):
PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");

list = Py_BuildValue("[iis]", 1, 2, "three");

Es mucho más común usar PyObject_SetItem() y amigos con elementos cuyas referencias solo está prestando,
como argumentos que se pasaron a la función que está escribiendo. En ese caso, su comportamiento con respecto a
los recuentos de referencias es mucho más sensato, ya que no tiene que incrementar un recuento de referencias para
poder regalar una referencia («robarla»). Por ejemplo, esta función establece todos los elementos de una lista (en
realidad, cualquier secuencia mutable) en un elemento dado:
int
set_all(PyObject *target, PyObject *item)
{
Py_ssize_t i, n;

n = PyObject_Length(target);
(continué en la próxima página)

8 Capítulo 1. Introducción
 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

if (n < 0)
return -1;
for (i = 0; i < n; i++) {
PyObject *index = PyLong_FromSsize_t(i);
if (!index)
return -1;
if (PyObject_SetItem(target, index, item) < 0) {
Py_DECREF(index);
return -1;
}
Py_DECREF(index);
}
return 0;
}

La situación es ligeramente diferente para los valores de retorno de la función. Si bien pasar una referencia a la mayo-
ría de las funciones no cambia sus responsabilidades de propiedad para esa referencia, muchas funciones que retornan
una referencia a un objeto le otorgan la propiedad de la referencia. La razón es simple: en muchos casos, el objeto
retornado se crea sobre la marcha, y la referencia que obtiene es la única referencia al objeto. Por lo tanto, las funcio-
nes genéricas que retornan referencias de objeto, como PyObject_GetItem() y PySequence_GetItem(),
siempre retornan una nueva referencia (la entidad que llama se convierte en el propietario de la referencia).
Es importante darse cuenta de que si posee una referencia retornada por una función depende de a qué función llame
únicamente — el plumaje (el tipo del objeto pasado como argumento a la función) no entra en él! Por lo tanto, si
extrae un elemento de una lista usando PyList_GetItem(), no posee la referencia — pero si obtiene el mismo
elemento de la misma lista usando PySequence_GetItem() (que toma exactamente los mismos argumentos),
usted posee una referencia al objeto retornado.
Aquí hay un ejemplo de cómo podría escribir una función que calcule la suma de los elementos en una lista de enteros;
una vez usando PyList_GetItem(), y una vez usando PySequence_GetItem().
long
sum_list(PyObject *list)
{
Py_ssize_t i, n;
long total = 0, value;
PyObject *item;

n = PyList_Size(list);
if (n < 0)
return -1; /* Not a list */
for (i = 0; i < n; i++) {
item = PyList_GetItem(list, i); /* Can't fail */
if (!PyLong_Check(item)) continue; /* Skip non-integers */
value = PyLong_AsLong(item);
if (value == -1 && PyErr_Occurred())
/* Integer too big to fit in a C long, bail out */
return -1;
total += value;
}
return total;
}

long
sum_sequence(PyObject *sequence)
{
Py_ssize_t i, n;
long total = 0, value;
PyObject *item;
n = PySequence_Length(sequence);
if (n < 0)
(continué en la próxima página)

1.4. Objetos, tipos y conteos de referencias 9

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

return -1; /* Has no length */
for (i = 0; i < n; i++) {
item = PySequence_GetItem(sequence, i);
if (item == NULL)
return -1; /* Not a sequence, or other failure */
if (PyLong_Check(item)) {
value = PyLong_AsLong(item);
Py_DECREF(item);
if (value == -1 && PyErr_Occurred())
/* Integer too big to fit in a C long, bail out */
return -1;
total += value;
}
else {
Py_DECREF(item); /* Discard reference ownership */
}
}
return total;
}

1.4.2 Tipos

There are few other data types that play a significant role in the Python/C API; most are simple C types such as
int, long, double and char*. A few structure types are used to describe static tables used to list the functions
exported by a module or the data attributes of a new object type, and another is used to describe the value of a
complex number. These will be discussed together with the functions that use them.
type Py_ssize_t
Part of the Stable ABI. A signed integral type such that sizeof(Py_ssize_t) == sizeof(size_t).
C99 doesn’t define such a thing directly (size_t is an unsigned integral type). See PEP 353 for details.
PY_SSIZE_T_MAX is the largest positive value of type Py_ssize_t.

1.5 Excepciones

El programador de Python solo necesita lidiar con excepciones si se requiere un manejo específico de errores; las
excepciones no manejadas se propagan automáticamente a la persona que llama, luego a la persona que llama, y
así sucesivamente, hasta que llegan al intérprete de nivel superior, donde se informan al usuario acompañado de un
seguimiento de pila (stack traceback).
Para los programadores de C, sin embargo, la comprobación de errores siempre tiene que ser explícita. Todas las
funciones en la API Python/C pueden generar excepciones, a menos que se señale explícitamente en la documentación
de una función. En general, cuando una función encuentra un error, establece una excepción, descarta cualquier
referencia de objeto que posea y retorna un indicador de error. Si no se documenta lo contrario, este indicador
es NULL o -1, dependiendo del tipo de retorno de la función. Algunas funciones retornan un resultado booleano
verdadero/falso, con falso que indica un error. Muy pocas funciones no retornan ningún indicador de error explícito
o tienen un valor de retorno ambiguo, y requieren pruebas explícitas de errores con PyErr_Occurred(). Estas
excepciones siempre se documentan explícitamente.
El estado de excepción se mantiene en el almacenamiento por subproceso (esto es equivalente a usar el almacena-
miento global en una aplicación sin subprocesos). Un subproceso puede estar en uno de dos estados: se ha producido
una excepción o no. La función PyErr_Occurred() puede usarse para verificar esto: retorna una referencia
prestada al objeto de tipo de excepción cuando se produce una excepción, y NULL de lo contrario. Hay una serie de
funciones para establecer el estado de excepción: PyErr_SetString() es la función más común (aunque no la
más general) para establecer el estado de excepción, y PyErr_Clear() borra la excepción estado.
El estado de excepción completo consta de tres objetos (todos los cuales pueden ser NULL): el tipo de excepción, el
valor de excepción correspondiente y el rastreo. Estos tienen los mismos significados que el resultado de Python de

10 Capítulo 1. Introducción
 The Python/C API, Versión 3.11.0

sys.exc_info(); sin embargo, no son lo mismo: los objetos Python representan la última excepción manejada
por una declaración de Python try … except, mientras que el estado de excepción de nivel C solo existe mientras
se está pasando una excepción entre las funciones de C hasta que llega al bucle principal del intérprete de código de
bytes (bytecode) de Python, que se encarga de transferirlo a sys.exc_info() y amigos.
Tenga en cuenta que a partir de Python 1.5, la forma preferida y segura de subprocesos para acceder al estado de
excepción desde el código de Python es llamar a la función sys.exc_info(), que retorna el estado de excepción
por subproceso para el código de Python. Además, la semántica de ambas formas de acceder al estado de excepción
ha cambiado de modo que una función que detecta una excepción guardará y restaurará el estado de excepción de
su hilo para preservar el estado de excepción de su llamador. Esto evita errores comunes en el código de manejo
de excepciones causado por una función de aspecto inocente que sobrescribe la excepción que se maneja; También
reduce la extensión de vida útil a menudo no deseada para los objetos a los que hacen referencia los marcos de pila
en el rastreo.
Como principio general, una función que llama a otra función para realizar alguna tarea debe verificar si la función
llamada generó una excepción y, de ser así, pasar el estado de excepción a quien la llama (caller). Debe descartar
cualquier referencia de objeto que posea y retornar un indicador de error, pero no debe establecer otra excepción —
que sobrescribirá la excepción que se acaba de generar y perderá información importante sobre la causa exacta del
error.
Un ejemplo simple de detectar excepciones y pasarlas se muestra en el ejemplo sum_sequence() anterior. Sucede
que este ejemplo no necesita limpiar ninguna referencia de propiedad cuando detecta un error. La siguiente función
de ejemplo muestra algunos errores de limpieza. Primero, para recordar por qué le gusta Python, le mostramos el
código Python equivalente:

def incr_item(dict, key):

try:
item = dict[key]
except KeyError:
item = 0
dict[key] = item + 1

Aquí está el código C correspondiente, en todo su esplendor:

int
incr_item(PyObject *dict, PyObject *key)
{
/* Objects all initialized to NULL for Py_XDECREF */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* Return value initialized to -1 (failure) */

item = PyObject_GetItem(dict, key);

if (item == NULL) {
/* Handle KeyError only: */
if (!PyErr_ExceptionMatches(PyExc_KeyError))
goto error;

/* Clear the error and use zero: */

PyErr_Clear();
item = PyLong_FromLong(0L);
if (item == NULL)
goto error;
}
const_one = PyLong_FromLong(1L);
if (const_one == NULL)
goto error;

incremented_item = PyNumber_Add(item, const_one);

if (incremented_item == NULL)
goto error;

if (PyObject_SetItem(dict, key, incremented_item) < 0)

(continué en la próxima página)

1.5. Excepciones 11
The Python/C API, Versión 3.11.0

(proviene de la página anterior)

goto error;
rv = 0; /* Success */
/* Continue with cleanup code */

error:
/* Cleanup code, shared by success and failure path */

/* Use Py_XDECREF() to ignore NULL references */

Py_XDECREF(item);
Py_XDECREF(const_one);
Py_XDECREF(incremented_item);

return rv; /* -1 for error, 0 for success */

}

Este ejemplo representa un uso aprobado de la declaración goto en C! Ilustra el uso de

PyErr_ExceptionMatches() y PyErr_Clear() para manejar excepciones específicas, y el uso de
Py_XDECREF() para eliminar referencias propias que pueden ser NULL (tenga en cuenta la 'X'” en el nombre;
Py_DECREF() se bloqueará cuando se enfrente con una referencia NULL). Es importante que las variables
utilizadas para contener referencias propias se inicialicen en NULL para que esto funcione; Del mismo modo, el
valor de retorno propuesto se inicializa a -1 (falla) y solo se establece en éxito después de que la última llamada
realizada sea exitosa.

1.6 Integración de Python

La única tarea importante de la que solo tienen que preocuparse los integradores (a diferencia de los escritores de
extensión) del intérprete de Python es la inicialización, y posiblemente la finalización, del intérprete de Python. La
mayor parte de la funcionalidad del intérprete solo se puede usar después de que el intérprete se haya inicializado.
La función básica de inicialización es Py_Initialize(). Esto inicializa la tabla de módulos cargados y crea
los módulos fundamentales builtins, __main__, y sys. También inicializa la ruta de búsqueda del módulo
(sys.path).
Py_Initialize() does not set the «script argument list» (sys.argv). If this variable is needed by Python
code that will be executed later, setting PyConfig.argv and PyConfig.parse_argv must be set: see Python
Initialization Configuration.
En la mayoría de los sistemas (en particular, en Unix y Windows, aunque los detalles son ligeramente diferentes),
Py_Initialize() calcula la ruta de búsqueda del módulo basándose en su mejor estimación de la ubicación del
ejecutable del intérprete de Python estándar, suponiendo que la biblioteca de Python se encuentra en una ubicación fija
en relación con el ejecutable del intérprete de Python. En particular, busca un directorio llamado lib/pythonX.Y
relativo al directorio padre donde se encuentra el ejecutable llamado python en la ruta de búsqueda del comando
shell (la variable de entorno PATH).
Por ejemplo, si el ejecutable de Python se encuentra en /usr/local/bin/python, se supondrá que las biblio-
tecas están en /usr/local/lib/pythonX.Y. (De hecho, esta ruta particular también es la ubicación «alterna-
tiva», utilizada cuando no se encuentra un archivo ejecutable llamado python junto con PATH.) El usuario puede
anular este comportamiento configurando la variable de entorno PYTHONHOME, o inserte directorios adicionales
delante de la ruta estándar estableciendo PYTHONPATH.
La aplicación de integración puede dirigir la búsqueda llamando a Py_SetProgramName(file) antes llamando
Py_Initialize(). Tenga en cuenta que PYTHONHOME todavía anula esto y PYTHONPATH todavía se inserta
frente a la ruta estándar. Una aplicación que requiere un control total debe proporcionar su propia implementación de
Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), y Py_GetProgramFullPath() (todo
definido en Modules/getpath.c).
A veces, es deseable «no inicializar» Python. Por ejemplo, la aplicación puede querer comenzar de nuevo (hacer otra
llamada a Py_Initialize()) o la aplicación simplemente se hace con el uso de Python y quiere liberar memoria
asignada por Python. Esto se puede lograr llamando a Py_FinalizeEx(). La función Py_IsInitialized()

12 Capítulo 1. Introducción
 The Python/C API, Versión 3.11.0

retorna verdadero si Python se encuentra actualmente en el estado inicializado. Se proporciona más información
sobre estas funciones en un capítulo posterior. Tenga en cuenta que Py_FinalizeEx() no libera toda la memoria
asignada por el intérprete de Python, por ejemplo, la memoria asignada por los módulos de extensión actualmente no
se puede liberar.

1.7 Depuración de compilaciones

Python se puede construir con varios macros para permitir verificaciones adicionales del intérprete y los módulos de
extensión. Estas comprobaciones tienden a agregar una gran cantidad de sobrecarga al tiempo de ejecución, por lo
que no están habilitadas de forma predeterminada.
A full list of the various types of debugging builds is in the file Misc/SpecialBuilds.txt in the Python source
distribution. Builds are available that support tracing of reference counts, debugging the memory allocator, or low-
level profiling of the main interpreter loop. Only the most frequently used builds will be described in the remainder
of this section.
Compilar el intérprete con el macro Py_DEBUG definido produce lo que generalmente se entiende por una compi-
lación de depuración de Python. Py_DEBUG se habilita en la compilación de Unix agregando --with-pydebug
al comando ./configure. También está implícito en la presencia del macro no específico de Python _DEBUG.
Cuando Py_DEBUG está habilitado en la compilación de Unix, la optimización del compilador está deshabilitada.
Además de la depuración del recuento de referencia que se describe a continuación, se realizan verificaciones adi-
cionales, véase compilaciones de depuración.
Definiendo Py_TRACE_REFS habilita el rastreo de referencias (véase la opción configure
--with-trace-refs). Cuando se define, se mantiene una lista circular doblemente vinculada de objetos
activos al agregar dos campos adicionales a cada PyObject. También se realiza un seguimiento de las asignaciones
totales. Al salir, se imprimen todas las referencias existentes. (En modo interactivo, esto sucede después de cada
declaración ejecutada por el intérprete).
Consulte Misc/SpecialBuilds.txt en la distribución fuente de Python para obtener información más deta-
llada.

1.7. Depuración de compilaciones 13

The Python/C API, Versión 3.11.0

14 Capítulo 1. Introducción
 CAPÍTULO 2

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.

2.1 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.

15
The Python/C API, Versión 3.11.0

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.

2.1.1 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 estruc-
turas 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.

2.1.2 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.

16 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

2.2 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.

2.3 Contenido de la API limitada

Actualmente, la API limitada incluye los siguientes elementos:

• 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

2.2. Consideraciones de la plataforma 17

The Python/C API, Versión 3.11.0

• 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

18 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• 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

2.3. Contenido de la API limitada 19

The Python/C API, Versión 3.11.0

• 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_ExceptionMatches()
• PyErr_Fetch()
• PyErr_Format()
• PyErr_FormatV()
• PyErr_GetExcInfo()
• PyErr_GetHandledException()
• PyErr_GivenExceptionMatches()
• PyErr_NewException()
• PyErr_NewExceptionWithDoc()
• PyErr_NoMemory()
• PyErr_NormalizeException()
• PyErr_Occurred()

20 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• 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_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()

2.3. Contenido de la API limitada 21

The Python/C API, Versión 3.11.0

• 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

22 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• 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

2.3. Contenido de la API limitada 23

The Python/C API, Versión 3.11.0

• PyExc_Warning
• PyExc_WindowsError
• PyExc_ZeroDivisionError
• PyExceptionClass_Name()
• PyException_GetCause()
• PyException_GetContext()
• PyException_GetTraceback()
• 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()

24 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyImport_AppendInittab()
• PyImport_ExecCodeModule()
• PyImport_ExecCodeModuleEx()
• PyImport_ExecCodeModuleObject()
• PyImport_ExecCodeModuleWithPathnames()
• PyImport_GetImporter()
• PyImport_GetMagicNumber()
• PyImport_GetMagicTag()
• PyImport_GetModule()
• PyImport_GetModuleDict()
• PyImport_Import()
• PyImport_ImportFrozenModule()
• PyImport_ImportFrozenModuleObject()
• PyImport_ImportModule()
• PyImport_ImportModuleLevel()
• PyImport_ImportModuleLevelObject()
• PyImport_ImportModuleNoBlock()
• PyImport_ReloadModule()
• PyIndex_Check()
• PyInterpreterState
• PyInterpreterState_Clear()
• PyInterpreterState_Delete()
• PyInterpreterState_Get()
• PyInterpreterState_GetDict()
• PyInterpreterState_GetID()
• PyInterpreterState_New()
• PyIter_Check()
• PyIter_Next()
• PyIter_Send()
• PyListIter_Type
• PyListRevIter_Type
• PyList_Append()
• PyList_AsTuple()
• PyList_GetItem()
• PyList_GetSlice()
• PyList_Insert()
• PyList_New()
• PyList_Reverse()
• PyList_SetItem()

2.3. Contenido de la API limitada 25

The Python/C API, Versión 3.11.0

• PyList_SetSlice()
• PyList_Size()
• PyList_Sort()
• PyList_Type
• PyLongObject
• PyLongRangeIter_Type
• PyLong_AsDouble()
• PyLong_AsLong()
• PyLong_AsLongAndOverflow()
• PyLong_AsLongLong()
• PyLong_AsLongLongAndOverflow()
• PyLong_AsSize_t()
• PyLong_AsSsize_t()
• PyLong_AsUnsignedLong()
• PyLong_AsUnsignedLongLong()
• PyLong_AsUnsignedLongLongMask()
• PyLong_AsUnsignedLongMask()
• PyLong_AsVoidPtr()
• PyLong_FromDouble()
• PyLong_FromLong()
• PyLong_FromLongLong()
• PyLong_FromSize_t()
• PyLong_FromSsize_t()
• PyLong_FromString()
• PyLong_FromUnsignedLong()
• PyLong_FromUnsignedLongLong()
• PyLong_FromVoidPtr()
• PyLong_GetInfo()
• PyLong_Type
• PyMap_Type
• PyMapping_Check()
• PyMapping_GetItemString()
• PyMapping_HasKey()
• PyMapping_HasKeyString()
• PyMapping_Items()
• PyMapping_Keys()
• PyMapping_Length()
• PyMapping_SetItemString()
• PyMapping_Size()

26 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyMapping_Values()
• PyMem_Calloc()
• PyMem_Free()
• PyMem_Malloc()
• PyMem_Realloc()
• PyMemberDef
• PyMemberDescr_Type
• PyMemoryView_FromBuffer()
• PyMemoryView_FromMemory()
• PyMemoryView_FromObject()
• PyMemoryView_GetContiguous()
• PyMemoryView_Type
• PyMethodDef
• PyMethodDescr_Type
• PyModuleDef
• PyModuleDef_Base
• PyModuleDef_Init()
• PyModuleDef_Type
• PyModule_AddFunctions()
• PyModule_AddIntConstant()
• PyModule_AddObject()
• PyModule_AddObjectRef()
• PyModule_AddStringConstant()
• PyModule_AddType()
• PyModule_Create2()
• PyModule_ExecDef()
• PyModule_FromDefAndSpec2()
• PyModule_GetDef()
• PyModule_GetDict()
• PyModule_GetFilename()
• PyModule_GetFilenameObject()
• PyModule_GetName()
• PyModule_GetNameObject()
• PyModule_GetState()
• PyModule_New()
• PyModule_NewObject()
• PyModule_SetDocString()
• PyModule_Type
• PyNumber_Absolute()

2.3. Contenido de la API limitada 27

The Python/C API, Versión 3.11.0

• PyNumber_Add()
• PyNumber_And()
• PyNumber_AsSsize_t()
• PyNumber_Check()
• PyNumber_Divmod()
• PyNumber_Float()
• PyNumber_FloorDivide()
• PyNumber_InPlaceAdd()
• PyNumber_InPlaceAnd()
• PyNumber_InPlaceFloorDivide()
• PyNumber_InPlaceLshift()
• PyNumber_InPlaceMatrixMultiply()
• PyNumber_InPlaceMultiply()
• PyNumber_InPlaceOr()
• PyNumber_InPlacePower()
• PyNumber_InPlaceRemainder()
• PyNumber_InPlaceRshift()
• PyNumber_InPlaceSubtract()
• PyNumber_InPlaceTrueDivide()
• PyNumber_InPlaceXor()
• PyNumber_Index()
• PyNumber_Invert()
• PyNumber_Long()
• PyNumber_Lshift()
• PyNumber_MatrixMultiply()
• PyNumber_Multiply()
• PyNumber_Negative()
• PyNumber_Or()
• PyNumber_Positive()
• PyNumber_Power()
• PyNumber_Remainder()
• PyNumber_Rshift()
• PyNumber_Subtract()
• PyNumber_ToBase()
• PyNumber_TrueDivide()
• PyNumber_Xor()
• PyOS_AfterFork()
• PyOS_AfterFork_Child()
• PyOS_AfterFork_Parent()

28 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyOS_BeforeFork()
• PyOS_CheckStack()
• PyOS_FSPath()
• PyOS_InputHook
• PyOS_InterruptOccurred()
• PyOS_double_to_string()
• PyOS_getsig()
• PyOS_mystricmp()
• PyOS_mystrnicmp()
• PyOS_setsig()
• PyOS_sighandler_t
• PyOS_snprintf()
• PyOS_string_to_double()
• PyOS_strtol()
• PyOS_strtoul()
• PyOS_vsnprintf()
• PyObject
• PyObject.ob_refcnt
• PyObject.ob_type
• PyObject_ASCII()
• PyObject_AsCharBuffer()
• PyObject_AsFileDescriptor()
• PyObject_AsReadBuffer()
• PyObject_AsWriteBuffer()
• PyObject_Bytes()
• PyObject_Call()
• PyObject_CallFunction()
• PyObject_CallFunctionObjArgs()
• PyObject_CallMethod()
• PyObject_CallMethodObjArgs()
• PyObject_CallNoArgs()
• PyObject_CallObject()
• PyObject_Calloc()
• PyObject_CheckBuffer()
• PyObject_CheckReadBuffer()
• PyObject_ClearWeakRefs()
• PyObject_CopyData()
• PyObject_DelItem()
• PyObject_DelItemString()

2.3. Contenido de la API limitada 29

The Python/C API, Versión 3.11.0

• PyObject_Dir()
• PyObject_Format()
• PyObject_Free()
• PyObject_GC_Del()
• PyObject_GC_IsFinalized()
• PyObject_GC_IsTracked()
• PyObject_GC_Track()
• PyObject_GC_UnTrack()
• PyObject_GenericGetAttr()
• PyObject_GenericGetDict()
• PyObject_GenericSetAttr()
• PyObject_GenericSetDict()
• PyObject_GetAIter()
• PyObject_GetAttr()
• PyObject_GetAttrString()
• PyObject_GetBuffer()
• PyObject_GetItem()
• PyObject_GetIter()
• PyObject_HasAttr()
• PyObject_HasAttrString()
• PyObject_Hash()
• PyObject_HashNotImplemented()
• PyObject_Init()
• PyObject_InitVar()
• PyObject_IsInstance()
• PyObject_IsSubclass()
• PyObject_IsTrue()
• PyObject_Length()
• PyObject_Malloc()
• PyObject_Not()
• PyObject_Realloc()
• PyObject_Repr()
• PyObject_RichCompare()
• PyObject_RichCompareBool()
• PyObject_SelfIter()
• PyObject_SetAttr()
• PyObject_SetAttrString()
• PyObject_SetItem()
• PyObject_Size()

30 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyObject_Str()
• PyObject_Type()
• PyProperty_Type
• PyRangeIter_Type
• PyRange_Type
• PyReversed_Type
• PySeqIter_New()
• PySeqIter_Type
• PySequence_Check()
• PySequence_Concat()
• PySequence_Contains()
• PySequence_Count()
• PySequence_DelItem()
• PySequence_DelSlice()
• PySequence_Fast()
• PySequence_GetItem()
• PySequence_GetSlice()
• PySequence_In()
• PySequence_InPlaceConcat()
• PySequence_InPlaceRepeat()
• PySequence_Index()
• PySequence_Length()
• PySequence_List()
• PySequence_Repeat()
• PySequence_SetItem()
• PySequence_SetSlice()
• PySequence_Size()
• PySequence_Tuple()
• PySetIter_Type
• PySet_Add()
• PySet_Clear()
• PySet_Contains()
• PySet_Discard()
• PySet_New()
• PySet_Pop()
• PySet_Size()
• PySet_Type
• PySlice_AdjustIndices()
• PySlice_GetIndices()

2.3. Contenido de la API limitada 31

The Python/C API, Versión 3.11.0

• PySlice_GetIndicesEx()
• PySlice_New()
• PySlice_Type
• PySlice_Unpack()
• PyState_AddModule()
• PyState_FindModule()
• PyState_RemoveModule()
• PyStructSequence_Desc
• PyStructSequence_Field
• PyStructSequence_GetItem()
• PyStructSequence_New()
• PyStructSequence_NewType()
• PyStructSequence_SetItem()
• PyStructSequence_UnnamedField
• PySuper_Type
• PySys_AddWarnOption()
• PySys_AddWarnOptionUnicode()
• PySys_AddXOption()
• PySys_FormatStderr()
• PySys_FormatStdout()
• PySys_GetObject()
• PySys_GetXOptions()
• PySys_HasWarnOptions()
• PySys_ResetWarnOptions()
• PySys_SetArgv()
• PySys_SetArgvEx()
• PySys_SetObject()
• PySys_SetPath()
• PySys_WriteStderr()
• PySys_WriteStdout()
• PyThreadState
• PyThreadState_Clear()
• PyThreadState_Delete()
• PyThreadState_Get()
• PyThreadState_GetDict()
• PyThreadState_GetFrame()
• PyThreadState_GetID()
• PyThreadState_GetInterpreter()
• PyThreadState_New()

32 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyThreadState_SetAsyncExc()
• PyThreadState_Swap()
• PyThread_GetInfo()
• PyThread_ReInitTLS()
• PyThread_acquire_lock()
• PyThread_acquire_lock_timed()
• PyThread_allocate_lock()
• PyThread_create_key()
• PyThread_delete_key()
• PyThread_delete_key_value()
• PyThread_exit_thread()
• PyThread_free_lock()
• PyThread_get_key_value()
• PyThread_get_stacksize()
• PyThread_get_thread_ident()
• PyThread_get_thread_native_id()
• PyThread_init_thread()
• PyThread_release_lock()
• PyThread_set_key_value()
• PyThread_set_stacksize()
• PyThread_start_new_thread()
• PyThread_tss_alloc()
• PyThread_tss_create()
• PyThread_tss_delete()
• PyThread_tss_free()
• PyThread_tss_get()
• PyThread_tss_is_created()
• PyThread_tss_set()
• PyTraceBack_Here()
• PyTraceBack_Print()
• PyTraceBack_Type
• PyTupleIter_Type
• PyTuple_GetItem()
• PyTuple_GetSlice()
• PyTuple_New()
• PyTuple_Pack()
• PyTuple_SetItem()
• PyTuple_Size()
• PyTuple_Type

2.3. Contenido de la API limitada 33

The Python/C API, Versión 3.11.0

• PyTypeObject
• PyType_ClearCache()
• PyType_FromModuleAndSpec()
• PyType_FromSpec()
• PyType_FromSpecWithBases()
• PyType_GenericAlloc()
• PyType_GenericNew()
• PyType_GetFlags()
• PyType_GetModule()
• PyType_GetModuleState()
• PyType_GetName()
• PyType_GetQualName()
• PyType_GetSlot()
• PyType_IsSubtype()
• PyType_Modified()
• PyType_Ready()
• PyType_Slot
• PyType_Spec
• PyType_Type
• PyUnicodeDecodeError_Create()
• PyUnicodeDecodeError_GetEncoding()
• PyUnicodeDecodeError_GetEnd()
• PyUnicodeDecodeError_GetObject()
• PyUnicodeDecodeError_GetReason()
• PyUnicodeDecodeError_GetStart()
• PyUnicodeDecodeError_SetEnd()
• PyUnicodeDecodeError_SetReason()
• PyUnicodeDecodeError_SetStart()
• PyUnicodeEncodeError_GetEncoding()
• PyUnicodeEncodeError_GetEnd()
• PyUnicodeEncodeError_GetObject()
• PyUnicodeEncodeError_GetReason()
• PyUnicodeEncodeError_GetStart()
• PyUnicodeEncodeError_SetEnd()
• PyUnicodeEncodeError_SetReason()
• PyUnicodeEncodeError_SetStart()
• PyUnicodeIter_Type
• PyUnicodeTranslateError_GetEnd()
• PyUnicodeTranslateError_GetObject()

34 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyUnicodeTranslateError_GetReason()
• PyUnicodeTranslateError_GetStart()
• PyUnicodeTranslateError_SetEnd()
• PyUnicodeTranslateError_SetReason()
• PyUnicodeTranslateError_SetStart()
• PyUnicode_Append()
• PyUnicode_AppendAndDel()
• PyUnicode_AsASCIIString()
• PyUnicode_AsCharmapString()
• PyUnicode_AsDecodedObject()
• PyUnicode_AsDecodedUnicode()
• PyUnicode_AsEncodedObject()
• PyUnicode_AsEncodedString()
• PyUnicode_AsEncodedUnicode()
• PyUnicode_AsLatin1String()
• PyUnicode_AsMBCSString()
• PyUnicode_AsRawUnicodeEscapeString()
• PyUnicode_AsUCS4()
• PyUnicode_AsUCS4Copy()
• PyUnicode_AsUTF16String()
• PyUnicode_AsUTF32String()
• PyUnicode_AsUTF8AndSize()
• PyUnicode_AsUTF8String()
• PyUnicode_AsUnicodeEscapeString()
• PyUnicode_AsWideChar()
• PyUnicode_AsWideCharString()
• PyUnicode_BuildEncodingMap()
• PyUnicode_Compare()
• PyUnicode_CompareWithASCIIString()
• PyUnicode_Concat()
• PyUnicode_Contains()
• PyUnicode_Count()
• PyUnicode_Decode()
• PyUnicode_DecodeASCII()
• PyUnicode_DecodeCharmap()
• PyUnicode_DecodeCodePageStateful()
• PyUnicode_DecodeFSDefault()
• PyUnicode_DecodeFSDefaultAndSize()
• PyUnicode_DecodeLatin1()

2.3. Contenido de la API limitada 35

The Python/C API, Versión 3.11.0

• PyUnicode_DecodeLocale()
• PyUnicode_DecodeLocaleAndSize()
• PyUnicode_DecodeMBCS()
• PyUnicode_DecodeMBCSStateful()
• PyUnicode_DecodeRawUnicodeEscape()
• PyUnicode_DecodeUTF16()
• PyUnicode_DecodeUTF16Stateful()
• PyUnicode_DecodeUTF32()
• PyUnicode_DecodeUTF32Stateful()
• PyUnicode_DecodeUTF7()
• PyUnicode_DecodeUTF7Stateful()
• PyUnicode_DecodeUTF8()
• PyUnicode_DecodeUTF8Stateful()
• PyUnicode_DecodeUnicodeEscape()
• PyUnicode_EncodeCodePage()
• PyUnicode_EncodeFSDefault()
• PyUnicode_EncodeLocale()
• PyUnicode_FSConverter()
• PyUnicode_FSDecoder()
• PyUnicode_Find()
• PyUnicode_FindChar()
• PyUnicode_Format()
• PyUnicode_FromEncodedObject()
• PyUnicode_FromFormat()
• PyUnicode_FromFormatV()
• PyUnicode_FromObject()
• PyUnicode_FromOrdinal()
• PyUnicode_FromString()
• PyUnicode_FromStringAndSize()
• PyUnicode_FromWideChar()
• PyUnicode_GetDefaultEncoding()
• PyUnicode_GetLength()
• PyUnicode_GetSize()
• PyUnicode_InternFromString()
• PyUnicode_InternImmortal()
• PyUnicode_InternInPlace()
• PyUnicode_IsIdentifier()
• PyUnicode_Join()
• PyUnicode_Partition()

36 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• PyUnicode_RPartition()
• PyUnicode_RSplit()
• PyUnicode_ReadChar()
• PyUnicode_Replace()
• PyUnicode_Resize()
• PyUnicode_RichCompare()
• PyUnicode_Split()
• PyUnicode_Splitlines()
• PyUnicode_Substring()
• PyUnicode_Tailmatch()
• PyUnicode_Translate()
• PyUnicode_Type
• PyUnicode_WriteChar()
• PyVarObject
• PyVarObject.ob_base
• PyVarObject.ob_size
• PyWeakReference
• PyWeakref_GetObject()
• PyWeakref_NewProxy()
• PyWeakref_NewRef()
• PyWrapperDescr_Type
• PyWrapper_New()
• PyZip_Type
• Py_AddPendingCall()
• Py_AtExit()
• Py_BEGIN_ALLOW_THREADS
• Py_BLOCK_THREADS
• Py_BuildValue()
• Py_BytesMain()
• Py_CompileString()
• Py_DecRef()
• Py_DecodeLocale()
• Py_END_ALLOW_THREADS
• Py_EncodeLocale()
• Py_EndInterpreter()
• Py_EnterRecursiveCall()
• Py_Exit()
• Py_FatalError()
• Py_FileSystemDefaultEncodeErrors

2.3. Contenido de la API limitada 37

The Python/C API, Versión 3.11.0

• Py_FileSystemDefaultEncoding
• Py_Finalize()
• Py_FinalizeEx()
• Py_GenericAlias()
• Py_GenericAliasType
• Py_GetBuildInfo()
• Py_GetCompiler()
• Py_GetCopyright()
• Py_GetExecPrefix()
• Py_GetPath()
• Py_GetPlatform()
• Py_GetPrefix()
• Py_GetProgramFullPath()
• Py_GetProgramName()
• Py_GetPythonHome()
• Py_GetRecursionLimit()
• Py_GetVersion()
• Py_HasFileSystemDefaultEncoding
• Py_IncRef()
• Py_Initialize()
• Py_InitializeEx()
• Py_Is()
• Py_IsFalse()
• Py_IsInitialized()
• Py_IsNone()
• Py_IsTrue()
• Py_LeaveRecursiveCall()
• Py_Main()
• Py_MakePendingCalls()
• Py_NewInterpreter()
• Py_NewRef()
• Py_ReprEnter()
• Py_ReprLeave()
• Py_SetPath()
• Py_SetProgramName()
• Py_SetPythonHome()
• Py_SetRecursionLimit()
• Py_UCS4
• Py_UNBLOCK_THREADS

38 Capítulo 2. Estabilidad de la API en C

 The Python/C API, Versión 3.11.0

• Py_UTF8Mode
• Py_VaBuildValue()
• Py_Version
• Py_XNewRef()
• Py_buffer
• Py_intptr_t
• Py_ssize_t
• Py_uintptr_t
• allocfunc
• binaryfunc
• descrgetfunc
• descrsetfunc
• destructor
• getattrfunc
• getattrofunc
• getiterfunc
• getter
• hashfunc
• initproc
• inquiry
• iternextfunc
• lenfunc
• newfunc
• objobjargproc
• objobjproc
• reprfunc
• richcmpfunc
• setattrfunc
• setattrofunc
• setter
• ssizeargfunc
• ssizeobjargproc
• ssizessizeargfunc
• ssizessizeobjargproc
• symtable
• ternaryfunc
• traverseproc
• unaryfunc
• visitproc

2.3. Contenido de la API limitada 39

The Python/C API, Versión 3.11.0

40 Capítulo 2. Estabilidad de la API en C

 CAPÍTULO 3

La capa de muy alto nivel

Las funciones en este capítulo te permitirán ejecutar código fuente de Python desde un archivo o un búfer, pero no
te permitirán interactuar de una manera detallada con el intérprete.
Varias de estas funciones aceptan un símbolo de inicio de la gramática como parámetro. Los símbolos de inicio
disponibles son Py_eval_input, Py_file_input, y Py_single_input. Estos se describen siguiendo las
funciones que los aceptan como parámetros.
Note also that several of these functions take FILE* parameters. One particular issue which needs to be handled
carefully is that the FILE structure for different C libraries can be different and incompatible. Under Windows (at
least), it is possible for dynamically linked extensions to actually use different libraries, so care should be taken that
FILE* parameters are only passed to these functions if it is certain that they were created by the same library that
the Python runtime is using.
int Py_Main(int argc, wchar_t **argv)
Part of the Stable ABI. El programa principal para el intérprete estándar. Está disponible para programas que
incorporan Python. Los parámetros argc y argv deben prepararse exactamente como los que se pasan a la
función main() de un programa en C (convertido a wchar_t de acuerdo con la configuración regional del
usuario). Es importante tener en cuenta que la lista de argumentos puede ser modificada (pero el contenido
de las cadenas de caracteres señaladas por la lista de argumentos no lo es). El valor de retorno será 0 si el
intérprete acaba normalmente (es decir, sin excepción), 1 si el intérprete acaba debido a una excepción, o 2 si
la lista de parámetros no representa una línea de comando Python válida.
Tenga en cuenta que si se lanza un SystemExit no manejado, esta función no retornará 1, pero saldrá del
proceso, siempre que Py_InspectFlag no esté configurado.
int Py_BytesMain(int argc, char **argv)
Part of the Stable ABI since version 3.8. Similar a Py_Main() pero argv es un arreglo de cadenas de caracteres
de bytes.
Nuevo en la versión 3.8.
int PyRun_AnyFile(FILE *fp, const char *filename)
Esta es una interfaz simplificada para PyRun_AnyFileExFlags() más abajo, dejando closeit establecido
a 0 y flags establecido a NULL.
int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Esta es una interfaz simplificada para PyRun_AnyFileExFlags() más abajo, dejando closeit establecido
a 0.

41
The Python/C API, Versión 3.11.0

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

Esta es una interfaz simplificada para PyRun_AnyFileExFlags() más abajo, dejando flags establecido
a NULL.
int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
If fp refers to a file associated with an interactive device (console or terminal input or Unix
pseudo-terminal), return the value of PyRun_InteractiveLoop(), otherwise return the re-
sult of PyRun_SimpleFile(). filename is decoded from the filesystem encoding (sys.
getfilesystemencoding()). If filename is NULL, this function uses "???" as the filename. If
closeit is true, the file is closed before PyRun_SimpleFileExFlags() returns.
int PyRun_SimpleString(const char *command)
This is a simplified interface to PyRun_SimpleStringFlags() below, leaving the
PyCompilerFlags* argument set to NULL.
int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
Ejecuta el código fuente de Python desde command en el módulo __main__ de acuerdo con el argumento
flags. Si __main__ aún no existe, se crea. Retorna 0 en caso de éxito o -1 si se produjo una excepción. Si
hubo un error, no hay forma de obtener la información de excepción. Para el significado de flags, ver abajo.
Tenga en cuenta que si no se maneja de otro modo SystemExit, esta función no retornará -1, pero saldrá
del proceso, siempre que Py_InspectFlag no esté configurado.
int PyRun_SimpleFile(FILE *fp, const char *filename)
Esta es una interfaz simplificada para PyRun_SimpleStringFlags() más abajo, dejando closeit esta-
blecido a 0 y flags establecido a NULL.
int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
Esta es una interfaz simplificada para PyRun_SimpleStringFlags() más abajo, dejando flags estable-
cido a NULL.
int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
Similar a PyRun_SimpleStringFlags(), pero el código fuente de Python se lee desde fp en lu-
gar de una cadena de caracteres en memoria. filename debe ser el nombre del fichero, se decodifica
desde filesystem encoding and error handler. Si closeit es verdadero, el fichero se cierra antes de que
PyRun_SimpleFileExFlags() retorne.

Nota: En Windows, fp debe abrirse en modo binario (por ejemplo, fopen(filename, "rb"). De lo
contrario, Python puede no manejar correctamente el archivo de script con la terminación de línea LF.

int PyRun_InteractiveOne(FILE *fp, const char *filename)

Esta es una interfaz simplificada para PyRun_InteractiveOneFlags() más abajo, dejando flags es-
tablecido a NULL.
int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Lee y ejecuta declaraciones de un archivo asociado con un dispositivo interactivo de acuerdo al argumento
flags. Se le solicitará al usuario usando sys.ps1 y sys.ps2. filename se decodifica a partir del manejador
de codificación y errores del sistema de archivos.
Retorna 0 cuando la entrada se ejecuta con éxito, -1 si hubo una excepción, o un código de error del archivo
errcode.h distribuido como parte de Python si hubo un error de análisis gramatical. (Tenga en cuenta que
errcode.h no está incluido en Python.h, por lo que debe incluirse específicamente si es necesario).
int PyRun_InteractiveLoop(FILE *fp, const char *filename)
Esta es una interfaz simplificada para PyRun_InteractiveLoopFlags() más abajo, dejando flags
establecido a NULL.
int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Lee y ejecuta declaraciones de un archivo asociado con un dispositivo interactivo hasta llegar al EOF. Se
le solicitará al usuario usando sys.ps1 y sys.ps2.*filename* se decodifica a partir del manejador de
codificación y errores del sistema de archivos. Retorna 0 en EOF o un número negativo en caso de falla.

42 Capítulo 3. La capa de muy alto nivel

 The Python/C API, Versión 3.11.0

int (*PyOS_InputHook)(void)
Part of the Stable ABI. Se puede configurar para que apunte a una función con el prototipo int
func(void). Se llamará a la función cuando el indicador del intérprete de Python esté a punto de estar
inactivo y espere la entrada del usuario desde el terminal. El valor de retorno es ignorado. Sobrescribiendo este
enlace se puede utilizar para integrar la solicitud del intérprete con otros bucles de eventos, como se hace en
Modules/_tkinter.c en el código fuente de Python.
char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)
Se puede configurar para que apunte a una función con el prototipo char *func (FILE *stdin,
FILE *stdout, char *prompt), sobrescribiendo la función predeterminada utilizada para leer una
sola línea de entrada desde el intérprete. Se espera que la función genere la cadena de caracteres prompt si
no es NULL, y luego lea una línea de entrada del archivo de entrada estándar proporcionado, retornando la
cadena de caracteres resultante. Por ejemplo, el módulo readline establece este enlace para proporcionar
funciones de edición de línea y finalización de tabulación.
El resultado debe ser una cadena de caracteres alocado por PyMem_RawMalloc() o
PyMem_RawRealloc(), o NULL si ocurre un error.
Distinto en la versión 3.4: El resultado debe ser alocado por PyMem_RawMalloc() o
PyMem_RawRealloc(), en vez de ser alocado por PyMem_Malloc() o PyMem_Realloc().
PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
Return value: New reference. Esta es una interfaz simplificada para PyRun_StringFlags() más abajo,
dejando flags establecido a NULL.
PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals,
PyCompilerFlags *flags)
Return value: New reference. Ejecuta el código fuente de Python desde str en el contexto especificado por los
objetos globals y locals con los indicadores del compilador especificados por flags. globals debe ser un diccio-
nario; locals puede ser cualquier objeto que implemente el protocolo de mapeo. El parámetro start especifica
el token de inicio que se debe usar para analizar el código fuente.
Retorna el resultado de ejecutar el código como un objeto Python, o NULL” si se produjo una excepción.
PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
Return value: New reference. Esta es una interfaz simplificada para PyRun_FileExFlags() más abajo,
dejando closeit establecido a 0 y flags establecido a NULL.
PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int
closeit)
Return value: New reference. Esta es una interfaz simplificada para PyRun_FileExFlags() más abajo,
dejando flags establecido a NULL.
PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals,
PyCompilerFlags *flags)
Return value: New reference. Esta es una interfaz simplificada para PyRun_FileExFlags() más abajo,
dejando closeit establecido a 0.
PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals,
int closeit, PyCompilerFlags *flags)
Return value: New reference. Similar a PyRun_StringFlags(), pero el código fuente de Python se lee
de fp en lugar de una cadena de caracteres en memoria. filename debe ser el nombre del fichero, es decodifi-
cado desde el filesystem encoding and error handler. Si closeit es verdadero, el fichero se cierra antes de que
PyRun_FileExFlags() retorne.
PyObject *Py_CompileString(const char *str, const char *filename, int start)
Return value: New reference. Part of the Stable ABI. Esta es una interfaz simplificada para
Py_CompileStringFlags() más abajo, dejando flags establecido a NULL.
PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
Return value: New reference. Esta es una interfaz simplificada para Py_CompileStringExFlags() más
abajo, con optimize establecido a -1.

43
The Python/C API, Versión 3.11.0

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags,
int optimize)
Return value: New reference. Analiza gramaticalmente y compila el código fuente de Python en str, retornando
el objeto de código resultante. El token de inicio viene dado por start; esto se puede usar para restringir el
código que se puede compilar y debe ser Py_eval_input, Py_file_input, o Py_single_input.
El nombre de archivo especificado por filename se usa para construir el objeto de código y puede aparecer en
tracebacks o mensajes de excepción SyntaxError. Esto retorna NULL” si el código no se puede analizar
gramaticalmente o compilar.
El número entero optimize especifica el nivel de optimización del compilador; un valor de -1 selecciona el nivel
de optimización del intérprete como se indica en las opciones -O. Los niveles explícitos son 0 (sin optimización;
__debug__ es verdadero), 1 (los asserts se eliminan, __debug__ es falso) o 2 (los docstrings también se
eliminan) )
Nuevo en la versión 3.4.
PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags
*flags, int optimize)
Return value: New reference. Como Py_CompileStringObject(), pero filename es una cadena de bytes
decodificada a partir del manejador de codificación y errores del sistema de archivos.
Nuevo en la versión 3.2.
PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
Return value: New reference. Part of the Stable ABI. Esta es una interfaz simplificada para
PyEval_EvalCodeEx(), con solo el objeto de código y las variables globales y locales. Los otros ar-
gumentos están establecidos en NULL.
PyObject *PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int
argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int
defcount, PyObject *kwdefs, PyObject *closure)
Return value: New reference. Part of the Stable ABI. Evaluar un objeto de código precompilado, dado un
entorno particular para su evaluación. Este entorno consta de un diccionario de variables globales, un objeto de
mapeo de variables locales, arreglos de argumentos, palabras clave y valores predeterminados, un diccionario
de valores predeterminados para argumentos keyword-only y una tupla de cierre de células.
PyObject *PyEval_EvalFrame(PyFrameObject *f)
Return value: New reference. Part of the Stable ABI. Evaluar un marco de ejecución. Esta es una interfaz
simplificada para PyEval_EvalFrameEx(), para compatibilidad con versiones anteriores.
PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
Return value: New reference. Part of the Stable ABI. Esta es la función principal sin barnizar de la interpretación
de Python. El objeto de código asociado con el marco de ejecución del marco f se ejecuta, interpretando el
código de bytes y ejecutando llamadas según sea necesario. El parámetro adicional throwflag se puede ignorar
por lo general; si es verdadero, entonces se lanza una excepción de inmediato; esto se usa para los métodos
throw() de objetos generadores.
Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar
que no descarte silenciosamente una excepción activa.
int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
Esta función cambia los flags del marco de evaluación actual, y retorna verdad (true) en caso de éxito, falso
(false) en caso de fallo.
int Py_eval_input
El símbolo de inicio de la gramática de Python para expresiones aisladas; para usar con
Py_CompileString().
int Py_file_input
El símbolo de inicio de la gramática de Python para secuencias de declaración leídos desde un archivo u otra
fuente; para usar con Py_CompileString(). Este es el símbolo usado cuando se compile un código fuente
en Python arbitrariamente largo.

44 Capítulo 3. La capa de muy alto nivel

 The Python/C API, Versión 3.11.0

int Py_single_input
El símbolo de inicio de la gramática de Python para una declaración única; para usar con
Py_CompileString(). Este es el símbolo usado para el bucle interactivo del intérprete.
struct PyCompilerFlags
Esta es la estructura usada para contener los flags del compilador. En casos donde el código es sólo compilado,
es pasado como int flags, y en casos donde el código es ejecutado, es pasado como PyCompilerFlags
*flags. En este caso, from __future__ import puede modificar los flags.
Siempre y cuando PyCompilerFlags *flags es NULL, cf_flags es tratado como igual a 0, y cual-
quier modificación debido a from __future__ import es descartada.
int cf_flags
Flags del compilador.
int cf_feature_version
cf_feature_version es la versión menor de Python. Debe ser inicializado a PY_MINOR_VERSION.
El campo es ignorado por defecto, es usado si y solo si el flag PyCF_ONLY_AST está configurado en
cf_flags.
Distinto en la versión 3.8: Agregado el campo cf_feature_version.
int CO_FUTURE_DIVISION
Este bit puede ser configurado en flags para causar que un operador de división / sea interpretado como una
«división real» de acuerdo a PEP 238.

45
The Python/C API, Versión 3.11.0

46 Capítulo 3. La capa de muy alto nivel

 CAPÍTULO 4

Conteo de referencias

Los macros de esta sección se utilizan para administrar conteos de referencia de objetos Python.
void Py_INCREF(PyObject *o)
Incrementar el recuento de referencia para el objeto o.
Esta función se usa generalmente para convertir un borrowed reference en un strong reference en su lugar. La
función Py_NewRef() se puede utilizar para crear un nuevo strong reference.
El objeto no debe ser NULL; si no está seguro de que no sea NULL, use Py_XINCREF().
void Py_XINCREF(PyObject *o)
Incrementa el conteo de referencia para el objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene
efecto.
Ver también Py_XNewRef().
PyObject *Py_NewRef(PyObject *o)
Part of the Stable ABI since version 3.10. Crea un nuevo strong reference a un objeto: incrementa el recuento
de referencias del objeto o y retorna el objeto o.
Cuando el strong reference ya no sea necesario Py_DECREF() debe ser llamado para disminuir el recuento
de referencias del objeto.
El objeto o no debe ser NULL; use Py_XNewRef() si o puede ser NULL.
Por ejemplo:

Py_INCREF(obj);
self->attr = obj;

puede ser escrito como:

self->attr = Py_NewRef(obj);

Ver también Py_INCREF().

Nuevo en la versión 3.10.
PyObject *Py_XNewRef(PyObject *o)
Part of the Stable ABI since version 3.10. Similar a Py_NewRef(), pero el objeto o puede ser NULL.
Si el objeto o es NULL, la función solo retorna NULL.

47
The Python/C API, Versión 3.11.0

Nuevo en la versión 3.10.

void Py_DECREF(PyObject *o)
Decrementa el conteo de referencia para el objeto o.
Si el recuento de referencias llega a cero, se invoca la función de desasignación del tipo de objeto (que no debe
ser NULL).
Esta función se usa generalmente para eliminar un strong reference antes de salir de su alcance.
El objeto no debe ser NULL; si no está seguro de que no sea NULL, use Py_XINCREF().

Advertencia: La función de desasignación puede hacer que se invoque un código arbitrario de Python (por
ejemplo, cuando se desasigna una instancia de clase con un método __del__()). Si bien las excepciones
en dicho código no se propagan, el código ejecutado tiene acceso libre a todas las variables globales de
Python. Esto significa que cualquier objeto al que se pueda acceder desde una variable global debe estar en
un estado coherente antes de invocar Py_DECREF(). Por ejemplo, el código para eliminar un objeto de
una lista debe copiar una referencia al objeto eliminado en una variable temporal, actualizar la estructura
de datos de la lista y luego llamar a Py_DECREF() para la variable temporal.

void Py_XDECREF(PyObject *o)

Disminuye el conteo de referencia para el objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene
efecto; de lo contrario, el efecto es el mismo que para Py_DECREF(), y se aplica la misma advertencia.
void Py_CLEAR(PyObject *o)
Disminuye el conteo de referencia para el objeto o. El objeto puede ser NULL, en cuyo caso el macro no tiene
efecto; de lo contrario, el efecto es el mismo que para Py_DECREF(), excepto que el argumento también se
establece en NULL. La advertencia para Py_DECREF() no se aplica con respecto al objeto pasado porque
el macro usa cuidadosamente una variable temporal y establece el argumento en NULL antes de disminuir su
conteo de referencia.
Es una buena idea usar este macro siempre que disminuya el conteo de referencia de un objeto que pueda
atravesarse durante la recolección de basura.
void Py_IncRef(PyObject *o)
Part of the Stable ABI. Incrementa el conteo de referencias para objeto o. Una versión de la función
Py_XINCREF(). Puede utilizarse para la integración dinámica en tiempo de ejecución de Python.
void Py_DecRef(PyObject *o)
Part of the Stable ABI. Disminuye el conteo de referencias del objeto o. Una versión de la función
Py_XDECREF(). Puede utilizarse para la integración dinámica en tiempo de ejecución de Python.
Las siguientes funciones o macros son solo para uso dentro del núcleo del intérprete: _Py_Dealloc(),
_Py_ForgetReference(), _Py_NewReference(), así como la variable global _Py_RefTotal.

48 Capítulo 4. Conteo de referencias

 CAPÍTULO 5

Manejo de excepciones

Las funciones descritas en este capítulo le permitirán manejar y lanzar excepciones de Python. Es importante com-
prender algunos de los conceptos básicos del manejo de excepciones de Python. Funciona de manera similar a la
variable POSIX errno: hay un indicador global (por hilo) del último error que ocurrió. La mayoría de las funciones
de C API no borran esto en caso de éxito, pero lo configurarán para indicar la causa del error en caso de falla. La
mayoría de las funciones de C API también retornan un indicador de error, generalmente NULL si se supone que
retornan un puntero, o -1 si retornan un número entero (excepción: las funciones PyArg_* retornan 1 para el éxito
y 0 para el fracaso).
Concretamente, el indicador de error consta de tres punteros de objeto: el tipo de excepción, el valor de la excep-
ción y el objeto de rastreo. Cualquiera de esos punteros puede ser NULL si no está configurado (aunque algunas
combinaciones están prohibidas, por ejemplo, no puede tener un rastreo no NULL si el tipo de excepción es NULL).
Cuando una función debe fallar porque alguna función que llamó falló, generalmente no establece el indicador de
error; la función que llamó ya lo configuró. Es responsable de manejar el error y borrar la excepción o regresar
después de limpiar cualquier recurso que tenga (como referencias de objetos o asignaciones de memoria); debería
no continuar normalmente si no está preparado para manejar el error. Si regresa debido a un error, es importante
indicarle a la persona que llama que se ha establecido un error. Si el error no se maneja o se propaga cuidadosamente,
es posible que las llamadas adicionales a la API de Python/C no se comporten como se espera y pueden fallar de
manera misteriosa.

Nota: El indicador de error es no el resultado de sys.exc_info(). El primero corresponde a una excepción

que aún no se detecta (y, por lo tanto, todavía se está propagando), mientras que el segundo retorna una excepción
después de que se detecta (y, por lo tanto, ha dejado de propagarse).

5.1 Impresión y limpieza

void PyErr_Clear()
Part of the Stable ABI. Borra el indicador de error. Si el indicador de error no está configurado, no hay efecto.
void PyErr_PrintEx(int set_sys_last_vars)
Part of the Stable ABI. Imprime un rastreo estándar en sys.stderr y borra el indicador de error. A menos
que el error sea un Salida del sistema, en ese caso no se imprime ningún rastreo y el proceso de
Python se cerrará con el código de error especificado por la instancia de Salida del sistema.

49
The Python/C API, Versión 3.11.0

Llame a esta función solo cuando el indicador de error está configurado. De lo contrario, provocará un error
fatal!
Si set_sys_last_vars no es cero, las variables sys.last_type, sys.last_value y sys.
last_traceback se establecerán en el tipo, valor y rastreo de la excepción impresa, respectivamente.
void PyErr_Print()
Part of the Stable ABI. Alias para PyErr_PrintEx(1).
void PyErr_WriteUnraisable(PyObject *obj)
Part of the Stable ABI. Llama sys.unraisablehook() utilizando la excepción actual y el argumento
obj.
Esta función de utilidad imprime un mensaje de advertencia en sys.stderr cuando se ha establecido una
excepción, pero es imposible que el intérprete la active. Se usa, por ejemplo, cuando ocurre una excepción en
un método __del__().
La función se llama con un solo argumento obj que identifica el contexto en el que ocurrió la excepción que no
se evalúa. Si es posible, la repr obj se imprimirá en el mensaje de advertencia.
Se debe establecer una excepción al llamar a esta función.

5.2 Lanzando excepciones

Estas funciones lo ayudan a configurar el indicador de error del hilo actual. Por conveniencia, algunas de estas fun-
ciones siempre retornarán un puntero NULL para usar en una declaración return.
void PyErr_SetString(PyObject *type, const char *message)
Part of the Stable ABI. Esta es la forma más común de configurar el indicador de error. El primer ar-
gumento especifica el tipo de excepción; Normalmente es una de las excepciones estándar, por ejemplo
PyExc_RuntimeError. No necesita incrementar su recuento de referencia. El segundo argumento es un
mensaje de error; se decodifica a partir de 'utf-8'.
void PyErr_SetObject(PyObject *type, PyObject *value)
Part of the Stable ABI. Esta función es similar a PyErr_SetString() pero le permite especificar un objeto
Python arbitrario para el «valor» de la excepción.
PyObject *PyErr_Format(PyObject *exception, const char *format, ...)
Return value: Always NULL. Part of the Stable ABI. Esta función establece el indicador de error y retorna
NULL. exception debe ser una clase de excepción Python. El format y los parámetros posteriores ayudan a
formatear el mensaje de error; tienen el mismo significado y valores que en PyUnicode_FromFormat().
format es una cadena de caracteres codificada en ASCII.
PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
Return value: Always NULL. Part of the Stable ABI since version 3.5. Igual que PyErr_Format(), pero
tomando un argumento va_list en lugar de un número variable de argumentos.
Nuevo en la versión 3.5.
void PyErr_SetNone(PyObject *type)
Part of the Stable ABI. Esta es una abreviatura de PyErr_SetObject(type, Py_None).
int PyErr_BadArgument()
Part of the Stable ABI. Esta es una abreviatura de PyErr_SetString(PyExc_TypeError,
message), donde message indica que se invocó una operación incorporada con un argumento ilegal. Es
principalmente para uso interno.
PyObject *PyErr_NoMemory()
Return value: Always NULL. Part of the Stable ABI. Esta es una abreviatura de
PyErr_SetNone(PyExc_MemoryError); retorna NULL para que una función de asignación de
objetos pueda escribir return PyErr_NoMemory(); cuando se queda sin memoria.

50 Capítulo 5. Manejo de excepciones

 The Python/C API, Versión 3.11.0

PyObject *PyErr_SetFromErrno(PyObject *type)

Return value: Always NULL. Part of the Stable ABI. Esta es una función conveniente para lanzar una excepción
cuando una función de biblioteca C ha retornado un error y establece la variable C errno. Construye un
objeto tupla cuyo primer elemento es el valor entero errno y cuyo segundo elemento es el mensaje de error
correspondiente (obtenido de strerror()), y luego llama a PyErr_SetObject(type , objeto).
En Unix, cuando el valor errno es EINTR, que indica una llamada interrumpida del sistema, esto llama
PyErr_CheckSignals(), y si eso establece el indicador de error, lo deja configurado a ese. La función
siempre retorna NULL, por lo que una función envolvente alrededor de una llamada del sistema puede escribir
return PyErr_SetFromErrno (type); cuando la llamada del sistema retorna un error.
PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
Return value: Always NULL. Part of the Stable ABI. Similar a PyErr_SetFromErrno(), con el com-
portamiento adicional de que si filenameObject * no es “NULL“, se pasa al constructor de *type como tercer
parámetro. En el caso de la excepción OSError, se utiliza para definir el atributo filename de la instancia
de excepción.
PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject,
PyObject *filenameObject2)
Return value: Always NULL. Part of the Stable ABI since version 3.7. Similar a
PyErr_SetFromErrnoWithFilenameObject(), pero toma un segundo objeto de nombre de
archivo, para lanzar errores cuando falla una función que toma dos nombres de archivo.
Nuevo en la versión 3.4.
PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Return value: Always NULL. Part of the Stable ABI. Similar a PyErr_SetFromErrnoWithFilenameObject(),
pero el nombre del archivo se da como una cadena de caracteres de C. filename se decodifica a partir de la
codificación de filesystem encoding and error handler.
PyObject *PyErr_SetFromWindowsErr(int ierr)
Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7. Esta es una función con-
veniente para lanzar WindowsError. Si se llama con ierr de 0, el código de error retornado por una
llamada a GetLastError() se usa en su lugar. Llama a la función Win32 FormatMessage() para
recuperar la descripción de Windows del código de error proporcionado por ierr o GetLastError(),
luego construye un objeto de tupla cuyo primer elemento es el ierr valor y cuyo segundo ele-
mento es el mensaje de error correspondiente (obtenido de FormatMessage()), y luego llama a
PyErr_SetObject(PyExc_WindowsError, object). Esta función siempre retorna NULL.
Disponibilidad: Windows.
PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7. Similar a
PyErr_SetFromWindowsErr(), con un parámetro adicional que especifica el tipo de excepción que
se lanzará.
Disponibilidad: Windows.
PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7. Similar a
PyErr_SetFromWindowsErrWithFilenameObject(), pero el nombre del archivo se da como una
cadena de caracteres de C. filename se decodifica a partir de la codificación del sistema de archivos (os.
fsdecode()).
Disponibilidad: Windows.
PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject
*filename)
Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7. Similar a
PyErr_SetFromWindowsErrWithFilenameObject(), con un parámetro adicional que especifi-
ca el tipo de excepción que se lanzará.
Disponibilidad: Windows.

5.2. Lanzando excepciones 51

The Python/C API, Versión 3.11.0

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject

*filename, PyObject *filename2)
Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7. Similar a
PyErr_SetExcFromWindowsErrWithFilenameObject(), pero acepta un segundo objeto de
nombre de archivo.
Disponibilidad: Windows.
Nuevo en la versión 3.4.
PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char
*filename)
Return value: Always NULL. Part of the Stable ABI on Windows since version 3.7. Similar a
PyErr_SetFromWindowsErrWithFilename(), con un parámetro adicional que especifica el tipo
de excepción que se lanzará.
Disponibilidad: Windows.
PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
Return value: Always NULL. Part of the Stable ABI since version 3.7. Esta es una función conveniente para subir
ImportError. msg se establecerá como la cadena de mensaje de la excepción. name y path, que pueden ser
NULL, se establecerán como atributos respectivos name y path de ImportError.
Nuevo en la versión 3.3.
PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name,
PyObject *path)
Return value: Always NULL. Part of the Stable ABI since version 3.6. Al igual que
PyErr_SetImportError() pero esta función permite especificar una subclase de ImportError para
aumentar.
Nuevo en la versión 3.6.
void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
Establece información de archivo, línea y desplazamiento para la excepción actual. Si la excepción actual no es
un SyntaxError, establece atributos adicionales, lo que hace que el sub sistema de impresión de excepciones
piense que la excepción es SyntaxError.
Nuevo en la versión 3.4.
void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
Part of the Stable ABI since version 3.7. Como PyErr_SyntaxLocationObject(), pero filename es
una cadena de bytes decodificada a partir de filesystem encoding and error handler.
Nuevo en la versión 3.2.
void PyErr_SyntaxLocation(const char *filename, int lineno)
Part of the Stable ABI. Como PyErr_SyntaxLocationEx(), pero se omite el parámetro col_offset.
void PyErr_BadInternalCall()
Part of the Stable ABI. Esta es una abreviatura de PyErr_SetString(PyExc_SystemError,
message), donde message indica que se invocó una operación interna (por ejemplo, una función de Pyt-
hon/C API) con un argumento ilegal. Es principalmente para uso interno.

52 Capítulo 5. Manejo de excepciones

 The Python/C API, Versión 3.11.0

5.3 Emitir advertencias

Use estas funciones para emitir advertencias desde el código C. Reflejan funciones similares exportadas por el módulo
Python warnings. Normalmente imprimen un mensaje de advertencia a sys.stderr; sin embargo, también es posible
que el usuario haya especificado que las advertencias se conviertan en errores, y en ese caso lanzarán una excepción.
También es posible que las funciones generen una excepción debido a un problema con la maquinaria de advertencia.
El valor de retorno es 0 si no se lanza una excepción, o -1 si se lanza una excepción. (No es posible determinar
si realmente se imprime un mensaje de advertencia, ni cuál es el motivo de la excepción; esto es intencional). Si se
produce una excepción, la persona que llama debe hacer su manejo normal de excepciones (por ejemplo, referencias
propiedad de Py_DECREF() y retornan un valor de error).
int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)
Part of the Stable ABI. Emite un mensaje de advertencia. El argumento category es una categoría de advertencia
(ver más abajo) o NULL; el argumento message es una cadena de caracteres codificada en UTF-8. stack_level
es un número positivo que proporciona una cantidad de marcos de pila; la advertencia se emitirá desde la línea
de código que se está ejecutando actualmente en ese marco de pila. Un stack_level de 1 es la función que llama
PyErr_WarnEx(), 2 es la función por encima de eso, y así sucesivamente.
Las categorías de advertencia deben ser subclases de PyExc_Warning; PyExc_Warning es una subcla-
se de PyExc_Exception; la categoría de advertencia predeterminada es PyExc_RuntimeWarning.
Las categorías de advertencia estándar de Python están disponibles como variables globales cuyos nombres se
enumeran en Categorías de advertencia estándar.
Para obtener información sobre el control de advertencia, consulte la documentación del módulo warnings
y la opción -W en la documentación de la línea de comandos. No hay API de C para el control de advertencia.
int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno,
PyObject *module, PyObject *registry)
Emite un mensaje de advertencia con control explícito sobre todos los atributos de advertencia. Este es un
contenedor sencillo alrededor de la función Python warnings.warn_explicit(); consulte allí para
obtener más información. Los argumentos module y registry pueden establecerse en NULL para obtener el
efecto predeterminado que se describe allí.
Nuevo en la versión 3.4.
int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const
char *module, PyObject *registry)
Part of the Stable ABI. Similar a PyErr_WarnExplicitObject() excepto que message y module son
cadenas codificadas UTF-8, y filename se decodifica de filesystem encoding and error handler.
int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
Part of the Stable ABI. Función similar a PyErr_WarnEx(), pero usa PyUnicode_FromFormat()
para formatear el mensaje de advertencia. format es una cadena de caracteres codificada en ASCII.
Nuevo en la versión 3.2.
int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
Part of the Stable ABI since version 3.6. Función similar a PyErr_WarnFormat(), pero category es
ResourceWarning y pasa source a warnings.WarningMessage().
Nuevo en la versión 3.6.

5.3. Emitir advertencias 53

The Python/C API, Versión 3.11.0

5.4 Consultando el indicador de error

PyObject *PyErr_Occurred()
Return value: Borrowed reference. Part of the Stable ABI. Prueba si el indicador de error está configurado.
Si se establece, retorna la excepción type (el primer argumento de la última llamada a una de las funciones
PyErr_Set* o PyErr_Restore()). Si no está configurado, retorna NULL. No posee una referencia al
valor de retorno, por lo que no necesita usar Py_DECREF().
La persona que llama debe retener el GIL.

Nota: No compare el valor de retorno con una excepción específica; use PyErr_ExceptionMatches()
en su lugar, como se muestra a continuación. (La comparación podría fallar fácilmente ya que la excepción
puede ser una instancia en lugar de una clase, en el caso de una excepción de clase, o puede ser una subclase
de la excepción esperada).

int PyErr_ExceptionMatches(PyObject *exc)

Part of the Stable ABI. Equivalente a PyErr_GivenExceptionMatches(PyErr_Occurred(),
exc). Esto solo debería llamarse cuando se establece una excepción; se producirá una infracción de acce-
so a la memoria si no se ha producido ninguna excepción.
int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
Part of the Stable ABI. Retorna verdadero si la excepción dada coincide con el tipo de excepción en exc. Si
exc es un objeto de clase, esto también retorna verdadero cuando dado es una instancia de una subclase. Si exc
es una tupla, se busca una coincidencia en todos los tipos de excepción en la tupla (y recursivamente en sub
tuplas).
void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Part of the Stable ABI. Recupera el indicador de error en tres variables cuyas direcciones se pasan. Si el
indicador de error no está configurado, configure las tres variables en NULL. Si está configurado, se borrará
y usted tendrá una referencia a cada objeto recuperado. El objeto de valor y rastreo puede ser NULL incluso
cuando el objeto de tipo no lo es.

Nota: Normalmente, esta función solo la usa el código que necesita capturar excepciones o el código que
necesita guardar y restaurar el indicador de error temporalmente, por ejemplo:

{
PyObject *type, *value, *traceback;
PyErr_Fetch(&type, &value, &traceback);

/* ... code that might produce other errors ... */

PyErr_Restore(type, value, traceback);

}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

Part of the Stable ABI. Establece el indicador de error de los tres objetos. Si el indicador de error ya está
configurado, se borra primero. Si los objetos son NULL, el indicador de error se borra. No pase un tipo NULL
y un valor o rastreo no NULL. El tipo de excepción debería ser una clase. No pase un tipo o valor de excepción
no válido. (Violar estas reglas causará problemas sutiles más adelante). Esta llamada quita una referencia a cada
objeto: debe tener una referencia a cada objeto antes de la llamada y después de la llamada ya no posee estas
referencias. (Si no comprende esto, no use esta función. Se lo advertí).

Nota: Normalmente, esta función solo la usa el código que necesita guardar y restaurar el indicador de error
temporalmente. Use PyErr_Fetch() para guardar el indicador de error actual.

54 Capítulo 5. Manejo de excepciones

 The Python/C API, Versión 3.11.0

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)

Part of the Stable ABI. Bajo ciertas circunstancias, los valores retornados por PyErr_Fetch() a continua-
ción pueden ser «no normalizados», lo que significa que *exc es un objeto de clase pero *val no es una
instancia de la misma clase . Esta función se puede utilizar para crear instancias de la clase en ese caso. Si
los valores ya están normalizados, no pasa nada. La normalización retrasada se implementa para mejorar el
rendimiento.

Nota: Esta función no establece implícitamente el atributo __traceback__ en el valor de excepción. Si

se desea establecer el rastreo de manera adecuada, se necesita el siguiente fragmento adicional:
if (tb != NULL) {
PyException_SetTraceback(val, tb);
}

PyObject *PyErr_GetHandledException(void)
Part of the Stable ABI since version 3.11. Recupera la instancia de excepción activa, como la que devolvería
sys.exception(). Esto se refiere a una excepción que ya fue capturada, no a una excepción recién lan-
zada. Retorna una nueva referencia a la excepción o NULL. No modifica el estado de excepción del intérprete.

Nota: Esta función normalmente no es utilizada por el código que quiere manejar excepciones. En cam-
bio, se puede usar cuando el código necesita guardar y restaurar el estado de excepción temporalmente. Use
PyErr_SetHandledException() para restaurar o borrar el estado de excepción.

Nuevo en la versión 3.11.

void PyErr_SetHandledException(PyObject *exc)
Part of the Stable ABI since version 3.11. Establece la excepción activa, como se conoce de sys.
exception(). Esto se refiere a la excepción que ya fue capturada, no a una excepción que fue lanzada
recientemente. Para borrar el estado de la excepción, pasa NULL.

Nota: Esta función normalmente no es utilizada por el código que quiere manejar excepciones. En cam-
bio, se puede usar cuando el código necesita guardar y restaurar el estado de excepción temporalmente. Use
PyErr_GetHandledException() para leer el estado de excepción.

Nuevo en la versión 3.11.

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Part of the Stable ABI since version 3.7. Recupera la información de excepción, como se conoce de sys.
exc_info(). Esto se refiere a una excepción que ya fue capturada, no a una excepción que fue lanzada
recientemente. Retorna nuevas referencias para los tres objetos, cualquiera de los cuales puede ser NULL.
No modifica el estado de información de excepción. Esta función se mantiene por retro-compatibilidad. Es
preferible usar PyErr_GetHandledException().

Nota: Esta función normalmente no es utilizada por el código que quiere manejar excepciones. En cam-
bio, se puede usar cuando el código necesita guardar y restaurar el estado de excepción temporalmente. Use
PyErr_SetExcInfo() para restaurar o borrar el estado de excepción.

Nuevo en la versión 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
Part of the Stable ABI since version 3.7. Establece la información de excepción, como se conoce de sys.
exc_info(). Esto se refiere a una excepción que ya fue capturada, no a una excepción que fue lan-
zada recientemente. Esta función roba las referencias de los argumentos. Para borrar el estado de excep-
ción, pase NULL para los tres argumentos. Para ver las reglas generales sobre los tres argumentos, consulte
PyErr_SetHandledException().

5.4. Consultando el indicador de error 55

The Python/C API, Versión 3.11.0

Nota: Esta función normalmente no es utilizada por el código que quiere manejar excepciones. En cam-
bio, se puede usar cuando el código necesita guardar y restaurar el estado de excepción temporalmente. Use
PyErr_GetExcInfo() para leer el estado de excepción.

Nuevo en la versión 3.3.

Distinto en la versión 3.11: Los argumentos type y traceback ya no se utilizan y pueden ser NULL. El
intérprete los deriva ahora de la instancia de la excepción (el argumento value). La función sigue robando
referencias de los tres argumentos.

5.5 Manejo de señal

int PyErr_CheckSignals()
Part of the Stable ABI. Esta función interactúa con el manejo de señales de Python.
Si la función se llama desde el hilo principal y bajo el intérprete principal de Python, verifica si se ha enviado
una señal a los procesos y, de ser así, invoca el manejador de señales correspondiente. Si el módulo signal
es compatible, esto puede invocar un manejador de señales escrito en Python.
La función intenta manejar todas las señales pendientes y luego devuelve 0. Sin embargo, si un manejador de
señales de Python lanza una excepción, el indicador de error se establece y la función devuelve -1 inmedia-
tamente (de modo que es posible que otras señales pendientes no se hayan manejado todavía: estarán en la
siguiente invocación de PyErr_CheckSignals()).
Si la función se llama desde un hilo no principal, o bajo un intérprete de Python no principal, no hace nada y
devuelve 0.
Esta función se puede llamar mediante un código C de ejecución prolongada que quiere ser interrumpible por
las peticiones del usuario (como presionar Ctrl-C).

Nota: El controlador de señales de Python predeterminado para SIGINT lanza la excepción

KeyboardInterrupt.

void PyErr_SetInterrupt()
Part of the Stable ABI. Simula el efecto de la llegada de una señal SIGINT. Esto es equivalente a
PyErr_SetInterruptEx(SIGINT).

Nota: Esta función es segura para señales asíncronas. Se puede llamar sin el GIL y desde un manejador de
señales de C.

int PyErr_SetInterruptEx(int signum)

Part of the Stable ABI since version 3.10. Simula el efecto de la llegada de una señal. La próxima vez que sea
llamado PyErr_CheckSignals(), se llamará al manejador de señal de Python para el número de señal
dado.
Esta función puede ser llamada por código C que configura su propio manejo de señales y quiere que los
manejadores de señales de Python sean invocados como se espera cuando se solicita una interrupción (por
ejemplo, cuando el usuario presiona Ctrl-C para interrumpir una operación).
Si la señal dada no es manejada por Python (se configuró en signal.SIG_DFL o signal.SIG_IGN), se
ignorará.
Si signum está fuera del rango permitido de números de señal, se devuelve -1. De lo contrario, se devuelve 0.
Esta función nunca cambia el indicador de error.

56 Capítulo 5. Manejo de excepciones

 The Python/C API, Versión 3.11.0

Nota: Esta función es segura para señales asíncronas. Se puede llamar sin el GIL y desde un manejador de
señales de C.

Nuevo en la versión 3.10.

int PySignal_SetWakeupFd(int fd)
Esta función de utilidad especifica un descriptor de archivo en el que el número de señal se escribe como un
solo byte cada vez que se recibe una señal. fd debe ser sin bloqueo. retorna el descriptor de archivo anterior.
El valor -1 desactiva la función; Este es el estado inicial. Esto es equivalente a signal.
set_wakeup_fd() en Python, pero sin verificación de errores. fd debe ser un descriptor de archivo válido.
La función solo debe llamarse desde el hilo principal.
Distinto en la versión 3.5: En Windows, la función ahora también admite controladores de socket.

5.6 Clases de Excepción

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)

Return value: New reference. Part of the Stable ABI. Esta función de utilidad crea y retorna una nueva clase de
excepción. El argumento name debe ser el nombre de la nueva excepción, una cadena de caracteres en C de la
forma module.classname. Los argumentos base y dict son normalmente NULL. Esto crea un objeto de
clase derivado de Exception (accesible en C como PyExc_Exception).
El atributo __module__ de la nueva clase se establece en la primera parte (hasta el último punto) del argu-
mento name, y el nombre de la clase se establece en la última parte (después del último punto). El argumento
base se puede usar para especificar clases base alternativas; puede ser solo una clase o una tupla de clases. El
argumento dict se puede usar para especificar un diccionario de variables de clase y métodos.
PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject
*dict)
Return value: New reference. Part of the Stable ABI. Igual que PyErr_NewException(), excepto que
la nueva clase de excepción puede recibir fácilmente una cadena de documentación: si doc no es NULL, se
utilizará como la cadena de documentación para la clase de excepción.
Nuevo en la versión 3.2.

5.7 Objetos Excepción

PyObject *PyException_GetTraceback(PyObject *ex)

Return value: New reference. Part of the Stable ABI. Retorna el rastreo asociado con la excepción como una
nueva referencia, accesible desde Python a través de __traceback__. Si no hay un rastreo asociado, esto
retorna NULL.
int PyException_SetTraceback(PyObject *ex, PyObject *tb)
Part of the Stable ABI. Establezca el rastreo asociado con la excepción a tb. Use Py_None para borrarlo.
PyObject *PyException_GetContext(PyObject *ex)
Return value: New reference. Part of the Stable ABI. Retorna el contexto (otra instancia de excepción durante
cuyo manejo ex se generó) asociado con la excepción como una nueva referencia, accesible desde Python a
través de __context__. Si no hay un contexto asociado, esto retorna NULL.
void PyException_SetContext(PyObject *ex, PyObject *ctx)
Part of the Stable ABI. Establece el contexto asociado con la excepción a ctx. Use NULL para borrarlo. No hay
verificación de tipo para asegurarse de que ctx es una instancia de excepción. Esto roba una referencia a ctx.

5.6. Clases de Excepción 57

The Python/C API, Versión 3.11.0

PyObject *PyException_GetCause(PyObject *ex)

Return value: New reference. Part of the Stable ABI. Retorna la causa (ya sea una instancia de excepción,
o None, establecida por raise ... from ...) asociada con la excepción como una nueva referencia,
como accesible desde Python a través de __causa__.
void PyException_SetCause(PyObject *ex, PyObject *cause)
Part of the Stable ABI. Establece la causa asociada con la excepción a cause. Use NULL para borrarlo. No
hay verificación de tipo para asegurarse de que cause sea una instancia de excepción o None. Esto roba una
referencia a cause.
__suppress_context__ es implícitamente establecido en True por esta función.

5.8 Objetos Unicode de Excepción

Las siguientes funciones se utilizan para crear y modificar excepciones Unicode de C.

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length,
Py_ssize_t start, Py_ssize_t end, const char *reason)
Return value: New reference. Part of the Stable ABI. Crea un objeto UnicodeDecodeError con los atri-
butos encoding, object, length, start, end y reason. encoding y reason son cadenas codificadas UTF-8.
PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)
Return value: New reference. Part of the Stable ABI. Retorna el atributo encoding del objeto de excepción dado.
PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)
PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)
PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)
Return value: New reference. Part of the Stable ABI. Retorna el atributo object del objeto de excepción dado.
int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
Part of the Stable ABI. Obtiene el atributo start del objeto de excepción dado y lo coloca en *start. start no
debe ser NULL. retorna 0 en caso de éxito, -1 en caso de error.
int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
Part of the Stable ABI. Establece el atributo start del objeto de excepción dado en start. Retorna 0 en caso de
éxito, -1 en caso de error.
int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
Part of the Stable ABI. Obtiene el atributo end del objeto de excepción dado y lo coloca en *end. end no debe
ser NULL. retorna 0 en caso de éxito, -1 en caso de error.
int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
Part of the Stable ABI. Establece el atributo end del objeto de excepción dado en end. Retorna 0 en caso de
éxito, -1 en caso de error.
PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)
PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)

58 Capítulo 5. Manejo de excepciones

 The Python/C API, Versión 3.11.0

PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)

Return value: New reference. Part of the Stable ABI. Retorna el atributo reason del objeto de excepción dado.
int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
Part of the Stable ABI. Establece el atributo reason del objeto de excepción dado en reason. Retorna 0 en caso
de éxito, -1 en caso de error.

5.9 Control de Recursión

Estas dos funciones proporcionan una forma de realizar llamadas recursivas seguras en el nivel C, tanto en el núcleo
como en los módulos de extensión. Son necesarios si el código recursivo no invoca necesariamente el código Python
(que rastrea su profundidad de recursión automáticamente). Tampoco son necesarios para las implementaciones de
tp_call porque call protocol se encarga del manejo de la recursividad.
int Py_EnterRecursiveCall(const char *where)
Part of the Stable ABI since version 3.9. Marca un punto donde una llamada recursiva de nivel C está a punto
de realizarse.
Si USE_STACKCHECK está definido, esta función verifica si la pila del SO se desbordó usando
PyOS_CheckStack(). En este caso, establece un MemoryError y retorna un valor distinto de cero.
La función verifica si se alcanza el límite de recursión. Si este es el caso, se establece a RecursionError
y se retorna un valor distinto de cero. De lo contrario, se retorna cero.
where debería ser una cadena de caracteres codificada en UTF-8 como "en la comprobación de
instancia" para concatenarse con el mensaje RecursionError causado por el límite de profundidad
de recursión.
Distinto en la versión 3.9: Esta función ahora también está disponible en la API limitada.
void Py_LeaveRecursiveCall(void)
Part of the Stable ABI since version 3.9. Termina una Py_EnterRecursiveCall(). Se debe llamar una
vez por cada invocación exitosa de Py_EnterRecursiveCall().
Distinto en la versión 3.9: Esta función ahora también está disponible en la API limitada.
La implementación adecuada de tp_repr para los tipos de contenedor requiere un manejo de recursión especial.
Además de proteger la pila, tp_repr también necesita rastrear objetos para evitar ciclos. Las siguientes dos funcio-
nes facilitan esta funcionalidad. Efectivamente, estos son los C equivalentes a reprlib.recursive_repr().

int Py_ReprEnter(PyObject *object)

Part of the Stable ABI. Llamado al comienzo de la implementación tp_repr para detectar ciclos.
Si el objeto ya ha sido procesado, la función retorna un entero positivo. En ese caso, la implementación
tp_repr debería retornar un objeto de cadena que indique un ciclo. Como ejemplos, los objetos dict
retornan {...} y los objetos list retornan [...].
La función retornará un entero negativo si se alcanza el límite de recursión. En ese caso, la implementación
tp_repr normalmente debería retornar NULL.
De lo contrario, la función retorna cero y la implementación tp_repr puede continuar normalmente.
void Py_ReprLeave(PyObject *object)
Part of the Stable ABI. Termina a Py_ReprEnter(). Se debe llamar una vez por cada invocación de
Py_ReprEnter() que retorna cero.

5.9. Control de Recursión 59

The Python/C API, Versión 3.11.0

5.10 Excepciones Estándar

Todas las excepciones estándar de Python están disponibles como variables globales cuyos nombres son PyExc_
seguidos del nombre de excepción de Python. Estos tienen el tipo PyObject*; todos son objetos de clase. Para
completar, aquí están todas las variables:

Nombre en C Nombre en Python Notas

1
PyExc_BaseException BaseException
Página 61, 1
PyExc_Exception Exception
Página 61, 1
PyExc_ArithmeticError ArithmeticError
PyExc_AssertionError AssertionError
PyExc_AttributeError AttributeError
PyExc_BlockingIOError BlockingIOError
PyExc_BrokenPipeError BrokenPipeError
PyExc_BufferError BufferError
PyExc_ChildProcessError ChildProcessError
PyExc_ConnectionAbortedError
ConnectionAbortedError
PyExc_ConnectionError ConnectionError
PyExc_ConnectionRefusedError
ConnectionRefusedError
PyExc_ConnectionResetError
ConnectionResetError
PyExc_EOFError EOFError
PyExc_FileExistsError FileExistsError
PyExc_FileNotFoundError FileNotFoundError
PyExc_FloatingPointError FloatingPointError
PyExc_GeneratorExit GeneratorExit
PyExc_ImportError ImportError
PyExc_IndentationError IndentationError
PyExc_IndexError IndexError
PyExc_InterruptedError InterruptedError
PyExc_IsADirectoryError IsADirectoryError
PyExc_KeyError KeyError
PyExc_KeyboardInterrupt KeyboardInterrupt
Página 61, 1
PyExc_LookupError LookupError
PyExc_MemoryError MemoryError
PyExc_ModuleNotFoundErrorModuleNotFoundError
PyExc_NameError NameError
PyExc_NotADirectoryError NotADirectoryError
PyExc_NotImplementedErrorNotImplementedError
Página 61, 1
PyExc_OSError OSError
PyExc_OverflowError OverflowError
PyExc_PermissionError PermissionError
PyExc_ProcessLookupError ProcessLookupError
PyExc_RecursionError RecursionError
PyExc_ReferenceError ReferenceError
PyExc_RuntimeError RuntimeError
PyExc_StopAsyncIteration StopAsyncIteration
PyExc_StopIteration StopIteration
PyExc_SyntaxError SyntaxError
PyExc_SystemError SystemError
PyExc_SystemExit SystemExit
PyExc_TabError TabError
PyExc_TimeoutError TimeoutError
PyExc_TypeError TypeError
PyExc_UnboundLocalError UnboundLocalError
continué en la próxima página

60 Capítulo 5. Manejo de excepciones

 The Python/C API, Versión 3.11.0

Tabla 1 – proviene de la página anterior

Nombre en C Nombre en Python Notas
PyExc_UnicodeDecodeError UnicodeDecodeError
PyExc_UnicodeEncodeError UnicodeEncodeError
PyExc_UnicodeError UnicodeError
PyExc_UnicodeTranslateError
UnicodeTranslateError
PyExc_ValueError ValueError
PyExc_ZeroDivisionError ZeroDivisionError

Nuevo en la versión 3.3: PyExc_BlockingIOError, PyExc_BrokenPipeError,

PyExc_ChildProcessError, PyExc_ConnectionError, PyExc_ConnectionAbortedError,
PyExc_ConnectionRefusedError, PyExc_ConnectionResetError,
PyExc_FileExistsError, PyExc_FileNotFoundError, PyExc_InterruptedError,
PyExc_IsADirectoryError, PyExc_NotADirectoryError, PyExc_PermissionError,
PyExc_ProcessLookupError y PyExc_TimeoutError fueron introducidos luego de PEP 3151.
Nuevo en la versión 3.5: PyExc_StopAsyncIteration y PyExc_RecursionError.
Nuevo en la versión 3.6: PyExc_ModuleNotFoundError.
Estos son alias de compatibilidad para PyExc_OSError:

Nombre en C Notas
PyExc_EnvironmentError
PyExc_IOError
2
PyExc_WindowsError

Distinto en la versión 3.3: Estos alias solían ser tipos de excepción separados.
Notas:

5.11 Categorías de advertencia estándar

Todas las categorías de advertencia estándar de Python están disponibles como variables globales cuyos nombres son
PyExc_ seguidos del nombre de excepción de Python. Estos tienen el tipo PyObject*; todos son objetos de clase.
Para completar, aquí están todas las variables:

Nombre en C Nombre en Python Notas

3
PyExc_Warning Warning
PyExc_BytesWarning BytesWarning
PyExc_DeprecationWarning DeprecationWarning
PyExc_FutureWarning FutureWarning
PyExc_ImportWarning ImportWarning
PyExc_PendingDeprecationWarning PendingDeprecationWarning
PyExc_ResourceWarning ResourceWarning
PyExc_RuntimeWarning RuntimeWarning
PyExc_SyntaxWarning SyntaxWarning
PyExc_UnicodeWarning UnicodeWarning
PyExc_UserWarning UserWarning

Nuevo en la versión 3.2: PyExc_ResourceWarning.

Notas:

1 Esta es una clase base para otras excepciones estándar.

2 Solo se define en Windows; proteja el código que usa esto probando que la macro del preprocesador MS_WINDOWS está definida.
3 Esta es una clase base para otras categorías de advertencia estándar.

5.11. Categorías de advertencia estándar 61

The Python/C API, Versión 3.11.0

62 Capítulo 5. Manejo de excepciones

 CAPÍTULO 6

Utilidades

Las funciones de este capítulo realizan varias tareas de utilidad, que van desde ayudar a que el código C sea más portátil
en todas las plataformas, usar módulos Python desde C y analizar argumentos de funciones y construir valores Python
a partir de valores C.

6.1 Utilidades del sistema operativo

PyObject *PyOS_FSPath(PyObject *path)

Return value: New reference. Part of the Stable ABI since version 3.6. Retorna la representación del sistema de
archivos para path. Si el objeto es str o bytes, entonces su conteo de referencias se incrementa. Si el objeto
implementa la interfaz os.PathLike, entonces __fspath__() se retorna siempre que sea un objeto str
o bytes. De lo contrario TypeError se lanza y se retorna NULL.
Nuevo en la versión 3.6.
int Py_FdIsInteractive(FILE *fp, const char *filename)
Retorna verdadero (distinto de cero) si el archivo de E/S (I/O) estándar fp con nombre filename se considera
interactivo. Este es el caso de los archivos para los que isatty(fileno(fp)) es verdadero. Si el indicador
global Py_InteractiveFlag es verdadero, esta función también retorna verdadero si el puntero filename
es NULL o si el nombre es igual a una de las cadenas de caracteres '<stdin>' o '???'.
void PyOS_BeforeFork()
Part of the Stable ABI on platforms with fork() since version 3.7. Función para preparar algún estado interno
antes de una bifurcación de proceso (process fork). Esto debería llamarse antes de llamar a fork() o cualquier
función similar que clone el proceso actual. Solo disponible en sistemas donde fork() está definido.

Advertencia: La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»).
Lo mismo es cierto para PyOS_BeforeFork().

Nuevo en la versión 3.7.

void PyOS_AfterFork_Parent()
Part of the Stable ABI on platforms with fork() since version 3.7. Función para actualizar algún estado interno
después de una bifurcación de proceso. Se debe invocar desde el proceso principal después de llamar a fork()

63
The Python/C API, Versión 3.11.0

o cualquier función similar que clone el proceso actual, independientemente de si la clonación del proceso fue
exitosa. Solo disponible en sistemas donde fork() está definido.

Advertencia: La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»).
Lo mismo es cierto para PyOS_AfterFork_Parent().

Nuevo en la versión 3.7.

void PyOS_AfterFork_Child()
Part of the Stable ABI on platforms with fork() since version 3.7. Función para actualizar el estado del intér-
prete interno después de una bifurcación de proceso (process fork). Debe llamarse desde el proceso secundario
después de llamar a fork(), o cualquier función similar que clone el proceso actual, si existe alguna posibi-
lidad de que el proceso vuelva a llamar al intérprete de Python. Solo disponible en sistemas donde fork()
está definido.

Advertencia: La llamada C fork() solo debe hacerse desde hilo «principal» (del intérprete «principal»).
Lo mismo es cierto para PyOS_AfterFork_Child().

Nuevo en la versión 3.7.

Ver también:
os.register_at_fork() permite registrar funciones personalizadas de Python a las que puede llamar
PyOS_BeforeFork(), PyOS_AfterFork_Parent() y PyOS_AfterFork_Child().
void PyOS_AfterFork()
Part of the Stable ABI on platforms with fork(). Función para actualizar algún estado interno después de una
bifurcación de proceso (process fork); Esto debería llamarse en el nuevo proceso si el intérprete de Python
continuará siendo utilizado. Si se carga un nuevo ejecutable en el nuevo proceso, no es necesario llamar a esta
función.
Obsoleto desde la versión 3.7: Esta función es reemplazada por PyOS_AfterFork_Child().
int PyOS_CheckStack()
Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7. Retorna verdadero cuando el
intérprete se queda sin espacio de pila (stack space). Esta es una verificación confiable, pero solo está disponible
cuando USE_STACKCHECK está definido (actualmente en algunas versiones de Windows usando el compi-
lador de Microsoft Visual C++). USE_STACKCHECK se definirá automáticamente; nunca debe cambiar la
definición en su propio código.
PyOS_sighandler_t PyOS_getsig(int i)
Part of the Stable ABI. Retorna el controlador de señal actual para la señal i. Esta es una pequeña envoltura alre-
dedor de sigaction() o signal(). ¡No llame a esas funciones directamente! PyOS_sighandler_t
es un alias typedef para void (*)(int).
PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
Part of the Stable ABI. Configura el controlador de señal para la señal i como h; retorna el antiguo controlador de
señal. Esta es una pequeña envoltura alrededor de sigaction() o signal(). ¡No llame a esas funciones
directamente! PyOS_sighandler_t es un alias typedef para void (*)(int).
wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
Part of the Stable ABI since version 3.7.

Advertencia: Esta función no debe llamarse directamente: utilice la API PyConfig con la función
PyConfig_SetBytesString() que asegura que Python está preinicializado.
Esta función no debe llamarse antes de que Python esté preinicializado y para que la configuración local
LC_CTYPE esté correctamente configurada: véase la función Py_PreInitialize().

64 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

Decodifica una cadena de bytes a partir del manejador de codificación y errores del sistema de archivos. Si el
controlador de error es el controlador de error surrogateescape, los bytes no codificables se decodifican como
caracteres en el rango U+DC80..U+DCFF; y si una secuencia de bytes se puede decodificar como un carácter
sustituto, escape los bytes usando el controlador de error surrogateescape en lugar de decodificarlos.
Retorna un puntero a una cadena de caracteres anchos recientemente asignada, use PyMem_RawFree() para
liberar la memoria. Si el tamaño no es NULL, escribe el número de caracteres anchos excluyendo el carácter
nulo en *size
Retorna NULL en caso de error de decodificación o error de asignación de memoria. Si size no es NULL,
*size se establece en (size_t) -1 en caso de error de memoria o en (size_t) -2 en caso de error
de decodificación.
El filesystem encoding and error handler son seleccionados por PyConfig_Read(): ver
filesystem_encoding y filesystem_errors que pertenecen a PyConfig.
Los errores de decodificación nunca deberían ocurrir, a menos que haya un error en la biblioteca C.
Utilice la función Py_EncodeLocale() para codificar la cadena de caracteres en una cadena de bytes.
Ver también:
Las funciones PyUnicode_DecodeFSDefaultAndSize() y PyUnicode_DecodeLocaleAndSize().
Nuevo en la versión 3.5.
Distinto en la versión 3.7: La función ahora utiliza la codificación UTF-8 en el Modo Python UTF-8.
Distinto en la versión 3.8: La función ahora usa la codificación UTF-8 en Windows si
Py_LegacyWindowsFSEncodingFlag es cero;
char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
Part of the Stable ABI since version 3.7. Codifica una cadena de caracteres amplios según el término filesystem
encoding and error handler. Si el gestor de errores es surrogateescape error handler, los caracteres sustituidos
en el rango U+DC80..U+DCFF se convierten en bytes 0x80..0xFF.
Retorna un puntero a una cadena de bytes recién asignada, usa PyMem_Free() para liberar la memoria.
Retorna NULL si se genera un error de codificación o error de asignación de memoria.
Si error_pos no es NULL, *error_pos se establece en (size_t)-1 en caso de éxito, o se establece en el
índice del carácter no válido en el error de codificación.
El filesystem encoding and error handler son seleccionados por PyConfig_Read(): ver
filesystem_encoding y filesystem_errors que pertenecen a PyConfig.
Use la función Py_DecodeLocale() para decodificar la cadena de bytes en una cadena de caracteres
anchos.

Advertencia: Esta función no debe llamarse antes de que Python esté preinicializado y para que la confi-
guración local LC_CTYPE esté correctamente configurada: véase la función Py_PreInitialize().

Ver también:
Las funciones PyUnicode_EncodeFSDefault() y PyUnicode_EncodeLocale().
Nuevo en la versión 3.5.
Distinto en la versión 3.7: La función ahora utiliza la codificación UTF-8 en el Modo Python UTF-8.
Distinto en la versión 3.8: La función ahora usa la codificación UTF-8 en Windows si
Py_LegacyWindowsFSEncodingFlag es cero.

6.1. Utilidades del sistema operativo 65

The Python/C API, Versión 3.11.0

6.2 Funciones del Sistema

Estas son funciones de utilidad que hacen que la funcionalidad del módulo sys sea accesible para el código C. Todos
funcionan con el diccionario del módulo sys del subproceso actual del intérprete, que está contenido en la estructura
interna del estado del subproceso.
PyObject *PySys_GetObject(const char *name)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto name del módulo sys o NULL si
no existe, sin establecer una excepción.
int PySys_SetObject(const char *name, PyObject *v)
Part of the Stable ABI. Establece name en el módulo sys en v a menos que v sea NULL, en cuyo caso name
se elimina del módulo sys. Retorna 0 en caso de éxito, -1 en caso de error.
void PySys_ResetWarnOptions()
Part of the Stable ABI. Restablece sys.warnoptions a una lista vacía. Esta función puede llamarse antes
de Py_Initialize().
void PySys_AddWarnOption(const wchar_t *s)
Part of the Stable ABI. Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su
lugar se debe usar: PyConfig.warnoptions, ver Configuración de inicialización de Python.
Agrega s a sys.warnoptions. Esta función debe llamarse antes de Py_Initialize() para afectar la
lista de filtros de advertencias.
Obsoleto desde la versión 3.11.
void PySys_AddWarnOptionUnicode(PyObject *unicode)
Part of the Stable ABI. Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su
lugar se debe usar: PyConfig.warnoptions, ver Configuración de inicialización de Python.
Agrega unicode a sys.warnoptions.
Nota: esta función no se puede utilizar actualmente desde fuera de la implementación de CPython, ya que debe
llamarse antes de la importación implícita de warnings en Py_Initialize() para que sea efectiva,
pero no se puede llamar hasta que se haya inicializado suficiente tiempo de ejecución para permitir la creación
de objetos Unicode.
Obsoleto desde la versión 3.11.
void PySys_SetPath(const wchar_t *path)
Part of the Stable ABI. Esta API se mantiene para conservar compatibilidad con versiones anteriores, en su lugar
se debe usar: PyConfig.module_search_paths y PyConfig.module_search_paths_set,
ver Python Initialization Configuration.
Establece sys.path en un objeto lista de rutas que se encuentra en path, que debería ser una lista de rutas
separadas con el delimitador de ruta de búsqueda de la plataforma (: en Unix, ; en Windows )
Obsoleto desde la versión 3.11.
void PySys_WriteStdout(const char *format, ...)
Part of the Stable ABI. Escribe la cadena de caracteres de salida descrita por format en sys.stdout. No se
lanzan excepciones, incluso si se produce el truncamiento (ver más abajo).
format debe limitar el tamaño total de la cadena de caracteres de salida formateada a 1000 bytes o menos;
después de 1000 bytes, la cadena de caracteres de salida se trunca. En particular, esto significa que no deben
existir formatos «%s» sin restricciones; estos deben limitarse usando «%.<N>s» donde <N> es un número
decimal calculado de modo que <N> más el tamaño máximo de otro texto formateado no exceda los 1000
bytes. También tenga cuidado con «%f», que puede imprimir cientos de dígitos para números muy grandes.
Si ocurre un problema, o sys.stdout no está configurado, el mensaje formateado se escribe en el real (nivel
C) stdout.

66 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

void PySys_WriteStderr(const char *format, ...)

Part of the Stable ABI. Como PySys_WriteStdout(), pero escribe a sys.stderr o stderr en su lugar.
void PySys_FormatStdout(const char *format, ...)
Part of the Stable ABI. Función similar a PySys_WriteStdout() pero formatea el mensaje usando
PyUnicode_FromFormatV() y no trunca el mensaje a una longitud arbitraria.
Nuevo en la versión 3.2.
void PySys_FormatStderr(const char *format, ...)
Part of the Stable ABI. Como PySys_FormatStdout(), pero escribe a sys.stderr o stderr en su
lugar.
Nuevo en la versión 3.2.
void PySys_AddXOption(const wchar_t *s)
Part of the Stable ABI since version 3.7. Esta API se mantiene para conservar compatibilidad con versiones
anteriores, en su lugar se debe usar: PyConfig.xoptions, ver Configuración de inicialización de Python.
Analiza (parse) s como un conjunto de opciones -X y los agrega a la asignación de opciones actual tal como lo
retorna PySys_GetXOptions(). Esta función puede llamarse antes de Py_Initialize().
Nuevo en la versión 3.2.
Obsoleto desde la versión 3.11.
PyObject *PySys_GetXOptions()
Return value: Borrowed reference. Part of the Stable ABI since version 3.7. Retorna el diccionario actual de
opciones -X, de manera similar a sys._xoptions. En caso de error, se retorna NULL y se establece una
excepción.
Nuevo en la versión 3.2.
int PySys_Audit(const char *event, const char *format, ...)
Lanza un evento de auditoría con cualquier gancho activo. Retorna cero para el éxito y no cero con una excep-
ción establecida en caso de error.
Si se han agregado ganchos, format y otros argumentos se utilizarán para construir una tupla para pasar. Además
de N, están disponibles los mismos caracteres de formato que los utilizados en Py_BuildValue(). Si el
valor generado no es una tupla, se agregará a una tupla de un solo elemento. (La opción de formato N consume
una referencia, pero dado que no hay forma de saber si se consumirán argumentos para esta función, su uso
puede causar fugas de referencia).
Tenga en cuenta que los caracteres de formato # deben tratarse como Py_ssize_t, independientemente de
si se definió PY_SSIZE_T_CLEAN.
sys.audit() realiza la misma función del código Python.
Nuevo en la versión 3.8.
Distinto en la versión 3.8.2: Requiere Py_ssize_t para los caracteres de formato #. Anteriormente, se
lanzaba una advertencia de deprecación inevitable.
int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
Agrega el hook invocable a la lista de hooks de auditoría activos. Retorna cero para el éxito y no cero en caso
de error. Si el tiempo de ejecución se ha inicializado, también configura un error en caso de fallo. Los hooks
agregados a través de esta API se llaman para todos los intérpretes creados por el tiempo de ejecución.
El puntero userData se pasa a la función gancho. Dado que las funciones de enlace pueden llamarse desde
diferentes tiempos de ejecución, este puntero no debe referirse directamente al estado de Python.
Es seguro llamar a esta función antes de Py_Initialize(). Cuando se llama después de la inicialización
del tiempo de ejecución, se notifican los enlaces de auditoría existentes y pueden anular silenciosamente la
operación al generar un error subclasificado de Excepción (otros errores no se silenciarán).

6.2. Funciones del Sistema 67

The Python/C API, Versión 3.11.0

La función (hook) es de tipo int (*)(const char *event, PyObject *args, void
*userData), donde args está garantizado como un PyTupleObject. La función hook siempre se llama
con el GIL en poder del intérprete de Python que lanzó el evento.
Ver PEP 578 para una descripción detallada de la auditoría. Las funciones en el tiempo de ejecución y la
biblioteca estándar que generan eventos se enumeran en table de eventos de auditoria. Los detalles se encuentran
en la documentación de cada función.
Lanza un evento de auditoria sys.addaudithook sin argumentos.
Nuevo en la versión 3.8.

6.3 Control de procesos

void Py_FatalError(const char *message)

Part of the Stable ABI. Imprime un mensaje de error fatal y elimina el proceso. No se realiza limpieza. Esta
función solo debe invocarse cuando se detecta una condición que haría peligroso continuar usando el intérprete
de Python; por ejemplo, cuando la administración del objeto parece estar dañada. En Unix, se llama a la función
de biblioteca C estándar abort() que intentará producir un archivo core.
La función Py_FatalError() se reemplaza con una macro que registra automáticamente el nombre de la
función actual, a menos que se defina la macro Py_LIMITED_API.
Distinto en la versión 3.9: Registra el nombre de la función automáticamente.
void Py_Exit(int status)
Part of the Stable ABI. Sale del proceso actual. Esto llama Py_FinalizeEx() y luego llama a la función
estándar de la biblioteca C exit(status). Si Py_FinalizeEx() indica un error, el estado de salida se
establece en 120.
Distinto en la versión 3.6: Los errores de finalización ya no se ignoran.
int Py_AtExit(void (*func)())
Part of the Stable ABI. Registra una función de limpieza a la que llamará Py_FinalizeEx(). Se llamará a
la función de limpieza sin argumentos y no debería retornar ningún valor. Como máximo se pueden registrar 32
funciones de limpieza. Cuando el registro es exitoso, Py_AtExit() retorna 0; en caso de error, retorna -1.
La última función de limpieza registrada se llama primero. Cada función de limpieza se llamará como máximo
una vez. Dado que la finalización interna de Python se habrá completado antes de la función de limpieza, func
no debería llamar a las API de Python.

6.4 Importando Módulos

PyObject *PyImport_ImportModule(const char *name)

Return value: New reference. Part of the Stable ABI. Esta es una interfaz simplificada para
PyImport_ImportModuleEx() a continuación, dejando los argumentos globals y locals establecidos
en NULL y level establecidos en 0. Cuando el argumento name contiene un punto (cuando especifica un sub-
módulo de un paquete), el argumento fromlist se establece en la lista ['*'] para que el valor de retorno sea
el módulo con nombre en lugar del paquete de nivel superior que lo contiene como lo haría de lo contrario
sea el caso. (Desafortunadamente, esto tiene un efecto secundario adicional cuando name de hecho especifica
un subpaquete en lugar de un submódulo: los submódulos especificados en la variable __all__ del paquete
están cargados). Retorna una nueva referencia al módulo importado, o NULL con una excepción establecida
en caso de error. Una importación fallida de un módulo no deja el módulo en sys.modules.
Esta función siempre usa importaciones absolutas.

68 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

PyObject *PyImport_ImportModuleNoBlock(const char *name)

Return value: New reference. Part of the Stable ABI. Esta función es un alias obsoleto de
PyImport_ImportModule().
Distinto en la versión 3.3: Esta función solía fallar inmediatamente cuando el bloqueo de importación era
retenido por otro hilo. Sin embargo, en Python 3.3, el esquema de bloqueo cambió a bloqueos por módulo para
la mayoría de los propósitos, por lo que el comportamiento especial de esta función ya no es necesario.
PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject
*fromlist)
Return value: New reference. Importa un módulo. Esto se describe mejor haciendo referencia a la función
Python incorporada __import__().
El valor de retorno es una nueva referencia al módulo importado o paquete de nivel superior, o NULL con una
excepción establecida en caso de error. Al igual que para __import__(), el valor de retorno cuando se
solicitó un submódulo de un paquete normalmente es el paquete de nivel superior, a menos que se proporcione
un fromlist no vacío.
Las importaciones que fallan eliminan objetos de módulo incompletos, como con
PyImport_ImportModule().
PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals,
PyObject *fromlist, int level)
Return value: New reference. Part of the Stable ABI since version 3.7. Importa un módulo. Esto se descri-
be mejor haciendo referencia a la función Python incorporada __import__(), ya que la función estándar
__import__() llama a esta función directamente.
El valor de retorno es una nueva referencia al módulo importado o paquete de nivel superior, o NULL con una
excepción establecida en caso de error. Al igual que para __import__(), el valor de retorno cuando se
solicitó un submódulo de un paquete normalmente es el paquete de nivel superior, a menos que se proporcione
un fromlist no vacío.
Nuevo en la versión 3.3.
PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals,
PyObject *fromlist, int level)
Return value: New reference. Part of the Stable ABI. Similar a PyImport_ImportModuleLevelObject(),
pero el nombre es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.
Distinto en la versión 3.3: Los valores negativos para level ya no se aceptan.
PyObject *PyImport_Import(PyObject *name)
Return value: New reference. Part of the Stable ABI. Esta es una interfaz de nivel superior que llama a la
«función de enlace de importación» actual (con un nivel explícito de 0, que significa importación absoluta).
Invoca la función __import__() de las __builtins__ de los globales (globals) actuales. Esto significa
que la importación se realiza utilizando los ganchos de importación instalados en el entorno actual.
Esta función siempre usa importaciones absolutas.
PyObject *PyImport_ReloadModule(PyObject *m)
Return value: New reference. Part of the Stable ABI. Recarga un módulo. Retorna una nueva referencia al
módulo recargado, o NULL con una excepción establecida en caso de error (el módulo todavía existe en este
caso).
PyObject *PyImport_AddModuleObject(PyObject *name)
Return value: Borrowed reference. Part of the Stable ABI since version 3.7. Retorna el objeto módulo corres-
pondiente a un nombre de módulo. El argumento name puede tener la forma package.module. Primero
revise el diccionario de módulos si hay uno allí, y si no, crea uno nuevo y lo agrega al diccionario de módulos.
Retorna NULL con una excepción establecida en caso de error.

Nota: Esta función no carga ni importa el módulo; si el módulo no estaba cargado, obtendrá un objeto de
módulo vacío. Utilice PyImport_ImportModule() o una de sus variantes para importar un módulo. Las

6.4. Importando Módulos 69

The Python/C API, Versión 3.11.0

estructuras de paquete implicadas por un nombre punteado para name no se crean si aún no están presentes.

Nuevo en la versión 3.3.

PyObject *PyImport_AddModule(const char *name)
Return value: Borrowed reference. Part of the Stable ABI. Similar a PyImport_AddModuleObject(),
pero el nombre es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.
PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
Return value: New reference. Part of the Stable ABI. Dado un nombre de módulo (posiblemente de la forma
package.module) y un objeto código leído desde un archivo de bytecode de Python u obtenido de la función
incorporada compile(), carga el módulo. Retorna una nueva referencia al objeto módulo, o NULL con una
excepción establecida si se produjo un error. name se elimina de sys.modules en casos de error, incluso
si name ya estaba en sys.modules en la entrada a PyImport_ExecCodeModule(). Dejar módulos
inicializados de forma incompleta en sys.modules es peligroso, ya que las importaciones de dichos módulos
no tienen forma de saber que el objeto del módulo es un estado desconocido (y probablemente dañado con
respecto a las intenciones del autor del módulo).
Los módulos __spec__ y __loader__ se establecerán, si no se han configurado ya, con los valores apro-
piados. El cargador de la especificación se establecerá en el módulo __loader__ (si está configurado) y en
una instancia de SourceFileLoader de lo contrario.
El atributo del módulo __file__ se establecerá en el objeto código co_filename. Si corresponde, tam-
bién se establecerá __cached__.
Esta función volverá a cargar el módulo si ya se importó. Consulte PyImport_ReloadModule() para
conocer la forma prevista de volver a cargar un módulo.
Si name apunta a un nombre punteado de la forma package.module, cualquier estructura de paquete que
no se haya creado aún no se creará.
Ver también PyImport_ExecCodeModuleEx() y PyImport_ExecCodeModuleWithPathnames().
PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
Return value: New reference. Part of the Stable ABI. Como PyImport_ExecCodeModule(), pero el
atributo __file__ del objeto del módulo se establece en pathname si no es NULL.
Ver también PyImport_ExecCodeModuleWithPathnames().
PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname,
PyObject *cpathname)
Return value: New reference. Part of the Stable ABI since version 3.7. Como
PyImport_ExecCodeModuleEx(), pero el atributo __cached__ del objeto módulo se establece en
cpathname si no es NULL. De las tres funciones, esta es la recomendada para usar.
Nuevo en la versión 3.3.
PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char
*pathname, const char *cpathname)
Return value: New reference. Part of the Stable ABI. Como PyImport_ExecCodeModuleObject(),
pero name, pathname y cpathname son cadenas de caracteres codificadas UTF-8. También se intenta averiguar
cuál debe ser el valor de pathname de cpathname si el primero se establece en NULL.
Nuevo en la versión 3.2.
Distinto en la versión 3.3: Utiliza imp.source_from_cache() para calcular la ruta de origen si solo se
proporciona la ruta del bytecode.
long PyImport_GetMagicNumber()
Part of the Stable ABI. Retorna el número mágico para los archivos de bytecode de Python (también conocido
como archivos .pyc). El número mágico debe estar presente en los primeros cuatro bytes del archivo de código
de bytes, en orden de bytes little-endian. Retorna -1 en caso de error.
Distinto en la versión 3.3: Retorna un valor de -1 en caso de error.

70 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

const char *PyImport_GetMagicTag()

Part of the Stable ABI. Retorna la cadena de caracteres de etiqueta mágica para nombres de archivo de có-
digo de bytes Python en formato PEP 3147. Tenga en cuenta que el valor en sys.implementation.
cache_tag es autoritario y debe usarse en lugar de esta función.
Nuevo en la versión 3.2.
PyObject *PyImport_GetModuleDict()
Return value: Borrowed reference. Part of the Stable ABI. Retorna el diccionario utilizado para la administración
del módulo (también conocido como sys.modules). Tenga en cuenta que esta es una variable por intérprete.
PyObject *PyImport_GetModule(PyObject *name)
Return value: New reference. Part of the Stable ABI since version 3.8. Retorna el módulo ya importado con el
nombre dado. Si el módulo aún no se ha importado, retorna NULL pero no establece un error. Retorna NULL
y establece un error si falla la búsqueda.
Nuevo en la versión 3.7.
PyObject *PyImport_GetImporter(PyObject *path)
Return value: New reference. Part of the Stable ABI. Retorna un objeto buscador para un elemento path sys.
path/pkg.__path__, posiblemente obteniéndolo del diccionario sys.path_importer_cache. Si
aún no estaba en caché, atraviesa sys.path_hooks hasta que se encuentre un gancho (hook) que pueda
manejar el elemento de ruta. Retorna None si ningún gancho podría; esto le dice a la persona que llama que
path based finder no pudo encontrar un buscador para este elemento de ruta. Guarda en el resultado (caché)
en sys.path_importer_cache. Retorna una nueva referencia al objeto del buscador.
int PyImport_ImportFrozenModuleObject(PyObject *name)
Return value: New reference. Part of the Stable ABI since version 3.7. Carga un módulo congelado llamado
name. Retorna 1 para el éxito, 0 si no se encuentra el módulo y -1 con una excepción establecida si falla la ini-
cialización. Para acceder al módulo importado con una carga exitosa, use PyImport_ImportModule().
(Tenga en cuenta el nombre inapropiado — esta función volvería a cargar el módulo si ya se importó).
Nuevo en la versión 3.3.
Distinto en la versión 3.4: El atributo __file__ ya no está establecido en el módulo.
int PyImport_ImportFrozenModule(const char *name)
Part of the Stable ABI. Similar a PyImport_ImportFrozenModuleObject(), pero el nombre es una
cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.
struct _frozen
Esta es la definición del tipo de estructura para los descriptores de módulos congelados, según lo generado con
la herramienta freeze (ver Tools/freeze en la distribución de código fuente de Python). Su definición,
que se encuentra en Include/import.h, es:

struct _frozen {
const char *name;
const unsigned char *code;
int size;
bool is_package;
};

Distinto en la versión 3.11: El nuevo campo is_package indica si el módulo es un paquete o no. Esto
sustituye a la configuración del campo size con un valor negativo.
const struct _frozen *PyImport_FrozenModules
Este puntero se inicializa para apuntar a un arreglo de registros _frozen, terminado por uno cuyos registros
son todos NULL o cero. Cuando se importa un módulo congelado, se busca en esta tabla. El código de terceros
podría jugar con esto para proporcionar una colección de módulos congelados creada dinámicamente.
int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))
Part of the Stable ABI. Agrega un solo módulo a la tabla existente de módulos incorporados. Este es un con-
tenedor conveniente PyImport_ExtendInittab(), que retorna -1 si la tabla no se puede extender. El

6.4. Importando Módulos 71

The Python/C API, Versión 3.11.0

nuevo módulo se puede importar con el nombre name, y utiliza la función initfunc como la función de inicia-
lización llamada en el primer intento de importación. Esto debería llamarse antes de Py_Initialize().
struct _inittab
Estructura que describe una sola entrada en la lista de módulos incorporados. Cada una de estas estructuras
proporciona el nombre y la función de inicialización de un módulo incorporado en el intérprete. El nombre
es una cadena de caracteres codificada ASCII. Los programas que incorporan Python pueden usar una ma-
triz de estas estructuras junto con PyImport_ExtendInittab() para proporcionar módulos integrados
adicionales. La estructura se define en Include/import.h como:
struct _inittab {
const char *name; /* ASCII encoded string */
PyObject* (*initfunc)(void);
};

int PyImport_ExtendInittab(struct _inittab *newtab)

Agrega una colección de módulos a la tabla de módulos integrados. El arreglo newtab debe terminar con una
entrada centinela que contiene NULL para el campo name; Si no se proporciona el valor centinela, se puede
producir un error de memoria. Retorna 0 en caso de éxito o -1 si se puede asignar memoria insuficiente para
ampliar la tabla interna. En caso de error, no se agregan módulos a la tabla interna. Esta función debe ser
llamada antes de Py_Initialize().
Si Python es inicializado múltiples veces, se debe llamar PyImport_AppendInittab() o
PyImport_ExtendInittab() antes de cada inicialización de Python.

6.5 Soporte de empaquetado (marshalling) de datos

Estas rutinas permiten que el código C funcione con objetos serializados utilizando el mismo formato de datos que
el módulo marshal. Hay funciones para escribir datos en el formato de serialización y funciones adicionales que
se pueden usar para volver a leer los datos. Los archivos utilizados para almacenar datos ordenados deben abrirse en
modo binario.
Los valores numéricos se almacenan con el byte menos significativo primero.
El módulo admite dos versiones del formato de datos: la versión 0 es la versión histórica, la versión 1 comparte
cadenas de caracteres internas en el archivo y al desempaquetar (unmarshalling). La versión 2 usa un formato binario
para números de punto flotante. Py_MARSHAL_VERSION indica el formato de archivo actual (actualmente 2).
void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Empaqueta (marshal) un entero value long a un archivo file. Esto solo escribirá los 32 bits menos significativos
de value; sin importar el tamaño del tipo long nativo. version indica el formato del archivo.
void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
Empaqueta (marshal) un objeto Python, value, a un archivo file. version indica el formato del archivo.
PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)
Return value: New reference. Retorna un objeto de bytes que contiene la representación empaquetada (mars-
halled) de value. version indica el formato del archivo.
Las siguientes funciones permiten volver a leer los valores empaquetados (marshalled).
long PyMarshal_ReadLongFromFile(FILE *file)
Retorna un entero long de C desde el flujo de datos FILE* abierto para lectura. Solo se puede leer un valor
de 32 bits con esta función, independientemente del tamaño nativo del tipo long.
En caso de error, establece la excepción apropiada (EOFError) y retorna -1.
int PyMarshal_ReadShortFromFile(FILE *file)
Retorna un entero short de C desde el flujo de datos FILE* abierto para lectura. Solo se puede leer un valor
de 16 bits con esta función, independientemente del tamaño nativo del tipo short.
En caso de error, establece la excepción apropiada (EOFError) y retorna -1.

72 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)

Return value: New reference. Retorna un objeto Python del flujo de datos FILE* abierto para lectura.
En caso de error, establece la excepción apropiada (EOFError, ValueError o TypeError) y retorna
NULL.
PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)
Return value: New reference. Retorna un objeto Python del flujo de datos FILE* abierto para lectura. A dife-
rencia de PyMarshal_ReadObjectFromFile(), esta función asume que no se leerán más objetos del
archivo, lo que le permite cargar agresivamente los datos del archivo en la memoria para que la deserialización
pueda operar desde dichos datos en lugar de leer un byte a la vez desde el archivo. Solo use esta variante si
está seguro de que no leerá nada más del archivo.
En caso de error, establece la excepción apropiada (EOFError, ValueError o TypeError) y retorna
NULL.
PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
Return value: New reference. Retorna un objeto Python del flujo de datos en un búfer de bytes que contiene len
bytes a los que apunta data.
En caso de error, establece la excepción apropiada (EOFError, ValueError o TypeError) y retorna
NULL.

6.6 Analizando argumentos y construyendo valores

Estas funciones son útiles al crear sus propias funciones y métodos de extensiones. Información y ejemplos adicionales
están disponibles en extending-index.
Las tres primeras de estas funciones descritas, PyArg_ParseTuple(),
PyArg_ParseTupleAndKeywords(), y PyArg_Parse(), todas usan cadenas de caracteres de for-
mato que se utilizan para contarle a la función sobre los argumentos esperados. Las cadenas de caracteres de formato
utilizan la misma sintaxis para cada una de estas funciones.

6.6.1 Analizando argumentos

Una cadena de formato consta de cero o más «unidades de formato.» Una unidad de formato describe un objeto
Python; por lo general es un solo carácter o una secuencia de unidades formato entre paréntesis. Con unas pocas
excepciones, una unidad de formato que no es una secuencia entre paréntesis normalmente corresponde a un único
argumento de dirección de estas funciones. En la siguiente descripción, la forma citada es la unidad de formato; la
entrada en paréntesis (redondos) es el tipo de objeto Python que coincida con la unidad de formato; y la entrada entre
corchetes [cuadrados] es el tipo de la variable(s) C cuya dirección debe ser pasada.

Cadena de caracteres y búferes

Estos formatos permiten acceder a un objeto como un bloque contiguo de memoria. Usted no tiene que proporcionar
almacenamiento en bruto para el Unicode o área de bytes retornada.
En general, cuando un formato establece un puntero a un búfer, el búfer es gestionado por el objeto de Python
correspondiente, y el búfer comparte la vida útil de este objeto. Usted no tendrá que liberar cualquier memoria usted
mismo. Las únicas excepciones son es, es#, et y et#.
Sin embargo, cuando una estructura Py_buffer se llena, la memoria intermedia subyacente está bloqueada de
manera que la persona que llama puede posteriormente utilizar la memoria intermedia incluso dentro de un bloque
Py_BEGIN_ALLOW_THREADS sin el riesgo de que los datos mutables sean redimensionados o destruidos. Como
resultado, usted tiene que llamar PyBuffer_Release() después de haber terminado de procesar los datos (o
en caso de aborto temprano).
A menos que se indique lo contrario, los búferes no son terminados en NULL (NUL-terminated).

6.6. Analizando argumentos y construyendo valores 73

The Python/C API, Versión 3.11.0

Algunos formatos requieren bytes-like object de sólo lectura, y establecen un puntero en lugar de una estructura de
búfer. Trabajan comprobando que el campo del objeto PyBufferProcs.bf_releasebuffer es NULL, que
no permite objetos mutables como bytearray.

Nota: Para todas las variantes de formatos # (s#, y#, etc.), la macro PY_SSIZE_T_CLEAN tiene que estar definida
antes de incluir Python.h. En Python 3.9 y versiones anteriores, el tipo del argumento length es Py_ssize_t si
la macro PY_SSIZE_T_CLEAN está definida, o int si no lo está.

s (str) [const char *] Convierte un objeto Unicode a un puntero C a una cadena de caracteres. Un puntero a
una cadena de caracteres existente se almacena en la variable puntero del carácter cuya dirección se pasa.
La cadena de caracteres en C es terminada en NULL. La cadena de caracteres de Python no debe contener
puntos de código incrustado nulos; si lo hace, se lanza una excepción ValueError. Los objetos Unicode se
convierten en cadenas de caracteres de C utilizando codificación 'utf-8'. Si esta conversión fallase lanza
un UnicodeError.

Nota: Este formato no acepta objetos de tipo bytes. Si desea aceptar los caminos del sistema
de archivos y convertirlos en cadenas de caracteres C, es preferible utilizar el formato O& con
PyUnicode_FSConverter() como convertidor.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando se encontraron puntos de código nulos
incrustados en la cadena de caracteres de Python.
s* (str o bytes-like object) [Py_buffer] Este formato acepta objetos Unicode, así como objetos de tipo bytes.
Llena una estructura Py_buffer proporcionada por la persona que llama. En este caso la cadena de carac-
teres de C resultante puede contener bytes NUL embebidos. Los objetos Unicode se convierten en cadenas de
caracteres C utilizando codificación 'utf-8'.
s# (str, bytes-like object de sólo lectura) [const char *, Py_ssize_t] Como s*, excepto que no acepta los
objetos mutables. El resultado se almacena en dos variables de C, la primera un puntero a una cadena de
caracteres C, el segundo es su longitud. La cadena de caracteres puede contener caracteres nulos incrustados.
Los objetos Unicode se convierten en cadenas de caracteres C utilizando codificación 'utf-8'.
z (str o None) [const char *] Como s, pero el objeto Python también puede ser None, en cuyo caso el puntero
C se establece en NULL.
z* (str, bytes-like object o None) [Py_buffer] Como s*, pero el objeto Python también puede ser None, en cuyo
caso el miembro de buf de la estructura Py_buffer se establece en NULL.
z# (str, bytes-like object de sólo lectura o None) [const char *, Py_ssize_t] Como s#, pero el objeto Pyt-
hon también puede ser None, en cuyo caso el puntero C se establece en NULL.
y (bytes-like object de sólo lectura) [const char *] Este formato convierte un objeto de tipo bytes a un puntero C a
una cadena de caracteres; no acepta objetos Unicode. El búfer de bytes no debe contener bytes nulos incrustados;
si lo hace, se lanza una excepción ValueError.
Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando bytes nulos incrustados se encontraron
en el buffer de bytes.
y* (bytes-like object) [Py_buffer] Esta variante de s* no acepta objetos Unicode, solamente los objetos de tipo
bytes. Esta es la forma recomendada para aceptar datos binarios.
y# (bytes-like object de sólo lectura) [const char *, Py_ssize_t] Esta variante en s# no acepta objetos Uni-
code, solo objetos similares a bytes.
S (bytes) [PyBytesObject *] Requires that the Python object is a bytes object, without attempting any con-
version. Raises TypeError if the object is not a bytes object. The C variable may also be declared as
PyObject*.
Y (bytearray) [PyByteArrayObject *] Requires that the Python object is a bytearray object, without at-
tempting any conversion. Raises TypeError if the object is not a bytearray object. The C variable may
also be declared as PyObject*.

74 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

u (str) [const Py_UNICODE *] Convierte un objeto Unicode de Python a un puntero a un búfer C NUL termi-
nado de caracteres Unicode. Debe pasar la dirección de una variable de puntero Py_UNICODE, que se llena
con el puntero a un búfer Unicode existente. Tenga en cuenta que el ancho de un carácter Py_UNICODE
depende de las opciones de compilación (que es 16 o 32 bits). La cadena de Python no debe contener puntos
de código incrustado nulos; si lo hace, se lanza una excepción ValueError.
Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando se encontraron puntos de código nulos
incrustados en la cadena de caracteres de Python.
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API de viejo estilo Py_UNICODE;
favor migrar al uso de PyUnicode_AsWideCharString().
u# (str) [const Py_UNICODE *, Py_ssize_t] Esta variante en u almacena en dos variables de C, el primero
un puntero a un búfer de datos Unicode, el segundo de su longitud. Esta variante permite puntos de código
nulos.
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API de viejo estilo Py_UNICODE;
favor migrar al uso de PyUnicode_AsWideCharString().
Z (str o None) [const Py_UNICODE *] Como u, pero el objeto Python también puede ser None, en cuyo caso
el puntero Py_UNICODE se establece en NULL.
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API de viejo estilo Py_UNICODE;
favor migrar al uso de PyUnicode_AsWideCharString().
z# (str o None) [const Py_UNICODE *, Py_ssize_t] Al igual que u#, pero el objeto Python también puede
ser None, en cuyo caso el puntero Py_UNICODE se establece en NULL.
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API de viejo estilo Py_UNICODE;
favor migrar al uso de PyUnicode_AsWideCharString().
U (str) [PyObject *] Requires that the Python object is a Unicode object, without attempting any conversion. Rai-
ses TypeError if the object is not a Unicode object. The C variable may also be declared as PyObject*.
w* (bytes-like object de lectura y escritura) [Py_buffer] Este formato acepta cualquier objeto que implemente la
interfaz del búfer de lectura-escritura. Llena la estructura Py_buffer proporcionada por quien llama. El
búfer puede contener bytes nulos incrustados. Quien llama tiene que llamar PyBuffer_Release() cuando
termina con el búfer.
es (str) [const char *encoding, char **buffer] Esta variante en s se usa para codificar Unicode en un búfer de
caracteres. Solo funciona para datos codificados sin bytes NUL integrados.
This format requires two arguments. The first is only used as input, and must be a const char* which
points to the name of an encoding as a NUL-terminated string, or NULL, in which case 'utf-8' encoding
is used. An exception is raised if the named encoding is not known to Python. The second argument must be
a char**; the value of the pointer it references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.
PyArg_ParseTuple() asignará un búfer del tamaño necesitado, copiará los datos codificados en este búfer
y ajustará *buffer para referenciar el nuevo almacenamiento asignado. Quien llama es responsable para llamar
PyMem_Free() para liberar el búfer asignado después de su uso.
et (str, bytes o bytearray) [const char *encoding, char **buffer] Igual que es, excepto que los objetos
de cadena de caracteres de bytes se pasan sin recodificarlos. En cambio, la implementación supone que el objeto
de cadena de caracteres de bytes utiliza la codificación que se pasa como parámetro.
es# (str) [const char *encoding, char **buffer, Py_ssize_t *buffer_length] Esta variante en s# se usa
para codificar Unicode en un búfer de caracteres. A diferencia del formato es, esta variante permite datos
de entrada que contienen caracteres NUL.
It requires three arguments. The first is only used as input, and must be a const char* which points to the
name of an encoding as a NUL-terminated string, or NULL, in which case 'utf-8' encoding is used. An
exception is raised if the named encoding is not known to Python. The second argument must be a char**;
the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will
be encoded in the encoding specified by the first argument. The third argument must be a pointer to an integer;
the referenced integer will be set to the number of bytes in the output buffer.

6.6. Analizando argumentos y construyendo valores 75

The Python/C API, Versión 3.11.0

Hay dos modos de operación:

Si *buffer señala un puntero NULL, la función asignará un búfer del tamaño necesario, copiará los datos co-
dificados en este búfer y configurará *buffer para hacer referencia al almacenamiento recién asignado. Quien
llama es responsable de llamar a PyMem_Free() para liberar el búfer asignado después del uso.
Si *buffer apunta a un puntero no NULL (un búfer ya asignado), PyArg_ParseTuple() usará esta ubica-
ción como el búfer e interpretará el valor inicial de *buffer_length como el tamaño del búfer. Luego copiará los
datos codificados en el búfer y los terminará en NUL. Si el búfer no es lo suficientemente grande, se establecerá
a ValueError.
En ambos casos, *buffer_length se establece a la longitud de los datos codificados sin el byte NUL final.
et# (str, bytes o bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]
Igual que es#, excepto que los objetos de cadena de caracteres de bytes se pasan sin recodificarlos. En
cambio, la implementación supone que el objeto de cadena de caracteres de bytes utiliza la codificación que
se pasa como parámetro.

Números

b (int) [unsigned char] Convert a nonnegative Python integer to an unsigned tiny int, stored in a C unsigned
char.
B (int) [unsigned char] Convert a Python integer to a tiny int without overflow checking, stored in a C unsigned
char.
h (int) [short int] Convert a Python integer to a C short int.
H (int) [unsigned short int] Convert a Python integer to a C unsigned short int, without overflow chec-
king.
i (int) [int] Convert a Python integer to a plain C int.
I (int) [unsigned int] Convert a Python integer to a C unsigned int, without overflow checking.
l (int) [long int] Convert a Python integer to a C long int.
k (int) [unsigned long] Convert a Python integer to a C unsigned long without overflow checking.
L (int) [long long] Convert a Python integer to a C long long.
K (int) [unsigned long long] Convert a Python integer to a C unsigned long long without overflow chec-
king.
n (int) [Py_ssize_t] Convierte un entero de Python a un Py_ssize_t de C.
c (bytes o bytearray de largo 1) [char] Convert a Python byte, represented as a bytes or bytearray ob-
ject of length 1, to a C char.
Distinto en la versión 3.3: Permite objetos bytearray.
C (str de largo 1) [int] Convert a Python character, represented as a str object of length 1, to a C int.
f (float) [float] Convert a Python floating point number to a C float.
d (float) [double] Convert a Python floating point number to a C double.
D (complex) [Py_complex] Convierte un número complejo de Python en una estructura Py_complex de C.

76 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

Otros objetos

O (object) [PyObject *] Almacena un objeto Python (sin ninguna conversión) en un puntero de objeto C. El pro-
grama C recibe así el objeto real que se pasó. El recuento de referencia del objeto no aumenta. El puntero
almacenado no es NULL.
O! (object) [typeobject, PyObject *] Store a Python object in a C object pointer. This is similar to O, but takes two
C arguments: the first is the address of a Python type object, the second is the address of the C variable (of
type PyObject*) into which the object pointer is stored. If the Python object does not have the required
type, TypeError is raised.
O& (object) [converter, anything] Convert a Python object to a C variable through a converter function. This takes
two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to
void*. The converter function in turn is called as follows:

status = converter(object, address);

where object is the Python object to be converted and address is the void* argument that was passed to the
PyArg_Parse* function. The returned status should be 1 for a successful conversion and 0 if the conversion
has failed. When the conversion fails, the converter function should raise an exception and leave the content of
address unmodified.
Si el converter retorna Py_CLEANUP_SUPPORTED, se puede llamar por segunda vez si el análisis del argu-
mento finalmente falla, dando al convertidor la oportunidad de liberar cualquier memoria que ya haya asignado.
En esta segunda llamada, el parámetro object será NULL; address tendrá el mismo valor que en la llamada ori-
ginal.
Distinto en la versión 3.1: Py_CLEANUP_SUPPORTED fue agregada.
p (bool) [int] Prueba el valor pasado por verdad (un booleano predicado p) y convierte el resultado a su valor
entero C verdadero/falso entero equivalente. Establece int en 1 si la expresión era verdadera y 0 si era falsa.
Esto acepta cualquier valor válido de Python. Consulte truth para obtener más información sobre cómo Python
prueba los valores por verdad.
Nuevo en la versión 3.3.
(items) (tuple) [matching-items] El objeto debe ser una secuencia de Python cuya longitud es el número de
unidades de formato en items. Los argumentos C deben corresponder a las unidades de formato individuales
en items. Las unidades de formato para secuencias pueden estar anidadas.
Es posible pasar enteros «largos» (enteros cuyo valor excede el de la plataforma LONG_MAX), sin embargo, no se
realiza una verificación de rango adecuada — los bits más significativos se truncan silenciosamente cuando el campo
receptor es demasiado pequeño para recibir el valor (en realidad, la semántica se hereda de las descargas en C — su
kilometraje puede variar).
Algunos otros caracteres tienen un significado en una cadena de formato. Esto puede no ocurrir dentro de paréntesis
anidados. Son:
| Indica que los argumentos restantes en la lista de argumentos de Python son opcionales. Las variables C corres-
pondientes a argumentos opcionales deben inicializarse a su valor predeterminado — cuando no se especifica
un argumento opcional, PyArg_ParseTuple() no toca el contenido de las variables C correspondientes.
$ PyArg_ParseTupleAndKeywords() solamente: indica que los argumentos restantes en la lista de argu-
mentos de Python son solo palabras clave. Actualmente, todos los argumentos de solo palabras clave también
deben ser argumentos opcionales, por lo que | siempre debe especificarse antes de $ en la cadena de formato.
Nuevo en la versión 3.3.
: La lista de unidades de formato termina aquí; la cadena después de los dos puntos se usa como el nombre de la
función en los mensajes de error (el «valor asociado» de la excepción que PyArg_ParseTuple() lanza).
; La lista de unidades de formato termina aquí; la cadena después del punto y coma se usa como mensaje de error
en lugar de del mensaje de error predeterminado. : y ; se excluyen mutuamente.
Tenga en cuenta que las referencias de objetos de Python que se proporcionan a la persona que llama son referencias
prestadas (borrowed); ¡no disminuya su conteo de referencias!

6.6. Analizando argumentos y construyendo valores 77

The Python/C API, Versión 3.11.0

Los argumentos adicionales pasados a estas funciones deben ser direcciones de variables cuyo tipo está determinado
por la cadena de formato; Estos se utilizan para almacenar valores de la tupla de entrada. Hay algunos casos, como
se describe en la lista de unidades de formato anterior, donde estos parámetros se utilizan como valores de entrada;
deben coincidir con lo especificado para la unidad de formato correspondiente en ese caso.
For the conversion to succeed, the arg object must match the format and the format must be exhausted. On success,
the PyArg_Parse* functions return true, otherwise they return false and raise an appropriate exception. When the
PyArg_Parse* functions fail due to conversion failure in one of the format units, the variables at the addresses
corresponding to that and the following format units are left untouched.

Funciones API

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

Part of the Stable ABI. Analiza los parámetros de una función que solo toma parámetros posicionales en
variables locales. Retorna verdadero en el éxito; en caso de fallo, retorna falso y lanza la excepción apropiada.
int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
Part of the Stable ABI. Idéntico a PyArg_ParseTuple(), excepto que acepta una va_list en lugar de un
número variable de argumentos .
int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[],
...)
Part of the Stable ABI. Analiza los parámetros de una función que toma parámetros posicionales y de palabras
clave en variables locales. El argumento keywords es un arreglo terminado en NULL de nombres de parámetros
de palabras clave. Los nombres vacíos denotan parámetros solo posicionales. Retorna verdadero cuando hay
éxito; en caso de fallo, retorna falso y lanza la excepción apropiada.
Distinto en la versión 3.6: Soporte agregado para sólo parámetros posicionales.
int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char
*keywords[], va_list vargs)
Part of the Stable ABI. Idéntico a PyArg_ParseTupleAndKeywords(), excepto que acepta una va_list
en lugar de un número variable de argumentos.
int PyArg_ValidateKeywordArguments(PyObject*)
Part of the Stable ABI. Asegúrese de que las claves en el diccionario de argumentos de palabras clave son
cadenas. Esto solo es necesario si PyArg_ParseTupleAndKeywords() no se utiliza, ya que este último
ya hace esta comprobación.
Nuevo en la versión 3.2.
int PyArg_Parse(PyObject *args, const char *format, ...)
Part of the Stable ABI. Función utilizada para deconstruir las listas de argumentos de las funciones de «estilo
antiguo» — estas son funciones que usan el método de análisis de parámetros METH_OLDARGS, que se ha
eliminado en Python 3. No se recomienda su uso en el análisis de parámetros en código nuevo, y la mayoría del
código en el intérprete estándar se ha modificado para que ya no se use para ese propósito. Sin embargo, sigue
siendo una forma conveniente de descomponer otras tuplas, y puede continuar usándose para ese propósito.
int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
Part of the Stable ABI. A simpler form of parameter retrieval which does not use a format string to specify
the types of the arguments. Functions which use this method to retrieve their parameters should be declared as
METH_VARARGS in function or method tables. The tuple containing the actual parameters should be passed
as args; it must actually be a tuple. The length of the tuple must be at least min and no more than max; min and
max may be equal. Additional arguments must be passed to the function, each of which should be a pointer to a
PyObject* variable; these will be filled in with the values from args; they will contain borrowed references.
The variables which correspond to optional parameters not given by args will not be filled in; these should be
initialized by the caller. This function returns true on success and false if args is not a tuple or contains the
wrong number of elements; an exception will be set if there was a failure.
Este es un ejemplo del uso de esta función, tomado de las fuentes del módulo auxiliar _weakref para refe-
rencias débiles:

78 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
PyObject *object;
PyObject *callback = NULL;
PyObject *result = NULL;

if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {

result = PyWeakref_NewRef(object, callback);
}
return result;
}

La llamada a PyArg_UnpackTuple() en este ejemplo es completamente equivalente a esta llamada a

PyArg_ParseTuple():
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

6.6.2 Construyendo valores

PyObject *Py_BuildValue(const char *format, ...)

Return value: New reference. Part of the Stable ABI. Create a new value based on a format string similar to
those accepted by the PyArg_Parse* family of functions and a sequence of values. Returns the value or
NULL in the case of an error; an exception will be raised if NULL is returned.
Py_BuildValue() no siempre genera una tupla. Construye una tupla solo si su cadena de formato contiene
dos o más unidades de formato. Si la cadena de formato está vacía, retorna None; si contiene exactamente una
unidad de formato, retorna el objeto que describa esa unidad de formato. Para forzarlo a retornar una tupla de
tamaño 0 o uno, paréntesis la cadena de formato.
Cuando los búfer de memoria se pasan como parámetros para suministrar datos para construir objetos, como
para los formatos s y s#, los datos requeridos se copian. Las memorias intermedias proporcionadas por quien
llama nunca son referenciadas por los objetos creados por Py_BuildValue(). En otras palabras, si su
código invoca malloc() y pasa la memoria asignada a Py_BuildValue(), su código es responsable de
llamar a free() para esa memoria una vez retorna Py_BuildValue().
En la siguiente descripción, la cadena de caracteres entre comillas, así, es la unidad de formato; la entrada
entre paréntesis (redondos) es el tipo de objeto Python que retornará la unidad de formato; y la entrada entre
corchetes [cuadrados] es el tipo de los valores C que se pasarán.
Los caracteres espacio, tabulación, dos puntos y coma se ignoran en las cadenas de formato (pero no dentro
de las unidades de formato como s#). Esto se puede usar para hacer que las cadenas de formato largo sean un
poco más legibles.
s (str o None) [const char *] Convierte una cadena de caracteres C terminada en nulo en un objeto Python
str usando la codificación 'utf-8'. Si el puntero de la cadena de caracteres C es NULL, se usa None.
s# (str o None) [const char *, Py_ssize_t] Convierte una cadena de caracteres de C y su longitud en
un objeto Python str utilizando la codificación 'utf-8'. Si el puntero de la cadena de caracteres de
C es NULL, la longitud se ignora y se retorna None.
y (bytes) [const char *] Esto convierte una cadena de caracteres de C en un objeto Python bytes. Si el
puntero de la cadena de caracteres de C es NULL, se retorna None.
y# (bytes) [const char *, Py_ssize_t] Esto convierte una cadena de caracteres de C y sus longitudes
en un objeto Python. Si el puntero de la cadena de caracteres de C es NULL, se retorna None.
z (str o None) [const char *] Igual que s.
z# (str o None) [const char *, Py_ssize_t] Igual que s#.
u (str) [const wchar_t *] Convert a null-terminated wchar_t buffer of Unicode (UTF-16 or UCS-4) data
to a Python Unicode object. If the Unicode buffer pointer is NULL, None is returned.

6.6. Analizando argumentos y construyendo valores 79

The Python/C API, Versión 3.11.0

u# (str) [const wchar_t *, Py_ssize_t] Convierte un búfer de datos Unicode (UTF-16 o UCS-4) y su
longitud en un objeto Python Unicode. Si el puntero del búfer Unicode es NULL, la longitud se ignora y
se retorna None.
U (str o None) [const char *] Igual que s.
z# (str o None) [const char *, Py_ssize_t] Igual que s#.
i (int) [int] Convert a plain C int to a Python integer object.
b (int) [char] Convert a plain C char to a Python integer object.
h (int) [short int] Convert a plain C short int to a Python integer object.
l (int) [long int] Convert a C long int to a Python integer object.
B (int) [unsigned char] Convert a C unsigned char to a Python integer object.
H (int) [unsigned short int] Convert a C unsigned short int to a Python integer object.
I (int) [unsigned int] Convert a C unsigned int to a Python integer object.
k (int) [unsigned long] Convert a C unsigned long to a Python integer object.
L (int) [long long] Convert a C long long to a Python integer object.
K (int) [unsigned long long] Convert a C unsigned long long to a Python integer object.
n (int) [Py_ssize_t] Convierte un Py_ssize_t de C a un entero de Python.
c (bytes de largo 1) [char] Convert a C int representing a byte to a Python bytes object of length 1.
C (str de largo 1) [int] Convert a C int representing a character to Python str object of length 1.
d (float) [double] Convert a C double to a Python floating point number.
f (float) [float] Convert a C float to a Python floating point number.
D (complex) [Py_complex *] Convierte una estructura Py_complex de C en un número complejo de
Python.
O (object) [PyObject *] Pasa un objeto Python sin tocarlo (excepto por su recuento de referencia, que se
incrementa en uno). Si el objeto pasado es un puntero NULL, se supone que esto fue causado por-
que la llamada que produjo el argumento encontró un error y estableció una excepción. Por lo tanto,
Py_BuildValue() retornará NULL pero no lanzará una excepción. Si aún no se ha producido nin-
guna excepción, se establece SystemError.
S (object) [PyObject *] Igual que O.
N (object) [PyObject *] Igual que O, excepto que no incrementa el recuento de referencia en el objeto. Útil
cuando el objeto se crea mediante una llamada a un constructor de objetos en la lista de argumentos.
O& (object) [converter, anything] Convert anything to a Python object through a converter function. The fun-
ction is called with anything (which should be compatible with void*) as its argument and should return
a «new» Python object, or NULL if an error occurred.
(items) (tuple) [matching-items] Convierta una secuencia de valores C en una tupla de Python con el
mismo número de elementos.
[items] (list) [matching-items] Convierte una secuencia de valores C en una lista de Python con el mis-
mo número de elementos.
{items} (dict) [matching-items] Convierte una secuencia de valores C en un diccionario Python. Cada
par de valores C consecutivos agrega un elemento al diccionario, que sirve como clave y valor, respecti-
vamente.
Si hay un error en la cadena de formato, se establece la excepción SystemError y se retorna NULL.
PyObject *Py_VaBuildValue(const char *format, va_list vargs)
Return value: New reference. Part of the Stable ABI. Idéntico a Py_BuildValue(), excepto que acepta una
va_list en lugar de un número variable de argumentos.

80 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

6.7 Conversión y formato de cadenas de caracteres

Funciones para conversión de números y salida de cadena de caracteres formateadas.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
Part of the Stable ABI. Salida de no más de size bytes a str según la cadena de caracteres de formato format y
los argumentos adicionales. Consulte la página de manual de Unix snprintf(3).
int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
Part of the Stable ABI. Salida de no más de size bytes a str según la cadena de caracteres de formato format y
la lista de argumentos variables va. Página de manual de Unix vsnprintf(3).
PyOS_snprintf() y PyOS_vsnprintf() envuelven las funciones estándar de la biblioteca C snprintf()
y vsnprintf(). Su propósito es garantizar un comportamiento consistente en casos de esquina (corner cases), que
las funciones del Estándar C no hacen.
The wrappers ensure that str[size-1] is always '\0' upon return. They never write more than size bytes (in-
cluding the trailing '\0') into str. Both functions require that str != NULL, size > 0, format != NULL
and size < INT_MAX. Note that this means there is no equivalent to the C99 n = snprintf(NULL, 0,
...) which would determine the necessary buffer size.
El valor de retorno (rv) para estas funciones debe interpretarse de la siguiente manera:
• Cuando 0 <= rv < size, la conversión de salida fue exitosa y los caracteres rv se escribieron en str (ex-
cluyendo el byte '\0' final en str[rv]).
• Cuando rv >= size, la conversión de salida se truncó y se habría necesitado un búfer con rv + 1 bytes
para tener éxito. str[size-1] es '\0' en este caso.
• Cuando rv < 0, «sucedió algo malo». str[size-1] es '\0' en este caso también, pero el resto de str
no está definido. La causa exacta del error depende de la plataforma subyacente.
Las siguientes funciones proporcionan cadenas de caracteres independientes de la configuración regional para numerar
las conversiones.
double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
Part of the Stable ABI. Convert a string s to a double, raising a Python exception on failure. The set of
accepted strings corresponds to the set of strings accepted by Python’s float() constructor, except that s
must not have leading or trailing whitespace. The conversion is independent of the current locale.
Si endptr es NULL, convierte toda la cadena de caracteres. Lanza ValueError y retorna -1.0 si la cadena
de caracteres no es una representación válida de un número de punto flotante.
Si endptr no es NULL, convierte la mayor cantidad posible de la cadena de caracteres y configura *endptr
para que apunte al primer carácter no convertido. Si ningún segmento inicial de la cadena de caracteres es la
representación válida de un número de punto flotante, configura *endptr para que apunte al comienzo de la
cadena de caracteres, lanza ValueError y retorna -1.0.
Si s representa un valor que es demasiado grande para almacenar en un flotante (por ejemplo, "1e500"
es una cadena de caracteres de este tipo en muchas plataformas), entonces si overflow_exception es
NULL retorna Py_HUGE_VAL (con un signo apropiado) y no establece ninguna excepción. De lo contrario,
overflow_exception debe apuntar a un objeto excepción de Python; lanza esa excepción y retorna -1.
0. En ambos casos, configura *endptr para que apunte al primer carácter después del valor convertido.
Si se produce algún otro error durante la conversión (por ejemplo, un error de falta de memoria), establece la
excepción Python adecuada y retorna -1.0.
Nuevo en la versión 3.1.
char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
Part of the Stable ABI. Convert a double val to a string using supplied format_code, precision, and flags.
format_code debe ser uno de 'e', 'E', 'f', 'F', 'g', 'G' or 'r'. Para 'r', la precision suministrada
debe ser 0 y se ignora. El código de formato 'r' especifica el formato estándar repr().

6.7. Conversión y formato de cadenas de caracteres 81

The Python/C API, Versión 3.11.0

flags puede ser cero o más de los valores Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, o Py_DTSF_ALT,
unidos por or (or-ed) juntos:
• Py_DTSF_SIGN significa preceder siempre a la cadena de caracteres retornada con un carácter de signo,
incluso si val no es negativo.
• Py_DTSF_ADD_DOT_0 significa asegurarse de que la cadena de caracteres retornada no se verá como
un número entero.
• Py_DTSF_ALT significa aplicar reglas de formato «alternativas». Consulte la documentación del espe-
cificador PyOS_snprintf() '#' para obtener más detalles.
Si ptype no es NULL, el valor al que apunta se establecerá en uno de Py_DTST_FINITE,
Py_DTST_INFINITE o Py_DTST_NAN, lo que significa que val es un número finito, un número infinito
o no es un número, respectivamente.
El valor de retorno es un puntero a buffer con la cadena de caracteres convertida o NULL si la conversión falla.
La persona que llama es responsable de liberar la cadena de caracteres retornada llamando a PyMem_Free().
Nuevo en la versión 3.1.
int PyOS_stricmp(const char *s1, const char *s2)
Comparación no sensible a mayúsculas y minúsculas en cadenas de caracteres. La función se comporta casi de
manera idéntica a strcmp(), excepto que ignora el caso.
int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)
Comparación no sensible a mayúsculas y minúsculas en cadenas de caracteres. La función se comporta casi de
manera idéntica a strncmp(), excepto que ignora el caso.

6.8 Reflexión

PyObject *PyEval_GetBuiltins(void)
Return value: Borrowed reference. Part of the Stable ABI. Retorna un diccionario de las construcciones en el
marco de ejecución actual, o el intérprete del estado del hilo si no se está ejecutando ningún marco actualmente.
PyObject *PyEval_GetLocals(void)
Return value: Borrowed reference. Part of the Stable ABI. Retorna un diccionario de las variables locales en el
marco de ejecución actual, o NULL si actualmente no se está ejecutando ningún marco.
PyObject *PyEval_GetGlobals(void)
Return value: Borrowed reference. Part of the Stable ABI. Retorna un diccionario de las variables globales en
el marco de ejecución actual, o NULL si actualmente no se está ejecutando ningún marco.
PyFrameObject *PyEval_GetFrame(void)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el marco del estado del hilo actual, que es
NULL si actualmente no se está ejecutando ningún marco.
Vea también PyThreadState_GetFrame().
const char *PyEval_GetFuncName(PyObject *func)
Part of the Stable ABI. Retorna el nombre de func si es una función, clase u objeto de instancia; de lo contrario,
el nombre del tipo funcs.
const char *PyEval_GetFuncDesc(PyObject *func)
Part of the Stable ABI. Retorna una cadena de caracteres de descripción, según el tipo de func. Los valores
de retorno incluyen «()» para funciones y métodos, «constructor», «instancia» y «objeto». Concatenado con el
resultado de PyEval_GetFuncName(), el resultado será una descripción de func.

82 Capítulo 6. Utilidades
 The Python/C API, Versión 3.11.0

6.9 Registro de códec y funciones de soporte

int PyCodec_Register(PyObject *search_function)

Part of the Stable ABI. Registra una nueva función de búsqueda de códec.
Como efecto secundario, intenta cargar el paquete encodings, si aún no lo ha hecho, para asegurarse de que
siempre esté primero en la lista de funciones de búsqueda.
int PyCodec_Unregister(PyObject *search_function)
Part of the Stable ABI since version 3.10. Anula el registro de una función de búsqueda de códecs y borra el
caché del registro. Si la función de búsqueda no está registrada, no hace nada. Retorna 0 en caso de éxito.
Lanza una excepción y devuelva -1 en caso de error.
Nuevo en la versión 3.10.
int PyCodec_KnownEncoding(const char *encoding)
Part of the Stable ABI. Retorna 1 o 0 dependiendo de si hay un códec registrado para el encoding dado. Esta
función siempre finaliza con éxito.
PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. API de codificación genérica basada en códec.
object se pasa a través de la función de codificador encontrada por el encoding dado usando el método de manejo
de errores definido por errors. errors pueden ser NULL para usar el método predeterminado definido para el
códec. Lanza un LookupError si no se puede encontrar el codificador.
PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. API de decodificación basada en códec genérico.
object se pasa a través de la función de decodificador encontrada por el encoding dado usando el método de
manejo de errores definido por errors. errors puede ser NULL para usar el método predeterminado definido
para el códec. Lanza un LookupError si no se puede encontrar el codificador.

6.9.1 API de búsqueda de códec

En las siguientes funciones, la cadena de caracteres encoding se busca convertida a todos los caracteres en minúscula,
lo que hace que las codificaciones se busquen a través de este mecanismo sin distinción entre mayúsculas y minúsculas.
Si no se encuentra ningún códec, se establece un KeyError y se retorna NULL.
PyObject *PyCodec_Encoder(const char *encoding)
Return value: New reference. Part of the Stable ABI. Obtiene una función de codificador para el encoding dado.
PyObject *PyCodec_Decoder(const char *encoding)
Return value: New reference. Part of the Stable ABI. Obtiene una función de decodificador para el encoding
dado.
PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. Obtiene un objeto IncrementalEncoder para el
encoding dada.
PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. Obtiene un objeto IncrementalDecoder para el
encoding dado.
PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
Return value: New reference. Part of the Stable ABI. Obtiene una función de fábrica StreamReader para el
encoding dado.
PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
Return value: New reference. Part of the Stable ABI. Obtiene una función de fábrica StreamWriter por el
encoding dado.

6.9. Registro de códec y funciones de soporte 83

The Python/C API, Versión 3.11.0

6.9.2 API de registro para controladores de errores de codificación Unicode

int PyCodec_RegisterError(const char *name, PyObject *error)

Part of the Stable ABI. Registra la función de devolución de llamada de manejo de errores error bajo el nombre
name dado. Esta función de devolución de llamada será llamada por un códec cuando encuentre caracteres no
codificables / bytes no codificables y name se especifica como parámetro de error en la llamada a la función de
codificación / decodificación.
La devolución de llamada obtiene un único argumento, una instancia de UnicodeEncodeError,
UnicodeDecodeError o UnicodeTranslateError que contiene información sobre la secuencia
problemática de caracteres o bytes y su desplazamiento en la cadena original (consulte Objetos Unicode de Ex-
cepción para funciones para extraer esta información). La devolución de llamada debe lanzar la excepción dada
o retornar una tupla de dos elementos que contiene el reemplazo de la secuencia problemática, y un número
entero que proporciona el desplazamiento en la cadena original en la que se debe reanudar la codificación /
decodificación.
Retorna 0 en caso de éxito, -1 en caso de error.
PyObject *PyCodec_LookupError(const char *name)
Return value: New reference. Part of the Stable ABI. Busca la función de devolución de llamada de manejo de
errores registrada con name. Como caso especial se puede pasar NULL, en cuyo caso se retornará la devolución
de llamada de manejo de errores para «estricto».
PyObject *PyCodec_StrictErrors(PyObject *exc)
Return value: Always NULL. Part of the Stable ABI. Lanza exc como una excepción.
PyObject *PyCodec_IgnoreErrors(PyObject *exc)
Return value: New reference. Part of the Stable ABI. Ignora el error Unicode, omitiendo la entrada defectuosa.
PyObject *PyCodec_ReplaceErrors(PyObject *exc)
Return value: New reference. Part of the Stable ABI. Reemplaza el error de codificación Unicode con ? o
U+FFFD.
PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
Return value: New reference. Part of the Stable ABI. Reemplaza el error de codificación Unicode con referencias
de caracteres XML.
PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)
Return value: New reference. Part of the Stable ABI. Reemplaza el error de codificación Unicode con escapes
de barra invertida (\x, \u y \U).
PyObject *PyCodec_NameReplaceErrors(PyObject *exc)
Return value: New reference. Part of the Stable ABI since version 3.7. Reemplaza el error de codificación
Unicode con escapes \N{...}.
Nuevo en la versión 3.5.

84 Capítulo 6. Utilidades
 CAPÍTULO 7

Capa de objetos abstractos

Las funciones de este capítulo interactúan con los objetos de Python independientemente de su tipo, o con amplias
clases de tipos de objetos (por ejemplo, todos los tipos numéricos o todos los tipos de secuencia). Cuando se usan en
tipos de objetos para los que no se aplican, lanzarán una excepción de Python.
No es posible utilizar estas funciones en objetos que no se inicializan correctamente, como un objeto de lista que ha
sido creado por PyList_New(), pero cuyos elementos no se han establecido en algunos valores no-“NULL“ aún.

7.1 Protocolo de objeto

PyObject *Py_NotImplemented
El singleton NotImplemented, se usa para indicar que una operación no está implementada para la com-
binación de tipos dada.
Py_RETURN_NOTIMPLEMENTED
Maneja adecuadamente el retorno Py_NotImplemented desde una función C (es decir, incremente el
recuento de referencias de NotImplemented y lo retorna).
int PyObject_Print(PyObject *o, FILE *fp, int flags)
Imprime un objeto o, en el archivo fp. Retorna -1 en caso de error. El argumento de las banderas se usa
para habilitar ciertas opciones de impresión. La única opción actualmente admitida es Py_PRINT_RAW; si se
proporciona, se escribe str() del objeto en lugar de repr().
int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
Part of the Stable ABI. Retorna 1 si o tiene el atributo attr_name, y 0 en caso contrario. Esto es equivalente a
la expresión de Python hasattr(o, attr_name). Esta función siempre finaliza exitosamente.
Tenga en cuenta que las excepciones que se producen al llamar a los métodos a __getattr__() y
__getattribute__() se suprimirán. Para obtener informe de errores, utilice PyObject_GetAttr()
alternativamente.
int PyObject_HasAttrString(PyObject *o, const char *attr_name)
Part of the Stable ABI. Retorna 1 si o tiene el atributo attr_name, y 0 en caso contrario. Esto es equivalente a
la expresión de Python hasattr(o, attr_name). Esta función siempre finaliza exitosamente.
Tenga en cuenta que las excepciones que se producen al llamar a __getattr__() y
__getattribute__() y al crear un objeto de cadena temporal se suprimirán. Para obtener infor-
mes de errores, utilice PyObject_GetAttrString() en su lugar.

85
The Python/C API, Versión 3.11.0

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

Return value: New reference. Part of the Stable ABI. Recupera un atributo llamado attr_name del objeto o.
Retorna el valor del atributo en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión
de Python o.attr_name.
PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)
Return value: New reference. Part of the Stable ABI. Recupera un atributo llamado attr_name del objeto o.
Retorna el valor del atributo en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión
de Python o.attr_name.
PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)
Return value: New reference. Part of the Stable ABI. Función getter de atributo genérico que debe colocarse en
la ranura tp_getattro de un objeto tipo. Busca un descriptor en el diccionario de clases en el MRO del
objeto, así como un atributo en el objeto __ dict__ (si está presente). Como se describe en descriptors, los
descriptores de datos tienen preferencia sobre los atributos de instancia, mientras que los descriptores que no
son de datos no lo hacen. De lo contrario, se lanza un AttributeError.
int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
Part of the Stable ABI. Establece el valor del atributo llamado attr_name, para el objeto o, en el valor v. Lanza
una excepción y retorna -1 en caso de falla; retorna 0 en caso de éxito. Este es el equivalente de la declaración
de Python o.attr_name = v.
Si v es NULL, el atributo se elimina. Este comportamiento está deprecado en favor de usar
PyObject_DelAttr(), pero por el momento no hay planes de quitarlo.
int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
Part of the Stable ABI. Establece el valor del atributo llamado attr_name, para el objeto o, en el valor v. Lanza
una excepción y retorna -1 en caso de falla; retorna 0 en caso de éxito. Este es el equivalente de la declaración
de Python o.attr_name = v.
Si v es NULL, el atributo se elimina, sin embargo, esta característica está deprecada en favor de usar
PyObject_DelAttrString().
int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
Part of the Stable ABI. Establecimiento de atributo genérico y función de eliminación que está destinada a
colocarse en la ranura de un objeto tipo tp_setattro. Busca un descriptor de datos en el diccionario de
clases en el MRO del objeto y, si se encuentra, tiene preferencia sobre la configuración o eliminación del atributo
en el diccionario de instancias. De lo contrario, el atributo se establece o elimina en el objeto __dict__ (si
está presente). En caso de éxito, se retorna 0; de lo contrario, se lanza un AttributeError y se retorna
-1.
int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
Elimina el atributo llamado attr_name, para el objeto o. Retorna -1 en caso de falla. Este es el equivalente de
la declaración de Python del o.attr_name.
int PyObject_DelAttrString(PyObject *o, const char *attr_name)
Elimina el atributo llamado attr_name, para el objeto o. Retorna -1 en caso de falla. Este es el equivalente de
la declaración de Python del o.attr_name.
PyObject *PyObject_GenericGetDict(PyObject *o, void *context)
Return value: New reference. Part of the Stable ABI since version 3.10. Una implementación genérica para
obtener un descriptor __dict__. Crea el diccionario si es necesario.
Esta función también puede ser llamada para obtener el __dict__ del objeto o. Se pasa context igual a NULL
cuando se lo llama. Dado que esta función puede necesitar asignar memoria para el diccionario, puede ser más
eficiente llamar a PyObject_GetAttr() para acceder a un atributo del objeto.
En caso de fallo, retorna NULL con una excepción establecida.
Nuevo en la versión 3.3.

86 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

Part of the Stable ABI since version 3.7. Una implementación genérica para el creador de un descriptor
__dict__. Esta implementación no permite que se elimine el diccionario.
Nuevo en la versión 3.3.
PyObject **_PyObject_GetDictPtr(PyObject *obj)
Retorna un puntero al __dict__ del objeto obj. Si no hay __dict__, retorna NULL sin establecer una
excepción.
Esta función puede necesitar asignar memoria para el diccionario, por lo que puede ser más eficiente llamar a
PyObject_GetAttr() para acceder a un atributo del objeto.
PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Return value: New reference. Part of the Stable ABI. Compara los valores de o1 y o2 utilizando la operación
especificada por opid, que debe ser uno de los siguientes Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, o Py_GE,
correspondiente a <, <=, ==, !=, > o >= respectivamente. Este es el equivalente de la expresión de Python o1
op o2, donde op es el operador correspondiente a opid. Retorna el valor de la comparación en caso de éxito
o NULL en caso de error.
int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
Part of the Stable ABI. Compara los valores de o1 y o2 utilizando la operación especificada por opid, que debe
ser uno de los siguientes Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, o Py_GE, correspondiente a <, <=, ==,
!=, > o >= respectivamente. Retorna -1 en caso de error, 0 si el resultado es falso, 1 en caso contrario. Este
es el equivalente de la expresión de Python o1 op o2, donde op es el operador correspondiente a opid.

Nota: Si o1 y o2 son el mismo objeto, PyObject_RichCompareBool() siempre retornará 1 para Py_EQ y

0 para Py_NE.

PyObject *PyObject_Repr(PyObject *o)

Return value: New reference. Part of the Stable ABI. Calcula una representación de cadena de caracteres del
objeto o. Retorna la representación de cadena de caracteres en caso de éxito, NULL en caso de error. Este es
el equivalente de la expresión de Python repr(o). Llamado por la función incorporada repr().
Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar
que no descarte silenciosamente una excepción activa.
PyObject *PyObject_ASCII(PyObject *o)
Return value: New reference. Part of the Stable ABI. Como PyObject_Repr(), calcula una representación
de cadena de caracteres del objeto o, pero escapa los caracteres no ASCII en la cadena de caracteres retornada
por PyObject_Repr() con \x, \u o \U escapa. Esto genera una cadena de caracteres similar a la que
retorna PyObject_Repr() en Python 2. Llamado por la función incorporada ascii().
PyObject *PyObject_Str(PyObject *o)
Return value: New reference. Part of the Stable ABI. Calcula una representación de cadena de caracteres del
objeto o. Retorna la representación de cadena de caracteres en caso de éxito, NULL en caso de error. Llamado
por la función incorporada str() y, por lo tanto, por la función print().
Distinto en la versión 3.4: Esta función ahora incluye una afirmación de depuración para ayudar a garantizar
que no descarte silenciosamente una excepción activa.
PyObject *PyObject_Bytes(PyObject *o)
Return value: New reference. Part of the Stable ABI. Calcula una representación de bytes del objeto o. NULL
se retorna en caso de error y un objeto de bytes en caso de éxito. Esto es equivalente a la expresión de Python
bytes(o), cuando o no es un número entero. A diferencia de bytes(o), se lanza un TypeError cuando o
es un entero en lugar de un objeto de bytes con inicialización cero.
int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
Part of the Stable ABI. Retorna 1 si la clase derived es idéntica o derivada de la clase cls; de lo contrario,
retorna 0. En caso de error, retorna -1.

7.1. Protocolo de objeto 87

The Python/C API, Versión 3.11.0

Si cls es una tupla, la verificación se realizará con cada entrada en cls. El resultado será 1 cuando al menos una
de las verificaciones retorne 1, de lo contrario será 0.
Si cls tiene un método __subclasscheck__(), se llamará para determinar el estado de la subclase como
se describe en PEP 3119. De lo contrario, derived es una subclase de cls si es una subclase directa o indirecta,
es decir, contenida en cls.__ mro__.
Normalmente, solo los objetos clase, es decir, las instancias de type o una clase derivada, se consideran clases.
Sin embargo, los objetos pueden anular esto al tener un atributo __bases__ (que debe ser una tupla de clases
base).
int PyObject_IsInstance(PyObject *inst, PyObject *cls)
Part of the Stable ABI. Retorna 1 si inst es una instancia de la clase cls o una subclase de cls, o 0 si no. En caso
de error, retorna -1 y establece una excepción.
Si cls es una tupla, la verificación se realizará con cada entrada en cls. El resultado será 1 cuando al menos una
de las verificaciones retorne 1, de lo contrario será 0.
Si cls tiene un método __instancecheck__(), se llamará para determinar el estado de la subclase como
se describe en PEP 3119. De lo contrario, inst es una instancia de cls si su clase es una subclase de cls.
Una instancia inst puede anular lo que se considera su clase al tener un atributo __class__.
Un objeto cls puede anular si se considera una clase y cuáles son sus clases base, al tener un atributo
__bases__ (que debe ser una tupla de clases base).
Py_hash_t PyObject_Hash(PyObject *o)
Part of the Stable ABI. Calcula y retorna el valor hash de un objeto o. En caso de fallo, retorna -1. Este es el
equivalente de la expresión de Python hash(o).
Distinto en la versión 3.2: El tipo de retorno ahora es Py_hash_t. Este es un entero con signo del mismo tamaño
que Py_ssize_t.
Py_hash_t PyObject_HashNotImplemented(PyObject *o)
Part of the Stable ABI. Establece un TypeError indicando que type(o) no es hashable y retorna -1. Esta
función recibe un tratamiento especial cuando se almacena en una ranura tp_hash, lo que permite que un
tipo indique explícitamente al intérprete que no es hashable.
int PyObject_IsTrue(PyObject *o)
Part of the Stable ABI. Retorna 1 si el objeto o se considera verdadero y 0 en caso contrario. Esto es equivalente
a la expresión de Python not not o. En caso de error, retorna -1.
int PyObject_Not(PyObject *o)
Part of the Stable ABI. Retorna 0 si el objeto o se considera verdadero, y 1 de lo contrario. Esto es equivalente
a la expresión de Python not o. En caso de error, retorna -1.
PyObject *PyObject_Type(PyObject *o)
Return value: New reference. Part of the Stable ABI. Cuando o no es NULL, retorna un tipo de objeto corres-
pondiente al tipo de objeto del objeto o. En caso de falla, lanza SystemError y retorna NULL. Esto es
equivalente a la expresión de Python type(o). Esta función incrementa el recuento de referencia del valor
de retorno. Realmente no hay razón para usar esta función en lugar de la función Py_TYPE(), que retorna
un puntero de tipo PyTypeObject*, excepto cuando se necesita el recuento de referencias incrementado.
int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
Retorna un valor no-nulo si el objeto o es de tipo type o un subtipo de type, y 0 en cualquier otro caso. Ninguno
de los dos parámetros debe ser NULL.
Py_ssize_t PyObject_Size(PyObject *o)
Py_ssize_t PyObject_Length(PyObject *o)
Part of the Stable ABI. Retorna la longitud del objeto o. Si el objeto o proporciona los protocolos de secuencia
y mapeo, se retorna la longitud de la secuencia. En caso de error, se retorna -1. Este es el equivalente a la
expresión de Python len(o).

88 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

Retorna una longitud estimada para el objeto o. Primero intenta retornar su longitud real, luego una estimación
usando __length_hint__(), y finalmente retorna el valor predeterminado. En caso de error, retorna -1.
Este es el equivalente a la expresión de Python operator.length_hint(o, defaultvalue).
Nuevo en la versión 3.4.
PyObject *PyObject_GetItem(PyObject *o, PyObject *key)
Return value: New reference. Part of the Stable ABI. Retorna el elemento de o correspondiente a la clave key
del objeto o NULL en caso de error. Este es el equivalente de la expresión de Python o[key].
int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
Part of the Stable ABI. Asigna el objeto key al valor v. Lanza una excepción y retorna -1 en caso de error;
retorna 0 en caso de éxito. Este es el equivalente de la declaración de Python o[key] = v. Esta función no
roba una referencia a v.
int PyObject_DelItem(PyObject *o, PyObject *key)
Part of the Stable ABI. Elimina la asignación para el objeto key del objeto o. Retorna -1 en caso de falla. Esto
es equivalente a la declaración de Python del o[key].
PyObject *PyObject_Dir(PyObject *o)
Return value: New reference. Part of the Stable ABI. Esto es equivalente a la expresión de Python dir(o), que
retorna una lista (posiblemente vacía) de cadenas de caracteres apropiadas para el argumento del objeto, o NULL
si hubo un error. Si el argumento es NULL, es como el Python dir(), que retorna los nombres de los locales
actuales; en este caso, si no hay un marco de ejecución activo, se retorna NULL pero PyErr_Occurred()
retornará falso.
PyObject *PyObject_GetIter(PyObject *o)
Return value: New reference. Part of the Stable ABI. Esto es equivalente a la expresión de Python iter(o).
Retorna un nuevo iterador para el argumento del objeto, o el propio objeto si el objeto ya es un iterador. Lanza
TypeError y retorna NULL si el objeto no puede iterarse.
PyObject *PyObject_GetAIter(PyObject *o)
Return value: New reference. Part of the Stable ABI since version 3.10. Esto es equivalente a la expresión de
Python aiter(o). Toma un objeto AsyncIterable y retorna AsyncIterator. Este es típicamente
un nuevo iterador, pero si el argumento es AsyncIterator, se retornará a sí mismo. Lanza TypeError
y retorna NULL si el objeto no puede ser iterado.
Nuevo en la versión 3.10.

7.2 Protocolo de llamada

CPython admite dos protocolos de llamada diferentes: tp_call y vectorcall.

7.2.1 El protocolo tp_call

Las instancias de clases que establecen tp_call son invocables. La firma del slot es:

PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);

Se realiza una llamada usando una tupla para los argumentos posicionales y un dict para los argumentos de palabras
clave, de manera similar a callable(*args, **kwargs) en el código Python. args debe ser no NULL (use
una tupla vacía si no hay argumentos) pero kwargs puede ser NULL si no hay argumentos de palabra clave.
Esta convención no solo es utilizada por tp_call: tp_new y tp_init también pasan argumentos de esta manera.
To call an object, use PyObject_Call() or another call API.

7.2. Protocolo de llamada 89

The Python/C API, Versión 3.11.0

7.2.2 El protocolo vectorcall

Nuevo en la versión 3.9.

El protocolo vectorcall se introdujo en PEP 590 como un protocolo adicional para hacer que las llamadas sean más
eficientes.
Como regla general, CPython preferirá el vectorcall para llamadas internas si el invocable lo admite. Sin embargo,
esta no es una regla estricta. Además, algunas extensiones de terceros usan tp_call directamente (en lugar de usar
PyObject_Call()). Por lo tanto, una clase que admita vectorcall también debe implementar tp_call. Ade-
más, el invocable debe comportarse de la misma manera independientemente del protocolo que se utilice. La forma
recomendada de lograr esto es configurando tp_call en PyVectorcall_Call(). Vale la pena repetirlo:

Advertencia: Una clase que admita vectorcall debe también implementar tp_call con la misma semántica.

Una clase no debería implementar vectorcall si eso fuera más lento que tp_call. Por ejemplo, si el destinatario de la
llamada necesita convertir los argumentos a una tupla args y un dict kwargs de todos modos, entonces no tiene sentido
implementar vectorcall.
Las clases pueden implementar el protocolo vectorcall habilitando el indicador
Py_TPFLAGS_HAVE_VECTORCALL y la configuración tp_vectorcall_offset al desplazamiento
dentro de la estructura del objeto donde aparece un vectorcallfunc. Este es un puntero a una función con la siguiente
firma:
typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject
*kwnames)

• callable es el objeto siendo invocado.

• args es un arreglo en C que consta de los argumentos posicionales seguidos por el valores de los argu-
mentos de la palabra clave. Puede ser NULL si no hay argumentos.
• nargsf es el número de argumentos posicionales más posiblemente el flag
PY_VECTORCALL_ARGUMENTS_OFFSET. Para obtener el número real de argumentos posicionales
de nargsf, use PyVectorcall_NARGS().
• kwnames es una tupla que contiene los nombres de los argumentos de la palabra clave; en otras pala-
bras, las claves del diccionario kwargs. Estos nombres deben ser cadenas (instancias de str o una sub-
clase) y deben ser únicos. Si no hay argumentos de palabras clave, entonces kwnames puede ser NULL.
PY_VECTORCALL_ARGUMENTS_OFFSET
Si este flag se establece en un argumento vectorcall nargsf, el destinatario de la llamada puede cambiar tempo-
ralmente args[-1]. En otras palabras, args apunta al argumento 1 (no 0) en el vector asignado. El destinatario
de la llamada debe restaurar el valor de args[-1] antes de regresar.
Para PyObject_VectorcallMethod(), este flag significa en cambio que args[0] puede cambiarse.
Siempre que puedan hacerlo de forma económica (sin asignación adicional), se anima a las personas que llaman
a utilizar PY_VECTORCALL_ARGUMENTS_OFFSET. Si lo hace, permitirá que las personas que llaman,
como los métodos enlazados, realicen sus llamadas posteriores (que incluyen un argumento self antepuesto) de
manera muy eficiente.
Para llamar a un objeto que implementa vectorcall, use una función call API como con cualquier otro invocable.
PyObject_Vectorcall() normalmente será más eficiente.

Nota: En CPython 3.8, la API de vectorcall y las funciones relacionadas es-

taban disponibles provisionalmente bajo nombres con un guión bajo inicial:
_PyObject_Vectorcall, _Py_TPFLAGS_HAVE_VECTORCALL, _PyObject_VectorcallMethod,
_PyVectorcall_Function, _PyObject_CallMethodNoArgs, _PyObject_CallMethodOneArg.
Además, PyObject_VectorcallDict estaba disponible como _PyObject_FastCallDict. Los nom-
bres antiguos todavía se definen como alias de los nuevos nombres no subrayados.

90 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

Control de recursión

Cuando se usa tp_call, los destinatarios no necesitan preocuparse por recursividad: CPython usa
Py_EnterRecursiveCall() y Py_LeaveRecursiveCall() para llamadas realizadas usando tp_call.
Por eficiencia, este no es el caso de las llamadas realizadas mediante vectorcall: el destinatario de la llamada debe
utilizar Py_EnterRecursiveCall y Py_LeaveRecursiveCall si es necesario.

API de soporte para vectorcall

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

Dado un argumento vectorcall nargsf, retorna el número real de argumentos. Actualmente equivalente a:

(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)

Sin embargo, la función PyVectorcall_NARGS debe usarse para permitir futuras extensiones.
Nuevo en la versión 3.8.
vectorcallfunc PyVectorcall_Function(PyObject *op)
Si op no admite el protocolo vectorcall (ya sea porque el tipo no lo hace o porque la instancia específica no
lo hace), retorna NULL. De lo contrario, retorna el puntero de la función vectorcall almacenado en op. Esta
función nunca lanza una excepción.
Esto es principalmente útil para verificar si op admite vectorcall, lo cual se puede hacer marcando
PyVectorcall_Function(op) != NULL.
Nuevo en la versión 3.8.
PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
Llama a la vectorcallfunc de callable con argumentos posicionales y de palabras clave dados en una
tupla y dict, respectivamente.
Esta es una función especializada, destinada a colocarse en el slot tp_call o usarse en una implementación
de tp_call. No comprueba el flag Py_TPFLAGS_HAVE_VECTORCALL y no vuelve a tp_call.
Nuevo en la versión 3.8.

7.2.3 API para invocar objetos

Hay varias funciones disponibles para llamar a un objeto Python. Cada una convierte sus argumentos a una convención
respaldada por el objeto llamado, ya sea tp_call o vectorcall. Para realizar la menor conversión posible, elija la que
mejor se adapte al formato de datos que tiene disponible.
La siguiente tabla resume las funciones disponibles; consulte la documentación individual para obtener más detalles.

Función invocable args kwargs

PyObject_Call() PyObject * tupla dict/NULL
PyObject_CallNoArgs() PyObject * — —
PyObject_CallOneArg() PyObject * 1 objeto —
PyObject_CallObject() PyObject * tuple/NULL —
PyObject_CallFunction() PyObject * formato —
PyObject_CallMethod() obj + char* formato —
PyObject_CallFunctionObjArgs() PyObject * variadica —
PyObject_CallMethodObjArgs() obj + nombre variadica —
PyObject_CallMethodNoArgs() obj + nombre — —
PyObject_CallMethodOneArg() obj + nombre 1 objeto —
PyObject_Vectorcall() PyObject * vectorcall vectorcall
PyObject_VectorcallDict() PyObject * vectorcall dict/NULL
PyObject_VectorcallMethod() arg + nombre vectorcall vectorcall

7.2. Protocolo de llamada 91

The Python/C API, Versión 3.11.0

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

Return value: New reference. Part of the Stable ABI. Llama a un objeto de Python invocable callable, con
argumentos dados por la tupla args, y argumentos con nombre dados por el diccionario kwargs.
args no debe ser NULL; use una tupla vacía si no se necesitan argumentos. Si no se necesitan argumentos con
nombre, kwargs puede ser NULL.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Este es el equivalente de la expresión de Python: callable(*args, **kwargs).
PyObject *PyObject_CallNoArgs(PyObject *callable)
Part of the Stable ABI since version 3.10. Llama a un objeto de Python invocable callable sin ningún argumento.
Es la forma más eficiente de llamar a un objeto Python invocable sin ningún argumento.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Nuevo en la versión 3.9.
PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)
Llama a un objeto de Python invocable callable con exactamente 1 argumento posicional arg y sin argumentos
de palabra clave.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Nuevo en la versión 3.9.
PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)
Return value: New reference. Part of the Stable ABI. Llama a un objeto de Python invocable callable, con
argumentos dados por la tupla args. Si no se necesitan argumentos, entonces args puede ser NULL.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Este es el equivalente de la expresión de Python: callable(*args).
PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)
Return value: New reference. Part of the Stable ABI. Llama a un objeto de Python invocable callable, con un
número variable de argumentos C. Los argumentos de C se describen usando una cadena de caracteres de
formato de estilo Py_BuildValue(). El formato puede ser NULL, lo que indica que no se proporcionan
argumentos.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Este es el equivalente de la expresión de Python: callable(*args).
Note that if you only pass PyObject* args, PyObject_CallFunctionObjArgs() is a faster alter-
native.
Distinto en la versión 3.4: El tipo de format se cambió desde char *.
PyObject *PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
Return value: New reference. Part of the Stable ABI. Llama al método llamado name del objeto obj con un
número variable de argumentos en C. Los argumentos de C se describen mediante una cadena de formato
Py_BuildValue() que debería producir una tupla.
El formato puede ser NULL, lo que indica que no se proporcionan argumentos.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Este es el equivalente de la expresión de Python: obj.name(arg1, arg2, ...).
Note that if you only pass PyObject* args, PyObject_CallMethodObjArgs() is a faster alternative.
Distinto en la versión 3.4: Los tipos de name y format se cambiaron desde char *.

92 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)

Return value: New reference. Part of the Stable ABI. Call a callable Python object callable, with a variable
number of PyObject* arguments. The arguments are provided as a variable number of parameters followed
by NULL.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Este es el equivalente de la expresión de Python: callable(arg1, arg2, ...).
PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)
Return value: New reference. Part of the Stable ABI. Call a method of the Python object obj, where the name
of the method is given as a Python string object in name. It is called with a variable number of PyObject*
arguments. The arguments are provided as a variable number of parameters followed by NULL.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
PyObject *PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
Llama a un método del objeto de Python obj sin argumentos, donde el nombre del método se da como un objeto
de cadena de caracteres de Python en name.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Nuevo en la versión 3.9.
PyObject *PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
Llame a un método del objeto de Python obj con un único argumento posicional arg, donde el nombre del
método se proporciona como un objeto de cadena de caracteres de Python en name.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Nuevo en la versión 3.9.
PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject
*kwnames)
Llama a un objeto de Python invocable callable. Los argumentos son los mismos que para
vectorcallfunc. Si callable admite vectorcall, esto llama directamente a la función vectorcall almacenada
en callable.
Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Nuevo en la versión 3.9.
PyObject *PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject
*kwdict)
Llamada invocable con argumentos posicionales pasados exactamente como en el protocolo vectorcall, pero con
argumentos de palabras clave pasados como un diccionario kwdict. El arreglo args contiene solo los argumentos
posicionales.
Independientemente del protocolo que se utilice internamente, es necesario realizar una conversión de argu-
mentos. Por lo tanto, esta función solo debe usarse si la persona que llama ya tiene un diccionario listo para
usar para los argumentos de palabras clave, pero no una tupla para los argumentos posicionales.
Nuevo en la versión 3.9.
PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject
*kwnames)
Llama a un método usando la convención de llamada vectorcall. El nombre del método se proporciona como
una cadena de Python name. El objeto cuyo método se llama es args[0], y el arreglo args que comienza en
args [1] representa los argumentos de la llamada. Debe haber al menos un argumento posicional. nargsf es el
número de argumentos posicionales que incluyen args [0], más PY_VECTORCALL_ARGUMENTS_OFFSET
si el valor de args[0] puede cambiarse temporalmente. Los argumentos de palabras clave se pueden pasar
como en PyObject_Vectorcall().
Si el objeto tiene la característica Py_TPFLAGS_METHOD_DESCRIPTOR, esto llamará al objeto de método
independiente con el vector args completo como argumentos.

7.2. Protocolo de llamada 93

The Python/C API, Versión 3.11.0

Retorna el resultado de la llamada en caso de éxito o lanza una excepción y retorna NULL en caso de error.
Nuevo en la versión 3.9.

7.2.4 API de soporte de llamadas

int PyCallable_Check(PyObject *o)

Part of the Stable ABI. Determina si el objeto o es invocable. Retorna 1 si el objeto es invocable y 0 en caso
contrario. Esta función siempre finaliza con éxito.

7.3 Protocolo de números

int PyNumber_Check(PyObject *o)

Part of the Stable ABI. Retorna 1 si el objeto o proporciona protocolos numéricos, y falso en caso contrario.
Esta función siempre finaliza con éxito.
Distinto en la versión 3.8: Retorna 1 si o es un índice entero.
PyObject *PyNumber_Add(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de agregar o1 y o2, o NULL en caso
de falla. Este es el equivalente de la expresión de Python o1 + o2.
PyObject *PyNumber_Subtract(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de restar o2 de o1, o NULL en caso
de falla. Este es el equivalente de la expresión de Python o1 - o2.
PyObject *PyNumber_Multiply(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de multiplicar o1 y o2, o NULL en
caso de error. Este es el equivalente de la expresión de Python o1 * o2.
PyObject *PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI since version 3.7. Retorna el resultado de la multiplicación
de matrices en o1 y o2, o NULL en caso de falla. Este es el equivalente de la expresión de Python o1 @ o2.
Nuevo en la versión 3.5.
PyObject *PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Return the floor of o1 divided by o2, or NULL on failure.
This is the equivalent of the Python expression o1 // o2.
PyObject *PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Return a reasonable approximation for the mathematical
value of o1 divided by o2, or NULL on failure. The return value is «approximate» because binary floating point
numbers are approximate; it is not possible to represent all real numbers in base two. This function can return
a floating point value when passed two integers. This is the equivalent of the Python expression o1 / o2.
PyObject *PyNumber_Remainder(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resto de dividir o1 entre o2 o NULL en caso de
error. Este es el equivalente de la expresión de Python o1% o2.
PyObject *PyNumber_Divmod(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Vea la función incorporada divmod(). Retorna NULL
en caso de falla. Este es el equivalente de la expresión de Python divmod (o1, o2).
PyObject *PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
Return value: New reference. Part of the Stable ABI. Consulte la función incorporada pow(). Retorna NULL
en caso de falla. Este es el equivalente de la expresión de Python pow(o1, o2, o3), donde o3 es opcional.
Si se ignora o3, pase Py_None en su lugar (pasar NULL por o3 provocaría un acceso ilegal a la memoria).

94 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

PyObject *PyNumber_Negative(PyObject *o)

Return value: New reference. Part of the Stable ABI. Retorna la negación de o en caso de éxito o NULL en caso
de error. Este es el equivalente de la expresión de Python -o.
PyObject *PyNumber_Positive(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna o en caso de éxito o NULL en caso de error. Este
es el equivalente de la expresión de Python +o.
PyObject *PyNumber_Absolute(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna el valor absoluto de o o NULL en caso de error.
Este es el equivalente de la expresión de Python abs(o).
PyObject *PyNumber_Invert(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna la negación bit a bit de o en caso de éxito o NULL
en caso de error. Este es el equivalente de la expresión de Python ~o.
PyObject *PyNumber_Lshift(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado del desplazamiento a la izquierda o1
por o2 en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python o1 << o2.
PyObject *PyNumber_Rshift(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado del desplazamiento a la derecha o1
por o2 en caso de éxito o NULL en caso de error. Este es el equivalente de la expresión de Python o1 >> o2.
PyObject *PyNumber_And(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el «bit a bit y» (bitwise and) de o1 y o2 en caso
de éxito y NULL en caso de error. Este es el equivalente de la expresión de Python o1 & o2.
PyObject *PyNumber_Xor(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el «bit a bit o exclusivo» (bitwise exclusive or) de
o1 por o2 en caso de éxito, o NULL en caso de error. Este es el equivalente de la expresión de Python o1 ^
o2.
PyObject *PyNumber_Or(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el «bit a bit o» (bitwise or) de o1 y o2 en caso de
éxito, o NULL en caso de error. Este es el equivalente de la expresión de Python o1 | o2.
PyObject *PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de agregar o1 y o2, o NULL en caso de
falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración
de Python o1 += o2.
PyObject *PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de restar o2 de o1, o NULL en caso de
falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración
de Python o1 -= o2.
PyObject *PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de multiplicar o1 y o2, o NULL en
caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la
declaración de Python o1 *= o2.
PyObject *PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI since version 3.7. Retorna el resultado de la multiplicación
de matrices en o1 y o2, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo
admite. Este es el equivalente de la declaración de Python o1 @= o2.
Nuevo en la versión 3.5.

7.3. Protocolo de números 95

The Python/C API, Versión 3.11.0

PyObject *PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference. Part of the Stable ABI. Retorna el piso matemático de dividir o1 por o2, o NULL
en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la
declaración de Python o1 //= o2.
PyObject *PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Return a reasonable approximation for the mathematical
value of o1 divided by o2, or NULL on failure. The return value is «approximate» because binary floating point
numbers are approximate; it is not possible to represent all real numbers in base two. This function can return
a floating point value when passed two integers. The operation is done in-place when o1 supports it. This is the
equivalent of the Python statement o1 /= o2.
PyObject *PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resto de dividir o1 entre o2 o NULL en caso de
error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de la declaración
de Python o1%= o2.
PyObject *PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
Return value: New reference. Part of the Stable ABI. Consulte la función incorporada pow(). Retorna NULL
en caso de falla. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es el equivalente de
la declaración de Python o1 **= o2 cuando o3 es Py_None, o una variante en su lugar (in-place) de pow
(o1, o2, o3) de lo contrario. Si se ignora o3, pase Py_None en su lugar (pasar NULL para o3 provocaría
un acceso ilegal a la memoria).
PyObject *PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado del desplazamiento a la izquierda o1
por o2 en caso de éxito o NULL en caso de error. La operación se realiza en su sitio (in-place) cuando o1 lo
admite. Este es el equivalente de la declaración de Python o1 <<= o2.
PyObject *PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el resultado del desplazamiento a la derecha o1
por o2 en caso de éxito o NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo
admite. Este es el equivalente de la declaración de Python o1 >>= o2.
PyObject *PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el «bit a bit y» (bitwise and) de o1 y o2 en caso
de éxito y NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1 lo admite. Este es
el equivalente de la declaración de Python o1 &= o2.
PyObject *PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el «bit a bit o exclusivo» (bitwise exclusive or) de
o1 por o2 en caso de éxito, o NULL en caso de error. La operación se realiza en su lugar (in-place) cuando o1
lo admite. Este es el equivalente de la declaración de Python o1 ^= o2.
PyObject *PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna el «bit a bit o» (bitwise or) de o1 y o2 en caso
de éxito, o NULL en caso de error. La operación se realiza en su lugar in-place cuando o1 lo admite. Este es el
equivalente de la declaración de Python o1 |= o2.
PyObject *PyNumber_Long(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna el o convertido a un objeto entero en caso de
éxito, o NULL en caso de error. Este es el equivalente de la expresión de Python int(o).
PyObject *PyNumber_Float(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna el o convertido a un objeto flotante en caso de
éxito o NULL en caso de error. Este es el equivalente de la expresión de Python float(o).
PyObject *PyNumber_Index(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna el o convertido aun entero de Python (int) en caso
de éxito o NULL con una excepción TypeError lanzada en caso de error.

96 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

Distinto en la versión 3.10: El resultado siempre tiene el tipo exacto int. Anteriormente, el resultado podía
ser una instancia de una subclase de int.
PyObject *PyNumber_ToBase(PyObject *n, int base)
Return value: New reference. Part of the Stable ABI. Retorna el entero n convertido a base base como una cadena
de caracteres. El argumento base debe ser uno de 2, 8, 10 o 16. Para la base 2, 8 o 16, la cadena retornada está
prefijada con un marcador base de '0b'”, '0o' o '0x', respectivamente. Si n no es un entero (int) Python,
primero se convierte con PyNumber_Index().
Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
Part of the Stable ABI. Returns o converted to a Py_ssize_t value if o can be interpreted as an integer. If
the call fails, an exception is raised and -1 is returned.
If o can be converted to a Python int but the attempt to convert to a Py_ssize_t value would rai-
se an OverflowError, then the exc argument is the type of exception that will be raised (usually
IndexError or OverflowError). If exc is NULL, then the exception is cleared and the value is clip-
ped to PY_SSIZE_T_MIN for a negative integer or PY_SSIZE_T_MAX for a positive integer.
int PyIndex_Check(PyObject *o)
Part of the Stable ABI since version 3.8. Returns 1 if o is an index integer (has the nb_index slot of the
tp_as_number structure filled in), and 0 otherwise. This function always succeeds.

7.4 Protocolo de secuencia

int PySequence_Check(PyObject *o)

Part of the Stable ABI. Return 1 if the object provides the sequence protocol, and 0 otherwise. Note that it
returns 1 for Python classes with a __getitem__() method, unless they are dict subclasses, since in
general it is impossible to determine what type of keys the class supports. This function always succeeds.
Py_ssize_t PySequence_Size(PyObject *o)
Py_ssize_t PySequence_Length(PyObject *o)
Part of the Stable ABI. Retorna el número de objetos en secuencia o en caso de éxito y -1 en caso de error.
Esto es equivalente a la expresión de Python len(o).
PyObject *PySequence_Concat(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna la concatenación de o1 y o2 en caso de éxito, y
NULL en caso de error. Este es el equivalente de la expresión de Python o1+o2.
PyObject *PySequence_Repeat(PyObject *o, Py_ssize_t count)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de repetir el objeto de secuencia o
count veces, o NULL en caso de falla. Este es el equivalente de la expresión de Python o*count.
PyObject *PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
Return value: New reference. Part of the Stable ABI. Retorna la concatenación de o1 y o2 en caso de éxito, y
NULL en caso de error. La operación se realiza en su lugar in-place cuando o1 lo admite. Este es el equivalente
de la expresión de Python o1+=o2.
PyObject *PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
Return value: New reference. Part of the Stable ABI. Retorna el resultado de repetir el objeto de secuencia o
count veces, o NULL en caso de falla. La operación se realiza en su lugar (in-place) cuando o lo admite. Este
es el equivalente de la expresión de Python o*=count.
PyObject *PySequence_GetItem(PyObject *o, Py_ssize_t i)
Return value: New reference. Part of the Stable ABI. Retorna el elemento i-ésimo de o o NULL en caso de error.
Este es el equivalente de la expresión de Python o[i].
PyObject *PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return value: New reference. Part of the Stable ABI. Retorna la rebanada del objeto secuencia o entre i1 y i2,
o NULL en caso de error. Este es el equivalente de la expresión de Python o[i1:i2].

7.4. Protocolo de secuencia 97

The Python/C API, Versión 3.11.0

int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)

Part of the Stable ABI. Asigna el objeto v al elemento i-ésimo de o. Lanza una excepción y retorna -1 en caso
de falla; retorna 0 en caso de éxito. Este es el equivalente de la declaración de Python o[i]=v. Esta función
no roba una referencia a v.
If v is NULL, the element is deleted, but this feature is deprecated in favour of using
PySequence_DelItem().
int PySequence_DelItem(PyObject *o, Py_ssize_t i)
Part of the Stable ABI. Elimina el elemento i-ésimo del objeto o. Retorna -1 en caso de falla. Este es el
equivalente de la declaración de Python del o[i].
int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
Part of the Stable ABI. Asigna el objeto secuencia v al segmento en el objeto secuencia o de i1 a i2. Este es el
equivalente de la declaración de Python o[i1:i2]=v.
int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Part of the Stable ABI. Elimina el segmento en el objeto secuencia o de i1 a i2. Retorna -1 en caso de falla.
Este es el equivalente de la declaración de Python del o[i1:i2].
Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
Part of the Stable ABI. Retorna el número de apariciones de value en o, es decir, retorna el número de claves
para las que o[clave]==value. En caso de fallo, retorna -1. Esto es equivalente a la expresión de Python
o.count(value).
int PySequence_Contains(PyObject *o, PyObject *value)
Part of the Stable ABI. Determine si o contiene valor. Si un elemento en o es igual a value, retorna 1; de lo
contrario, retorna 0. En caso de error, retorna -1. Esto es equivalente a la expresión de Python value in
o.
Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
Part of the Stable ABI. Retorna el primer índice i para el que o[i]==value. En caso de error, retorna -1.
Esto es equivalente a la expresión de Python o.index(value).
PyObject *PySequence_List(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna un objeto lista con el mismo contenido que la
secuencia o iterable o, o NULL en caso de error. La lista retornada está garantizada como nueva. Esto es
equivalente a la expresión de Python list(o).
PyObject *PySequence_Tuple(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna un objeto tupla con el mismo contenido que la
secuencia o iterable o, o NULL en caso de error. Si o es una tupla, se retornará una nueva referencia; de lo
contrario, se construirá una tupla con el contenido apropiado. Esto es equivalente a la expresión de Python
tupla(o).
PyObject *PySequence_Fast(PyObject *o, const char *m)
Return value: New reference. Part of the Stable ABI. Retorna la secuencia o iterable o como un objeto utilizable
por la otra familia de funciones PySequence_Fast*. Si el objeto no es una secuencia o no es iterable, lanza
TypeError con m como texto del mensaje. Retorna NULL en caso de falla.
Las funciones PySequence_Fast* se denominan así porque suponen que o es un PyTupleObject o
un PyListObject y acceden a los campos de datos de o directamente.
Como detalle de implementación de CPython, si o ya es una secuencia o lista, se retornará.
Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
Returns the length of o, assuming that o was returned by PySequence_Fast() and that
o is not NULL. The size can also be retrieved by calling PySequence_Size() on o, but
PySequence_Fast_GET_SIZE() is faster because it can assume o is a list or tuple.

98 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

PyObject *PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)

Return value: Borrowed reference. Retorna el elemento i-ésimo de o, suponiendo que o haya sido retornado por
PySequence_Fast(), o no es NULL y que i está dentro de los límites.
PyObject **PySequence_Fast_ITEMS(PyObject *o)
Retorna el arreglo subyacente de punteros PyObject. Asume que o fue retornado por PySequence_Fast()
y o no es NULL.
Tenga en cuenta que si una lista cambia de tamaño, la reasignación puede reubicar el arreglo de elementos. Por
lo tanto, solo use el puntero de arreglo subyacente en contextos donde la secuencia no puede cambiar.
PyObject *PySequence_ITEM(PyObject *o, Py_ssize_t i)
Return value: New reference. Retorna el elemento i-ésimo de o o NULL en caso de error. Es la forma más
rápida de PySequence_GetItem() pero sin verificar que PySequence_Check() en o es verdadero
y sin ajuste para índices negativos.

7.5 Protocolo de mapeo

Consulte también PyObject_GetItem(), PyObject_SetItem() y PyObject_DelItem().

int PyMapping_Check(PyObject *o)
Part of the Stable ABI. Return 1 if the object provides the mapping protocol or supports slicing, and 0 ot-
herwise. Note that it returns 1 for Python classes with a __getitem__() method, since in general it is
impossible to determine what type of keys the class supports. This function always succeeds.
Py_ssize_t PyMapping_Size(PyObject *o)
Py_ssize_t PyMapping_Length(PyObject *o)
Part of the Stable ABI. Retorna el número de claves en el objeto o en caso de éxito, y -1 en caso de error. Esto
es equivalente a la expresión de Python len(o).
PyObject *PyMapping_GetItemString(PyObject *o, const char *key)
Return value: New reference. Part of the Stable ABI. Retorna el elemento de o correspondiente a la cadena de
caracteres key o NULL en caso de error. Este es el equivalente de la expresión de Python o[key]. Ver también
PyObject_GetItem().
int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
Part of the Stable ABI. Asigna la cadena de caracteres key al valor v en el objeto o. Retorna -1 en caso de falla.
Este es el equivalente de la declaración de Python o[key] = v. Ver también PyObject_SetItem().
Esta función no roba una referencia a v.
int PyMapping_DelItem(PyObject *o, PyObject *key)
Elimina la asignación para el objeto key del objeto o. Retorna -1 en caso de falla. Esto es equivalente a la
declaración de Python del o[key]. Este es un alias de PyObject_DelItem().
int PyMapping_DelItemString(PyObject *o, const char *key)
Elimina la asignación de la cadena de caracteres key del objeto o. Retorna -1 en caso de falla. Esto es equiva-
lente a la declaración de Python del o[key].
int PyMapping_HasKey(PyObject *o, PyObject *key)
Part of the Stable ABI. Retorna 1 si el objeto de mapeo tiene la clave key y 0 de lo contrario. Esto es equivalente
a la expresión de Python key in o. Esta función siempre finaliza con éxito.
Tenga en cuenta que las excepciones que se producen al llamar al método __getitem__() se suprimirán.
Para obtener informes de errores, utilice PyObject_GetItem() en su lugar.
int PyMapping_HasKeyString(PyObject *o, const char *key)
Part of the Stable ABI. Retorna 1 si el objeto de mapeo tiene la clave key y 0 de lo contrario. Esto es equivalente
a la expresión de Python key in o. Esta función siempre finaliza con éxito.

7.5. Protocolo de mapeo 99

The Python/C API, Versión 3.11.0

Tenga en cuenta que las excepciones que se producen al llamar al método __getitem__() y al crear
un objeto de cadena de caracteres temporal se suprimirán. Para obtener informes de errores, utilice
PyMapping_GetItemString() en su lugar.
PyObject *PyMapping_Keys(PyObject *o)
Return value: New reference. Part of the Stable ABI. En caso de éxito, retorna una lista de las claves en el objeto
o. En caso de fallo, retorna NULL.
Distinto en la versión 3.7: Anteriormente, la función retornaba una lista o una tupla.
PyObject *PyMapping_Values(PyObject *o)
Return value: New reference. Part of the Stable ABI. En caso de éxito, retorna una lista de los valores en el
objeto o. En caso de fallo, retorna NULL.
Distinto en la versión 3.7: Anteriormente, la función retornaba una lista o una tupla.
PyObject *PyMapping_Items(PyObject *o)
Return value: New reference. Part of the Stable ABI. En caso de éxito, retorna una lista de los elementos en
el objeto o, donde cada elemento es una tupla que contiene un par clave-valor (key-value). En caso de fallo,
retorna NULL.
Distinto en la versión 3.7: Anteriormente, la función retornaba una lista o una tupla.

7.6 Protocolo iterador

Hay dos funciones específicas para trabajar con iteradores.

int PyIter_Check(PyObject *o)
Part of the Stable ABI since version 3.8. Return non-zero if the object o can be safely passed to
PyIter_Next(), and 0 otherwise. This function always succeeds.
int PyAIter_Check(PyObject *o)
Part of the Stable ABI since version 3.10. Return non-zero if the object o provides the AsyncIterator
protocol, and 0 otherwise. This function always succeeds.
Nuevo en la versión 3.10.
PyObject *PyIter_Next(PyObject *o)
Return value: New reference. Part of the Stable ABI. Return the next value from the iterator o. The object must
be an iterator according to PyIter_Check() (it is up to the caller to check this). If there are no remaining
values, returns NULL with no exception set. If an error occurs while retrieving the item, returns NULL and
passes along the exception.
Para escribir un bucle que itera sobre un iterador, el código en C debería verse así:

PyObject *iterator = PyObject_GetIter(obj);

PyObject *item;

if (iterator == NULL) {
/* propagate error */
}

while ((item = PyIter_Next(iterator))) {

/* do something with item */
...
/* release reference when done */
Py_DECREF(item);
}

Py_DECREF(iterator);

(continué en la próxima página)

100 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

if (PyErr_Occurred()) {
/* propagate error */
}
else {
/* continue doing useful work */
}

type PySendResult
El valor de enumeración utilizado para representar diferentes resultados de PyIter_Send().
Nuevo en la versión 3.10.
PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)
Part of the Stable ABI since version 3.10. Envía el valor arg al iterador iter. Retorna:
• PYGEN_RETURN si el iterador regresa. El valor de retorno se retorna a través de presult.
• PYGEN_NEXT si el iterador cede. El valor cedido se retorna a través de presult.
• PYGEN_ERROR si el iterador ha lanzado una excepción. presult se establece en NULL.
Nuevo en la versión 3.10.

7.7 Protocolo Búfer

Ciertos objetos disponibles en Python ajustan el acceso a un arreglo de memoria subyacente o buffer. Dichos objetos
incluyen el incorporado bytes y bytearray, y algunos tipos de extensión como array.array. Las bibliotecas
de terceros pueden definir sus propios tipos para fines especiales, como el procesamiento de imágenes o el análisis
numérico.
Si bien cada uno de estos tipos tiene su propia semántica, comparten la característica común de estar respaldados por
un búfer de memoria posiblemente grande. Es deseable, en algunas situaciones, acceder a ese búfer directamente y
sin copia intermedia.
Python proporciona una instalación de este tipo en el nivel C en la forma de protocolo búfer. Este protocolo tiene dos
lados:
• en el lado del productor, un tipo puede exportar una «interfaz de búfer» que permite a los objetos de ese tipo
exponer información sobre su búfer subyacente. Esta interfaz se describe en la sección Estructuras de Objetos
Búfer;
• en el lado del consumidor, hay varios medios disponibles para obtener un puntero a los datos subyacentes sin
procesar de un objeto (por ejemplo, un parámetro de método).
Los objetos simples como bytes y bytearray exponen su búfer subyacente en forma orientada a bytes. Otras
formas son posibles; por ejemplo, los elementos expuestos por un array.array pueden ser valores de varios bytes.
Un consumidor de ejemplo de la interfaz del búfer es el método write() de objetos de archivo: cualquier objeto
que pueda exportar una serie de bytes a través de la interfaz del búfer puede escribirse en un archivo. Mientras que
write() solo necesita acceso de solo lectura a los contenidos internos del objeto que se le pasa, otros métodos
como readinto() necesitan acceso de escritura a los contenidos de su argumento. La interfaz del búfer permite
que los objetos permitan o rechacen selectivamente la exportación de búferes de lectura-escritura y solo lectura.
Hay dos formas para que un consumidor de la interfaz del búfer adquiera un búfer sobre un objeto de destino:
• llamar PyObject_GetBuffer() con los parámetros correctos;
• llamar PyArg_ParseTuple() (o uno de sus hermanos) con uno de los y*, w* o s* códigos de formato.
En ambos casos, se debe llamar a PyBuffer_Release() cuando ya no se necesita el búfer. De lo contrario,
podrían surgir varios problemas, como pérdidas de recursos.

7.7. Protocolo Búfer 101

The Python/C API, Versión 3.11.0

7.7.1 Estructura de búfer

Las estructuras de búfer (o simplemente «búferes») son útiles como una forma de exponer los datos binarios de otro
objeto al programador de Python. También se pueden usar como un mecanismo de corte de copia cero. Usando su
capacidad para hacer referencia a un bloque de memoria, es posible exponer cualquier información al programador
Python con bastante facilidad. La memoria podría ser una matriz grande y constante en una extensión C, podría ser
un bloque de memoria sin procesar para su manipulación antes de pasar a una biblioteca del sistema operativo, o
podría usarse para pasar datos estructurados en su formato nativo en memoria .
Contrariamente a la mayoría de los tipos de datos expuestos por el intérprete de Python, los búferes no son punteros
PyObject sino estructuras C simples. Esto les permite ser creados y copiados de manera muy simple. Cuando se
necesita un contenedor genérico alrededor de un búfer, un objeto memoryview puede ser creado.
Para obtener instrucciones breves sobre cómo escribir un objeto de exportación, consulte Estructuras de objetos búfer.
Para obtener un búfer, consulte PyObject_GetBuffer().
type Py_buffer
Part of the Stable ABI (including all members) since version 3.11.
void *buf
Un puntero al inicio de la estructura lógica descrita por los campos del búfer. Puede ser cualquier ubica-
ción dentro del bloque de memoria física subyacente del exportador. Por ejemplo, con negativo strides
el valor puede apuntar al final del bloque de memoria.
Para arreglos contiguous, el valor apunta al comienzo del bloque de memoria.
PyObject *obj
Una nueva referencia al objeto exportador. La referencia es propiedad del consumidor y automáticamente
disminuye y se establece en NULL por PyBuffer_Release(). El campo es el equivalente del valor
de retorno de cualquier función estándar de C-API.
Como un caso especial, para los búferes temporary que están envueltos por
PyMemoryView_FromBuffer() o PyBuffer_FillInfo() este campo es NULL. En
general, los objetos de exportación NO DEBEN usar este esquema.
Py_ssize_t len
product(shape) * itemize. Para arreglos contiguos, esta es la longitud del bloque de memoria
subyacente. Para arreglos no contiguos, es la longitud que tendría la estructura lógica si se copiara en una
representación contigua.
Accede a ((char *)buf)[0] hasta ((char *)buf)[len-1] solo es válido si el búfer se
ha obtenido mediante una solicitud que garantiza la contigüidad. En la mayoría de los casos, dicha soli-
citud será PyBUF_SIMPLE o PyBUF_WRITABLE.
int readonly
Un indicador de si el búfer es de solo lectura. Este campo está controlado por el indicador
PyBUF_WRITABLE.
Py_ssize_t itemsize
Tamaño del elemento en bytes de un solo elemento. Igual que el valor de struct.calcsize()
invocado en valores no NULL format.
Excepción importante: si un consumidor solicita un búfer sin el indicador PyBUF_FORMAT, format
se establecerá en NULL, pero itemsize todavía tiene el valor para el formato original.
Si shape está presente, la igualdad product(shape) * itemsize == len aún se mantiene y
el consumidor puede usar itemsize para navegar el búfer.
Si shape es NULL como resultado de un PyBUF_SIMPLE o un PyBUF_WRITABLE, el consumidor
debe ignorar itemsize y asume itemsize == 1.
const char *format
Una cadena de caracteres terminada en NUL en sintaxis de estilo del modulo struct que describe el
contenido de un solo elemento. Si esto es NULL, se supone "B" (bytes sin signo).

102 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

Este campo está controlado por el indicador PyBUF_FORMAT.

int ndim
El número de dimensiones que representa la memoria como un arreglo n-dimensional. Si es “ 0“, buf
apunta a un solo elemento que representa un escalar. En este caso, shape, strides y suboffsets
DEBE ser NULL.
La macro PyBUF_MAX_NDIM limita el número máximo de dimensiones a 64. Los exportadores DE-
BEN respetar este límite, los consumidores de búfer multidimensionales DEBEN poder manejar hasta
dimensiones PyBUF_MAX_NDIM.
Py_ssize_t *shape
Un arreglo de Py_ssize_t de longitud ndim que indica la forma de la memoria como un arreglo n-
dimensional. Tenga en cuenta que shape[0] * ... * shape[ndim-1] * itemsize DEBE
ser igual a len.
Los valores de forma están restringidos a shape[n] >= 0. El caso shape[n] == 0 requiere aten-
ción especial. Vea arreglos complejos (complex arrays) para más información.
El arreglo de formas es de sólo lectura para el consumidor.
Py_ssize_t *strides
Un arreglo de Py_ssize_t de longitud ndim que proporciona el número de bytes que se omiten para
llegar a un nuevo elemento en cada dimensión.
Los valores de stride pueden ser cualquier número entero. Para los arreglos regulares, los pasos son ge-
neralmente positivos, pero un consumidor DEBE ser capaz de manejar el caso strides[n] <= 0.
Ver complex arrays para más información.
El arreglo strides es de sólo lectura para el consumidor.
Py_ssize_t *suboffsets
Un arreglo de Py_ssize_t de longitud ndim. Si suboffsets[n] >= 0, los valores almacenados
a lo largo de la enésima dimensión son punteros y el valor del suboffsets dicta cuántos bytes agregar a cada
puntero después de desreferenciarlos. Un valor de suboffsets negativo indica que no debe producirse una
desreferenciación (striding en un bloque de memoria contiguo).
Si todos los suboffsets son negativos (es decir, no se necesita desreferenciar), entonces este campo debe
ser NULL (el valor predeterminado).
Python Imaging Library (PIL) utiliza este tipo de representación de arreglos. Consulte complex arrays
para obtener más información sobre cómo acceder a los elementos de dicho arreglo.
El arreglo de suboffsets es de sólo lectura para el consumidor.
void *internal
Esto es para uso interno del objeto exportador. Por ejemplo, el exportador podría volver a emitirlo como
un número entero y utilizarlo para almacenar indicadores sobre si las matrices de forma, strides y suboffsets
deben liberarse cuando se libera el búfer. El consumidor NO DEBE alterar este valor.

7.7.2 Tipos de solicitud búfer

Los búferes obtienen generalmente enviando una solicitud de búfer a un objeto de exportación a través de
PyObject_GetBuffer(). Dado que la complejidad de la estructura lógica de la memoria puede variar drásti-
camente, el consumidor usa el argumento flags para especificar el tipo de búfer exacto que puede manejar.
Todos los campos Py_buffer están definidos inequívocamente por el tipo de solicitud.

7.7. Protocolo Búfer 103

The Python/C API, Versión 3.11.0

campos independientes de solicitud

Los siguientes campos no están influenciados por flags y siempre deben completarse con los valores correctos: obj,
buf, len, itemsize, ndim.

formato de sólo lectura

PyBUF_WRITABLE
Controla el campo readonly. Si se establece, el exportador DEBE proporcionar un búfer de
escritura o, de lo contrario, informar de un error. De lo contrario, el exportador PUEDE propor-
cionar un búfer de solo lectura o de escritura, pero la elección DEBE ser coherente para todos los
consumidores.
PyBUF_FORMAT
Controla el campo format. Si se establece, este campo DEBE completarse correctamente. De lo
contrario, este campo DEBE ser NULL.
PyBUF_WRITABLE puede ser |”d a cualquiera de las banderas en la siguiente sección. Dado que PyBUF_SIMPLE
se define como 0, PyBUF_WRITABLE puede usarse como un indicador independiente para solicitar un búfer de
escritura simple.
PyBUF_FORMAT puede ser |”d para cualquiera de las banderas excepto PyBUF_SIMPLE. Este último ya implica
el formato B (bytes sin signo).

formas, strides, suboffsets

Las banderas que controlan la estructura lógica de la memoria se enumeran en orden decreciente de complejidad.
Tenga en cuenta que cada bandera contiene todos los bits de las banderas debajo de ella.

Solicitud forma strides suboffsets

sí sí si es necesario
PyBUF_INDIRECT

sí sí NULL
PyBUF_STRIDES

sí NULL NULL
PyBUF_ND

NULL NULL NULL

PyBUF_SIMPLE

solicitudes de contigüidad

La contigüidad C o Fortran se puede solicitar explícitamente, con y sin información de paso. Sin información de paso,
el búfer debe ser C-contiguo.

104 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

Solicitud forma strides suboffsets contig

sí sí NULL C
PyBUF_C_CONTIGUOUS

sí sí NULL F
PyBUF_F_CONTIGUOUS

sí sí NULL CoF
PyBUF_ANY_CONTIGUOUS

PyBUF_ND sí NULL NULL C

solicitudes compuestas

Todas las solicitudes posibles están completamente definidas por alguna combinación de las banderas en la sección
anterior. Por conveniencia, el protocolo de memoria intermedia proporciona combinaciones de uso frecuente como
indicadores únicos.
En la siguiente tabla U significa contigüidad indefinida. El consumidor tendría que llamar a
PyBuffer_IsContiguous() para determinar la contigüidad.

Solicitud forma strides suboffsets contig sólo lectura formato

sí sí si es necesario U 0 sí
PyBUF_FULL

sí sí si es necesario U 1o0 sí
PyBUF_FULL_RO

sí sí NULL U 0 sí
PyBUF_RECORDS

sí sí NULL U 1o0 sí
PyBUF_RECORDS_RO

sí sí NULL U 0 NULL
PyBUF_STRIDED

sí sí NULL U 1o0 NULL

PyBUF_STRIDED_RO

sí NULL NULL C 0 NULL

PyBUF_CONTIG

sí NULL NULL C 1o0 NULL

PyBUF_CONTIG_RO

7.7. Protocolo Búfer 105

The Python/C API, Versión 3.11.0

7.7.3 Arreglos complejos

Estilo NumPy: forma y strides

La estructura lógica de las matrices de estilo NumPy está definida por itemsize, ndim, shape y strides.
Si ndim == 0, la ubicación de memoria señalada por buf se interpreta como un escalar de tamaño itemsize.
En ese caso, tanto shape como strides son NULL.
Si strides es NULL, el arreglo se interpreta como un arreglo C n-dimensional estándar. De lo contrario, el consu-
midor debe acceder a un arreglo n-dimensional de la siguiente manera:
ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);

Como se señaló anteriormente, buf puede apuntar a cualquier ubicación dentro del bloque de memoria real. Un
exportador puede verificar la validez de un búfer con esta función:
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
"""Verify that the parameters represent a valid array within
the bounds of the allocated memory:
char *mem: start of the physical memory block
memlen: length of the physical memory block
offset: (char *)buf - mem
"""
if offset % itemsize:
return False
if offset < 0 or offset+itemsize > memlen:
return False
if any(v % itemsize for v in strides):
return False

if ndim <= 0:
return ndim == 0 and not shape and not strides
if 0 in shape:
return True

imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)

if strides[j] <= 0)
imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
if strides[j] > 0)

return 0 <= offset+imin and offset+imax+itemsize <= memlen

Estilo PIL: forma, strides y suboffsets

Además de los elementos normales, los arreglos de estilo PIL pueden contener punteros que deben seguirse para
llegar al siguiente elemento en una dimensión. Por ejemplo, el arreglo C tridimensional regular char v[2][2][3]
también se puede ver como un arreglo de 2 punteros a 2 arreglos bidimensionales: char (*v[2])[2][3]. En
la representación de suboffsets, esos dos punteros pueden incrustarse al comienzo de buf, apuntando a dos matrices
char x[2][3] que pueden ubicarse en cualquier lugar de la memoria.
Aquí hay una función que retorna un puntero al elemento en un arreglo N-D a la que apunta un índice N-dimensional
cuando hay strides y suboffsets no NULL:
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
(continué en la próxima página)

106 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}

7.7.4 Funciones relacionadas a búfer

int PyObject_CheckBuffer(PyObject *obj)

Part of the Stable ABI since version 3.11. Retorna 1 si obj admite la interfaz de búfer; de lo contrario, 0
cuando se retorna 1, no garantiza que PyObject_GetBuffer() tenga éxito. Esta función siempre finaliza
con éxito.
int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
Part of the Stable ABI since version 3.11. Envía una solicitud al exporter para completar la view según
lo especificado por flags. Si el exportador no puede proporcionar un búfer del tipo exacto, DEBE lanzar
PyExc_BufferError, establecer view->obj en NULL y retornar -1.
Si tiene éxito, completa view, establece view->obj en una nueva referencia a exporter y retorna 0. En el
caso de proveedores de búfer encadenados que redirigen las solicitudes a un solo objeto, view->obj PUEDE
referirse a este objeto en lugar de exporter (Ver Estructuras de objetos de búfer).
Las llamadas exitosas a PyObject_GetBuffer() deben combinarse con las llamadas a
PyBuffer_Release(), similar a malloc() y free(). Por lo tanto, después de que el consu-
midor haya terminado con el búfer, PyBuffer_Release() debe llamarse exactamente una vez.
void PyBuffer_Release(Py_buffer *view)
Part of the Stable ABI since version 3.11. Libera el búfer view y disminuye el conteo de referencias para
view->obj. Esta función DEBE llamarse cuando el búfer ya no se utiliza, de lo contrario, pueden producirse
fugas de referencia.
Es un error llamar a esta función en un búfer que no se obtuvo a través de PyObject_GetBuffer().
Py_ssize_t PyBuffer_SizeFromFormat(const char *format)
Part of the Stable ABI since version 3.11. Retorna el itemsize implícito de format. En caso de error,
lanza una excepción y retorna -1.
Nuevo en la versión 3.9.
int PyBuffer_IsContiguous(const Py_buffer *view, char order)
Part of the Stable ABI since version 3.11. Retorna 1 si la memoria definida por view es de estilo C (order es
'C') o de estilo Fortran (order es 'F') contiguous o uno cualquiera (order es 'A'). Retorna 0 de lo contrario.
Esta función siempre finaliza con éxito.
void *PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)
Part of the Stable ABI since version 3.11. Obtiene el área de memoria señalada por los indices dentro del view
dado. indices deben apuntar a un arreglo de índices view->ndim.
int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)
Part of the Stable ABI since version 3.11. Copia len bytes contiguos de buf a view. fort puede ser 'C' o 'F'
(para pedidos al estilo C o al estilo Fortran). 0 se retorna en caso de éxito, -1 en caso de error.
int PyBuffer_ToContiguous(void *buf, const Py_buffer *src, Py_ssize_t len, char order)
Part of the Stable ABI since version 3.11. Copia len bytes de src a su representación contigua en buf. order
puede ser 'C' o 'F' o ''A' (para pedidos al estilo C o al estilo Fortran o cualquiera) 0 se retorna en caso
de éxito, -1 en caso de error.
Esta función falla si len != src->len.

7.7. Protocolo Búfer 107

The Python/C API, Versión 3.11.0

int PyObject_CopyData(Py_buffer *dest, Py_buffer *src)

Part of the Stable ABI since version 3.11. Copiar datos del búfer src al dest. Puede convertir entre búferes de
estilo C o Fortran.
Se retorna 0 en caso de éxito, -1 en caso de error.
void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize,
char order)
Part of the Stable ABI since version 3.11. Rellena el arreglo strides con bytes de paso de un contiguous (estilo
C si order es 'C' o estilo Fortran si order es 'F ' ) arreglo de la forma dada con el número dado de bytes
por elemento.
int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int
flags)
Part of the Stable ABI since version 3.11. Maneje las solicitudes de búfer para un exportador que quiera exponer
buf de tamaño len con capacidad de escritura establecida de acuerdo con readonly. buf se interpreta como una
secuencia de bytes sin signo.
El argumento flags indica el tipo de solicitud. Esta función siempre llena view según lo especificado por flags,
a menos que buf haya sido designado como solo lectura y PyBUF_WRITABLE esté configurado en flags.
Si tiene éxito, establece view->obj en una nueva referencia a exporter y retorna 0. De lo contrario, aumenta
PyExc_BufferError, establece view->obj en NULL y retorna -1;
Si esta función se usa como parte de a getbufferproc, exporter DEBE establecerse en el objeto exportador y
flags deben pasarse sin modificaciones. De lo contrario, exporter DEBE ser NULL.

7.8 Protocolo de búfer antiguo

Obsoleto desde la versión 3.0.

Estas funciones formaban parte de la API del «antiguo protocolo de búfer» en Python 2. En Python 3, este protocolo
ya no existe, pero las funciones aún están expuestas para facilitar la transferencia del código 2.x. Actúan como una
envoltura de compatibilidad alrededor del nuevo protocolo de búfer, pero no le dan control sobre la vida útil de los
recursos adquiridos cuando se exporta un búfer.
Por lo tanto, se recomienda que llame PyObject_GetBuffer() (o y*``o ``w* format codes con la familia de
funciones PyArg_ParseTuple()) para obtener una vista de búfer sobre un objeto, y PyBuffer_Release()
cuando se puede liberar la vista de búfer.
int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
Part of the Stable ABI. Retorna un puntero a una ubicación de memoria de solo lectura que se puede usar como
entrada basada en caracteres. El argumento obj debe admitir la interfaz de búfer de caracteres de segmento
único. En caso de éxito, retorna 0, establece buffer en la ubicación de memoria y buffer_len en la longitud del
búfer. Retorna -1 y lanza TypeError en caso de error.
int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
Part of the Stable ABI. Retorna un puntero a una ubicación de memoria de solo lectura que contiene datos
arbitrarios. El argumento obj debe admitir la interfaz de búfer legible de segmento único. En caso de éxito,
retorna 0, establece buffer en la ubicación de memoria y buffer_len en la longitud del búfer. Retorna -1 y lanza
un TypeError en caso de error.
int PyObject_CheckReadBuffer(PyObject *o)
Part of the Stable ABI. Retorna 1 si o admite la interfaz de búfer legible de segmento único. De lo contrario,
retorna 0. Esta función siempre finaliza con éxito.
Tenga en cuenta que esta función intenta obtener y liberar un búfer, y las excepciones que se produ-
cen al llamar a las funciones correspondientes se suprimirán. Para obtener informes de errores, utilice
PyObject_GetBuffer() en su lugar.

108 Capítulo 7. Capa de objetos abstractos

 The Python/C API, Versión 3.11.0

int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)

Part of the Stable ABI. Retorna un puntero a una ubicación de memoria de escritura. El argumento obj debe
admitir la interfaz de búfer de caracteres de segmento único. En caso de éxito, retorna 0, establece buffer en
la ubicación de memoria y buffer_len en la longitud del búfer. Retorna -1 y lanza un TypeError en caso de
error.

7.8. Protocolo de búfer antiguo 109

The Python/C API, Versión 3.11.0

110 Capítulo 7. Capa de objetos abstractos

 CAPÍTULO 8

Capa de objetos concretos

Las funciones de este capítulo son específicas de ciertos tipos de objetos de Python. Pasarles un objeto del tipo
incorrecto no es una buena idea; si recibe un objeto de un programa Python y no está seguro de que tenga el tipo
correcto, primero debe realizar una verificación de tipo; por ejemplo, para verificar que un objeto es un diccionario,
utilice PyDict_Check(). El capítulo está estructurado como el «árbol genealógico» de los tipos de objetos Python.

Advertencia: Si bien las funciones descritas en este capítulo verifican cuidadosamente el tipo de objetos que se
pasan, muchos de ellos no verifican si se pasa NULL en lugar de un objeto válido. Permitir que se pase NULL
puede causar violaciones de acceso a la memoria y la terminación inmediata del intérprete.

8.1 Objetos fundamentales

Esta sección describe los objetos de tipo Python y el objeto singleton None.

8.1.1 Objetos Tipos

type PyTypeObject
Part of the Limited API (as an opaque struct). La estructura C de los objetos utilizados para describir los tipos
incorporados.
PyTypeObject PyType_Type
Part of the Stable ABI. Este es el objeto tipo para objetos tipo; es el mismo objeto que type en la capa Python.
int PyType_Check(PyObject *o)
Retorna un valor distinto de cero si el objeto o es un objeto tipo, incluidas las instancias de tipos derivados del
objeto de tipo estándar. Retorna 0 en todos los demás casos. Esta función siempre finaliza con éxito.
int PyType_CheckExact(PyObject *o)
Retorna un valor distinto de cero si el objeto o es un objeto tipo, pero no un subtipo del objeto tipo estándar.
Retorna 0 en todos los demás casos. Esta función siempre finaliza con éxito.
unsigned int PyType_ClearCache()
Part of the Stable ABI. Borra la caché de búsqueda interna. Retorna la etiqueta (tag) de la versión actual.

111
The Python/C API, Versión 3.11.0

unsigned long PyType_GetFlags(PyTypeObject *type)

Part of the Stable ABI. Return the tp_flags member of type. This function is primarily meant for use with
Py_LIMITED_API; the individual flag bits are guaranteed to be stable across Python releases, but access to
tp_flags itself is not part of the limited API.
Nuevo en la versión 3.2.
Distinto en la versión 3.4: El tipo de retorno es ahora unsigned long en vez de long.
void PyType_Modified(PyTypeObject *type)
Part of the Stable ABI. Invalida la memoria caché de búsqueda interna para el tipo y todos sus subtipos. Esta
función debe llamarse después de cualquier modificación manual de los atributos o clases base del tipo.
int PyType_HasFeature(PyTypeObject *o, int feature)
Retorna un valor distinto de cero si el tipo objeto o establece la característica feature. Las características de
tipo se indican mediante flags de un solo bit.
int PyType_IS_GC(PyTypeObject *o)
Retorna verdadero si el objeto tipo incluye soporte para el detector de ciclo; Esto prueba el indicador de tipo
Py_TPFLAGS_HAVE_GC.
int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
Part of the Stable ABI. Retorna verdadero si a es un subtipo de b.
Esta función solo busca subtipos reales, lo que significa que __subclasscheck__() no se llama en b.
Llama PyObject_IsSubclass() para hacer el mismo chequeo que issubclass() haría.
PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
Return value: New reference. Part of the Stable ABI. Controlador genérico para la ranura tp_alloc de un
objeto tipo. Usa el mecanismo de asignación de memoria predeterminado de Python para asignar una nueva
instancia e inicializar todo su contenido a NULL.
PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
Return value: New reference. Part of the Stable ABI. Controlador genérico para la ranura tp_new de un objeto
tipo. Crea una nueva instancia utilizando la ranura del tipo tp_alloc.
int PyType_Ready(PyTypeObject *type)
Part of the Stable ABI. Finalizar un objeto tipo. Se debe llamar a todos los objetos tipo para finalizar su
inicialización. Esta función es responsable de agregar ranuras heredadas de la clase base de un tipo. Retorna 0
en caso de éxito o retorna -1 y establece una excepción en caso de error.

Nota: Si algunas de las clases base implementan el protocolo GC y el tipo proporcionado no incluye el
Py_TPFLAGS_HAVE_GC en sus banderas, entonces el protocolo GC se implementará automáticamente
desde sus padres. Por el contrario, si el tipo que se está creando incluye Py_TPFLAGS_HAVE_GC en sus
banderas, entonces debe implementar el protocolo GC por sí mismo al implementar al menos el identificador
tp_traverse.

PyObject *PyType_GetName(PyTypeObject *type)

Return value: New reference. Part of the Stable ABI since version 3.11. Return the type’s name. Equivalent to
getting the type’s __name__ attribute.
Nuevo en la versión 3.11.
PyObject *PyType_GetQualName(PyTypeObject *type)
Return value: New reference. Part of the Stable ABI since version 3.11. Return the type’s qualified name. Equi-
valent to getting the type’s __qualname__ attribute.
Nuevo en la versión 3.11.

112 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

void *PyType_GetSlot(PyTypeObject *type, int slot)

Part of the Stable ABI since version 3.4. Retorna el puntero de función almacenado en la ranura dada. Si el
resultado es NULL, esto indica que la ranura es NULL o que la función se llamó con parámetros no válidos.
Las personas que llaman suelen convertir el puntero de resultado en el tipo de función apropiado.
Consulte PyType_Slot.slot para conocer los posibles valores del argumento slot.
Nuevo en la versión 3.4.
Distinto en la versión 3.10: PyType_GetSlot() ahora puede aceptar todos los tipos. Anteriormente, estaba
limitado a heap types.
PyObject *PyType_GetModule(PyTypeObject *type)
Part of the Stable ABI since version 3.10. Retorna el objeto módulo asociado con el tipo dado cuando se creó
el tipo usando PyType_FromModuleAndSpec().
Si no hay ningún módulo asociado con el tipo dado, establece TypeError y retorna NULL.
This function is usually used to get the module in which a method is defined. Note that in such a method,
PyType_GetModule(Py_TYPE(self)) may not return the intended result. Py_TYPE(self) may
be a subclass of the intended class, and subclasses are not necessarily defined in the same module as their
superclass. See PyCMethod to get the class that defines the method. See PyType_GetModuleByDef()
for cases when PyCMethod cannot be used.
Nuevo en la versión 3.9.
void *PyType_GetModuleState(PyTypeObject *type)
Part of the Stable ABI since version 3.10. Retorna el estado del objeto de módulo asociado con el tipo dado.
Este es un atajo para llamar PyModule_GetState() en el resultado de PyType_GetModule().
Si no hay ningún módulo asociado con el tipo dado, establece TypeError y retorna NULL.
Si el tipo type tiene un módulo asociado pero su estado es NULL, retorna NULL sin establecer una excepción.
Nuevo en la versión 3.9.
PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
Find the first superclass whose module was created from the given PyModuleDef def, and return that module.
If no module is found, raises a TypeError and returns NULL.
This function is intended to be used together with PyModule_GetState() to get module state from slot
methods (such as tp_init or nb_add) and other places where a method’s defining class cannot be passed
using the PyCMethod calling convention.
Nuevo en la versión 3.11.

Crear tipos asignados en montículo (heap)

Las siguientes funciones y estructuras se utilizan para crear heap types.

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
Return value: New reference. Part of the Stable ABI since version 3.10. Crea y retorna un tipo heap a partir del
spec (Py_TPFLAGS_HEAPTYPE).
El argumento bases se puede utilizar para especificar clases base; puede ser solo una clase o una tupla de
clases. Si bases es NULL, en su lugar se utiliza la ranura Py_tp_bases. Si esa también es NULL, se usa la ranura
Py_tp_base en su lugar. Si también es NULL, el nuevo tipo se deriva de object.
El argumento module se puede utilizar para registrar el módulo en el que se define la nueva clase. Debe ser un
objeto de módulo o NULL. Si no es NULL, el módulo se asocia con el nuevo tipo y luego se puede recuperar con
PyType_GetModule(). El módulo asociado no es heredado por subclases; debe especificarse para cada
clase individualmente.
Esta función llama PyType_Ready() en el tipo nuevo.

8.1. Objetos fundamentales 113

The Python/C API, Versión 3.11.0

Nuevo en la versión 3.9.

Distinto en la versión 3.10: La función ahora acepta una sola clase como argumento bases y NULL como ranura
tp_doc.
PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
Return value: New reference. Part of the Stable ABI since version 3.3. Equivalente a
PyType_FromModuleAndSpec(NULL, spec, bases).
Nuevo en la versión 3.3.
PyObject *PyType_FromSpec(PyType_Spec *spec)
Return value: New reference. Part of the Stable ABI. Equivalente a
PyType_FromSpecWithBases(spec, NULL).
type PyType_Spec
Part of the Stable ABI (including all members). Estructura que define el comportamiento de un tipo.
const char *PyType_Spec.name
Nombre del tipo, utilizado para establecer PyTypeObject.tp_name.
int PyType_Spec.basicsize

int PyType_Spec.itemsize
Tamaño de la instancia en bytes, utilizado para establecer PyTypeObject.tp_basicsize y
PyTypeObject.tp_itemsize.
int PyType_Spec.flags
Banderas (flags) del tipo, que se usan para establecer PyTypeObject.tp_flags.
Si el indicador Py_TPFLAGS_HEAPTYPE no está establecido, PyType_FromSpecWithBases()
lo establece automáticamente.
PyType_Slot *PyType_Spec.slots
Arreglo de estructuras PyType_Slot. Terminado por el valor de ranura especial {0, NULL}.
type PyType_Slot
Part of the Stable ABI (including all members). Estructura que define la funcionalidad opcional de un tipo, que
contiene una ranura ID y un puntero de valor.
int PyType_Slot.slot

Una ranura ID.

Las ranuras IDs se nombran como los nombres de campo de las estructuras PyTypeObject,
PyNumberMethods, PySequenceMethods, PyMappingMethods y
PyAsyncMethods con un prefijo Py_ agregado. Por ejemplo, use:
• Py_tp_dealloc para establecer PyTypeObject.tp_dealloc
• Py_nb_add para establecer PyNumberMethods.nb_add
• Py_sq_length para establecer PySequenceMethods.sq_length
Los siguientes campos no se pueden configurar en absoluto usando PyType_Spec y
PyType_Slot:
• tp_dict
• tp_mro
• tp_cache
• tp_subclasses
• tp_weaklist
• tp_vectorcall

114 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

• tp_weaklistoffset (vea PyMemberDef)

• tp_dictoffset (vea PyMemberDef)
• tp_vectorcall_offset (vea PyMemberDef)
Estableciendo Py_tp_bases o Py_tp_base puede ser problemático en algunas platafor-
mas. Para evitar problemas, use el argumento bases de PyType_FromSpecWithBases()
en su lugar.
Distinto en la versión 3.9: Slots in PyBufferProcs may be set in the unlimited API.
Distinto en la versión 3.11: bf_getbuffer and bf_releasebuffer are now available under the
limited API.
void *PyType_Slot.pfunc
El valor deseado de la ranura. En la mayoría de los casos, este es un puntero a una función.
Las ranuras que no sean Py_tp_doc pueden no ser NULL.

8.1.2 El objeto None

Tenga en cuenta que PyTypeObject para None no está expuesto directamente en la API de Python/C. Co-
mo None es un singleton, es suficiente probar la identidad del objeto (usando == en C). No existe la función
PyNone_Check() por la misma razón.
PyObject *Py_None
El objeto None de Python, denota falta de valor. Este objeto no tiene métodos. Debe tratarse como cualquier
otro objeto con respecto a los recuentos de referencia.
Py_RETURN_NONE
Maneje adecuadamente el retorno Py_None desde una función en C (es decir, incremente el recuento de
referencia de None y devuélvalo).

8.2 Objetos numéricos

8.2.1 Objetos Enteros

Todos los enteros se implementan como objetos enteros «largos» (long) de tamaño arbitrario.
En caso de error, la mayoría de las API PyLong_As* retornan (tipo de retorno) -1 que no se puede
distinguir de un número. Use PyErr_Occurred() para desambiguar.
type PyLongObject
Part of the Limited API (as an opaque struct). Este subtipo de PyObject representa un objeto entero de
Python.
PyTypeObject PyLong_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo entero de Python. Este es el
mismo objeto que int en la capa de Python.
int PyLong_Check(PyObject *p)
Retorna verdadero si su argumento es un PyLongObject o un subtipo de PyLongObject. Esta función
siempre finaliza con éxito.
int PyLong_CheckExact(PyObject *p)
Retorna verdadero si su argumento es un PyLongObject, pero no un subtipo de PyLongObject. Esta
función siempre finaliza con éxito.

8.2. Objetos numéricos 115

The Python/C API, Versión 3.11.0

PyObject *PyLong_FromLong(long v)
Return value: New reference. Part of the Stable ABI. Retorna un objeto PyLongObject nuevo desde v, o
NULL en caso de error.
The current implementation keeps an array of integer objects for all integers between -5 and 256. When you
create an int in that range you actually just get back a reference to the existing object.
PyObject *PyLong_FromUnsignedLong(unsigned long v)
Return value: New reference. Part of the Stable ABI. Return a new PyLongObject object from a C
unsigned long, or NULL on failure.
PyObject *PyLong_FromSsize_t(Py_ssize_t v)
Return value: New reference. Part of the Stable ABI. Retorna un objeto PyLongObject nuevo desde un C
Py_ssize_t, o NULL en caso de error.
PyObject *PyLong_FromSize_t(size_t v)
Return value: New reference. Part of the Stable ABI. Retorna un objeto PyLongObject nuevo desde un C
size_t, o NULL en caso de error.
PyObject *PyLong_FromLongLong(long long v)
Return value: New reference. Part of the Stable ABI. Return a new PyLongObject object from a C long
long, or NULL on failure.
PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
Return value: New reference. Part of the Stable ABI. Return a new PyLongObject object from a C
unsigned long long, or NULL on failure.
PyObject *PyLong_FromDouble(double v)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto PyLongObject de la parte
entera de v, o NULL en caso de error.
PyObject *PyLong_FromString(const char *str, char **pend, int base)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo PyLongObject basado en el valor
de cadena de caracteres en str, que se interpreta de acuerdo con la raíz en base. Si pend no es NULL, * pend
apuntará al primer carácter en str que sigue a la representación del número. Si base es 0, str se interpreta
utilizando la definición integers; en este caso, los ceros a la izquierda en un número decimal distinto de cero
lanzan un ValueError. Si base no es 0, debe estar entre 2 y 36, inclusive. Se ignoran los espacios iniciales
y los guiones bajos individuales después de un especificador base y entre dígitos. Si no hay dígitos, se lanzará
ValueError.
PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)
Return value: New reference. Convierte una secuencia de dígitos Unicode en la cadena de caracteres u en un
valor entero de Python.
Nuevo en la versión 3.3.
PyObject *PyLong_FromVoidPtr(void *p)
Return value: New reference. Part of the Stable ABI. Crea un entero de Python desde el puntero p. El valor del
puntero se puede recuperar del valor resultante usando PyLong_AsVoidPtr().
long PyLong_AsLong(PyObject *obj)
Part of the Stable ABI. Return a C long representation of obj. If obj is not an instance of PyLongObject,
first call its __index__() method (if present) to convert it to a PyLongObject.
Raise OverflowError if the value of obj is out of range for a long.
Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.
Distinto en la versión 3.8: Use __index__() si está disponible.
Distinto en la versión 3.10: Esta función no usará más __int__().

116 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Part of the Stable ABI. Return a C long representation of obj. If obj is not an instance of PyLongObject,
first call its __index__() method (if present) to convert it to a PyLongObject.
Si el valor de obj es mayor que LONG_MAX o menor que LONG_MIN, establece *overflow * en “1“ o “-1“,
respectivamente, y retorna “-1“; de lo contrario, establece **overflow en 0. Si se produce alguna otra excepción,
configura *overflow en 0 y retorna -1 como de costumbre.
Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.
Distinto en la versión 3.8: Use __index__() si está disponible.
Distinto en la versión 3.10: Esta función no usará más __int__().
long long PyLong_AsLongLong(PyObject *obj)
Part of the Stable ABI. Return a C long long representation of obj. If obj is not an instance of
PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.
Raise OverflowError if the value of obj is out of range for a long long.
Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.
Distinto en la versión 3.8: Use __index__() si está disponible.
Distinto en la versión 3.10: Esta función no usará más __int__().
long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
Part of the Stable ABI. Return a C long long representation of obj. If obj is not an instance of
PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.
Si el valor de obj es mayor que LLONG_MAX o menor que LLONG_MIN, establece *overflow en 1 o -1,
respectivamente, y retorna -1; de lo contrario, establece *overflow en 0. Si se produce alguna otra excepción,
configura *overflow en 0 y retorna -1 como de costumbre.
Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.
Nuevo en la versión 3.2.
Distinto en la versión 3.8: Use __index__() si está disponible.
Distinto en la versión 3.10: Esta función no usará más __int__().
Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
Part of the Stable ABI. Retorna una representación de C Py_ssize_t de pylong. pylong debe ser una instancia
de PyLongObject.
Lanza OverflowError si el valor de pylong está fuera de rango para un Py_ssize_t.
Retorna -1 en caso de error. Use PyErr_Occurred() para desambiguar.
unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
Part of the Stable ABI. Return a C unsigned long representation of pylong. pylong must be an instance
of PyLongObject.
Raise OverflowError if the value of pylong is out of range for a unsigned long.
Retorna (unsigned long)-1 en caso de error. Use PyErr_Occurred() para desambiguar.
size_t PyLong_AsSize_t(PyObject *pylong)
Part of the Stable ABI. Retorna una representación de C size_t de pylong. pylong debe ser una instancia de
PyLongObject.
Lanza OverflowError si el valor de pylong está fuera de rango para un size_t.
Retorna (size_t) -1 en caso de error. Use PyErr_Occurred() para desambiguar.

8.2. Objetos numéricos 117

The Python/C API, Versión 3.11.0

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

Part of the Stable ABI. Return a C unsigned long long representation of pylong. pylong must be an
instance of PyLongObject.
Raise OverflowError if the value of pylong is out of range for an unsigned long long.
Retorna (unsigned long long) -1 en caso de error. Use PyErr_Occurred() para desambiguar.
Distinto en la versión 3.1: Ahora un pylong negativo lanza un OverflowError, no TypeError.
unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
Part of the Stable ABI. Return a C unsigned long representation of obj. If obj is not an instance of
PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.
If the value of obj is out of range for an unsigned long, return the reduction of that value modulo
ULONG_MAX + 1.
Retorna (unsigned long)-1 en caso de error. Use PyErr_Occurred() para desambiguar.
Distinto en la versión 3.8: Use __index__() si está disponible.
Distinto en la versión 3.10: Esta función no usará más __int__().
unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
Part of the Stable ABI. Return a C unsigned long long representation of obj. If obj is not an instance
of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.
If the value of obj is out of range for an unsigned long long, return the reduction of that value modulo
ULLONG_MAX + 1.
Retorna (unsigned long long) -1 por error. Use PyErr_Occurred() para desambiguar.
Distinto en la versión 3.8: Use __index__() si está disponible.
Distinto en la versión 3.10: Esta función no usará más __int__().
double PyLong_AsDouble(PyObject *pylong)
Part of the Stable ABI. Return a C double representation of pylong. pylong must be an instance of
PyLongObject.
Raise OverflowError if the value of pylong is out of range for a double.
Retorna -1.0 en caso de error. Use PyErr_Occurred() para desambiguar.
void *PyLong_AsVoidPtr(PyObject *pylong)
Part of the Stable ABI. Convert a Python integer pylong to a C void pointer. If pylong cannot be converted,
an OverflowError will be raised. This is only assured to produce a usable void pointer for values created
with PyLong_FromVoidPtr().
Retorna NULL en caso de error. Use PyErr_Occurred() para desambiguar.

8.2.2 Objetos Booleanos

Los booleanos en Python se implementan como una subclase de enteros. Solo hay dos booleanos Py_False y
Py_True. Como tal, las funciones normales de creación y eliminación no se aplican a los booleanos. Sin embargo,
los siguientes macros están disponibles.
int PyBool_Check(PyObject *o)
Retorna verdadero si o es de tipo PyBool_Type. Esta función siempre finaliza con éxito.
PyObject *Py_False
El objeto False de Python. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con
respecto a los recuentos de referencia.

118 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *Py_True
El objeto True de Python. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con respecto
a los recuentos de referencia.
Py_RETURN_FALSE
Retorna Py_False de una función, incrementando adecuadamente su recuento de referencia.
Py_RETURN_TRUE
Retorna Py_True desde una función, incrementando adecuadamente su recuento de referencia.
PyObject *PyBool_FromLong(long v)
Return value: New reference. Part of the Stable ABI. Retorna una nueva referencia a Py_True o Py_False
dependiendo del valor de verdad de v.

8.2.3 Objetos de punto flotante

type PyFloatObject
Este subtipo de PyObject representa un objeto de punto flotante de Python.
PyTypeObject PyFloat_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo de punto flotante de Python. Este
es el mismo objeto que float en la capa de Python.
int PyFloat_Check(PyObject *p)
Retorna verdadero si su argumento es un PyFloatObject o un subtipo de PyFloatObject. Esta función
siempre finaliza con éxito.
int PyFloat_CheckExact(PyObject *p)
Retorna verdadero si su argumento es un PyFloatObject, pero no un subtipo de PyFloatObject. Esta
función siempre finaliza con éxito.
PyObject *PyFloat_FromString(PyObject *str)
Return value: New reference. Part of the Stable ABI. Crea un objeto PyFloatObject en función del valor
de cadena de caracteres en str o NULL en caso de error.
PyObject *PyFloat_FromDouble(double v)
Return value: New reference. Part of the Stable ABI. Crea un objeto PyFloatObject a partir de v, o NULL
en caso de error.
double PyFloat_AsDouble(PyObject *pyfloat)
Part of the Stable ABI. Return a C double representation of the contents of pyfloat. If pyfloat is not a Python
floating point object but has a __float__() method, this method will first be called to convert pyfloat into a
float. If __float__() is not defined then it falls back to __index__(). This method returns -1.0 upon
failure, so one should call PyErr_Occurred() to check for errors.
Distinto en la versión 3.8: Utilice __index__() si está disponible.
double PyFloat_AS_DOUBLE(PyObject *pyfloat)
Return a C double representation of the contents of pyfloat, but without error checking.
PyObject *PyFloat_GetInfo(void)
Return value: New reference. Part of the Stable ABI. Retorna una instancia de structseq que contiene información
sobre la precisión, los valores mínimos y máximos de un flotante. Es una envoltura delgada alrededor del archivo
de encabezado float.h.
double PyFloat_GetMax()
Part of the Stable ABI. Return the maximum representable finite float DBL_MAX as C double.
double PyFloat_GetMin()
Part of the Stable ABI. Return the minimum normalized positive float DBL_MIN as C double.

8.2. Objetos numéricos 119

The Python/C API, Versión 3.11.0

Pack and Unpack functions

The pack and unpack functions provide an efficient platform-independent way to store floating-point values as byte
strings. The Pack routines produce a bytes string from a C double, and the Unpack routines produce a C double
from such a bytes string. The suffix (2, 4 or 8) specifies the number of bytes in the bytes string.
On platforms that appear to use IEEE 754 formats these functions work by copying bits. On other platforms, the
2-byte format is identical to the IEEE 754 binary16 half-precision format, the 4-byte format (32-bit) is identical to
the IEEE 754 binary32 single precision format, and the 8-byte format to the IEEE 754 binary64 double precision
format, although the packing of INFs and NaNs (if such things exist on the platform) isn’t handled correctly, and
attempting to unpack a bytes string containing an IEEE INF or NaN will raise an exception.
On non-IEEE platforms with more precision, or larger dynamic range, than IEEE 754 supports, not all values can be
packed; on non-IEEE platforms with less precision, or smaller dynamic range, not all values can be unpacked. What
happens in such cases is partly accidental (alas).
Nuevo en la versión 3.11.

8.2.4 Pack functions

The pack routines write 2, 4 or 8 bytes, starting at p. le is an int argument, non-zero if you want the bytes string in
little-endian format (exponent last, at p+1, p+3, or p+6 p+7), zero if you want big-endian format (exponent first,
at p). The PY_BIG_ENDIAN constant can be used to use the native endian: it is equal to 1 on big endian processor,
or 0 on little endian processor.
Return value: 0 if all is OK, -1 if error (and an exception is set, most likely OverflowError).
There are two problems on non-IEEE platforms:
• What this does is undefined if x is a NaN or infinity.
• -0.0 and +0.0 produce the same bytes string.
int PyFloat_Pack2(double x, unsigned char *p, int le)
Pack a C double as the IEEE 754 binary16 half-precision format.
int PyFloat_Pack4(double x, unsigned char *p, int le)
Pack a C double as the IEEE 754 binary32 single precision format.
int PyFloat_Pack8(double x, unsigned char *p, int le)
Pack a C double as the IEEE 754 binary64 double precision format.

8.2.5 Unpack functions

The unpack routines read 2, 4 or 8 bytes, starting at p. le is an int argument, non-zero if the bytes string is in
little-endian format (exponent last, at p+1, p+3 or p+6 and p+7), zero if big-endian (exponent first, at p). The
PY_BIG_ENDIAN constant can be used to use the native endian: it is equal to 1 on big endian processor, or 0 on
little endian processor.
Return value: The unpacked double. On error, this is -1.0 and PyErr_Occurred() is true (and an exception is
set, most likely OverflowError).
Note that on a non-IEEE platform this will refuse to unpack a bytes string that represents a NaN or infinity.
double PyFloat_Unpack2(const unsigned char *p, int le)
Unpack the IEEE 754 binary16 half-precision format as a C double.
double PyFloat_Unpack4(const unsigned char *p, int le)
Unpack the IEEE 754 binary32 single precision format as a C double.
double PyFloat_Unpack8(const unsigned char *p, int le)
Unpack the IEEE 754 binary64 double precision format as a C double.

120 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

8.2.6 Objetos de números complejos

Los objetos de números complejos de Python se implementan como dos tipos distintos cuando se ven desde la API
de C: uno es el objeto de Python expuesto a los programas de Python, y el otro es una estructura en C que representa
el valor de número complejo real. La API proporciona funciones para trabajar con ambos.

Números complejos como estructuras C

Tenga en cuenta que las funciones que aceptan estas estructuras como parámetros y las retornan como resultados lo
hacen por valor en lugar de desreferenciarlas a través de punteros. Esto es consistente en toda la API.
type Py_complex
La estructura C que corresponde a la porción de valor de un objeto de número complejo de Python. La mayoría
de las funciones para tratar con objetos de números complejos utilizan estructuras de este tipo como valores
de entrada o salida, según corresponda. Se define como:

typedef struct {
double real;
double imag;
} Py_complex;

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

Retorna la suma de dos números complejos, utilizando la representación C Py_complex.
Py_complex _Py_c_diff(Py_complex left, Py_complex right)
Retorna la diferencia entre dos números complejos, usando la representación C Py_complex.
Py_complex _Py_c_neg(Py_complex num)
Retorna la negación del número complejo num, utilizando la representación C Py_complex.
Py_complex _Py_c_prod(Py_complex left, Py_complex right)
Retorna el producto de dos números complejos, usando la representación C Py_complex.
Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
Retorna el cociente de dos números complejos, utilizando la representación C Py_complex.
Si divisor es nulo, este método retorna cero y establece errno en EDOM.
Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
Retorna la exponenciación de num por exp, utilizando la representación C Py_complex.
Si num es nulo y exp no es un número real positivo, este método retorna cero y establece errno a EDOM.

Números complejos como objetos de Python

type PyComplexObject
Este subtipo de PyObject representa un objeto de número complejo de Python.
PyTypeObject PyComplex_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo de número complejo de Python.
Es el mismo objeto que complex en la capa de Python.
int PyComplex_Check(PyObject *p)
Retorna verdadero si su argumento es un PyComplexObject o un subtipo de PyComplexObject. Esta
función siempre finaliza con éxito.
int PyComplex_CheckExact(PyObject *p)
Retorna verdadero si su argumento es un PyComplexObject, pero no un subtipo de PyComplexObject.
Esta función siempre finaliza con éxito.

8.2. Objetos numéricos 121

The Python/C API, Versión 3.11.0

PyObject *PyComplex_FromCComplex(Py_complex v)
Return value: New reference. Crea un nuevo objeto de número complejo de Python a partir de un valor C
Py_complex.
PyObject *PyComplex_FromDoubles(double real, double imag)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto PyComplexObject de real e
imag.
double PyComplex_RealAsDouble(PyObject *op)
Part of the Stable ABI. Return the real part of op as a C double.
double PyComplex_ImagAsDouble(PyObject *op)
Part of the Stable ABI. Return the imaginary part of op as a C double.
Py_complex PyComplex_AsCComplex(PyObject *op)
Retorna el valor Py_complex del número complejo op.
Si op no es un objeto de número complejo de Python pero tiene un método __complex__(), pri-
mero se llamará a este método para convertir op en un objeto de número complejo de Python. Si
__complex__() no está definido, vuelve a __float__(). Si __float__() no está definido, entonces
recurre a __index__(). En caso de falla, este método retorna -1.0 como un valor real.
Distinto en la versión 3.8: Use __index__() si está disponible.

8.3 Objetos de secuencia

Las operaciones genéricas en los objetos de secuencia se discutieron en el capítulo anterior; Esta sección trata sobre
los tipos específicos de objetos de secuencia que son intrínsecos al lenguaje Python.

8.3.1 Objetos Bytes

These functions raise TypeError when expecting a bytes parameter and called with a non-bytes parameter.
type PyBytesObject
Este subtipo de PyObject representa un objeto bytes de Python.
PyTypeObject PyBytes_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo bytes de Python; es el mismo
objeto que bytes en la capa de Python.
int PyBytes_Check(PyObject *o)
Retorna verdadero si el objeto o es un objeto bytes o una instancia de un subtipo del tipo bytes. Esta función
siempre finaliza con éxito.
int PyBytes_CheckExact(PyObject *o)
Retorna verdadero si el objeto o es un objeto bytes, pero no una instancia de un subtipo del tipo bytes. Esta
función siempre finaliza con éxito.
PyObject *PyBytes_FromString(const char *v)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto bytes con una copia de la cadena
de caracteres v como valor en caso de éxito y NULL en caso de error. El parámetro v no debe ser NULL; no se
comprobará.
PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto bytes con una copia de la cadena
de caracteres v como valor y longitud len en caso de éxito y NULL en caso de error. Si v es NULL, el contenido
del objeto bytes no se inicializa.

122 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *PyBytes_FromFormat(const char *format, ...)

Return value: New reference. Part of the Stable ABI. Toma una cadena de caracteres format del estilo C
printf() y un número variable de argumentos, calcula el tamaño del objeto bytes Python resultante y
retorna un objeto bytes con los valores formateados. Los argumentos variables deben ser tipos C y deben
corresponder exactamente a los caracteres de formato en la cadena de caracteres format. Se permiten los
siguientes caracteres de formato:

Caracteres de formato Tipo Comentario

%% n/a El carácter literal %.
%c int Un solo byte, representado como un C int.
%d int Equivalente a printf("%d").1
%u unsigned int Equivalente a printf("%u").1
%ld long Equivalente a printf("%ld").1
%lu unsigned long Equivalente a printf("%lu").1
%zd Py_ssize_t Equivalente a printf("%zd").1
%zu size_t Equivalente a printf("%zu").1
%i int Equivalente a printf("%i").1
%x int Equivalente a printf("%x").1
%s const char* Un arreglo de caracteres C terminados en nulo.
%p const void* La representación hexadecimal de un puntero en C.
Principalmente equivalente a printf("%p") excepto
que se garantiza que comience con el literal 0x,
independientemente de lo que produzca el printf de la
plataforma.

Un carácter de formato no reconocido hace que todo el resto de la cadena de caracteres de formato se copie
como está en el objeto de resultado y se descartan los argumentos adicionales.
PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)
Return value: New reference. Part of the Stable ABI. Idéntica a PyBytes_FromFormat() excepto que
toma exactamente dos argumentos.
PyObject *PyBytes_FromObject(PyObject *o)
Return value: New reference. Part of the Stable ABI. Retorna la representación en bytes del objeto o que im-
plementa el protocolo de búfer.
Py_ssize_t PyBytes_Size(PyObject *o)
Part of the Stable ABI. Retorna la longitud de los bytes en el objeto bytes o.
Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
Similar to PyBytes_Size(), but without error checking.
char *PyBytes_AsString(PyObject *o)
Part of the Stable ABI. Retorna un puntero al contenido de o. El puntero se refiere al búfer interno de o, que
consiste en bytes len(o) + 1. El último byte en el búfer siempre es nulo, independientemente de si hay
otros bytes nulos. Los datos no deben modificarse de ninguna manera, a menos que el objeto se haya creado
usando PyBytes_FromStringAndSize(NULL, size). No debe ser desasignado. Si o no es un objeto
de bytes en absoluto, PyBytes_AsString() retorna NULL y lanza un TypeError.
char *PyBytes_AS_STRING(PyObject *string)
Similar to PyBytes_AsString(), but without error checking.
int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
Part of the Stable ABI. Retorna los contenidos terminados en nulo del objeto obj a través de las variables de
salida buffer y length.
Si length es NULL, el objeto bytes no puede contener bytes nulos incrustados; si lo hace, la función retorna -1
y se lanza un ValueError.
1 Para especificadores de enteros (d, u, ld, lu, zd, zu, i, x): el indicador de conversión 0 tiene efecto incluso cuando se proporciona una precisión.

8.3. Objetos de secuencia 123

The Python/C API, Versión 3.11.0

El búfer se refiere a un búfer interno de obj, que incluye un byte nulo adicional al final (sin contar en
length). Los datos no deben modificarse de ninguna manera, a menos que el objeto se haya creado usando
PyBytes_FromStringAndSize(NULL, size). No debe ser desasignado. Si obj no es un objeto by-
tes en absoluto, PyBytes_AsStringAndSize() retorna -1 y lanza TypeError.
Distinto en la versión 3.5: Anteriormente, TypeError se lanzaba cuando se encontraban bytes nulos incrus-
tados en el objeto bytes.
void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
Part of the Stable ABI. Crea un nuevo objeto de bytes en *bytes que contiene el contenido de newpart agregado
a bytes; la persona que llama poseerá la nueva referencia. La referencia al valor anterior de bytes será robada.
Si no se puede crear el nuevo objeto, la referencia anterior a bytes se seguirá descartando y el valor de *bytes
se establecerá en NULL; Se establecerá la excepción apropiada.
void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Part of the Stable ABI. Crea un nuevo objeto de bytes en *bytes que contenga el contenido de newpart agregado
a bytes. Esta versión disminuye el recuento de referencias de newpart.
int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
Una forma de cambiar el tamaño de un objeto bytes aunque sea «inmutable». Solo use esto para construir un
nuevo objeto bytes; no use esto si los bytes ya pueden ser conocidos en otras partes del código. Es un error
llamar a esta función si el recuento en el objeto bytes de entrada no es uno. Pasa la dirección de un objeto de
bytes existente como un lvalue (puede escribirse en él) y el nuevo tamaño deseado. En caso de éxito, *bytes
retiene el objeto de bytes redimensionados y se retorna 0; la dirección en *bytes puede diferir de su valor de
entrada. Si la reasignación falla, el objeto de bytes original en *bytes se desasigna, *bytes se establece en NULL,
MemoryError se establece y se retorna -1 .

8.3.2 Objetos de arreglos de bytes (bytearrays)

type PyByteArrayObject
Este subtipo de PyObject representa un objeto arreglo de bytes de Python.
PyTypeObject PyByteArray_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo arreglo de bytes de Python; es el
mismo objeto que bytearray en la capa de Python.

Macros de verificación de tipos

int PyByteArray_Check(PyObject *o)

Retorna verdadero si el objeto o es un objeto de arreglo de bytes o una instancia de un subtipo del tipo arreglo
de bytes. Esta función siempre finaliza con éxito.
int PyByteArray_CheckExact(PyObject *o)
Retorna verdadero si el objeto o es un objeto de arreglo de bytes, pero no una instancia de un subtipo del tipo
arreglo de bytes. Esta función siempre finaliza con éxito.

Funciones API directas

PyObject *PyByteArray_FromObject(PyObject *o)

Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto de arreglo de bytes de cualquier
objeto, o, que implementa el buffer protocol.
PyObject *PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Return value: New reference. Part of the Stable ABI. Crea un nuevo objeto de arreglo de bytes a partir de string
y su longitud, len. En caso de fallo, se retorna NULL.

124 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *PyByteArray_Concat(PyObject *a, PyObject *b)

Return value: New reference. Part of the Stable ABI. Une los arreglos de bytes (bytearrays) a y b y retorna un
nuevo arreglo de bytes (bytearray) con el resultado.
Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Part of the Stable ABI. Retorna el tamaño de bytearray después de buscar un puntero NULL.
char *PyByteArray_AsString(PyObject *bytearray)
Part of the Stable ABI. Retorna el contenido de bytearray como un arreglo de caracteres después de verificar
un puntero NULL. La arreglo retornado siempre tiene un byte nulo adicional agregado.
int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
Part of the Stable ABI. Cambia el tamaño del búfer interno de bytearray a len.

Macros

Estos macros intercambian seguridad por velocidad y no comprueban punteros.

char *PyByteArray_AS_STRING(PyObject *bytearray)
Similar a PyByteArray_AsString(), pero sin comprobación de errores.
Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
Similar a PyByteArray_Size(), pero sin comprobación de errores.

8.3.3 Objetos y códecs Unicode

Objetos Unicode

Desde la implementación del PEP 393 en Python 3.3, los objetos Unicode utilizan internamente una variedad de
representaciones, para permitir el manejo del rango completo de caracteres Unicode mientras se mantiene la eficiencia
de memoria. Hay casos especiales para cadenas de caracteres donde todos los puntos de código están por debajo de
128, 256 o 65536; de lo contrario, los puntos de código deben estar por debajo de 1114112 (que es el rango completo
de Unicode).
Py_UNICODE* and UTF-8 representations are created on demand and cached in the Unicode object. The
Py_UNICODE* representation is deprecated and inefficient.
Debido a la transición entre las API antiguas y las API nuevas, los objetos Unicode pueden estar internamente en dos
estados dependiendo de cómo se crearon:
• Los objetos Unicode «canónicos» son todos los objetos creados por una API Unicode no obsoleta. Utilizan la
representación más eficiente permitida por la implementación.
• «legacy» Unicode objects have been created through one of the deprecated APIs (typically
PyUnicode_FromUnicode()) and only bear the Py_UNICODE* representation; you will have to
call PyUnicode_READY() on them before calling any other API.

Nota: El objeto Unicode «heredado» se eliminará en Python 3.12 con APIs obsoletas. Todos los objetos Unicode
serán «canónicos» desde entonces. Consulte PEP 623 para obtener más información.

8.3. Objetos de secuencia 125

The Python/C API, Versión 3.11.0

Tipo Unicode

Estos son los tipos básicos de objetos Unicode utilizados para la implementación de Unicode en Python:
type Py_UCS4
type Py_UCS2
type Py_UCS1
Part of the Stable ABI. Estos tipos son definiciones de tipo (typedefs) para los tipos “enteros sin signo” (unsigned
int) lo suficientemente anchos como para contener caracteres de 32 bits, 16 bits y 8 bits, respectivamente.
Cuando se trate con caracteres Unicode individuales, use Py_UCS4.
Nuevo en la versión 3.3.
type Py_UNICODE
This is a typedef of wchar_t, which is a 16-bit type or 32-bit type depending on the platform.
Distinto en la versión 3.3: En versiones anteriores, este era un tipo de 16 bits o de 32 bits, dependiendo de si
seleccionó una versión Unicode «estrecha» o «amplia» de Python en el momento de la compilación.
type PyASCIIObject
type PyCompactUnicodeObject
type PyUnicodeObject
Estos subtipos de PyObject representan un objeto Python Unicode. En casi todos los casos, no deben usarse
directamente, ya que todas las funciones API que se ocupan de objetos Unicode toman y retornan punteros
PyObject.
Nuevo en la versión 3.3.
PyTypeObject PyUnicode_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo Python Unicode. Está expuesto
al código de Python como str.
The following APIs are C macros and static inlined functions for fast checks and access to internal read-only data of
Unicode objects:
int PyUnicode_Check(PyObject *o)
Retorna verdadero si el objeto o es un objeto Unicode o una instancia de un subtipo Unicode.
int PyUnicode_CheckExact(PyObject *o)
Retorna verdadero (True) si el objeto o es un objeto Unicode, pero no una instancia de un subtipo.
int PyUnicode_READY(PyObject *o)
Asegura que el objeto de cadena de caracteres o esté en la representación «canónica». Esto es necesario antes
de usar cualquiera de las macros de acceso que se describen a continuación.
Retorna 0 en caso de éxito y -1 con una excepción establecida en caso de error, que ocurre en particular si
falla la asignación de memoria.
Nuevo en la versión 3.3.
Obsoleto desde la versión 3.10, se eliminará en la versión 3.12: Esta API será removida con
PyUnicode_FromUnicode().
Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
Retorna la longitud de la cadena de caracteres Unicode, en puntos de código. o tiene que ser un objeto Unicode
en la representación «canónica» (no marcada).
Nuevo en la versión 3.3.
Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *o)
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *o)

126 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *o)

Retorna un puntero a la representación canónica emitida a los tipos enteros UCS1, UCS2 o UCS4 para el
acceso directo a los caracteres. No se realizan verificaciones si la representación canónica tiene el tamaño de
carácter correcto; use PyUnicode_KIND() para seleccionar el macro correcto. Asegúrese de que se haya
llamado a PyUnicode_READY() antes de acceder a esto.
Nuevo en la versión 3.3.
PyUnicode_WCHAR_KIND
PyUnicode_1BYTE_KIND
PyUnicode_2BYTE_KIND
PyUnicode_4BYTE_KIND
Retorna los valores de la macro PyUnicode_KIND().
Nuevo en la versión 3.3.
Obsoleto desde la versión 3.10, se eliminará en la versión 3.12: PyUnicode_WCHAR_KIND está deprecada.
int PyUnicode_KIND(PyObject *o)
Retorna una de las constantes de tipo PyUnicode (ver arriba) que indican cuántos bytes por carácter utiliza
este objeto Unicode para almacenar sus datos. o tiene que ser un objeto Unicode en la representación «canónica»
(no marcada).
Nuevo en la versión 3.3.
void *PyUnicode_DATA(PyObject *o)
Retorna un puntero vacío al búfer Unicode sin formato. o tiene que ser un objeto Unicode en la representación
«canónica» (no marcada).
Nuevo en la versión 3.3.
void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)
Write into a canonical representation data (as obtained with PyUnicode_DATA()). This function performs
no sanity checks, and is intended for usage in loops. The caller should cache the kind value and data pointer
as obtained from other calls. index is the index in the string (starts at 0) and value is the new code point value
which should be written to that location.
Nuevo en la versión 3.3.
Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)
Lee un punto de código de una representación canónica data (obtenido con PyUnicode_DATA()). No se
realizan verificaciones ni llamadas preparadas.
Nuevo en la versión 3.3.
Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)
Lee un carácter de un objeto Unicode o, que debe estar en la representación «canónica». Esto es menos eficiente
que PyUnicode_READ() si realiza varias lecturas consecutivas.
Nuevo en la versión 3.3.
Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *o)
Retorna el punto de código máximo adecuado para crear otra cadena de caracteres basada en o, que debe
estar en la representación «canónica». Esto siempre es una aproximación pero más eficiente que iterar sobre la
cadena.
Nuevo en la versión 3.3.
Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
Retorna el tamaño de la representación en desuso Py_UNICODE, en unidades de código (esto incluye pares
sustitutos como 2 unidades). o tiene que ser un objeto Unicode (no marcado).
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API Unicode de estilo antiguo, por
favor migrar para usar PyUnicode_GET_LENGTH().

8.3. Objetos de secuencia 127

The Python/C API, Versión 3.11.0

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

Retorna el tamaño de la representación en desuso Py_UNICODE en bytes. o tiene que ser un objeto Unicode
(no marcado).
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API Unicode de estilo antiguo, por
favor migrar para usar PyUnicode_GET_LENGTH().
Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *o)
const char *PyUnicode_AS_DATA(PyObject *o)
Return a pointer to a Py_UNICODE representation of the object. The returned buffer is always terminated
with an extra null code point. It may also contain embedded null code points, which would cause the string to
be truncated when used in most C functions. The AS_DATA form casts the pointer to const char*. The o
argument has to be a Unicode object (not checked).
Distinto en la versión 3.3: This function is now inefficient – because in many cases the Py_UNICODE re-
presentation does not exist and needs to be created – and can fail (return NULL with an exception set). Try
to port the code to use the new PyUnicode_nBYTE_DATA() macros or use PyUnicode_WRITE() or
PyUnicode_READ().
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la antigua API Unicode, por favor migre
para usar la familia de macros PyUnicode_nBYTE_DATA().
int PyUnicode_IsIdentifier(PyObject *o)
Part of the Stable ABI. Retorna 1 si la cadena de caracteres es un identificador válido de acuerdo con la
definición del lenguaje, sección identifiers. Retorna 0 de lo contrario.
Distinto en la versión 3.9: La función ya no llama a Py_FatalError() si la cadena de caracteres no está
lista.

Propiedades de caracteres Unicode

Unicode proporciona muchas propiedades de caracteres diferentes. Los que se necesitan con mayor frecuencia están
disponibles a través de estas macros que se asignan a las funciones de C según la configuración de Python.
int Py_UNICODE_ISSPACE(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter de espacio en blanco.
int Py_UNICODE_ISLOWER(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter en minúscula.
int Py_UNICODE_ISUPPER(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter en mayúscula.
int Py_UNICODE_ISTITLE(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter en caso de título (titlecase).
int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter de salto de línea.
int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter decimal o no.
int Py_UNICODE_ISDIGIT(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter de dígitos.
int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter numérico.
int Py_UNICODE_ISALPHA(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter alfabético.

128 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

Retorna 1 o 0 dependiendo de si ch es un carácter alfanumérico.
int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)
Retorna 1 o 0 dependiendo de si ch es un carácter imprimible. Los caracteres no imprimibles son aquellos
definidos en la base de datos de caracteres Unicode como «Otro» o «Separador», excepto el espacio ASCII
(0x20) que se considera imprimible. (Tenga en cuenta que los caracteres imprimibles en este contexto son
aquellos a los que no se debe escapar cuando repr() se invoca en una cadena de caracteres. No tiene relación
con el manejo de cadenas de caracteres escritas en sys.stdout o sys.stderr.)
Estas API se pueden usar para conversiones caracteres rápidas y directos:
Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)
Retorna el carácter ch convertido a minúsculas.
Obsoleto desde la versión 3.3: Esta función utiliza conversiones simples.
Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)
Retorna el carácter ch convertido a mayúsculas.
Obsoleto desde la versión 3.3: Esta función utiliza conversiones simples.
Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)
Retorna el carácter ch convertido a formato de título (titlecase).
Obsoleto desde la versión 3.3: Esta función utiliza conversiones simples.
int Py_UNICODE_TODECIMAL(Py_UCS4 ch)
Retorna el carácter ch convertido a un entero positivo decimal. Retorna -1 si esto no es posible. Esta macro
no lanza excepciones.
int Py_UNICODE_TODIGIT(Py_UCS4 ch)
Retorna el carácter ch convertido a un entero de un solo dígito. Retorna -1 si esto no es posible. Esta macro
no lanza excepciones.
double Py_UNICODE_TONUMERIC(Py_UCS4 ch)
Retorna el carácter ch convertido a doble. retorne -1.0 si esto no es posible. Esta macro no lanza excepciones.
Estas API se pueden usar para trabajar con sustitutos:
Py_UNICODE_IS_SURROGATE(ch)
Comprueba si ch es un sustituto (0xD800 <= ch <= 0xDFFF).
Py_UNICODE_IS_HIGH_SURROGATE(ch)
Comprueba si ch es un sustituto alto (0xD800 <= ch <= 0xDFFF).
Py_UNICODE_IS_LOW_SURROGATE(ch)
Comprueba si ch es un sustituto bajo (0xD800 <= ch <= 0xDFFF).
Py_UNICODE_JOIN_SURROGATES(high, low)
Une dos caracteres sustitutos y retorna un solo valor Py_UCS4. high y low son respectivamente los sustitutos
iniciales y finales en un par sustituto.

8.3. Objetos de secuencia 129

The Python/C API, Versión 3.11.0

Creando y accediendo a cadenas de caracteres Unicode

Para crear objetos Unicode y acceder a sus propiedades de secuencia básicas, use estas API:
PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
Return value: New reference. Crea un nuevo objeto Unicode. maxchar debe ser el punto de código máximo que
se colocará en la cadena de caracteres. Como una aproximación, se puede redondear al valor más cercano en
la secuencia 127, 255, 65535, 1114111.
Esta es la forma recomendada de asignar un nuevo objeto Unicode. Los objetos creados con esta función no se
pueden redimensionar.
Nuevo en la versión 3.3.
PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
Return value: New reference. Crea un nuevo objeto Unicode con el tipo kind dado (los valores posibles son
PyUnicode_1BYTE_KIND etc., según lo retornado por PyUnicode_KIND()). El búfer debe apuntar a
un vector (array) de tamaño unidades de 1, 2 o 4 bytes por carácter, según el tipo.
If necessary, the input buffer is copied and transformed into the canonical representation. For example, if the
buffer is a UCS4 string (PyUnicode_4BYTE_KIND) and it consists only of codepoints in the UCS1 range,
it will be transformed into UCS1 (PyUnicode_1BYTE_KIND).
Nuevo en la versión 3.3.
PyObject *PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode desde el búfer de caracteres u.
Los bytes se interpretarán como codificados en UTF-8. El búfer se copia en el nuevo objeto. Si el búfer no es
NULL, el valor de retorno podría ser un objeto compartido, es decir, no se permite la modificación de los datos.
Si u es NULL, esta función se comporta como PyUnicode_FromUnicode() con el búfer establecido en
NULL. Este uso se considera obsoleto (deprecated) en favor de PyUnicode_New().
PyObject *PyUnicode_FromString(const char *u)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode a partir de un búfer u de caracteres
terminado en nulo y codificado en UTF-8.
PyObject *PyUnicode_FromFormat(const char *format, ...)
Return value: New reference. Part of the Stable ABI. Toma una cadena de caracteres format con el estilo
de printf() en C y un número variable de argumentos, calcula el tamaño de la cadena Python Unicode
resultante y retorna una cadena de caracteres con los valores formateados. Los argumentos variables deben ser
tipos de C y deben corresponder exactamente a los caracteres de formato en la cadena de caracteres format
codificada en ASCII. Se permiten los siguientes caracteres de formato:

130 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

Formatear caracteres Tipo Comentario

%% n/a El carácter literal %.
%c int Un solo carácter, representado como un entero (int)
de C.
%d int Equivalente a printf("%d").1
%u unsigned int Equivalente a printf("%u").Página 131, 1
%ld long Equivalente a printf("%ld").Página 131, 1
%li long Equivalente a printf("%li").Página 131, 1
%lu unsigned long Equivalente a printf("%lu").Página 131, 1
%lld long long Equivalente a printf("%lld").Página 131, 1
%lli long long Equivalente a printf("%lli").Página 131, 1
%llu unsigned long long Equivalente a printf("%llu").Página 131, 1
%zd Py_ssize_t Equivalente a printf("%zd").Página 131, 1
%zi Py_ssize_t Equivalente a printf("%zi").Página 131, 1
%zu size_t Equivalente a printf("%zu").Página 131, 1
%i int Equivalente a printf("%i").Página 131, 1
%x int Equivalente a printf("%x").Página 131, 1
%s const char* Un arreglo de caracteres de C terminada en nulo.
%p const void* La representación hexadecimal de un puntero en C.
Principalmente equivalente a printf("%p")
excepto que se garantiza que comience con el literal
0x, independiente de lo que produzca el printf
de la plataforma.
%A PyObject* El resultado de llamar ascii().
%U PyObject* Un objeto Unicode.
%V PyObject*, const char* Un objeto Unicode (que puede ser NULL) y un
arreglo de caracteres de C terminada en nulo como
segundo parámetro (que se utilizará, si el primer
parámetro es NULL).
%S PyObject* El resultado de llamar PyObject_Str().
%R PyObject* El resultado de llamar PyObject_Repr().

Un carácter de formato no reconocido hace que todo el resto de la cadena de formato se copie tal cual a la
cadena de resultado y se descartan los argumentos adicionales.

Nota: La unidad del formateador de ancho es el número de caracteres en lugar de bytes. La unidad
del formateador de precisión es la cantidad de bytes para "%s" y "%V" `` (si el argumento
``PyObject* es NULL), y una cantidad de caracteres para "%A", "%U", "%S", "%R" y "%V" (si el
argumento PyObject* no es NULL).

Distinto en la versión 3.2: Soporte agregado para "%lld" y "%llu".

Distinto en la versión 3.3: Soporte agregado para "%li", "%lli" y "%zi".
Distinto en la versión 3.4: Soporte agregado para formateadores de anchura y precisión para "%s", "%A",
"%U", "%V", "%S", "%R".
PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)
Return value: New reference. Part of the Stable ABI. Idéntico a PyUnicode_FromFormat() excepto que
toma exactamente dos argumentos.
PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. Decodifica un objeto codificado obj en un objeto Unicode.
1 Para especificadores de enteros (d, u, ld, li, lu, lld, lli, llu, zd, zi, zu, i, x): el indicador de conversión 0 tiene efecto incluso cuando se proporciona

una precisión.

8.3. Objetos de secuencia 131

The Python/C API, Versión 3.11.0

bytes, bytearray y otros los objetos similares a bytes se decodifican de acuerdo con el encoding dado y
utilizan el manejo de errores definido por errors. Ambos pueden ser NULL para que la interfaz use los valores
predeterminados (ver Códecs incorporados para más detalles).
Todos los demás objetos, incluidos los objetos Unicode, hacen que se establezca un TypeError.
La API retorna NULL si hubo un error. La entidad que hace la llamadas es la responsable de desreferenciar los
objetos retornados.
Py_ssize_t PyUnicode_GetLength(PyObject *unicode)
Part of the Stable ABI since version 3.7. Retorna la longitud del objeto Unicode, en puntos de código.
Nuevo en la versión 3.3.
Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t
from_start, Py_ssize_t how_many)
Copia caracteres de un objeto Unicode en otro. Esta función realiza la conversión de caracteres cuando es
necesario y recurre a memcpy() si es posible. Retorna -1 y establece una excepción en caso de error; de lo
contrario, retorna el número de caracteres copiados.
Nuevo en la versión 3.3.
Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)
Rellena una cadena con un carácter: escriba fill_char en unicode[inicio:inicio+longitud].
Falla si fill_char es más grande que el carácter máximo de la cadena, o si la cadena tiene más de 1 referencia.
Retorna el número de caracteres escritos o retorna -1 y lanza una excepción en caso de error.
Nuevo en la versión 3.3.
int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
Part of the Stable ABI since version 3.7. Escribe un carácter en una cadena de caracteres. La cadena debe
haberse creado a través de PyUnicode_New(). Dado que se supone que las cadenas de caracteres Unicode
son inmutables, la cadena no debe compartirse o no se ha cifrado todavía.
Esta función comprueba que unicode es un objeto Unicode, que el índice no está fuera de los límites y que el
objeto se puede modificar de forma segura (es decir, si su número de referencia es uno).
Nuevo en la versión 3.3.
Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)
Part of the Stable ABI since version 3.7. Read a character from a string. This function checks that unicode
is a Unicode object and the index is not out of bounds, in contrast to PyUnicode_READ_CHAR(), which
performs no error checking.
Nuevo en la versión 3.3.
PyObject *PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)
Return value: New reference. Part of the Stable ABI since version 3.7. Retorna una subcadena de caracteres de
str, desde el índice de caracteres start (incluido) al índice de caracteres end (excluido). Los índices negativos
no son compatibles.
Nuevo en la versión 3.3.
Py_UCS4 *PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
Part of the Stable ABI since version 3.7. Copia la cadena de caracteres u en un búfer UCS4, incluido un carácter
nulo, si copy_null está configurado. Retorna NULL y establece una excepción en caso de error (en particular, a
SystemError si buflen es menor que la longitud de u). buffer se retorna en caso de éxito.
Nuevo en la versión 3.3.
Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u)
Part of the Stable ABI since version 3.7. Copia la cadena de caracteres u en un nuevo búfer UCS4 que se asigna
usando PyMem_Malloc(). Si esto falla, se retorna NULL con un MemoryError establecido. El búfer
retornado siempre tiene un punto de código nulo adicional agregado.

132 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

Nuevo en la versión 3.3.

APIs de Py_UNICODE deprecadas

Obsoleto desde la versión 3.3, se eliminará en la versión 3.12.

Estas funciones API están en desuso con la implementación de PEP 393. Los módulos de extensión pueden continuar
usándolos, ya que no se eliminarán en Python 3.x, pero deben ser conscientes de que su uso ahora puede causar
problemas de rendimiento y memoria.
PyObject *PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
Return value: New reference. Crea un objeto Unicode desde el búfer Py_UNICODE u del tamaño dado. u puede
ser NULL, lo que hace que el contenido no esté definido. Es responsabilidad del usuario completar los datos
necesarios. El búfer se copia en el nuevo objeto.
Si el búfer no es NULL, el valor de retorno podría ser un objeto compartido. Por lo tanto, la modificación del
objeto Unicode resultante solo se permite cuando u es NULL.
Si el búfer es NULL, se debe llamar a PyUnicode_READY() una vez que se haya llenado el contenido de
la cadena de caracteres antes de usar cualquiera de las macros de acceso, como PyUnicode_KIND().
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Por favor migrar para usar
PyUnicode_FromKindAndData(), PyUnicode_FromWideChar() o PyUnicode_New().
Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)
Return a read-only pointer to the Unicode object’s internal Py_UNICODE buffer, or NULL on error. This will
create the Py_UNICODE* representation of the object if it is not yet available. The buffer is always terminated
with an extra null code point. Note that the resulting Py_UNICODE string may also contain embedded null
code points, which would cause the string to be truncated when used in most C functions.
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte del estilo antiguo de la
API Unicode, por favor migrar para usar PyUnicode_AsUCS4(), PyUnicode_AsWideChar(),
PyUnicode_ReadChar() o APIs nuevas similares.
Py_UNICODE *PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)
Like PyUnicode_AsUnicode(), but also saves the Py_UNICODE() array length (excluding the extra
null terminator) in size. Note that the resulting Py_UNICODE* string may contain embedded null code points,
which would cause the string to be truncated when used in most C functions.
Nuevo en la versión 3.3.
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte del estilo antiguo de la
API Unicode, por favor migrar para usar PyUnicode_AsUCS4(), PyUnicode_AsWideChar(),
PyUnicode_ReadChar() o APIs nuevas similares.
Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
Part of the Stable ABI. Retorna el tamaño de la representación en desuso Py_UNICODE, en unidades de código
(esto incluye pares sustitutos como 2 unidades).
Obsoleto desde la versión 3.3, se eliminará en la versión 3.12: Parte de la API Unicode de estilo antiguo, por
favor migrar para usar PyUnicode_GET_LENGTH().
PyObject *PyUnicode_FromObject(PyObject *obj)
Return value: New reference. Part of the Stable ABI. Copia una instancia de un subtipo Unicode a un nuevo
objeto Unicode verdadero si es necesario. Si obj ya es un verdadero objeto Unicode (no un subtipo), retorna la
referencia con un recuento incrementado.
Los objetos que no sean Unicode o sus subtipos causarán un TypeError.

8.3. Objetos de secuencia 133

The Python/C API, Versión 3.11.0

Codificación regional

La codificación local actual se puede utilizar para decodificar texto del sistema operativo.
PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)
Return value: New reference. Part of the Stable ABI since version 3.7. Decodifica una cadena de caracteres
UTF-8 en Android y VxWorks, o de la codificación de configuración regional actual en otras plataformas. Los
manejadores de errores admitidos son "estricto" y "subrogateescape" (PEP 383). El decodifica-
dor usa el controlador de errores "estricto" si errors es“NULL“. str debe terminar con un carácter nulo
pero no puede contener caracteres nulos incrustados.
Utilice PyUnicode_DecodeFSDefaultAndSize() para decodificar una cadena de
Py_FileSystemDefaultEncoding (la codificación de la configuración regional leída al iniciar
Python).
Esta función ignora el modo Python UTF-8.
Ver también:
La función Py_DecodeLocale().
Nuevo en la versión 3.3.
Distinto en la versión 3.7: La función ahora también usa la codificación de configuración regional actual para el
controlador de errores subrogateescape, excepto en Android. Anteriormente, Py_DecodeLocale()
se usaba para el subrogateescape, y la codificación local actual se usaba para estricto.
PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)
Return value: New reference. Part of the Stable ABI since version 3.7. Similar a
PyUnicode_DecodeLocaleAndSize(), pero calcula la longitud de la cadena de caracteres usando
strlen().
Nuevo en la versión 3.3.
PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)
Return value: New reference. Part of the Stable ABI since version 3.7. Codifica un objeto Unicode UTF-8 en
Android y VxWorks, o en la codificación local actual en otras plataformas. Los manejadores de errores admiti-
dos son "estricto" `` y ``"subrogateescape" (PEP 383). El codificador utiliza el controlador
de errores "estricto" si errors es NULL. Retorna un objeto bytes. unicode no puede contener caracteres
nulos incrustados.
Utilice PyUnicode_EncodeFSDefault() para codificar una cadena de caracteres en
Py_FileSystemDefaultEncoding (la codificación de la configuración regional leída al iniciar
Python).
Esta función ignora el modo Python UTF-8.
Ver también:
La función Py_EncodeLocale().
Nuevo en la versión 3.3.
Distinto en la versión 3.7: La función ahora también usa la codificación de configuración regional actual para el
controlador de errores subrogateescape, excepto en Android. Anteriormente, Py_EncodeLocale()
se usaba para el subrogateescape, y la codificación local actual se usaba para estricto.

134 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

Codificación del sistema de archivos

Para codificar y decodificar nombres de archivo y otras cadenas de caracteres de

entorno, Py_FileSystemDefaultEncoding debe usarse como codificación, y
Py_FileSystemDefaultEncodeErrors debe usarse como controlador de errores (PEP 383 y PEP
529). Para codificar nombres de archivo a bytes durante el análisis de argumentos, se debe usar el convertidor
"O&", pasando PyUnicode_FSConverter() como la función de conversión:
int PyUnicode_FSConverter(PyObject *obj, void *result)
Part of the Stable ABI. ParseTuple converter: encode str objects – obtained directly or through the os.
PathLike interface – to bytes using PyUnicode_EncodeFSDefault(); bytes objects are output
as-is. result must be a PyBytesObject* which must be released when it is no longer used.
Nuevo en la versión 3.1.
Distinto en la versión 3.6: Acepta un objeto similar a una ruta (path-like object).
Para decodificar nombres de archivo a str durante el análisis de argumentos, se debe usar el convertidor "O&",
pasando PyUnicode_FSDecoder() como la función de conversión:
int PyUnicode_FSDecoder(PyObject *obj, void *result)
Part of the Stable ABI. ParseTuple converter: decode bytes objects – obtained either directly or indirectly
through the os.PathLike interface – to str using PyUnicode_DecodeFSDefaultAndSize();
str objects are output as-is. result must be a PyUnicodeObject* which must be released when it is no
longer used.
Nuevo en la versión 3.2.
Distinto en la versión 3.6: Acepta un objeto similar a una ruta (path-like object).
PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
Return value: New reference. Part of the Stable ABI. Decodifica una cadena desde el codificador de sistema de
archivos y gestor de errores.
Si Py_FileSystemDefaultEncoding no está configurado, recurre a la codificación de configuración
regional.
Py_FileSystemDefaultEncoding se inicializa al inicio desde la codificación local y no se puede mo-
dificar más tarde. Si se necesita decodificar una cadena de caracteres de la codificación local actual, utilice
PyUnicode_DecodeLocaleAndSize().
Ver también:
La función Py_DecodeLocale().
Distinto en la versión 3.6: Utilice el controlador de errores Py_FileSystemDefaultEncodeErrors.
PyObject *PyUnicode_DecodeFSDefault(const char *s)
Return value: New reference. Part of the Stable ABI. Decodifica una cadena terminada en nulo desde el codi-
ficador de sistema de archivos y gestor de errores.
Si Py_FileSystemDefaultEncoding no está configurado, recurre a la codificación de configuración
regional.
Utilice PyUnicode_DecodeFSDefaultAndSize() si conoce la longitud de la cadena.
Distinto en la versión 3.6: Utilice el controlador de errores Py_FileSystemDefaultEncodeErrors.
PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Uni-
code para Py_FileSystemDefaultEncoding con el manejador de errores
Py_FileSystemDefaultEncodeErrors, y retorna bytes. Tenga en cuenta que el objeto re-
sultante bytes puede contener bytes nulos.
Si Py_FileSystemDefaultEncoding no está configurado, recurre a la codificación de configuración
regional.

8.3. Objetos de secuencia 135

The Python/C API, Versión 3.11.0

Py_FileSystemDefaultEncoding se inicializa al inicio desde la codificación local y no se

puede modificar más tarde. Si necesita codificar una cadena a la codificación local actual, utilice
PyUnicode_EncodeLocale().
Ver también:
La función Py_EncodeLocale().
Nuevo en la versión 3.2.
Distinto en la versión 3.6: Utilice el controlador de errores Py_FileSystemDefaultEncodeErrors.

soporte wchar_t

wchar_t support for platforms which support it:

PyObject *PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
Return value: New reference. Part of the Stable ABI. Create a Unicode object from the wchar_t buffer w of
the given size. Passing -1 as the size indicates that the function must itself compute the length, using wcslen.
Return NULL on failure.
Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
Part of the Stable ABI. Copy the Unicode object contents into the wchar_t buffer w. At most size
wchar_t characters are copied (excluding a possibly trailing null termination character). Return the number
of wchar_t characters copied or -1 in case of an error. Note that the resulting wchar_t* string may or
may not be null-terminated. It is the responsibility of the caller to make sure that the wchar_t* string is
null-terminated in case this is required by the application. Also, note that the wchar_t* string might contain
null characters, which would cause the string to be truncated when used with most C functions.
wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
Part of the Stable ABI since version 3.7. Convert the Unicode object to a wide character string. The output
string always ends with a null character. If size is not NULL, write the number of wide characters (excluding
the trailing null termination character) into *size. Note that the resulting wchar_t string might contain null
characters, which would cause the string to be truncated when used with most C functions. If size is NULL and
the wchar_t* string contains null characters a ValueError is raised.
Retorna un búfer asignado por PyMem_Alloc() (utilice PyMem_Free() para liberarlo) en caso de éxito.
En caso de error, retorna NULL y *size no está definido. Provoca un MemoryError si falla la asignación de
memoria.
Nuevo en la versión 3.2.
Distinto en la versión 3.7: Raises a ValueError if size is NULL and the wchar_t* string contains null
characters.

Códecs incorporados

Python proporciona un conjunto de códecs integrados que están escritos en C para mayor velocidad. Todos estos
códecs se pueden usar directamente a través de las siguientes funciones.
Muchas de las siguientes API toman dos argumentos de encoding y errors, y tienen la misma semántica que las del
constructor de objetos de cadena incorporado str().
Establecer la codificación en NULL hace que se use la codificación predeterminada, que es ASCII. Las llamadas al
sistema de archivos deben usar PyUnicode_FSConverter() para codificar nombres de archivos. Esto utiliza la
variable Py_FileSystemDefaultEncoding internamente. Esta variable debe tratarse como de solo lectura:
en algunos sistemas, será un puntero a una cadena de caracteres estática, en otros, cambiará en tiempo de ejecución
(como cuando la aplicación invoca setlocale).
El manejo de errores se establece mediante errors que también pueden establecerse en NULL, lo que significa usar el
manejo predeterminado definido para el códec. El manejo de errores predeterminado para todos los códecs integrados
es «estricto» (se lanza ValueError).

136 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

The codecs all use a similar interface. Only deviations from the following generic ones are documented for simplicity.

Códecs genéricos

Estas son las APIs de códecs genéricos:

PyObject *PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena codificada s. encoding y errors tienen el mismo significado que los parámetros del mismo nombre en la
función incorporada str(). El códec que se utilizará se busca utilizando el registro de códec Python. Retorna
NULL si el códec provocó una excepción.
PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode y retorna el resultado como un
objeto de bytes de Python. encoding y errors tienen el mismo significado que los parámetros del mismo nombre
en el método Unicode encode(). El códec que se utilizará se busca utilizando el registro de códec Python.
Retorna NULL si el códec provocó una excepción.

Códecs UTF-8

Estas son las APIs del códec UTF-8:

PyObject *PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena codificada UTF-8 s. Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t
*consumed)
Return value: New reference. Part of the Stable ABI. Si consumed es NULL, se comporta como
PyUnicode_DecodeUTF8(). Si consumed no es NULL, las secuencias de bytes UTF-8 incompletas no se
tratarán como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados
se almacenará en consumed.
PyObject *PyUnicode_AsUTF8String(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode usando UTF-8 y retorna el
resultado como un objeto de bytes de Python. El manejo de errores es «estricto». Retorna NULL si el códec
provocó una excepción.
const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
Part of the Stable ABI since version 3.10. Retorna un puntero a la codificación UTF-8 del objeto Unicode y
almacena el tamaño de la representación codificada (en bytes) en size. El argumento size puede ser NULL; en
este caso no se almacenará el tamaño. El búfer retornado siempre tiene un byte nulo adicional agregado (no
incluido en size), independientemente de si hay otros puntos de código nulo.
En caso de error, se retorna NULL con un conjunto de excepciones y no se almacena size.
This caches the UTF-8 representation of the string in the Unicode object, and subsequent calls will return a
pointer to the same buffer. The caller is not responsible for deallocating the buffer. The buffer is deallocated
and pointers to it become invalid when the Unicode object is garbage collected.
Nuevo en la versión 3.3.
Distinto en la versión 3.7: El tipo de retorno ahora es const char * en lugar de char *.
Distinto en la versión 3.10: Esta función es parte de la API limitada.
const char *PyUnicode_AsUTF8(PyObject *unicode)
Como PyUnicode_AsUTF8AndSize(), pero no almacena el tamaño.
Nuevo en la versión 3.3.
Distinto en la versión 3.7: El tipo de retorno ahora es const char * en lugar de char *.

8.3. Objetos de secuencia 137

The Python/C API, Versión 3.11.0

Códecs UTF-32

Estas son las APIs de códecs para UTF-32:

PyObject *PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Return value: New reference. Part of the Stable ABI. Decodifica size bytes de una cadena de búfer codificada
UTF-32 y retorna el objeto Unicode correspondiente. errors (si no es NULL) define el manejo de errores. Su
valor predeterminado es «estricto».
Si byteorder no es NULL, el decodificador comienza a decodificar utilizando el orden de bytes dado:
*byteorder == -1: little endian
*byteorder == 0: native order
*byteorder == 1: big endian

Si *byteorder es cero, y los primeros cuatro bytes de los datos de entrada son una marca de orden de bytes
(BOM), el decodificador cambia a este orden de bytes y la BOM no se copia en la cadena de caracteres Unicode
resultante. Si *byteorder es -1 o 1, cualquier marca de orden de bytes se copia en la salida.
Una vez completado, *byteorder se establece en el orden de bytes actual al final de los datos de entrada.
Si byteorder es NULL, el códec se inicia en modo de orden nativo.
Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int
*byteorder, Py_ssize_t *consumed)
Return value: New reference. Part of the Stable ABI. Si consumed es NULL, se comporta como
PyUnicode_DecodeUTF32(). Si consumed no es NULL, PyUnicode_DecodeUTF32Stateful()
no tratará las secuencias de bytes UTF-32 incompletas finales (como un número de bytes no divisible por cua-
tro) como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados se
almacenará en consumed.
PyObject *PyUnicode_AsUTF32String(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Retorna una cadena de bytes de Python usando la codi-
ficación UTF-32 en orden de bytes nativo. La cadena siempre comienza con una marca BOM. El manejo de
errores es «estricto». Retorna NULL si el códec provocó una excepción.

Códecs UTF-16

Estas son las APIs de códecs para UTF-16:

PyObject *PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Return value: New reference. Part of the Stable ABI. Decodifica size bytes de una cadena de caracteres de búfer
codificada UTF-16 y retorna el objeto Unicode correspondiente. errors (si no es NULL) define el manejo de
errores. Su valor predeterminado es «estricto».
Si byteorder no es NULL, el decodificador comienza a decodificar utilizando el orden de bytes dado:
*byteorder == -1: little endian
*byteorder == 0: native order
*byteorder == 1: big endian

Si *byteorder es cero, y los primeros dos bytes de los datos de entrada son una marca de orden de bytes
(BOM), el decodificador cambia a este orden de bytes y la BOM no se copia en la cadena de caracteres Unicode
resultante. Si *byteorder es -1 o 1, cualquier marca de orden de bytes se copia en la salida (donde dará
como resultado un \ufeff o un carácter \ufffe).
After completion, *byteorder is set to the current byte order at the end of input data.
Si byteorder es NULL, el códec se inicia en modo de orden nativo.
Retorna NULL si el códec provocó una excepción.

138 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int
*byteorder, Py_ssize_t *consumed)
Return value: New reference. Part of the Stable ABI. Si consumed es NULL, se comporta como
PyUnicode_DecodeUTF16(). Si consumed no es NULL, PyUnicode_DecodeUTF16Stateful()
no tratará las secuencias de bytes UTF-16 incompletas finales (como un número impar de bytes o un par sustitu-
to dividido) como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados
se almacenará en consumed.
PyObject *PyUnicode_AsUTF16String(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Retorna una cadena de bytes de Python usando la codi-
ficación UTF-16 en orden de bytes nativo. La cadena siempre comienza con una marca BOM. El manejo de
errores es «estricto». Retorna NULL si el códec provocó una excepción.

Códecs UTF-7

Estas son las APIs del códec UTF-7:

PyObject *PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena de caracteres codificada UTF-7 s. Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t
*consumed)
Return value: New reference. Part of the Stable ABI. Si consumed es NULL, se comporta como
PyUnicode_DecodeUTF7(). Si consumed no es NULL, las secciones UTF-7 base-64 incompletas no
se tratarán como un error. Esos bytes no serán decodificados y la cantidad de bytes que han sido decodificados
se almacenará en consumed.

Códecs Unicode escapado

Estas son las APIs de códecs para Unicode escapado:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena codificada Unicode escapada (Unicode-Escape) s. Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode usando Unicode escapado
(Unicode-Escape) y retorna el resultado como un objeto de bytes. El manejo de errores es «estricto». Retorna
NULL si el códec provocó una excepción.

Códecs para Unicode escapado en bruto

Estas son las API del códec Unicode escapado en bruto (Raw Unicode Escape):
PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena de caracteres codificada Unicode escapada en bruto (Raw-Unicode-Escape) s. Retorna NULL si el códec
provocó una excepción.
PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode usando Unicode escapado en
bruto (Raw-Unicode-Escape) y retorna el resultado como un objeto de bytes. El manejo de errores es «estricto».
Retorna NULL si el códec provocó una excepción.

8.3. Objetos de secuencia 139

The Python/C API, Versión 3.11.0

Códecs Latin-1

Estas son las API del códec Latin-1: Latin-1 corresponde a los primeros 256 ordinales Unicode y solo estos son
aceptados por los códecs durante la codificación.
PyObject *PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena de caracteres codificada en latin-1 s. Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_AsLatin1String(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode usando Latin-1 y retorna
el resultado como un objeto de bytes Python. El manejo de errores es «estricto». Retorna NULL si el códec
provocó una excepción.

Códecs ASCII

Estas son las API del códec ASCII. Solo se aceptan datos ASCII de 7 bits. Todos los demás códigos generan errores.
PyObject *PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena de caracteres codificada ASCII s. Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_AsASCIIString(PyObject *unicode)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode usando ASCII y retorna el
resultado como un objeto de bytes de Python. El manejo de errores es «estricto». Retorna NULL si el códec
provocó una excepción.

Códecs de mapa de caracteres

This codec is special in that it can be used to implement many different codecs (and this is in fact what was done
to obtain most of the standard codecs included in the encodings package). The codec uses mappings to enco-
de and decode characters. The mapping objects provided must support the __getitem__() mapping interface;
dictionaries and sequences work well.
Estos son las API de códec de mapeo:
PyObject *PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char
*errors)
Return value: New reference. Part of the Stable ABI. Crea un objeto Unicode decodificando size bytes de la
cadena de caracteres codificada s usando el objeto mapping dado. Retorna NULL si el códec provocó una
excepción.
Si mapping es NULL, se aplicará la decodificación Latin-1. De lo contrario, mapping debe asignar bytes ordi-
nales (enteros en el rango de 0 a 255) a cadenas de caracteres Unicode, enteros (que luego se interpretan como
ordinales Unicode) o None. Los bytes de datos sin asignar - los que causan un LookupError, así como los
que se asignan a None, 0xFFFE o '\ ufffe', se tratan como asignaciones indefinidas y causan un error.
PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Return value: New reference. Part of the Stable ABI. Codifica un objeto Unicode usando el objeto mapping
dado y retorna el resultado como un objeto de bytes. El manejo de errores es «estricto». Retorna NULL si el
códec provocó una excepción.
El objeto mapping debe asignar enteros ordinales Unicode a objetos de bytes, enteros en el rango de 0 a 255 o
None. Los ordinales de caracteres no asignados (los que causan un LookupError), así como los asignados
a Ninguno, se tratan como «mapeo indefinido» y causan un error.
La siguiente API de códec es especial en que asigna Unicode a Unicode.

140 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)

Return value: New reference. Part of the Stable ABI. Traduce una cadena de caracteres aplicando una tabla de
mapeo y retornando el objeto Unicode resultante. Retorna NULL cuando el códec provocó una excepción.
La tabla de mapeo debe mapear enteros ordinales Unicode a enteros ordinales Unicode o None (causando la
eliminación del carácter).
Las tablas de mapeo solo necesitan proporcionar la interfaz __getitem__(); Los diccionarios y las secuen-
cias funcionan bien. Los ordinales de caracteres no asignados (los que causan un LookupError) se dejan
intactos y se copian tal cual.
errors tiene el significado habitual para los códecs. Puede ser NULL, lo que indica que debe usar el manejo de
errores predeterminado.

Códecs MBCS para Windows

Estas son las API de códec MBCS. Actualmente solo están disponibles en Windows y utilizan los convertidores Win32
MBCS para implementar las conversiones. Tenga en cuenta que MBCS (o DBCS) es una clase de codificaciones, no
solo una. La codificación de destino está definida por la configuración del usuario en la máquina que ejecuta el códec.

PyObject *PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)

Return value: New reference. Part of the Stable ABI on Windows since version 3.7. Crea un objeto Unicode
decodificando size bytes de la cadena de caracteres codificada con MBCS s. Retorna NULL si el códec provocó
una excepción.
PyObject *PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t
*consumed)
Return value: New reference. Part of the Stable ABI on Windows since version 3.7. Si con-
sumed es NULL, se comporta como PyUnicode_DecodeMBCS(). Si consumed no es NULL,
PyUnicode_DecodeMBCSStateful() no decodificará el byte inicial y el número de bytes que se han
decodificado se almacenará en consumed.
PyObject *PyUnicode_AsMBCSString(PyObject *unicode)
Return value: New reference. Part of the Stable ABI on Windows since version 3.7. Codifica un objeto Unicode
usando MBCS y retorna el resultado como un objeto de bytes de Python. El manejo de errores es «estricto».
Retorna NULL si el códec provocó una excepción.
PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
Return value: New reference. Part of the Stable ABI on Windows since version 3.7. Codifica el objeto Unicode
utilizando la página de códigos especificada y retorna un objeto de bytes de Python. Retorna NULL si el códec
provocó una excepción. Use la página de códigos CP_ACP para obtener el codificador MBCS.
Nuevo en la versión 3.3.

Métodos & Ranuras (Slots)

Métodos y funciones de ranura (Slot)

Las siguientes API son capaces de manejar objetos Unicode y cadenas de caracteres en la entrada (nos referimos a
ellos como cadenas de caracteres en las descripciones) y retorna objetos Unicode o enteros según corresponda.
Todos retornan NULL o -1 si ocurre una excepción.
PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)
Return value: New reference. Part of the Stable ABI. Une dos cadenas de caracteres que dan una nueva cadena
de caracteres Unicode.

8.3. Objetos de secuencia 141

The Python/C API, Versión 3.11.0

PyObject *PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)

Return value: New reference. Part of the Stable ABI. Divide una cadena de caracteres dando una lista de cadenas
de caracteres Unicode. Si sep es NULL, la división se realizará en todas las subcadenas de espacios en blanco.
De lo contrario, las divisiones ocurren en el separador dado. A lo sumo se realizarán maxsplit divisiones. Si es
negativo, no se establece ningún límite. Los separadores no están incluidos en la lista resultante.
PyObject *PyUnicode_Splitlines(PyObject *s, int keepend)
Return value: New reference. Part of the Stable ABI. Split a Unicode string at line breaks, returning a list of
Unicode strings. CRLF is considered to be one line break. If keepend is 0, the line break characters are not
included in the resulting strings.
PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)
Return value: New reference. Part of the Stable ABI. Une una secuencia de cadenas de caracteres usando el
separator dado y retorna la cadena de caracteres Unicode resultante.
Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int
direction)
Part of the Stable ABI. Retorna 1 si substr coincide con str[start:end] en el final de cola dado (direction
== -1 significa hacer una coincidencia de prefijo, direction == 1 una coincidencia de sufijo), 0 de lo contrario.
retorne -1 si ocurrió un error.
Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Part of the Stable ABI. Retorna la primera posición de substr en str[start:end] usando la direction dada
(direction == 1 significa hacer una búsqueda hacia adelante, direction == -1 una búsqueda hacia atrás). El
valor de retorno es el índice de la primera coincidencia; un valor de -1 indica que no se encontró ninguna
coincidencia, y -2 indica que se produjo un error y se ha establecido una excepción.
Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)
Part of the Stable ABI since version 3.7. Retorna la primera posición del carácter ch en str[inicio:fin]
usando la direction dada (direction == 1 significa hacer una búsqueda hacia adelante, direction == -1 una
búsqueda hacia atrás). El valor de retorno es el índice de la primera coincidencia; un valor de -1 indica que
no se encontró ninguna coincidencia, y -2 indica que se produjo un error y se ha establecido una excepción.
Nuevo en la versión 3.3.
Distinto en la versión 3.7: start y end ahora están ajustados para comportarse como str[start:end].
Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
Part of the Stable ABI. Retorna el número de ocurrencias no superpuestas de substr en str[start:end].
Retorna -1 si ocurrió un error.
PyObject *PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
Return value: New reference. Part of the Stable ABI. Reemplaza como máximo maxcount ocurrencias de substr
en str con replstr y retorna el objeto Unicode resultante. maxcount == -1 significa reemplazar todas las ocu-
rrencias.
int PyUnicode_Compare(PyObject *left, PyObject *right)
Part of the Stable ABI. Compara dos cadenas de caracteres y retorna -1, 0, 1 para menor que, igual y mayor
que, respectivamente.
Esta función retorna -1 en caso de falla, por lo que se debe llamar a PyErr_Occurred() para verificar si
hay errores.
int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)
Part of the Stable ABI. Compare un objeto Unicode, uni, con string y retorna -1, 0, 1 para menor que, igual y
mayor que, respectivamente. Es mejor pasar solo cadenas de caracteres codificadas en ASCII, pero la función
interpreta la cadena de entrada como ISO-8859-1 si contiene caracteres no ASCII.
Esta función no lanza excepciones.
PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
Return value: New reference. Part of the Stable ABI. Comparación enriquecida de dos cadenas de caracteres
Unicode y retorna uno de los siguientes:

142 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

• NULL en caso de que se produzca una excepción

• Py_True o Py_False para comparaciones exitosas
• Py_NotImplemented en caso que se desconozca la combinación de tipos
Los posibles valores para op son Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT, y Py_LE.
PyObject *PyUnicode_Format(PyObject *format, PyObject *args)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto de cadena de caracteres desde
format y args; esto es análogo al format % args.
int PyUnicode_Contains(PyObject *container, PyObject *element)
Part of the Stable ABI. Comprueba si element está contenido en container y retorna verdadero o falso en
consecuencia.
element tiene que convertir a una cadena de caracteres Unicode. Se retorna -1 si hubo un error.
void PyUnicode_InternInPlace(PyObject **string)
Part of the Stable ABI. Interna el argumento *string en su lugar. El argumento debe ser la dirección de una
variable de puntero que apunta a un objeto Unicode de cadena de caracteres Python. Si hay una cadena de
caracteres interna existente que es igual a *string, establece *string (disminuyendo el recuento de referencias
del objeto de cadena de caracteres anterior e incrementando el recuento de referencias del objeto de cadena de
caracteres interna), de lo contrario deja solo *string y lo interna (incrementando su recuento de referencias).
(Aclaración: a pesar de que se habla mucho sobre el recuento de referencias, piense en esta función como
neutral de recuento de referencia; usted es el propietario del objeto después de la llamada si y solo si lo tenía
antes de la llamada).
PyObject *PyUnicode_InternFromString(const char *v)
Return value: New reference. Part of the Stable ABI. Una combinación de PyUnicode_FromString() y
PyUnicode_InternInPlace(), que retorna un nuevo objeto de cadena de caracteres Unicode que ha
sido creado internamente o una nueva referencia(«propia») a un objeto de cadena de caracteres interno anterior
con el mismo valor.

8.3.4 Objetos Tuplas

type PyTupleObject
Este subtipo de PyObject representa un objeto tupla de Python.
PyTypeObject PyTuple_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo tupla de Python; es el mismo
objeto que tuple en la capa de Python.
int PyTuple_Check(PyObject *p)
Retorna verdadero si p es un objeto tupla o una instancia de un subtipo del tipo tupla. Esta función siempre
finaliza con éxito.
int PyTuple_CheckExact(PyObject *p)
Retorna verdadero si p es un objeto tupla pero no una instancia de un subtipo del tipo tupla. Esta función
siempre finaliza con éxito.
PyObject *PyTuple_New(Py_ssize_t len)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto tupla de tamaño len o NULL en
caso de falla.
PyObject *PyTuple_Pack(Py_ssize_t n, ...)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto tupla de tamaño n, o NULL en
caso de falla. Los valores de tupla se inicializan en los argumentos C posteriores n que apuntan a objetos de
Python. PyTuple_Pack (2, a, b) es equivalente a Py_BuildValue("(OO)", a, b).

8.3. Objetos de secuencia 143

The Python/C API, Versión 3.11.0

Py_ssize_t PyTuple_Size(PyObject *p)

Part of the Stable ABI. Toma un puntero a un objeto de tupla y retorna el tamaño de esa tupla.
Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
Retorna el tamaño de la tupla p, que no debe ser NULL y apunta a una tupla; No se realiza ninguna comprobación
de errores.
PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto en la posición pos en la tupla señala-
da por p. Si pos es negativo o está fuera de los límites, retorna NULL y establece una excepción IndexError.
PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
Return value: Borrowed reference. Como PyTuple_GetItem(), pero no verifica sus argumentos.
PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
Return value: New reference. Part of the Stable ABI. Retorna la porción de la tupla señalada por p entre low y
high, o NULL en caso de falla. Este es el equivalente de la expresión de Python p[bajo:alto]. La indexación
desde el final de la lista no es compatible.
int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
Part of the Stable ABI. Inserta una referencia al objeto o en la posición pos de la tupla señalada por p. Retorna
0 en caso de éxito. Si pos está fuera de límites, retorna -1 y establece una excepción IndexError.

Nota: Esta función «roba» una referencia a o y descarta una referencia a un elemento que ya está en la tupla
en la posición afectada.

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

Al igual que PyTuple_SetItem(), pero no realiza ninguna comprobación de errores, y debe solo usarse
para completar tuplas nuevas.

Nota: This function «steals» a reference to o, and, unlike PyTuple_SetItem(), does not discard a refe-
rence to any item that is being replaced; any reference in the tuple at position pos will be leaked.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

Se puede usar para cambiar el tamaño de una tupla. newsize será el nuevo tamaño de la tupla. Debido a que se
supone que las tuplas son inmutables, esto solo debe usarse si solo hay una referencia al objeto. No use esto si
la tupla ya puede ser conocida por alguna otra parte del código. La tupla siempre crecerá o disminuirá al final.
Piense en esto como destruir la antigua tupla y crear una nueva, solo que de manera más eficiente. Retorna 0
en caso de éxito. El código del cliente nunca debe suponer que el valor resultante de *p será el mismo que
antes de llamar a esta función. Si se reemplaza el objeto referenciado por *p, se destruye el original *p. En
caso de fallo, retorna -1 y establece *p en NULL, y lanza MemoryError o SystemError.

8.3.5 Objetos de secuencia de estructura

Los objetos de secuencia de estructura son el equivalente en C de los objetos namedtuple(), es decir, una se-
cuencia a cuyos elementos también se puede acceder a través de atributos. Para crear una secuencia de estructura,
primero debe crear un tipo de secuencia de estructura específico.
PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)
Return value: New reference. Part of the Stable ABI. Crea un nuevo tipo de secuencia de estructura a partir
de los datos en desc, que se describen a continuación. Las instancias del tipo resultante se pueden crear con
PyStructSequence_New().
void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
Inicializa una secuencia de estructura tipo type desde desc en su lugar.

144 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

Lo mismo que PyStructSequence_InitType, pero retorna 0 en caso de éxito y -1 en caso de error.
Nuevo en la versión 3.4.
type PyStructSequence_Desc
Part of the Stable ABI (including all members). Contiene la meta información de un tipo de secuencia de
estructura para crear.

Campo Tipo C Significado

name const char * nombre del tipo de secuencia de estructura
doc const char * puntero al docstring para el tipo o NULL para omitir
fields PyStructSequence_Field
puntero al arreglo terminado en NULL con nombres de
* campo del nuevo tipo
n_in_sequence
int cantidad de campos visibles para el lado de Python (si se
usa como tupla)

type PyStructSequence_Field
Part of the Stable ABI (including all members). Describes a field of a struct sequence. As a struct sequen-
ce is modeled as a tuple, all fields are typed as PyObject*. The index in the fields array of the
PyStructSequence_Desc determines which field of the struct sequence is described.

Cam- Tipo C Significado

po
name const nombre para el campo o NULL para finalizar la lista de campos con nombre, establece
char * en PyStructSequence_UnnamedField para dejar sin nombre
doc const campo docstring o NULL para omitir
char *

const char *const PyStructSequence_UnnamedField

Part of the Stable ABI since version 3.11. Valor especial para un nombre de campo para dejarlo sin nombre.
Distinto en la versión 3.9: El tipo se cambió de char *.
PyObject *PyStructSequence_New(PyTypeObject *type)
Return value: New reference. Part of the Stable ABI. Crea una instancia de type, que debe haberse creado con
PyStructSequence_NewType().
PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto en la posición pos en la secuencia
de estructura apuntada por p. No se realiza la comprobación de límites.
PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
Return value: Borrowed reference. Macro equivalente de PyStructSequence_GetItem().
void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
Part of the Stable ABI. Establece el campo en el índice pos de la secuencia de estructura p en el valor o. Como
PyTuple_SET_ITEM(), esto solo debe usarse para completar instancias nuevas.

Nota: Esta función «roba» una referencia a o.

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

Similar to PyStructSequence_SetItem(), but implemented as a static inlined function.

Nota: Esta función «roba» una referencia a o.

8.3. Objetos de secuencia 145

The Python/C API, Versión 3.11.0

8.3.6 Objetos lista

type PyListObject
Este subtipo de PyObject representa un objeto lista de Python.
PyTypeObject PyList_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo de lista de Python. Este es el
mismo objeto que list en la capa de Python.
int PyList_Check(PyObject *p)
Retorna verdadero si p es un objeto de lista o una instancia de un subtipo del tipo lista. Esta función siempre
finaliza con éxito.
int PyList_CheckExact(PyObject *p)
Retorna verdadero si p es un objeto lista, pero no una instancia de un subtipo del tipo lista. Esta función siempre
finaliza con éxito.
PyObject *PyList_New(Py_ssize_t len)
Return value: New reference. Part of the Stable ABI. Retorna una nueva lista de longitud len en caso de éxito o
NULL en caso de error.

Nota: Si len es mayor que cero, los elementos del objeto de la lista retornada se establecen en NULL. Por lo
tanto, no puede utilizar funciones API abstractas como PySequence_SetItem() o exponer el objeto al
código Python antes de configurar todos los elementos en un objeto real con PyList_SetItem().

Py_ssize_t PyList_Size(PyObject *list)

Part of the Stable ABI. Retorna la longitud del objeto lista en list; esto es equivalente a len(list) en un
objeto lista.
Py_ssize_t PyList_GET_SIZE(PyObject *list)
Similar to PyList_Size(), but without error checking.
PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto en la posición index en la lista a la
que apunta list. La posición no debe ser negativa; La indexación desde el final de la lista no es compatible. Si
index está fuera de los límites (<0 o >= len(list)), retorna NULL y establece una excepción IndexError.
PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
Return value: Borrowed reference. Similar to PyList_GetItem(), but without error checking.
int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
Part of the Stable ABI. Establece el elemento en el índice index en la lista a item. Retorna 0 en caso de éxito.
Si index está fuera de límites, retorna -1 y establece una excepción IndexError.

Nota: Esta función «roba» una referencia a item y descarta una referencia a un elemento que ya está en la lista
en la posición afectada.

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)

Forma macro de PyList_SetItem() sin comprobación de errores. Esto normalmente solo se usa para
completar nuevas listas donde no hay contenido anterior.

Nota: Este macro «roba» una referencia a item y, a diferencia de PyList_SetItem(), no descarta una
referencia a ningún elemento que se está reemplazando; cualquier referencia en list en la posición i se filtrará.

146 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)

Part of the Stable ABI. Inserta el elemento item en la lista list delante del índice index. Retorna 0 si tiene éxito;
retorna -1 y establece una excepción si no tiene éxito. Análogo a list.insert(index, item).
int PyList_Append(PyObject *list, PyObject *item)
Part of the Stable ABI. Agrega el objeto item al final de la lista list. Retorna 0 si tiene éxito; retorna -1 y
establece una excepción si no tiene éxito. Análogo a list.append(item).
PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
Return value: New reference. Part of the Stable ABI. Retorna una lista de los objetos en list que contie-
ne los objetos between, low y high. Retorna NULL y establece una excepción si no tiene éxito. Análogo a
list[low:high]. La indexación desde el final de la lista no es compatible.
int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
Part of the Stable ABI. Establece el segmento de list entre low y high para el contenido de itemlist. Análogo
a list[low:high] = itemlist. La lista itemlist puede ser NULL, lo que indica la asignación de una
lista vacía (eliminación de segmentos). Retorna 0 en caso de éxito, -1 en caso de error. La indexación desde
el final de la lista no es compatible.
int PyList_Sort(PyObject *list)
Part of the Stable ABI. Ordena los elementos de list en su lugar. Retorna 0 en caso de éxito, -1 en caso de
error. Esto es equivalente a list.sort().
int PyList_Reverse(PyObject *list)
Part of the Stable ABI. Invierte los elementos de la lista list en su lugar. Retorna 0 en caso de éxito, -1 en caso
de error. Este es el equivalente de list.reverse().
PyObject *PyList_AsTuple(PyObject *list)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto tupla que contiene el contenido
de list; equivalente a tuple(list).

8.4 Objetos contenedor

8.4.1 Objetos Diccionarios

type PyDictObject
Este subtipo de PyObject representa un objeto diccionario de Python.
PyTypeObject PyDict_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo diccionario de Python. Este es
el mismo objeto que dict en la capa de Python.
int PyDict_Check(PyObject *p)
Retorna verdadero si p es un objeto dict o una instancia de un subtipo del tipo dict. Esta función siempre
finaliza con éxito.
int PyDict_CheckExact(PyObject *p)
Retorna verdadero si p es un objeto dict, pero no una instancia de un subtipo del tipo dict. Esta función
siempre finaliza con éxito.
PyObject *PyDict_New()
Return value: New reference. Part of the Stable ABI. Retorna un nuevo diccionario vacío, o NULL en caso de
falla.
PyObject *PyDictProxy_New(PyObject *mapping)
Return value: New reference. Part of the Stable ABI. Retorna un objeto a types.MappingProxyType
para una asignación que imponga un comportamiento de solo lectura. Esto normalmente se usa para crear una
vista para evitar la modificación del diccionario para los tipos de clase no dinámicos.

8.4. Objetos contenedor 147

The Python/C API, Versión 3.11.0

void PyDict_Clear(PyObject *p)

Part of the Stable ABI. Vacía un diccionario existente de todos los pares clave-valor (key-value).
int PyDict_Contains(PyObject *p, PyObject *key)
Part of the Stable ABI. Determine si el diccionario p contiene key. Si un elemento en p coincide con la clave
key, retorna 1; de lo contrario, retorna 0. En caso de error, retorna -1. Esto es equivalente a la expresión de
Python key in p.
PyObject *PyDict_Copy(PyObject *p)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo diccionario que contiene los mismos
pares clave-valor (key-value) que p.
int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Part of the Stable ABI. Inserta val en el diccionario p con una clave key. key debe ser hashable; si no lo es, se
lanzará TypeError. Retorna 0 en caso de éxito o -1 en caso de error. Esta función no roba una referencia
a val.
int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
Part of the Stable ABI. Insert val into the dictionary p using key as a key. key should be a const char*.
The key object is created using PyUnicode_FromString(key). Return 0 on success or -1 on failure.
This function does not steal a reference to val.
int PyDict_DelItem(PyObject *p, PyObject *key)
Part of the Stable ABI. Elimina la entrada en el diccionario p con la clave key. key debe ser hashable; si no lo
es, se lanza TypeError. Si key no está en el diccionario, se lanza KeyError. Retorna 0 en caso de éxito o
-1 en caso de error.
int PyDict_DelItemString(PyObject *p, const char *key)
Part of the Stable ABI. Elimina la entrada en el diccionario p que tiene una clave especificada por la cadena de
caracteres key. Si key no está en el diccionario, se lanza KeyError. Retorna 0 en caso de éxito o -1 en caso
de error.
PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto del diccionario p que tiene una
clave key. Retorna NULL si la clave key no está presente, pero sin lanzar una excepción.
Tenga en cuenta que las excepciones que se producen al llamar __hash__() y __eq__() se suprimirán
los métodos. Para obtener informes de errores, utilice PyDict_GetItemWithError () en su lugar.
Distinto en la versión 3.10: Llamar a esta API sin retener el GIL había sido permitido por motivos históricos.Ya
no está permitido.
PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
Return value: Borrowed reference. Part of the Stable ABI. Variante de PyDict_GetItem() que no suprime
las excepciones. Retorna NULL con una excepción establecida si se produjo una excepción. Retorna NULL sin
una excepción establecida si la clave no estaba presente.
PyObject *PyDict_GetItemString(PyObject *p, const char *key)
Return value: Borrowed reference. Part of the Stable ABI. This is the same as PyDict_GetItem(), but key
is specified as a const char*, rather than a PyObject*.
Tenga en cuenta que las excepciones que se producen al llamar a __hash__() y __eq__() y al
crear un objeto de cadena de caracteres temporal se suprimirán. Para obtener informes de errores, utilice
PyDict_GetItemWithError() en su lugar.
PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
Return value: Borrowed reference. Esto es lo mismo al nivel de Python dict.setdefault(). Si está pre-
sente, retorna el valor correspondiente a key del diccionario p. Si la clave no está en el dict, se inserta con el
valor defaultobj y se retorna defaultobj. Esta función evalúa la función hash de key solo una vez, en lugar de
evaluarla independientemente para la búsqueda y la inserción.
Nuevo en la versión 3.4.

148 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *PyDict_Items(PyObject *p)

Return value: New reference. Part of the Stable ABI. Retorna un PyListObject que contiene todos los
elementos del diccionario.
PyObject *PyDict_Keys(PyObject *p)
Return value: New reference. Part of the Stable ABI. Retorna un PyListObject que contiene todas las claves
del diccionario.
PyObject *PyDict_Values(PyObject *p)
Return value: New reference. Part of the Stable ABI. Retorna un PyListObject que contiene todos los
valores del diccionario p.
Py_ssize_t PyDict_Size(PyObject *p)
Part of the Stable ABI. Retorna el número de elementos en el diccionario. Esto es equivalente a len(p) en
un diccionario.
int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Part of the Stable ABI. Iterate over all key-value pairs in the dictionary p. The Py_ssize_t referred to by
ppos must be initialized to 0 prior to the first call to this function to start the iteration; the function returns true
for each pair in the dictionary, and false once all pairs have been reported. The parameters pkey and pvalue
should either point to PyObject* variables that will be filled in with each key and value, respectively, or may
be NULL. Any references returned through them are borrowed. ppos should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are
not consecutive.
Por ejemplo:
PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {

/* do something interesting with the values... */
...
}

El diccionario p no debe mutarse durante la iteración. Es seguro modificar los valores de las claves a medida
que recorre el diccionario, pero solo mientras el conjunto de claves no cambie. Por ejemplo:
PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {

long i = PyLong_AsLong(value);
if (i == -1 && PyErr_Occurred()) {
return -1;
}
PyObject *o = PyLong_FromLong(i + 1);
if (o == NULL)
return -1;
if (PyDict_SetItem(self->dict, key, o) < 0) {
Py_DECREF(o);
return -1;
}
Py_DECREF(o);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)

Part of the Stable ABI. Itera sobre el objeto de mapeo b agregando pares clave-valor al diccionario a. b puede
ser un diccionario o cualquier objeto que soporte PyMapping_Keys() y PyObject_GetItem(). Si
override es verdadero, los pares existentes en a se reemplazarán si se encuentra una clave coincidente en b, de
lo contrario, los pares solo se agregarán si no hay una clave coincidente en a. Retorna 0 en caso de éxito o -1
si se lanza una excepción.

8.4. Objetos contenedor 149

The Python/C API, Versión 3.11.0

int PyDict_Update(PyObject *a, PyObject *b)

Part of the Stable ABI. Esto es lo mismo que PyDict_Merge(a, b, 1) en C, y es similar a a.
update(b) en Python excepto que PyDict_Update() no vuelve a la iteración sobre una secuencia de
pares de valores clave si el segundo argumento no tiene el atributo «claves». Retorna 0 en caso de éxito o -1
si se produjo una excepción.
int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Part of the Stable ABI. Actualiza o combina en el diccionario a, desde los pares clave-valor en seq2. seq2 debe
ser un objeto iterable que produzca objetos iterables de longitud 2, vistos como pares clave-valor. En el caso
de claves duplicadas, el último gana si override es verdadero, de lo contrario, el primero gana. Retorna 0 en
caso de éxito o -1 si se produjo una excepción. El equivalente en Python (excepto el valor de retorno)
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
if override or key not in a:
a[key] = value

8.4.2 Objetos Conjunto

Esta sección detalla la API pública de los objetos set y frozenset. Cualquier funcionalidad que
no esté listada a continuación se accede mejor utilizando el protocolo abstracto de objetos (inclu-
yendo PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(),
PyObject_Repr(), PyObject_IsTrue(), PyObject_Print(), y PyObject_GetIter()) o el
protocolo numérico abstracto (incluyendo PyNumber_And(), PyNumber_Subtract(), PyNumber_Or(),
PyNumber_Xor(), PyNumber_InPlaceAnd(), PyNumber_InPlaceSubtract(),
PyNumber_InPlaceOr(), y PyNumber_InPlaceXor()).
type PySetObject
Este subtipo de PyObject se utiliza para mantener los datos internos de los objetos set y frozenset.
Es como un PyDictObject en el sentido de que tiene un tamaño fijo para los conjuntos pequeños (muy
parecido al almacenamiento de tuplas) y apuntará a un bloque de memoria separado y de tamaño variable para
los conjuntos de tamaño medio y grande (muy parecido al almacenamiento de listas). Ninguno de los campos
de esta estructura debe considerarse público y todos están sujetos a cambios. Todo el acceso debe hacerse a
través de la API documentada en lugar de manipular los valores de la estructura.
PyTypeObject PySet_Type
Part of the Stable ABI. Esta es una instancia de PyTypeObject que representa el tipo Python set.
PyTypeObject PyFrozenSet_Type
Part of the Stable ABI. Esta es una instancia de PyTypeObject que representa el tipo Python frozenset.
Los siguientes macros de comprobación de tipos funcionan en punteros a cualquier objeto de Python. Del mismo
modo, las funciones del constructor funcionan con cualquier objeto Python iterable.
int PySet_Check(PyObject *p)
Retorna verdadero si p es un objeto set o una instancia de un subtipo. Esta función siempre finaliza con éxito.
int PyFrozenSet_Check(PyObject *p)
Retorna verdadero si p es un objeto frozenset o una instancia de un subtipo. Esta función siempre finaliza
con éxito.
int PyAnySet_Check(PyObject *p)
Retorna verdadero si p es un objeto set, un objeto frozenset, o una instancia de un subtipo. Esta función
siempre finaliza con éxito.
int PySet_CheckExact(PyObject *p)
Retorna verdadero si p es un objeto set pero no una instancia de un subtipo. Esta función siempre finaliza con
éxito.
Nuevo en la versión 3.10.

150 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyAnySet_CheckExact(PyObject *p)

Retorna verdadero si p es un objeto set o un objeto frozenset pero no una instancia de un subtipo. Esta
función siempre finaliza con éxito.
int PyFrozenSet_CheckExact(PyObject *p)
Retorna verdadero si p es un objeto frozenset pero no una instancia de un subtipo. Esta función siempre
finaliza con éxito.
PyObject *PySet_New(PyObject *iterable)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo set que contiene objetos retornados
por iterable. El iterable puede ser NULL para crear un nuevo conjunto vacío. Retorna el nuevo conjunto en
caso de éxito o NULL en caso de error. Lanza TypeError si iterable no es realmente iterable. El constructor
también es útil para copiar un conjunto (c=set(s)).
PyObject *PyFrozenSet_New(PyObject *iterable)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo frozenset que contiene objetos
retornados por iterable. El iterable puede ser NULL para crear un nuevo conjunto congelado vacío. Retorna
el nuevo conjunto en caso de éxito o NULL en caso de error. Lanza TypeError si iterable no es realmente
iterable.
Las siguientes funciones y macros están disponibles para instancias de set o frozenset o instancias de sus sub-
tipos.
Py_ssize_t PySet_Size(PyObject *anyset)
Part of the Stable ABI. Retorna la longitud de un objeto set o frozenset. Equivalente a len(anyset).
Lanza un PyExc_SystemError si anyset no es set, frozenset, o una instancia de un subtipo.
Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
Forma macro de PySet_Size() sin comprobación de errores.
int PySet_Contains(PyObject *anyset, PyObject *key)
Part of the Stable ABI. Retorna 1 si se encuentra, 0 si no se encuentra y -1 si se encuentra un error. A
diferencia del método Python __contains__(), esta función no convierte automáticamente conjuntos
no compartibles en congelados temporales. Lanza un TypeError si la key no se puede compartir. Lanza
PyExc_SystemError si anyset no es un set, frozenset, o una instancia de un subtipo.
int PySet_Add(PyObject *set, PyObject *key)
Part of the Stable ABI. Añade key a una instancia set. También funciona con instancias de frozenset
(al igual que PyTuple_SetItem() puede usarse para rellenar los valores de nuevos frozensets antes
de que sean expuestos a otro código). Retorna 0 en caso de éxito o -1 en caso de fallo. Lanza un error
TypeError si la key no se puede intercambiar. Lanza un MemoryError si no hay espacio para crecer.
Lanza un SystemError si set no es una instancia de set o su subtipo.
Las siguientes funciones están disponibles para instancias de set o sus subtipos, pero no para instancias de
frozenset o sus subtipos.
int PySet_Discard(PyObject *set, PyObject *key)
Part of the Stable ABI. Retorna 1 si se encuentra y se elimina, 0 si no se encuentra (no se realiza ninguna acción)
y -1 si se encuentra un error. No lanza KeyError por faltar claves. Lanza un TypeError si la key no se
puede compartir. A diferencia del método Python discard(), esta función no convierte automáticamente
conjuntos no compartibles en congelados temporales. Lanza PyExc_SystemError si set no es una instancia
de set o su subtipo.
PyObject *PySet_Pop(PyObject *set)
Return value: New reference. Part of the Stable ABI. Retorna una nueva referencia a un objeto arbitrario en
el set y elimina el objeto del set. Retorna NULL en caso de falla. Lanza KeyError si el conjunto está vacío.
Lanza a SystemError si set no es una instancia de set o su subtipo.
int PySet_Clear(PyObject *set)
Part of the Stable ABI. Vacía un conjunto existente de todos los elementos.

8.4. Objetos contenedor 151

The Python/C API, Versión 3.11.0

8.5 Objetos de función

8.5.1 Objetos función

Hay algunas funciones específicas para las funciones de Python.

type PyFunctionObject
La estructura C utilizada para las funciones.
PyTypeObject PyFunction_Type
Esta es una instancia de PyTypeObject y representa el tipo función de Python. Está expuesto a los progra-
madores de Python como types.FunctionType.
int PyFunction_Check(PyObject *o)
Retorna verdadero si o es un objeto función (tiene tipo PyFunction_Type). El parámetro no debe ser
NULL. Esta función siempre finaliza con éxito.
PyObject *PyFunction_New(PyObject *code, PyObject *globals)
Return value: New reference. Retorna un nuevo objeto función asociado con el objeto código code. globals debe
ser un diccionario con las variables globales accesibles para la función.
The function’s docstring and name are retrieved from the code object. __module__ is retrieved from globals.
The argument defaults, annotations and closure are set to NULL. __qualname__ is set to the same value as the
code object’s co_qualname field.
PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
Return value: New reference. As PyFunction_New(), but also allows setting the function object’s
__qualname__ attribute. qualname should be a unicode object or NULL; if NULL, the __qualname__
attribute is set to the same value as the code object’s co_qualname field.
Nuevo en la versión 3.3.
PyObject *PyFunction_GetCode(PyObject *op)
Return value: Borrowed reference. Retorna el objeto código asociado con el objeto función op.
PyObject *PyFunction_GetGlobals(PyObject *op)
Return value: Borrowed reference. Retorna el diccionario global asociado con el objeto función op.
PyObject *PyFunction_GetModule(PyObject *op)
Return value: Borrowed reference. Retorna una referencia tomada (borrowed reference) al atributo __module__
del objeto función op. Puede ser NULL.
Éste es normalmente una cadena de caracteres que contiene el nombre del módulo, pero se puede establecer
en cualquier otro objeto mediante código Python.
PyObject *PyFunction_GetDefaults(PyObject *op)
Return value: Borrowed reference. Retorna los valores predeterminados del argumento del objeto función op.
Esto puede ser una tupla de argumentos o NULL.
int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
Establece los valores predeterminados del argumento para el objeto función op. defaults deben ser Py_None
o una tupla.
Lanza SystemError y retorna -1 en caso de error.
PyObject *PyFunction_GetClosure(PyObject *op)
Return value: Borrowed reference. Retorna el cierre asociado con el objeto función op. Esto puede ser NULL o
una tupla de objetos celda.
int PyFunction_SetClosure(PyObject *op, PyObject *closure)
Establece el cierre asociado con el objeto función op. cierre debe ser Py_None o una tupla de objetos celda.
Lanza SystemError y retorna -1 en caso de error.

152 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyObject *PyFunction_GetAnnotations(PyObject *op)

Return value: Borrowed reference. Retorna las anotaciones del objeto función op. Este puede ser un diccionario
mutable o NULL.
int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
Establece las anotaciones para el objeto función op. annotations debe ser un diccionario o Py_None.
Lanza SystemError y retorna -1 en caso de error.

8.5.2 Objetos de método de instancia

Un método de instancia es un contenedor para una PyCFunction y la nueva forma de vincular una PyCFunction
a un objeto de clase. Reemplaza la llamada anterior PyMethod_New (func, NULL, class).
PyTypeObject PyInstanceMethod_Type
Esta instancia de PyTypeObject representa el tipo de método de instancia de Python. No está expuesto a
los programas de Python.
int PyInstanceMethod_Check(PyObject *o)
Retorna verdadero si o es un objeto de método de instancia (tiene tipo PyInstanceMethod_Type). El
parámetro no debe ser NULL. Esta función siempre finaliza con éxito.
PyObject *PyInstanceMethod_New(PyObject *func)
Return value: New reference. Return a new instance method object, with func being any callable object. func is
the function that will be called when the instance method is called.
PyObject *PyInstanceMethod_Function(PyObject *im)
Return value: Borrowed reference. Retorna el objeto de función asociado con el método de instancia im.
PyObject *PyInstanceMethod_GET_FUNCTION(PyObject *im)
Return value: Borrowed reference. Versión macro de PyInstanceMethod_Function() que evita la
comprobación de errores.

8.5.3 Objetos método

Los métodos son objetos de función enlazados. Los métodos siempre están vinculados a una instancia de una clase
definida por el usuario. Los métodos no vinculados (métodos vinculados a un objeto de clase) ya no están disponibles.

PyTypeObject PyMethod_Type
Esta instancia de PyTypeObject representa el tipo de método Python. Esto está expuesto a los programas
de Python como types.MethodType.
int PyMethod_Check(PyObject *o)
Retorna verdadero si o es un objeto de método (tiene tipo PyMethod_Type). El parámetro no debe ser
NULL. Esta función siempre finaliza con éxito.
PyObject *PyMethod_New(PyObject *func, PyObject *self)
Return value: New reference. Retorna un nuevo objeto de método, con func como cualquier objeto invocable
y self la instancia en la que se debe vincular el método. func es la función que se llamará cuando se llame al
método. self no debe ser NULL.
PyObject *PyMethod_Function(PyObject *meth)
Return value: Borrowed reference. Retorna el objeto de función asociado con el método meth.
PyObject *PyMethod_GET_FUNCTION(PyObject *meth)
Return value: Borrowed reference. Versión macro de PyMethod_Function() que evita la comprobación
de errores.

8.5. Objetos de función 153

The Python/C API, Versión 3.11.0

PyObject *PyMethod_Self(PyObject *meth)

Return value: Borrowed reference. Retorna la instancia asociada con el método meth.
PyObject *PyMethod_GET_SELF(PyObject *meth)
Return value: Borrowed reference. Versión macro de PyMethod_Self() que evita la comprobación de
errores.

8.5.4 Objetos Celda

Los objetos celda (cell) se utilizan para implementar variables a las que hacen referencia varios ámbitos. Para cada
variable, se crea un objeto de celda para almacenar el valor; Las variables locales de cada marco de pila que hace
referencia al valor contienen una referencia a las celdas de ámbitos externos que también usan esa variable. Cuando
se accede al valor, se utiliza el valor contenido en la celda en lugar del objeto de la celda en sí. Esta desreferenciación
del objeto de celda requiere soporte del código de bytes generado; estos no se eliminan automáticamente cuando se
accede a ellos. No es probable que los objetos celda sean útiles en otros lugares.
type PyCellObject
La estructura C utilizada para objetos celda.
PyTypeObject PyCell_Type
El objeto tipo correspondiente a los objetos celda.
int PyCell_Check(ob)
Retorna verdadero si ob es un objeto de celda; ob no debe ser NULL. Esta función siempre finaliza con éxito.
PyObject *PyCell_New(PyObject *ob)
Return value: New reference. Crea y retorna un nuevo objeto de celda que contiene el valor ob. El parámetro
puede ser NULL.
PyObject *PyCell_Get(PyObject *cell)
Return value: New reference. Retorna el contenido de la celda cell.
PyObject *PyCell_GET(PyObject *cell)
Return value: Borrowed reference. Retorna el contenido de la celda cell, pero sin verificar que cell no sea NULL
y que sea un objeto de celda.
int PyCell_Set(PyObject *cell, PyObject *value)
Establece el contenido del objeto de celda cell con el valor value. Esto libera la referencia a cualquier contenido
actual de la celda. value puede ser NULL. cell no debe ser NULL; Si no es un objeto de celda, se retornará -1.
En caso de éxito, se retornará 0.
void PyCell_SET(PyObject *cell, PyObject *value)
Establece el valor del objeto de celda cell en el valor value. No se ajustan los recuentos de referencia y no se
realizan verificaciones de seguridad; cell no debe ser NULL y debe ser un objeto de celda.

8.5.5 Objetos Código

Los objetos código son un detalle de bajo nivel de la implementación de CPython. Cada uno representa un fragmento
de código ejecutable que aún no se ha vinculado a una función.
type PyCodeObject
La estructura en C de los objetos utilizados para describir objetos código. Los campos de este tipo están sujetos
a cambios en cualquier momento.
PyTypeObject PyCode_Type
Esta es una instancia de PyTypeObject que representa el tipo Python code.
int PyCode_Check(PyObject *co)
Retorna verdadero si co es un objeto code. Esta función siempre finaliza con éxito.

154 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyCode_GetNumFree(PyCodeObject *co)

Retorna el número de variables libres en co.
PyCodeObject *PyCode_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject
*code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject
*freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno,
PyObject *linetable, PyObject *exceptiontable)
Return value: New reference. Retorna un nuevo objeto de código. Si se necesita un objeto de código ficticio para
crear un marco (frame), usar PyCode_NewEmpty() en su lugar. Llamando PyCode_New() directamente
puede enlazarlo a una versión precisa de Python ya que la definición del código de bytes cambia a menudo.
Muchos de los argumentos de esta función están relacionados mutuamente de formas complejas, lo cual significa
que cambios sutiles en estos valores probablemente resulten en ejecuciones incorrectas o fallas en la VM.
Distinto en la versión 3.11: Se agregó el parámetro exceptiontable.
PyCodeObject *PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int
nlocals, int stacksize, int flags, PyObject *code, PyObject
*consts, PyObject *names, PyObject *varnames, PyObject
*freevars, PyObject *cellvars, PyObject *filename, PyObject
*name, int firstlineno, PyObject *linetable, PyObject
*exceptiontable)
Return value: New reference. Similar a PyCode_New(), pero con un «posonlyargcount» adicional para ar-
gumentos solo posicionales. Las mismas advertencias que aplican a PyCode_New también aplican a esta
función.
Nuevo en la versión 3.8.
Distinto en la versión 3.11: Se agregó el parámetro exceptiontable.
PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
Return value: New reference. Retorna un nuevo objeto de código vacío con el nombre de archivo especificado,
el nombre de la función y el número de la primera línea. Si el objeto código resultante es ejecutado, lanzará
una Exception.
int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)
Retorna el número de línea de la instrucción que se produce en o antes de byte_offset y finaliza después.
Si solo necesita el número de línea de un marco, use PyFrame_GetLineNumber() en su lugar.
Para iterar de manera eficiente sobre los números de línea en un objeto de código, use la API descrita en PEP
626.
int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line,
int *end_column)
Establece los punteros int pasados en los números de línea y columna del código fuente para las instrucciones
en byte_offset. Establece el valor en 0 cuando la información no está disponible para algún elemento en
particular.
Retorna 1 si la función fue exitosa y 0 de lo contrario.
PyObject *PyCode_GetCode(PyCodeObject *co)
Equivalente al código Python getattr(co, 'co_code'). Retorna una referencia fuerte a un
PyBytesObject representando el bytecode en un objecto código. En caso de error se retorna NULL y
se lanza una excepción.
Este PyBytesObject puede ser creado a pedido del intérprete y no necesariamente representa el bytecode
que es realmente ejecutado por CPython. Los casos de uso principales para esta función son depuradores y
perfiladores.
Nuevo en la versión 3.11.
PyObject *PyCode_GetVarnames(PyCodeObject *co)
Equivalente al código Python getattr(co, 'co_varnames'). Retorna una nueva referencia a un

8.5. Objetos de función 155

The Python/C API, Versión 3.11.0

PyTupleObject que contiene los nombres de las variables locales. En caso de error, retorna NULL y lanza
una excepción.
Nuevo en la versión 3.11.
PyObject *PyCode_GetCellvars(PyCodeObject *co)
Equivalente al código Python getattr(co, 'co_cellvars'). Retorna una nueva referencia a un
PyTupleObject que contiene los nombres de las variables locales referenciadas por funciones anidadas.
En caso de error, retorna NULL y lanza una excepción.
Nuevo en la versión 3.11.
PyObject *PyCode_GetFreevars(PyCodeObject *co)
Equivalente al código Python getattr(co, 'co_freevars'). Retorna una nueva referencia a un
PyTupleObject que contiene los nombres de las variables libres. En caso de error, retorna NULL y lanza
una excepción.
Nuevo en la versión 3.11.

8.6 Otros objetos

8.6.1 Objetos archivo

These APIs are a minimal emulation of the Python 2 C API for built-in file objects, which used to rely on the
buffered I/O (FILE*) support from the C standard library. In Python 3, files and streams use the new io module,
which defines several layers over the low-level unbuffered I/O of the operating system. The functions described below
are convenience C wrappers over these new APIs, and meant mostly for internal error reporting in the interpreter;
third-party code is advised to access the io APIs instead.
PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding,
const char *errors, const char *newline, int closefd)
Return value: New reference. Part of the Stable ABI. Crea un objeto archivo Python a partir del descriptor de
archivo de un archivo ya abierto fd. Los argumentos name, encoding, errors y newline pueden ser NULL para
usar los valores predeterminados; buffering puede ser -1 para usar el valor predeterminado. name se ignora y
se mantiene por compatibilidad con versiones anteriores. Retorna NULL en caso de error. Para obtener una
descripción más completa de los argumentos, consulte la documentación de la función io.open().

Advertencia: Dado que las transmisiones (streams) de Python tienen su propia capa de almacenamiento
en búfer, combinarlas con descriptores de archivos a nivel del sistema operativo puede producir varios
problemas (como un pedido inesperado de datos).

Distinto en la versión 3.2: Ignora el atributo name.

int PyObject_AsFileDescriptor(PyObject *p)
Part of the Stable ABI. Return the file descriptor associated with p as an int. If the object is an integer, its
value is returned. If not, the object’s fileno() method is called if it exists; the method must return an integer,
which is returned as the file descriptor value. Sets an exception and returns -1 on failure.
PyObject *PyFile_GetLine(PyObject *p, int n)
Return value: New reference. Part of the Stable ABI. Equivalente a p.readline([n]), esta función lee
una línea del objeto p. p puede ser un objeto archivo o cualquier objeto con un método readline(). Si n
es 0, se lee exactamente una línea, independientemente de la longitud de la línea. Si n es mayor que 0, no se
leerán más de n bytes del archivo; se puede retornar una línea parcial. En ambos casos, se retorna una cadena
de caracteres vacía si se llega al final del archivo de inmediato. Si n es menor que 0, sin embargo, se lee una
línea independientemente de la longitud, pero EOFError se lanza si se llega al final del archivo de inmediato.

156 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

Sobrescribe el comportamiento normal de io.open_code() para pasar su parámetro a través del contro-
lador proporcionado.
The handler is a function of type PyObject *(*)(PyObject *path, void *userData), where
path is guaranteed to be PyUnicodeObject.
El puntero userData se pasa a la función de enlace. Dado que las funciones de enlace pueden llamarse desde
diferentes tiempos de ejecución, este puntero no debe referirse directamente al estado de Python.
Como este hook se usa intencionalmente durante la importación, evite importar nuevos módulos durante su
ejecución a menos que se sepa que están congelados o disponibles en sys.modules.
Una vez que se ha establecido un hook, no se puede quitar ni reemplazar, y luego llamadas a
PyFile_SetOpenCodeHook() fallarán. En caso de error, la función retorna -1 y establece una excepción
si el intérprete se ha inicializado.
Es seguro llamar a esta función antes de Py_Initialize().
Genera un evento de auditoría setopencodehook sin argumentos.
Nuevo en la versión 3.8.
int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
Part of the Stable ABI. Escribe el objeto obj en el objeto archivo p. El único indicador admitido para flags es
Py_PRINT_RAW; si se proporciona, se escribe el str() del objeto en lugar de repr(). Retorna 0 en caso
de éxito o -1 en caso de error; se establecerá la excepción apropiada.
int PyFile_WriteString(const char *s, PyObject *p)
Part of the Stable ABI. Escribe la cadena s en el objeto archivo p. Retorna 0 en caso de éxito o -1 en caso de
error; se establecerá la excepción apropiada.

8.6.2 Objetos Modulo

PyTypeObject PyModule_Type
Part of the Stable ABI. Esta instancia de PyTypeObject representa el tipo de módulo Python. Esto está
expuesto a los programas de Python como types.ModuleType.
int PyModule_Check(PyObject *p)
Retorna verdadero si p es un objeto de módulo o un subtipo de un objeto de módulo. Esta función siempre
finaliza con éxito.
int PyModule_CheckExact(PyObject *p)
Retorna verdadero si p es un objeto módulo, pero no un subtipo de PyModule_Type. Esta función siempre
finaliza con éxito.
PyObject *PyModule_NewObject(PyObject *name)
Return value: New reference. Part of the Stable ABI since version 3.7. Retorna un nuevo objeto módu-
lo con el atributo __name__ establecido en name. Los atributos del módulo __name__, __doc__,
__package__, y __loader__ se completan (todos menos __name__ están configurados en None);
quien llama es responsable de proporcionar un atributo __file__.
Nuevo en la versión 3.3.
Distinto en la versión 3.4: __package__ y __loader__ están configurados en None.
PyObject *PyModule_New(const char *name)
Return value: New reference. Part of the Stable ABI. Similar a PyModule_NewObject(), pero el nombre
es una cadena de caracteres codificada UTF-8 en lugar de un objeto Unicode.

8.6. Otros objetos 157

The Python/C API, Versión 3.11.0

PyObject *PyModule_GetDict(PyObject *module)

Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto del diccionario que implementa
el espacio de nombres de module; este objeto es el mismo que el atributo __dict__ del objeto módulo. Si
module no es un objeto módulo (o un subtipo de un objeto de módulo), se lanza SystemError y se retorna
NULL.
It is recommended extensions use other PyModule_* and PyObject_* functions rather than directly ma-
nipulate a module’s __dict__.
PyObject *PyModule_GetNameObject(PyObject *module)
Return value: New reference. Part of the Stable ABI since version 3.7. Retorna el valor __name__ del module.
Si el módulo no proporciona uno, o si no es una cadena de caracteres, SystemError se lanza y se retorna
NULL.
Nuevo en la versión 3.3.
const char *PyModule_GetName(PyObject *module)
Part of the Stable ABI. Similar a PyModule_GetNameObject() pero retorna el nombre codificado a
'utf-8'.
void *PyModule_GetState(PyObject *module)
Part of the Stable ABI. Retorna el «estado» del módulo, es decir, un puntero al bloque de memoria asignado
en el momento de la creación del módulo, o NULL. Ver PyModuleDef.m_size.
PyModuleDef *PyModule_GetDef(PyObject *module)
Part of the Stable ABI. Retorna un puntero a la estructura PyModuleDef a partir de la cual se creó el módulo,
o NULL si el módulo no se creó a partir de una definición.
PyObject *PyModule_GetFilenameObject(PyObject *module)
Return value: New reference. Part of the Stable ABI. Retorna el nombre del archivo desde el cual module se
cargó utilizando el atributo __file__ del module. Si esto no está definido, o si no es una cadena de caracteres
unicode, lanza SystemError y retornar NULL; de lo contrario, retorna una referencia a un objeto Unicode.
Nuevo en la versión 3.2.
const char *PyModule_GetFilename(PyObject *module)
Part of the Stable ABI. Similar a PyModule_GetFilenameObject() pero retorna el nombre de archivo
codificado a “utf-8”.
Obsoleto desde la versión 3.2: PyModule_GetFilename() lanza UnicodeEncodeError en nombres
de archivo no codificables, use PyModule_GetFilenameObject() en su lugar.

Inicializando módulos en C

Los objetos módulos generalmente se crean a partir de módulos de extensión (bibliotecas compartidas que ex-
portan una función de inicialización) o módulos compilados (donde la función de inicialización se agrega usando
PyImport_AppendInittab()). Consulte building o extendiendo con incrustación para más detalles.
La función de inicialización puede pasar una instancia de definición de módulo a PyModule_Create(), y retornar
el objeto módulo resultante, o solicitar una «inicialización de múltiples fases» retornando la estructura de definición.
type PyModuleDef
Part of the Stable ABI (including all members). La estructura de definición de módulo, que contiene toda
la información necesaria para crear un objeto módulo. Por lo general, solo hay una variable estáticamente
inicializada de este tipo para cada módulo.
PyModuleDef_Base m_base
Siempre inicialice este miembro a PyModuleDef_HEAD_INIT.
const char *m_name
Nombre para el nuevo módulo.

158 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

const char *m_doc

Docstring para el módulo; por lo general, se usa una variable docstring creada con PyDoc_STRVAR.
Py_ssize_t m_size
El estado del módulo se puede mantener en un área de memoria por módulo que se puede recuperar con
PyModule_GetState(), en lugar de en globales estáticos. Esto hace que los módulos sean seguros
para su uso en múltiples sub-interpretadores.
Esta área de memoria se asigna en base a m_size en la creación del módulo, y se libera cuando el objeto
del módulo se desasigna, después de que se haya llamado a la función m_free, si está presente.
Establecer m_size en -1 significa que el módulo no admite sub-interpretadores, porque tiene un estado
global.
Establecerlo en un valor no negativo significa que el módulo se puede reinicializar y especifica la cantidad
adicional de memoria que requiere para su estado. Se requiere m_size no negativo para la inicialización
de múltiples fases.
Ver PEP 3121 para más detalles.
PyMethodDef *m_methods
Un puntero a una tabla de funciones de nivel de módulo, descrito por valores PyMethodDef. Puede
ser NULL si no hay funciones presentes.
PyModuleDef_Slot *m_slots
Un conjunto de definiciones de ranura para la inicialización de múltiples fases, terminadas por una entrada
{0, NULL}. Cuando se utiliza la inicialización monofásica, m_slots debe ser NULL.
Distinto en la versión 3.5: Antes de la versión 3.5, este miembro siempre estaba configurado en NULL y
se definía como:
inquiry m_reload

traverseproc m_traverse
Una función transversal para llamar durante el recorrido GC del objeto del módulo, o NULL si no es
necesario.
Esta función no se llama si se solicitó el estado del módulo pero aún no se asignó. Este es el caso in-
mediatamente después de que se crea el módulo y antes de que se ejecute (la función Py_mod_exec).
Más precisamente, esta función no se llama si m_size es mayor que 0 y el estado del módulo (como lo
retorna PyModule_GetState()) es NULL.
Distinto en la versión 3.9: Ya no se llama antes de que se asigne el estado del módulo.
inquiry m_clear
Una función clara para llamar durante la limpieza GC del objeto del módulo, o NULL si no es necesario.
Esta función no se llama si se solicitó el estado del módulo pero aún no se asignó. Este es el caso in-
mediatamente después de que se crea el módulo y antes de que se ejecute (la función Py_mod_exec).
Más precisamente, esta función no se llama si m_size es mayor que 0 y el estado del módulo (como lo
retorna PyModule_GetState()) es NULL.
Tal como PyTypeObject.tp_clear, esta función no siempre es llamada antes de la designación de
un módulo. Por ejemplo, cuando el recuento de referencias está listo para determinar que un objeto no se
usa más, la recolección de basura cíclica no se involucra y se llama a m_free directamente.
Distinto en la versión 3.9: Ya no se llama antes de que se asigne el estado del módulo.
freefunc m_free
Una función para llamar durante la desasignación del objeto del módulo, o NULL si no es necesario.
Esta función no se llama si se solicitó el estado del módulo pero aún no se asignó. Este es el caso in-
mediatamente después de que se crea el módulo y antes de que se ejecute (la función Py_mod_exec).
Más precisamente, esta función no se llama si m_size es mayor que 0 y el estado del módulo (como lo
retorna PyModule_GetState()) es NULL.

8.6. Otros objetos 159

The Python/C API, Versión 3.11.0

Distinto en la versión 3.9: Ya no se llama antes de que se asigne el estado del módulo.

Inicialización monofásica

La función de inicialización del módulo puede crear y retornar el objeto módulo directamente. Esto se conoce como
«inicialización monofásica» y utiliza una de las siguientes funciones de creación de dos módulos:
PyObject *PyModule_Create(PyModuleDef *def)
Return value: New reference. Crea un nuevo objeto módulo, dada la definición en def. Esto se comporta como
PyModule_Create2() con module_api_version establecido en PYTHON_API_VERSION.
PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)
Return value: New reference. Part of the Stable ABI. Crea un nuevo objeto de módulo, dada la definición en
def, asumiendo la versión de API module_api_version. Si esa versión no coincide con la versión del intérprete
en ejecución, se emite un RuntimeWarning.

Nota: La mayoría de los usos de esta función deberían usar PyModule_Create() en su lugar; solo use
esto si está seguro de que lo necesita.

Antes de que se retorne desde la función de inicialización, el objeto del módulo resultante normalmente se llena
utilizando funciones como PyModule_AddObjectRef().

Inicialización multifase

Una forma alternativa de especificar extensiones es solicitar una «inicialización de múltiples fases». Los módulos de
extensión creados de esta manera se comportan más como los módulos de Python: la inicialización se divide entre la
fase de creación (creation phase), cuando se crea el objeto módulo, y la fase de ejecución (execution phase), cuando
se llena. La distinción es similar a los métodos de clases __new__() y __init__().
A diferencia de los módulos creados con la inicialización monofásica, estos módulos no son singletons: si se elimina
la entrada sys.modules y el módulo se vuelve a importar, se crea un nuevo objeto módulo y el módulo anterior está
sujeto a la recolección normal de basura – Al igual que con los módulos de Python. Por defecto, los módulos múl-
tiples creados a partir de la misma definición deberían ser independientes: los cambios en uno no deberían afectar
a los demás. Esto significa que todo el estado debe ser específico para el objeto del módulo (usando, por ejemplo,
usando PyModule_GetState()), o su contenido (como el módulo __dict__ o clases individuales creadas
con PyType_FromSpec()).
Se espera que todos los módulos creados mediante la inicialización de múltiples fases admitan sub-interpretadores.
Asegurándose de que varios módulos sean independientes suele ser suficiente para lograr esto.
Para solicitar la inicialización de múltiples fases, la función de inicialización (PyInit_modulename) retorna una ins-
tancia de PyModuleDef con un m_slots no vacío. Antes de que se retorna, la instancia PyModuleDef debe
inicializarse con la siguiente función:
PyObject *PyModuleDef_Init(PyModuleDef *def)
Return value: Borrowed reference. Part of the Stable ABI since version 3.5. Asegura que la definición de un
módulo sea un objeto Python correctamente inicializado que informe correctamente su tipo y conteo de refe-
rencias.
Retorna def convertido a PyObject* o NULL si se produjo un error.
Nuevo en la versión 3.5.
El miembro m_slots de la definición del módulo debe apuntar a un arreglo de estructuras PyModuleDef_Slot:
type PyModuleDef_Slot

int slot
Una ranura ID, elegida entre los valores disponibles que se explican a continuación.

160 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

void *value
Valor de la ranura, cuyo significado depende de la ID de la ranura.
Nuevo en la versión 3.5.
El arreglo m_slots debe estar terminada por una ranura con id 0.
Los tipos de ranura disponibles son:
Py_mod_create
Especifica una función que se llama para crear el objeto del módulo en sí. El puntero value de este espacio debe
apuntar a una función de la firma:
PyObject *create_module(PyObject *spec, PyModuleDef *def)

La función recibe una instancia de ModuleSpec, como se define en PEP 451, y la definición del módulo.
Debería retornar un nuevo objeto de módulo, o establecer un error y retornar NULL.
Esta función debe mantenerse mínima. En particular, no debería llamar a código arbitrario de Python, ya que
intentar importar el mismo módulo nuevamente puede dar como resultado un bucle infinito.
Múltiples ranuras Py_mod_create no pueden especificarse en una definición de módulo.
Si no se especifica Py_mod_create, la maquinaria de importación creará un objeto de módulo normal
usando PyModule_New(). El nombre se toma de spec, no de la definición, para permitir que los módulos
de extensión se ajusten dinámicamente a su lugar en la jerarquía de módulos y se importen bajo diferentes
nombres a través de enlaces simbólicos, todo mientras se comparte una definición de módulo único.
No es necesario que el objeto retornado sea una instancia de PyModule_Type. Se puede usar cualquier tipo,
siempre que admita la configuración y la obtención de atributos relacionados con la importación. Sin embargo,
solo se pueden retornar instancias PyModule_Type si el PyModuleDef no tiene NULL m_traverse,
m_clear, m_free; m_size distinto de cero; o ranuras que no sean Py_mod_create.
Py_mod_exec
Especifica una función que se llama para ejecutar (execute) el módulo. Esto es equivalente a ejecutar el código
de un módulo Python: por lo general, esta función agrega clases y constantes al módulo. La firma de la función
es:
int exec_module(PyObject *module)

Si se especifican varias ranuras Py_mod_exec, se procesan en el orden en que aparecen en el arreglo m_slots.
Ver PEP 489 para más detalles sobre la inicialización de múltiples fases.

Funciones de creación de módulos de bajo nivel

Las siguientes funciones se invocan en segundo plano cuando se utiliza la inicialización de múltiples fases. Se pue-
den usar directamente, por ejemplo, al crear objetos de módulo de forma dinámica. Tenga en cuenta que tanto
PyModule_FromDefAndSpec como PyModule_ExecDef deben llamarse para inicializar completamente
un módulo.
PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
Return value: New reference. Cree un nuevo objeto módulo, dada la definición en module y ModuleSpec
spec. Esto se comporta como PyModule_FromDefAndSpec2() con module_api_version establecido en
PYTHON_API_VERSION.
Nuevo en la versión 3.5.
PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
Return value: New reference. Part of the Stable ABI since version 3.7. Cree un nuevo objeto módulo, dada la
definición en module y ModuleSpec spec, asumiendo la versión de API module_api_version. Si esa versión no
coincide con la versión del intérprete en ejecución, se emite un RuntimeWarning.

8.6. Otros objetos 161

The Python/C API, Versión 3.11.0

Nota: La mayoría de los usos de esta función deberían usar PyModule_FromDefAndSpec() en su lugar;
solo use esto si está seguro de que lo necesita.

Nuevo en la versión 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
Part of the Stable ABI since version 3.7. Procesa cualquier ranura de ejecución (Py_mod_exec) dado en def.
Nuevo en la versión 3.5.
int PyModule_SetDocString(PyObject *module, const char *docstring)
Part of the Stable ABI since version 3.7. Establece la cadena de caracteres de documentación para module en
docstring. Esta función se llama automáticamente cuando se crea un módulo desde PyModuleDef, usando
PyModule_Create o PyModule_FromDefAndSpec.
Nuevo en la versión 3.5.
int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
Part of the Stable ABI since version 3.7. Agrega las funciones del arreglo functions terminadas en NULL a mo-
dule. Consulte la documentación de PyMethodDef para obtener detalles sobre entradas individuales (debido
a la falta de un espacio de nombres de módulo compartido, las «funciones» de nivel de módulo implementadas
en C generalmente reciben el módulo como su primer parámetro, haciéndolos similares a la instancia métodos
en clases de Python). Esta función se llama automáticamente cuando se crea un módulo desde PyModuleDef,
usando PyModule_Create o PyModule_FromDefAndSpec.
Nuevo en la versión 3.5.

Funciones de soporte

La función de inicialización del módulo (si usa la inicialización de fase única) o una función llamada desde un intervalo
de ejecución del módulo (si usa la inicialización de múltiples fases), puede usar las siguientes funciones para ayudar
a inicializar el estado del módulo:
int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
Part of the Stable ABI since version 3.10. Agrega un objeto a module como name. Esta es una función de
conveniencia que se puede usar desde la función de inicialización del módulo.
En caso de éxito, retorna 0. En caso de error, lanza una excepción y retorna -1.
Retorna NULL si value es NULL. Debe llamarse lanzando una excepción en este caso.
Ejemplo de uso

static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
if (obj == NULL) {
return -1;
}
int res = PyModule_AddObjectRef(module, "spam", obj);
Py_DECREF(obj);
return res;
}

El ejemplo puede también ser escrito sin verificar explicitamente si obj es NULL:

static int
add_spam(PyObject *module, int value)
{
(continué en la próxima página)

162 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

PyObject *obj = PyLong_FromLong(value);
int res = PyModule_AddObjectRef(module, "spam", obj);
Py_XDECREF(obj);
return res;
}

Note que Py_XDECREF() debería ser usado en vez de Py_DECREF() en este caso, ya que obj puede ser
NULL.
Nuevo en la versión 3.10.
int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
Part of the Stable ABI. Similar a PyModule_AddObjectRef(), pero roba una referencia a value en caso
de éxito (en este caso retorna 0).
Se recomienda la nueva función PyModule_AddObjectRef(), ya que es sencillo introducir fugas de
referencias por un uso incorrecto de la función PyModule_AddObject().

Nota: A diferencia de otras funciones que roban referencias, PyModule_AddObject() solo disminuye
el conteo de referencias de value en caso de éxito.
Esto significa que su valor de retorno debe ser verificado, y el código de llamada debe Py_DECREF() value
manualmente en caso de error.

Ejemplo de uso

static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
if (obj == NULL) {
return -1;
}
if (PyModule_AddObject(module, "spam", obj) < 0) {
Py_DECREF(obj);
return -1;
}
// PyModule_AddObject() stole a reference to obj:
// Py_DECREF(obj) is not needed here
return 0;
}

El ejemplo puede también ser escrito sin verificar explicitamente si obj es NULL:

static int
add_spam(PyObject *module, int value)
{
PyObject *obj = PyLong_FromLong(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
Py_XDECREF(obj);
return -1;
}
// PyModule_AddObject() stole a reference to obj:
// Py_DECREF(obj) is not needed here
return 0;
}

Note que Py_XDECREF() debería ser usado en vez de Py_DECREF() en este caso, ya que obj puede ser
NULL.

8.6. Otros objetos 163

The Python/C API, Versión 3.11.0

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Part of the Stable ABI. Agrega una constante entera a module como name. Esta función de conveniencia se
puede usar desde la función de inicialización del módulo. Retorna -1 en caso de error, 0 en caso de éxito.
int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
Part of the Stable ABI. Agrega una constante de cadena a module como name. Esta función de conveniencia se
puede usar desde la función de inicialización del módulo. La cadena de caracteres value debe estar terminada
en NULL. Retorna -1 en caso de error, 0 en caso de éxito.
int PyModule_AddIntMacro(PyObject *module, macro)
Agrega una constante int a module. El nombre y el valor se toman de macro. Por ejemplo,
PyModule_AddIntMacro(module, AF_INET) agrega la constante int AF_INET con el valor de
AF_INET a module. Retorna -1 en caso de error, 0 en caso de éxito.
int PyModule_AddStringMacro(PyObject *module, macro)
Agrega una constante de cadena de caracteres a module.
int PyModule_AddType(PyObject *module, PyTypeObject *type)
Part of the Stable ABI since version 3.10. Agrega un objeto tipo a module. El objeto tipo se finaliza llamando
internamente PyType_Ready(). El nombre del objeto tipo se toma del último componente de tp_name
después del punto. Retorna -1 en caso de error, 0 en caso de éxito.
Nuevo en la versión 3.9.

Búsqueda de módulos

La inicialización monofásica crea módulos singleton que se pueden buscar en el contexto del intérprete actual. Esto
permite que el objeto módulo se recupere más tarde con solo una referencia a la definición del módulo.
Estas funciones no funcionarán en módulos creados mediante la inicialización de múltiples fases, ya que se pueden
crear múltiples módulos de este tipo desde una sola definición.
PyObject *PyState_FindModule(PyModuleDef *def)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto módulo que se creó a partir de
def para el intérprete actual. Este método requiere que el objeto módulo se haya adjuntado al estado del intér-
prete con PyState_AddModule() de antemano. En caso de que el objeto módulo correspondiente no se
encuentre o no se haya adjuntado al estado del intérprete, retornará NULL.
int PyState_AddModule(PyObject *module, PyModuleDef *def)
Part of the Stable ABI since version 3.3. Adjunta el objeto del módulo pasado a la función al estado del intérprete.
Esto permite que se pueda acceder al objeto del módulo a través de PyState_FindModule().
Solo es efectivo en módulos creados con la inicialización monofásica.
Python llama a PyState_AddModule automáticamente después de importar un módulo, por lo que es
innecesario (pero inofensivo) llamarlo desde el código de inicialización del módulo. Solo se necesita una lla-
mada explícita si el propio código de inicio del módulo llama posteriormente PyState_FindModule. La
función está destinada principalmente a implementar mecanismos de importación alternativos (ya sea llamán-
dolo directamente o refiriéndose a su implementación para obtener detalles de las actualizaciones de estado
requeridas).
La persona que llama debe retener el GIL.
Retorna 0 en caso de éxito o -1 en caso de error.
Nuevo en la versión 3.3.
int PyState_RemoveModule(PyModuleDef *def)
Part of the Stable ABI since version 3.3. Elimina el objeto del módulo creado a partir de def del estado del
intérprete. Retorna 0 en caso de éxito o -1 en caso de error.
La persona que llama debe retener el GIL.
Nuevo en la versión 3.3.

164 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

8.6.3 Objetos iteradores

Python proporciona dos objetos iteradores de propósito general. El primero, un iterador de secuencia, funciona con
una secuencia arbitraria que admite el método __getitem__(). El segundo funciona con un objeto invocable y un
valor centinela, llamando al invocable para cada elemento de la secuencia y finalizando la iteración cuando se retorna
el valor centinela.
PyTypeObject PySeqIter_Type
Part of the Stable ABI. Objeto tipo para objetos iteradores retornados por PySeqIter_New() y la forma
de un argumento de la función incorporada iter() para los tipos de secuencia incorporados.
int PySeqIter_Check(op)
Retorna verdadero si el tipo de op es PySeqIter_Type. Esta función siempre finaliza con éxito.
PyObject *PySeqIter_New(PyObject *seq)
Return value: New reference. Part of the Stable ABI. Retorna un iterador que funciona con un objeto de se-
cuencia general, seq. La iteración termina cuando la secuencia lanza IndexError para la operación de
suscripción.
PyTypeObject PyCallIter_Type
Part of the Stable ABI. Objeto tipo para los objetos iteradores retornados por PyCallIter_New() y la
forma de dos argumentos de la función incorporada iter().
int PyCallIter_Check(op)
Retorna verdadero si el tipo de op es PyCallIter_Type. Esta función siempre finaliza con éxito.
PyObject *PyCallIter_New(PyObject *callable, PyObject *sentinel)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo iterador. El primer parámetro, callable,
puede ser cualquier objeto invocable de Python que se pueda invocar sin parámetros; cada llamada debe retornar
el siguiente elemento en la iteración. Cuando callable retorna un valor igual a sentinel, la iteración finalizará.

8.6.4 Objetos descriptores

Los «descriptores» son objetos que describen algún atributo de un objeto. Se encuentran en el diccionario de objetos
tipo.
PyTypeObject PyProperty_Type
Part of the Stable ABI. El objeto de tipo para los tipos de descriptor incorporado.
PyObject *PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
Return value: New reference. Part of the Stable ABI.
PyObject *PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
Return value: New reference. Part of the Stable ABI.
PyObject *PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
Return value: New reference. Part of the Stable ABI.
PyObject *PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
Return value: New reference.
PyObject *PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
Return value: New reference. Part of the Stable ABI.
int PyDescr_IsData(PyObject *descr)
Retorna distinto de cero si el descriptor objetos descr describe un atributo de datos, o 0 si describe un método.
descr debe ser un objeto descriptor; no hay comprobación de errores.
PyObject *PyWrapper_New(PyObject*, PyObject*)
Return value: New reference. Part of the Stable ABI.

8.6. Otros objetos 165

The Python/C API, Versión 3.11.0

8.6.5 Objeto rebanada (slice)

PyTypeObject PySlice_Type
Part of the Stable ABI. El objeto tipo para objetos rebanadas. Esto es lo mismo que slice en la capa de
Python.
int PySlice_Check(PyObject *ob)
Retorna verdadero si ob es un objeto rebanada; ob no debe ser NULL. Esta función siempre finaliza con éxito.
PyObject *PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
Return value: New reference. Part of the Stable ABI. Retorna un nuevo objeto rebanada con los valores da-
dos. Los parámetros start, stop y step se utilizan como los valores de los atributos del objeto rebanada de los
mismos nombres. Cualquiera de los valores puede ser NULL, en cuyo caso se usará None para el atributo
correspondiente. Retorna NULL si no se puedo asignar el nuevo objeto.
int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t
*step)
Part of the Stable ABI. Recupera los índices start, stop y step del objeto rebanada slice, suponiendo una secuencia
de longitud length. Trata los índices mayores que length como errores.
Retorna 0 en caso de éxito y -1 en caso de error sin excepción establecida (a menos que uno de los índices no
sea None y no se haya convertido a un entero, en cuyo caso“- 1“ se retorna con una excepción establecida).
Probablemente no quiera usar esta función.
Distinto en la versión 3.2: El tipo de parámetro para el parámetro slice era PySliceObject* antes.
int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t
*step, Py_ssize_t *slicelength)
Part of the Stable ABI. Reemplazo utilizable para PySlice_GetIndices(). Recupera los índices de start,
stop, y step del objeto rebanada slice asumiendo una secuencia de longitud length, y almacena la longitud de
la rebanada en slicelength. Los índices fuera de los límites se recortan de manera coherente con el manejo de
sectores normales.
Retorna 0 en caso de éxito y -1 en caso de error con excepción establecida.

Nota: Esta función se considera no segura para secuencias redimensionables. Su invocación debe ser reem-
plazada por una combinación de PySlice_Unpack() y PySlice_AdjustIndices() donde:

if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) <␣

,→0) {

// return error
}

es reemplazado por:

if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {

// return error
}
slicelength = PySlice_AdjustIndices(length, &start, &stop, step);

Distinto en la versión 3.2: El tipo de parámetro para el parámetro slice era PySliceObject* antes.
Distinto en la versión 3.6.1: Si Py_LIMITED_API no se establece o establece el valor entre 0x03050400 y
0x03060000 (sin incluir) o 0x03060100 o un superior PySlice_GetIndicesEx() se implementa
como un macro usando PySlice_Unpack() y PySlice_AdjustIndices(). Los argumentos start,
stop y step se evalúan más de una vez.
Obsoleto desde la versión 3.6.1: Si Py_LIMITED_API se establece en un valor menor que 0x03050400 o
entre 0x03060000 y 0x03060100 (sin incluir) PySlice_GetIndicesEx() es una función obsoleta.

166 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)

Part of the Stable ABI since version 3.7. Extrae los miembros de datos start, stop, y step de un obje-
to rebanada como enteros en C. Reduce silenciosamente los valores mayores que PY_SSIZE_T_MAX a
PY_SSIZE_T_MAX, aumenta silenciosamente los valores start y stop inferiores a PY_SSIZE_T_MIN
a PY_SSIZE_T_MIN, y silenciosamente aumenta los valores de step a menos de -PY_SSE `` a
``-PY_SSIZE_T_MAX.
Retorna -1 en caso de error, 0 en caso de éxito.
Nuevo en la versión 3.6.1.
Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)
Part of the Stable ABI since version 3.7. Ajusta los índices de corte de inicio/fin asumiendo una secuencia de
la longitud especificada. Los índices fuera de los límites se recortan de manera coherente con el manejo de
sectores normales.
Retorna la longitud de la rebanada. Siempre exitoso. No llama al código de Python.
Nuevo en la versión 3.6.1.

8.6.6 Objeto Elipsis

PyObject *Py_Ellipsis
El objeto Elipsis de Python. Este objeto no tiene métodos. Debe tratarse como cualquier otro objeto con
respecto a los recuentos de referencia. Como Py_None es un objeto singleton.

8.6.7 Objetos de vista de memoria (MemoryView )

Un objeto memoryview expone la interfaz de búfer a nivel de C como un objeto Python que luego puede pasarse
como cualquier otro objeto.
PyObject *PyMemoryView_FromObject(PyObject *obj)
Return value: New reference. Part of the Stable ABI. Crea un objeto de vista de memoria memoryview a partir
de un objeto que proporciona la interfaz del búfer. Si obj admite exportaciones de búfer de escritura, el objeto
de vista de memoria será de lectura/escritura, de lo contrario puede ser de solo lectura o de lectura/escritura a
discreción del exportador.
PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
Return value: New reference. Part of the Stable ABI since version 3.7. Crea un objeto de vista de memoria
usando mem como el búfer subyacente. flags pueden ser uno de PyBUF_READ o PyBUF_WRITE.
Nuevo en la versión 3.3.
PyObject *PyMemoryView_FromBuffer(const Py_buffer *view)
Return value: New reference. Part of the Stable ABI since version 3.11. Crea un objeto de vista de
memoria que ajuste la estructura de búfer dada view. Para memorias intermedias de bytes simples,
PyMemoryView_FromMemory() es la función preferida.
PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
Return value: New reference. Part of the Stable ABI. Crea un objeto de vista de memoria memoryview para
un fragmento de memoria contiguo (contiguous, en order “C” o “F” de Fortran) desde un objeto que define la
interfaz del búfer. Si la memoria es contigua, el objeto de vista de memoria apunta a la memoria original. De
lo contrario, se realiza una copia y la vista de memoria apunta a un nuevo objeto de bytes.
int PyMemoryView_Check(PyObject *obj)
Retorna verdadero si el objeto obj es un objeto de vista de memoria. Actualmente no está permitido crear
subclases de memoryview. Esta función siempre finaliza con éxito.

8.6. Otros objetos 167

The Python/C API, Versión 3.11.0

Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)

Retorna un puntero a la copia privada de la vista de memoria del búfer del exportador. mview debe ser una
instancia de memoryview; este macro no verifica su tipo, debe hacerlo usted mismo o correrá el riesgo de fallas.
PyObject *PyMemoryView_GET_BASE(PyObject *mview)
Retorna un puntero al objeto de exportación en el que se basa la vista de memoria o NULL si
la vista de memoria ha sido creada por una de las funciones PyMemoryView_FromMemory() o
PyMemoryView_FromBuffer(). mview debe ser una instancia de memoryview.

8.6.8 Objetos de referencia débil

Python soporta referencias débiles como objetos de primera clase. Hay dos tipos de objetos específicos que imple-
mentan directamente referencias débiles. El primero es un objeto con referencia simple, y el segundo actúa como un
proxy del objeto original tanto como pueda.
int PyWeakref_Check(ob)
Retorna verdadero (true) si ob es una referencia o un objeto proxy. Esta función siempre finaliza con éxito.
int PyWeakref_CheckRef(ob)
Retorna verdadero (true) si ob es un objeto de referencia. Esta función siempre finaliza con éxito.
int PyWeakref_CheckProxy(ob)
Retorna verdadero (true) si ob es un objeto proxy. Esta función siempre finaliza con éxito.
PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)
Return value: New reference. Part of the Stable ABI. Return a weak reference object for the object ob. This
will always return a new reference, but is not guaranteed to create a new object; an existing reference object
may be returned. The second parameter, callback, can be a callable object that receives notification when ob is
garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback
may also be None or NULL. If ob is not a weakly referencable object, or if callback is not callable, None, or
NULL, this will return NULL and raise TypeError.
PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
Return value: New reference. Part of the Stable ABI. Return a weak reference proxy object for the object ob.
This will always return a new reference, but is not guaranteed to create a new object; an existing proxy object
may be returned. The second parameter, callback, can be a callable object that receives notification when ob is
garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback
may also be None or NULL. If ob is not a weakly referencable object, or if callback is not callable, None, or
NULL, this will return NULL and raise TypeError.
PyObject *PyWeakref_GetObject(PyObject *ref)
Return value: Borrowed reference. Part of the Stable ABI. Retorna el objeto referenciado desde una referencia
débil, ref. Si el referente no está vivo, retornará Py_None.

Nota: Esta función retorna una referencia borrowed reference al objeto referenciado. Esto significa que siempre
debe llamar a Py_INCREF() sobre el objeto, excepto cuando no pueda ser destruido antes del último uso de
la referencia prestada.

PyObject *PyWeakref_GET_OBJECT(PyObject *ref)

Return value: Borrowed reference. Similar to PyWeakref_GetObject(), but does no error checking.

168 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

8.6.9 Cápsulas

Consulta using-capsules para obtener más información sobre el uso de estos objetos.
Nuevo en la versión 3.1.
type PyCapsule
Este subtipo de PyObject representa un valor opaco, útil para los módulos de extensión C que necesitan
pasar un valor opaco (como un puntero void*) a través del código Python a otro código C . A menudo se usa
para hacer que un puntero de función C definido en un módulo esté disponible para otros módulos, por lo que
el mecanismo de importación regular se puede usar para acceder a las API C definidas en módulos cargados
dinámicamente.
type PyCapsule_Destructor
Part of the Stable ABI. El tipo de devolución de llamada de un destructor para una cápsula. Definido como:

typedef void (*PyCapsule_Destructor)(PyObject *);

Consulte PyCapsule_New() para conocer la semántica de las devoluciones de llamada de PyCapsu-

le_Destructor.
int PyCapsule_CheckExact(PyObject *p)
Retorna verdadero si su argumento es a PyCapsule. Esta función siempre finaliza con éxito.
PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Return value: New reference. Part of the Stable ABI. Crea un PyCapsule encapsulando el pointer. El argu-
mento pointer puede no ser NULL.
En caso de falla, establece una excepción y retorna NULL.
La cadena de caracteres name puede ser NULL o un puntero a una cadena C válida. Si no es NULL, esta cadena
de caracteres debe sobrevivir a la cápsula. (Aunque está permitido liberarlo dentro del destructor).
Si el argumento destructor no es NULL, se llamará con la cápsula como argumento cuando se destruya.
Si esta cápsula se almacenará como un atributo de un módulo, el nombre name debe especificarse co-
mo modulename.attributename. Esto permitirá que otros módulos importen la cápsula usando
PyCapsule_Import().
void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
Part of the Stable ABI. Recupera el pointer almacenado en la cápsula. En caso de falla, establece una excepción
y retorna NULL.
El parámetro name debe compararse exactamente con el nombre almacenado en la cápsula. Si el nombre alma-
cenado en la cápsula es NULL, el name pasado también debe ser NULL. Python usa la función C strcmp()
para comparar nombres de cápsulas.
PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Part of the Stable ABI. Retorna el destructor actual almacenado en la cápsula. En caso de falla, establece una
excepción y retorna NULL.
Es legal que una cápsula tenga un destructor NULL. Esto hace que un código de retorno NULL sea algo ambiguo;
use PyCapsule_IsValid() o PyErr_Occurred() para desambiguar.
void *PyCapsule_GetContext(PyObject *capsule)
Part of the Stable ABI. Retorna el contexto actual almacenado en la cápsula. En caso de falla, establece una
excepción y retorna NULL.
Es legal que una cápsula tenga un contexto NULL. Esto hace que un código de retorno NULL sea algo ambiguo;
use PyCapsule_IsValid() o PyErr_Occurred() para desambiguar.
const char *PyCapsule_GetName(PyObject *capsule)
Part of the Stable ABI. Retorna el nombre actual almacenado en la cápsula. En caso de falla, establece una
excepción y retorna NULL.

8.6. Otros objetos 169

The Python/C API, Versión 3.11.0

Es legal que una cápsula tenga un nombre NULL. Esto hace que un código de retorno NULL sea algo ambiguo;
use PyCapsule_IsValid() o PyErr_Occurred() para desambiguar.
void *PyCapsule_Import(const char *name, int no_block)
Part of the Stable ABI. Importa un puntero a un objeto C desde un atributo cápsula en un módulo. El parámetro
name debe especificar el nombre completo del atributo, como en module.attribute. El nombre name
almacenado en la cápsula debe coincidir exactamente con esta cadena de caracteres.
Retorna el puntero pointer interno de la cápsula en caso de éxito. En caso de falla, establece una excepción y
retorna NULL.
Distinto en la versión 3.3: no_block ya no tiene efecto.
int PyCapsule_IsValid(PyObject *capsule, const char *name)
Part of the Stable ABI. Determina si capsule es o no una cápsula válida. Una cápsula válida no es NULL,
pasa PyCapsule_CheckExact(), tiene un puntero no NULL almacenado y su nombre interno coincide
con el parámetro name. (Consulte PyCapsule_GetPointer() para obtener información sobre cómo se
comparan los nombres de las cápsulas).
En otras palabras, si PyCapsule_IsValid() retorna un valor verdadero, las llamadas a cualquiera de las
funciones de acceso (cualquier función que comience con PyCapsule_Get()) tienen éxito.
Retorna un valor distinto de cero si el objeto es válido y coincide con el nombre pasado. Retorna 0 de lo
contrario. Esta función no fallará.
int PyCapsule_SetContext(PyObject *capsule, void *context)
Part of the Stable ABI. Establece el puntero de contexto dentro de capsule a context.
Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.
int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Part of the Stable ABI. Establece el destructor dentro de capsule en destructor.
Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.
int PyCapsule_SetName(PyObject *capsule, const char *name)
Part of the Stable ABI. Establece el nombre dentro de capsule a name. Si no es NULL, el nombre debe sobrevivir
a la cápsula. Si el name anterior almacenado en la cápsula no era NULL, no se intenta liberarlo.
Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.
int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Part of the Stable ABI. Establece el puntero vacío dentro de capsule a pointer. El puntero puede no ser NULL.
Retorna 0 en caso de éxito. Retorna distinto de cero y establece una excepción en caso de error.

8.6.10 Objetos Frame

type PyFrameObject
Part of the Limited API (as an opaque struct). La estructura C de los objetos utilizados para describir los objetos
del frame.
No hay miembros públicos en esta estructura.
Distinto en la versión 3.11: Los miembros de esta estructura se han eliminado de la API pública de C. Consulte
la entrada Novedades para más detalles.
Las funciones PyEval_GetFrame() y PyThreadState_GetFrame() pueden utilizarse para obtener un
objeto frame.
Véase también Reflexión.

170 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)

Obtiene el frame exterior siguiente.
Retorna una strong reference, o NULL si frame no tiene frame exterior.
Nuevo en la versión 3.9.
PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)
Obtiene el atributo f_builtins del frame.
Retorna una strong reference, o NULL si frame no tiene frame exterior.
Nuevo en la versión 3.11.
PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)
Part of the Stable ABI since version 3.10. Obtenga el código frame.
Retorna un strong reference.
El resultado (frame code) no puede ser NULL.
Nuevo en la versión 3.9.
PyObject *PyFrame_GetGenerator(PyFrameObject *frame)
Obtiene el generador, rutina o generador asíncrono al que pertenece este frame, o NULL si este frame no es
propiedad de un generador. No lanza una excepción, incluso si el valor de retorno es NULL.
Retorna un strong reference, o NULL.
Nuevo en la versión 3.11.
PyObject *PyFrame_GetGlobals(PyFrameObject *frame)
Obtiene el atributo f_globals del frame.
Retorna una strong reference, o NULL si frame no tiene frame exterior.
Nuevo en la versión 3.11.
int PyFrame_GetLasti(PyFrameObject *frame)
Obtiene el atributo f_lasti del frame.
Retorna -1 si frame.f_lasti es None.
Nuevo en la versión 3.11.
PyObject *PyFrame_GetLocals(PyFrameObject *frame)
Obtiene el atributo f_locals del frame (dict).
Retorna un strong reference.
Nuevo en la versión 3.11.
int PyFrame_GetLineNumber(PyFrameObject *frame)
Part of the Stable ABI since version 3.10. Retorna el número de línea en la que se está ejecutando el frame.

8.6.11 Objetos Generadores

Los objetos generadores son lo que Python usa para implementar iteradores generadores. Normalmente se
crean iterando sobre una función que produce valores, en lugar de llamar explícitamente PyGen_New() o
PyGen_NewWithQualName().
type PyGenObject
La estructura en C utilizada para los objetos generadores.
PyTypeObject PyGen_Type
El objeto tipo correspondiente a los objetos generadores.

8.6. Otros objetos 171

The Python/C API, Versión 3.11.0

int PyGen_Check(PyObject *ob)

Retorna verdadero si ob es un objeto generador; ob no debe ser NULL. Esta función siempre finaliza con éxito.
int PyGen_CheckExact(PyObject *ob)
Retorna verdadero si el tipo de ob es PyGen_Type; ob no debe ser NULL. Esta función siempre finaliza con
éxito.
PyObject *PyGen_New(PyFrameObject *frame)
Return value: New reference. Crea y retorna un nuevo objeto generador basado en el objeto frame. Una refe-
rencia a frame es robada por esta función. El argumento no debe ser NULL.
PyObject *PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
Return value: New reference. Crea y retorna un nuevo objeto generador basado en el objeto frame, con
__name__ y __qualname__ establecido en name y qualname. Una referencia a frame es robada por
esta función. El argumento frame no debe ser NULL.

8.6.12 Objetos corrutina

Nuevo en la versión 3.5.

Los objetos de corrutina son las funciones declaradas con un retorno de palabra clave async.
type PyCoroObject
La estructura en C utilizada para objeto corrutina.
PyTypeObject PyCoro_Type
El tipo de objeto correspondiente a los objetos corrutina.
int PyCoro_CheckExact(PyObject *ob)
Retorna verdadero si el tipo de ob es PyCoro_Type; ob no debe ser NULL. Esta función siempre finaliza con
éxito.
PyObject *PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
Return value: New reference. Crea y retorna un nuevo objeto corrutina basado en el objeto frame, con
__name__ y __qualname__ establecido en name y qualname. Una referencia a frame es robada por
esta función. El argumento frame no debe ser NULL.

8.6.13 Objetos de variables de contexto

Distinto en la versión 3.7.1:

Nota: En Python 3.7.1, las firmas de todas las variables de contexto C APIs fueron cambiadas para usar punteros
PyObject en lugar de PyContext, PyContextVar, y PyContextToken, por ejemplo:

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

Ver bpo-34762 para más detalles.

Nuevo en la versión 3.7.

Esta sección detalla la API pública de C para el módulo contextvars.
type PyContext
La estructura C utilizada para representar un objeto contextvars.Context.

172 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

type PyContextVar
La estructura C utilizada para representar un objeto contextvars.ContextVar.
type PyContextToken
La estructura C solía representar un objeto contextvars.Token.
PyTypeObject PyContext_Type
El objeto de tipo que representa el tipo context.
PyTypeObject PyContextVar_Type
El objeto tipo que representa el tipo variable de contexto.
PyTypeObject PyContextToken_Type
El tipo objeto que representa el tipo token de variable de contexto.
Macros de verificación de tipo:
int PyContext_CheckExact(PyObject *o)
Retorna verdadero si o es de tipo PyContext_Type. o no debe ser NULL. Esta función siempre finaliza con
éxito.
int PyContextVar_CheckExact(PyObject *o)
Retorna verdadero si o es de tipo PyContextVar_Type. o no debe ser NULL. Esta función siempre finaliza
con éxito.
int PyContextToken_CheckExact(PyObject *o)
Retorna verdadero si o es de tipo PyContextToken_Type. o no debe ser NULL. Esta función siempre
finaliza con éxito.
Funciones de gestión de objetos de contexto:
PyObject *PyContext_New(void)
Return value: New reference. Crea un nuevo objeto de contexto vacío. Retorna NULL si se ha producido un
error.
PyObject *PyContext_Copy(PyObject *ctx)
Return value: New reference. Crea una copia superficial del objeto de contexto ctx pasado. Retorna NULL si se
ha producido un error.
PyObject *PyContext_CopyCurrent(void)
Return value: New reference. Crea una copia superficial del contexto actual del hilo. Retorna NULL si se ha
producido un error.
int PyContext_Enter(PyObject *ctx)
Establece ctx como el contexto actual para el hilo actual. Retorna 0 en caso de éxito y -1 en caso de error.
int PyContext_Exit(PyObject *ctx)
Desactiva el contexto ctx y restaura el contexto anterior como el contexto actual para el hilo actual. Retorna 0
en caso de éxito y -1 en caso de error.
Funciones variables de contexto:
PyObject *PyContextVar_New(const char *name, PyObject *def)
Return value: New reference. Crea un nuevo objeto ContextVar. El parámetro name se usa para propósitos
de introspección y depuración. El parámetro def especifica el valor predeterminado para la variable de contexto,
o NULL para no especificar un valor predeterminado. Si se ha producido un error, esta función retorna NULL.
int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)
Obtiene el valor de una variable de contexto. Retorna -1 si se produjo un error durante la búsqueda y 0 si no
se produjo ningún error, se haya encontrado o no un valor.
Si se encontró la variable de contexto, value será un puntero a ella. Si la variable de contexto not se encontró,
value apuntará a:

8.6. Otros objetos 173

The Python/C API, Versión 3.11.0

• default_value, si no es NULL;
• el valor predeterminado de var, si no es NULL;
• NULL
A excepción de NULL, la función retorna una nueva referencia.
PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
Return value: New reference. Establece el valor de var en value en el contexto actual. Retorna un nuevo objeto
token para este cambio, o NULL si se ha producido un error.
int PyContextVar_Reset(PyObject *var, PyObject *token)
Restablece el estado de la variable de contexto var a la que estaba antes PyContextVar_Set() que retornó
el token fue llamado. Esta función retorna 0 en caso de éxito y -1 en caso de error.

8.6.14 Objetos DateTime

El módulo datetime proporciona varios objetos de fecha y hora. Antes de usar cualquiera de estas funciones, el
archivo de encabezado datetime.h debe estar incluido en su fuente (tenga en cuenta que esto no está incluido en el
archivo Python.h), y la macro PyDateTime_IMPORT debe llamarse, generalmente como parte de la función de
inicialización del módulo. La macro coloca un puntero a una estructura C en una variable estática, PyDateTimeAPI,
que utilizan las siguientes macros.
Macro para acceder al singleton UTC:
PyObject *PyDateTime_TimeZone_UTC
Retorna la zona horaria singleton que representa UTC, el mismo objeto que datetime.timezone.utc.
Nuevo en la versión 3.7.
Macros de verificación de tipo:
int PyDate_Check(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_DateType o un subtipo de PyDateTime_DateType.
ob no debe ser NULL. Esta función siempre finaliza con éxito.
int PyDate_CheckExact(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_DateType. ob no debe ser NULL. Esta función siempre
finaliza con éxito.
int PyDateTime_Check(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_DateTimeType o un subtipo de
PyDateTime_DateTimeType. ob no debe ser NULL. Esta función siempre finaliza con éxito.
int PyDateTime_CheckExact(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_DateTimeType. ob no debe ser NULL. Esta función
siempre finaliza con éxito.
int PyTime_Check(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_TimeType o un subtipo de PyDateTime_TimeType.
ob no debe ser NULL. Esta función siempre finaliza con éxito.
int PyTime_CheckExact(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_TimeType. ob no debe ser NULL. Esta función siempre
finaliza con éxito.
int PyDelta_Check(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_DeltaType o un subtipo de
PyDateTime_DeltaType. ob no debe ser NULL. Esta función siempre finaliza con éxito.

174 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyDelta_CheckExact(PyObject *ob)

Retorna verdadero si ob es de tipo PyDateTime_DeltaType. ob no debe ser NULL. Esta función siempre
finaliza con éxito.
int PyTZInfo_Check(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_TZInfoType o un subtipo de
PyDateTime_TZInfoType. ob no debe ser NULL. Esta función siempre finaliza con éxito.
int PyTZInfo_CheckExact(PyObject *ob)
Retorna verdadero si ob es de tipo PyDateTime_TZInfoType. ob no debe ser NULL. Esta función siempre
finaliza con éxito.
Macros para crear objetos:
PyObject *PyDate_FromDate(int year, int month, int day)
Return value: New reference. Retorna un objeto datetime.date con el año, mes y día especificados.
PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int
usecond)
Return value: New reference. Retorna un objeto datetime.datetime con el año, mes, día, hora, minuto,
segundo y micro segundo especificados.
PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int
second, int usecond, int fold)
Return value: New reference. Retorna un objeto datetime.datetime con el año, mes, día, hora, minuto,
segundo, micro segundo y doblez especificados.
Nuevo en la versión 3.6.
PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)
Return value: New reference. Retorna un objeto datetime.time con la hora, minuto, segundo y micro
segundo especificados.
PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
Return value: New reference. Retorna un objeto datetime.time con la hora, minuto, segundo, micro se-
gundo y doblez especificados.
Nuevo en la versión 3.6.
PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)
Return value: New reference. Retorna un objeto datetime.timedelta que representa el número dado
de días, segundos y micro segundos. La normalización se realiza de modo que el número resultante de micro
segundos y segundos se encuentre en los rangos documentados para los objetos datetime.timedelta.
PyObject *PyTimeZone_FromOffset(PyDateTime_DeltaType *offset)
Return value: New reference. Retorna un objeto datetime.timezone con un desplazamiento fijo sin nom-
bre representado por el argumento offset.
Nuevo en la versión 3.7.
PyObject *PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType *offset, PyUnicode *name)
Return value: New reference. Retorna un objeto datetime.timezone con un desplazamiento fijo repre-
sentado por el argumento offset y con tzname name.
Nuevo en la versión 3.7.
Macros para extraer campos de objetos de fecha. El argumento debe ser una instancia de PyDateTime_Date, in-
cluidas las subclases (como PyDateTime_DateTime). El argumento no debe ser NULL y el tipo no está marcado:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)

Regrese el año, como un int positivo.

8.6. Otros objetos 175

The Python/C API, Versión 3.11.0

int PyDateTime_GET_MONTH(PyDateTime_Date *o)

Regresa el mes, como int del 1 al 12.
int PyDateTime_GET_DAY(PyDateTime_Date *o)
Retorna el día, como int del 1 al 31.
Macros para extraer campos de objetos de fecha y hora. El argumento debe ser una instancia de
PyDateTime_DateTime, incluidas las subclases. El argumento no debe ser NULL y el tipo no es comproba-
do:
int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
Retorna la hora, como un int de 0 hasta 23.
int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
Retorna el minuto, como un int de 0 hasta 59.
int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
Retorna el segundo, como un int de 0 hasta 59.
int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
Retorna el micro segundo, como un int de 0 hasta 999999.
int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)
Return the fold, as an int from 0 through 1.
Nuevo en la versión 3.6.
PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)
Retorna el tzinfo (que puede ser None).
Nuevo en la versión 3.10.
Macros para extraer campos de objetos de tiempo. El argumento debe ser una instancia de PyDateTime_Time,
incluidas las subclases. El argumento no debe ser NULL y el tipo no está marcado:
int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
Retorna la hora, como un int de 0 hasta 23.
int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
Retorna el minuto, como un int de 0 hasta 59.
int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
Retorna el segundo, como un int de 0 hasta 59.
int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
Retorna el micro segundo, como un int de 0 hasta 999999.
int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)
Return the fold, as an int from 0 through 1.
Nuevo en la versión 3.6.
PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)
Retorna el tzinfo (que puede ser None).
Nuevo en la versión 3.10.
Macros para extraer campos de objetos delta de tiempo. El argumento debe ser una instancia de
PyDateTime_Delta, incluidas las subclases. El argumento no debe ser NULL y el tipo no está marcado:
int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
Retorna el número de días, como un int desde -999999999 a 999999999.
Nuevo en la versión 3.3.

176 Capítulo 8. Capa de objetos concretos

 The Python/C API, Versión 3.11.0

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)

Retorna el número de segundos, como un int de 0 a 86399.
Nuevo en la versión 3.3.
int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
Retorna el número de micro segundos, como un int de 0 a 999999.
Nuevo en la versión 3.3.
Macros para la conveniencia de módulos que implementan la API DB:
PyObject *PyDateTime_FromTimestamp(PyObject *args)
Return value: New reference. Crea y retorna un nuevo objeto datetime.datetime dado una tupla de
argumentos adecuada para pasar a datetime.datetime.fromtimestamp().
PyObject *PyDate_FromTimestamp(PyObject *args)
Return value: New reference. Crea y retorna un nuevo objeto datetime.date dado una tupla de argumentos
adecuada para pasar a datetime.date.fromtimestamp().

8.6.15 Objetos para indicaciones de tipado

Se proporcionan varios tipos incorporados para indicaciones de tipado. Actualmente existen dos tipos – GenericAlias
y Union. Solo GenericAlias es expuesto a C.
PyObject *Py_GenericAlias(PyObject *origin, PyObject *args)
Part of the Stable ABI since version 3.9. Create a GenericAlias object. Equivalent to calling the Python
class types.GenericAlias. The origin and args arguments set the GenericAlias“s __origin__
and __args__ attributes respectively. origin should be a PyTypeObject*, and args can be a
PyTupleObject* or any PyObject*. If args passed is not a tuple, a 1-tuple is automatically constructed
and __args__ is set to (args,). Minimal checking is done for the arguments, so the function will succeed
even if origin is not a type. The GenericAlias“s __parameters__ attribute is constructed lazily from
__args__. On failure, an exception is raised and NULL is returned.
Aquí hay un ejemplo sobre cómo hacer un tipo de extensión genérica:

...
static PyMethodDef my_obj_methods[] = {
// Other methods.
...
{"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
...
}

Ver también:
El método del modelo de datos __class_getitem__().
Nuevo en la versión 3.9.
PyTypeObject Py_GenericAliasType
Part of the Stable ABI since version 3.9. El tipo en C del objeto retornado por Py_GenericAlias().
Equivalente a types.GenericAlias en Python.
Nuevo en la versión 3.9.

8.6. Otros objetos 177

The Python/C API, Versión 3.11.0

178 Capítulo 8. Capa de objetos concretos

 CAPÍTULO 9

Inicialización, Finalización e Hilos

Consulte también Configuración de inicialización de Python.

9.1 Antes de la inicialización de Python

En una aplicación que incorpora Python, se debe llamar a la función Py_Initialize() antes de usar cualquier
otra función de API Python/C; con la excepción de algunas funciones y variables de configuración global.
Las siguientes funciones se pueden invocar de forma segura antes de que se inicializa Python:
• Funciones de configuración:
– PyImport_AppendInittab()
– PyImport_ExtendInittab()
– PyInitFrozenExtensions()
– PyMem_SetAllocator()
– PyMem_SetupDebugHooks()
– PyObject_SetArenaAllocator()
– Py_SetPath()
– Py_SetProgramName()
– Py_SetPythonHome()
– Py_SetStandardStreamEncoding()
– PySys_AddWarnOption()
– PySys_AddXOption()
– PySys_ResetWarnOptions()
• Funciones informativas:
– Py_IsInitialized()
– PyMem_GetAllocator()
– PyObject_GetArenaAllocator()

179
The Python/C API, Versión 3.11.0

– Py_GetBuildInfo()
– Py_GetCompiler()
– Py_GetCopyright()
– Py_GetPlatform()
– Py_GetVersion()
• Utilidades:
– Py_DecodeLocale()
• Asignadores de memoria:
– PyMem_RawMalloc()
– PyMem_RawRealloc()
– PyMem_RawCalloc()
– PyMem_RawFree()

Nota: Las siguientes funciones no deben llamarse antes de Py_Initialize(): Py_EncodeLocale(),

Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix(), Py_GetProgramFullPath(),
Py_GetPythonHome(), Py_GetProgramName() y PyEval_InitThreads().

9.2 Variables de configuración global

Python tiene variables para la configuración global para controlar diferentes características y opciones. De forma
predeterminada, estos indicadores están controlados por opciones de línea de comando.
Cuando una opción establece un indicador, el valor del indicador es la cantidad de veces que se configuró la opción.
Por ejemplo, -b establece Py_BytesWarningFlag en 1 y -bb establece Py_BytesWarningFlag en 2.
int Py_BytesWarningFlag
Emite una advertencia al comparar bytes o bytearray con str o bytes con int. Emite un error si es
mayor o igual a 2.
Establecido por la opción -b.
int Py_DebugFlag
Activa la salida de depuración del analizador (solo para expertos, según las opciones de compilación).
Establecido por la opción -d y la variable de entorno PYTHONDEBUG.
int Py_DontWriteBytecodeFlag
Si se establece en un valor distinto de cero, Python no intentará escribir archivos .pyc en la importación de
módulos fuente.
Establecido por la opción -B y la variable de entorno PYTHONDONTWRITEBYTECODE.
int Py_FrozenFlag
Suprime los mensajes de error al calcular la ruta de búsqueda del módulo en Py_GetPath().
Private flag used by _freeze_module and frozenmain programs.
int Py_HashRandomizationFlag
Se establece en 1 si la variable de entorno PYTHONHASHSEED se establece en una cadena de caracteres no
vacía.
Si el indicador no es cero, lee la variable de entorno PYTHONHASHSEED para inicializar la semilla de hash
secreta.

180 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

int Py_IgnoreEnvironmentFlag
Ignorar todas las variables de entorno PYTHON*, por ejemplo PYTHONPATH y PYTHONHOME, eso podría
establecerse.
Establecido por las opciones -E y -I.
int Py_InspectFlag
Cuando se pasa una secuencia de comandos (script) como primer argumento o se usa la opción -c, ingresa al
modo interactivo después de ejecutar la secuencia de comandos o el comando, incluso cuando sys.stdin
no parece ser un terminal.
Establecido por la opción -i y la variable de entorno PYTHONINSPECT.
int Py_InteractiveFlag
Establecido por la opción -i.
int Py_IsolatedFlag
Ejecuta Python en modo aislado. En modo aislado sys.path no contiene ni el directorio de la secuencia de
comandos (script) ni el directorio de paquetes del sitio del usuario (site-pacages).
Establecido por la opción -I.
Nuevo en la versión 3.4.
int Py_LegacyWindowsFSEncodingFlag
Si la bandera no es cero, utilice la codificación mbcs con el gestor de errores replace en lugar de la co-
dificación UTF-8 con el gestor de error surrogatepass, para la filesystem encoding and error handler
(codificación del sistema de archivos y gestor de errores).
Establece en 1 si la variable de entorno PYTHONLEGACYWINDOWSFSENCODING está configurada en una
cadena de caracteres no vacía.
Ver PEP 529 para más detalles.
Disponibilidad: Windows.
int Py_LegacyWindowsStdioFlag
Si el indicador no es cero, use io.FileIO en lugar de WindowsConsoleIO para secuencias estándar
sys.
Establece en 1 si la variable de entorno PYTHONLEGACYWINDOWSSTDIO está configurada en una cadena
de caracteres no vacía.
Ver PEP 528 para más detalles.
Disponibilidad: Windows.
int Py_NoSiteFlag
Deshabilita la importación del módulo site y las manipulaciones dependientes del sitio de sys.path que
conlleva. También deshabilita estas manipulaciones si site se importa explícitamente más tarde (llama a
site.main() si desea que se activen).
Establecido por la opción -S.
int Py_NoUserSiteDirectory
No agregue el directorio de paquetes de sitio del usuario (site-packages) a sys.
path.
Establecido por las opciones -s y -I, y la variable de entorno PYTHONNOUSERSITE.
int Py_OptimizeFlag
Establecido por la opción -O y la variable de entorno PYTHONOPTIMIZE.

9.2. Variables de configuración global 181

The Python/C API, Versión 3.11.0

int Py_QuietFlag
No muestre los mensajes de copyright y de versión incluso en modo interactivo.
Establecido por la opción -q.
Nuevo en la versión 3.2.
int Py_UnbufferedStdioFlag
Obliga a las secuencias stdout y stderr a que no tengan búfer.
Establecido por la opción -u y la variable de entorno PYTHONUNBUFFERED.
int Py_VerboseFlag
Imprime un mensaje cada vez que se inicializa un módulo, mostrando el lugar (nombre de archivo o módulo
incorporado) desde el que se carga. Si es mayor o igual a 2, imprime un mensaje para cada archivo que se
verifica al buscar un módulo. También proporciona información sobre la limpieza del módulo a la salida.
Establecido por la opción -v y la variable de entorno PYTHONVERBOSE.

9.3 Inicializando y finalizando el intérprete

void Py_Initialize()
Part of the Stable ABI. Inicializa el intérprete de Python. En una aplicación que incorpora Python, se debe
llamar antes de usar cualquier otra función de API Python/C; vea Antes de la inicialización de Python para ver
algunas excepciones.
Esto inicializa la tabla de módulos cargados (sys.modules) y crea los módulos fundamentales builtins,
__main__ y sys. También inicializa la ruta de búsqueda del módulo (sys.path). No establece sys.
argv; use PySys_SetArgvEx() para eso. Este es un no-op cuando se llama por segunda vez (sin llamar
primero a Py_FinalizeEx()). No hay valor de retorno; es un error fatal si falla la inicialización.

Nota: En Windows, cambia el modo de consola de O_TEXT a O_BINARY, lo que también afectará los usos
de la consola que no sean de Python utilizando C Runtime.

void Py_InitializeEx(int initsigs)

Part of the Stable ABI. Esta función funciona como Py_Initialize() si initsigs es 1. Si initsigs es 0, omite
el registro de inicialización de los manejadores de señal, lo que podría ser útil cuando Python está incrustado.
int Py_IsInitialized()
Part of the Stable ABI. Retorna verdadero (distinto de cero) cuando el intérprete de Python se ha inicia-
lizado, falso (cero) si no. Después de que se llama a Py_FinalizeEx(), esto retorna falso hasta que
Py_Initialize() se llama de nuevo.
int Py_FinalizeEx()
Part of the Stable ABI since version 3.6. Deshace todas las inicializaciones realizadas por
Py_Initialize() y el uso posterior de las funciones de Python/C API, y destruye todos los sub-
intérpretes (ver Py_NewInterpreter() a continuación) que se crearon y aún no se destruyeron desde el
última llamada a Py_Initialize(). Idealmente, esto libera toda la memoria asignada por el intérprete de
Python. Este es un no-op cuando se llama por segunda vez (sin llamar a Py_Initialize() nuevamente
primero). Normalmente el valor de retorno es 0. Si hubo errores durante la finalización (lavado de datos
almacenados en el búfer), se retorna -1.
Esta función se proporciona por varias razones. Una aplicación de incrustación puede querer reiniciar Python
sin tener que reiniciar la aplicación misma. Una aplicación que ha cargado el intérprete de Python desde una
biblioteca cargable dinámicamente (o DLL) puede querer liberar toda la memoria asignada por Python antes
de descargar la DLL. Durante una búsqueda de pérdidas de memoria en una aplicación, un desarrollador puede
querer liberar toda la memoria asignada por Python antes de salir de la aplicación.

182 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

Errores y advertencias: La destrucción de módulos y objetos en módulos se realiza en orden aleatorio; esto
puede causar que los destructores (métodos __del__()) fallen cuando dependen de otros objetos (incluso
funciones) o módulos. Los módulos de extensión cargados dinámicamente cargados por Python no se descargan.
Es posible que no se liberen pequeñas cantidades de memoria asignadas por el intérprete de Python (si encuentra
una fuga, informe por favor). La memoria atada en referencias circulares entre objetos no se libera. Es posible
que parte de la memoria asignada por los módulos de extensión no se libere. Algunas extensiones pueden no
funcionar correctamente si su rutina de inicialización se llama más de una vez; Esto puede suceder si una
aplicación llama a Py_Initialize() y Py_FinalizeEx() más de una vez.
Genera un evento de auditoría cpython._PySys_ClearAuditHooks sin argumentos.
Nuevo en la versión 3.6.
void Py_Finalize()
Part of the Stable ABI. Esta es una versión compatible con versiones anteriores de Py_FinalizeEx() que
ignora el valor de retorno.

9.4 Parámetros de todo el proceso

int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)

This API is kept for backward compatibility: setting PyConfig.stdio_encoding and PyConfig.
stdio_errors should be used instead, see Python Initialization Configuration.
Esta función debería llamarse antes de Py_Initialize(), si es que se llama. Especifica qué codificación
y manejo de errores usar con IO estándar, con los mismos significados que en str.encode().
Reemplaza los valores PYTHONIOENCODING, y permite incrustar código para controlar la codificación IO
cuando la variable de entorno no funciona.
codificación o errores pueden ser NULL para usar PYTHONIOENCODING o valores predeterminados (depen-
diendo de otras configuraciones).
Tenga en cuenta que sys.stderr siempre usa el controlador de error «backslashreplace», independiente-
mente de esta configuración (o cualquier otra).
Si se llama a Py_FinalizeEx(), será necesario volver a llamar a esta función para afectar las llamadas
posteriores a Py_Initialize().
Retorna 0 si tiene éxito, un valor distinto de cero en caso de error (por ejemplo, llamar después de que el
intérprete ya se haya inicializado)
Nuevo en la versión 3.4.
Obsoleto desde la versión 3.11.
void Py_SetProgramName(const wchar_t *name)
Part of the Stable ABI. This API is kept for backward compatibility: setting PyConfig.program_name
should be used instead, see Python Initialization Configuration.
Esta función debería llamarse antes Py_Initialize() se llama por primera vez, si es que se llama. Le dice
al intérprete el valor del argumento argv[0] para la función main() del programa (convertido a caracteres
anchos). Esto es utilizado por Py_GetPath() y algunas otras funciones a continuación para encontrar las
bibliotecas de tiempo de ejecución de Python relativas al ejecutable del intérprete. El valor predeterminado
es 'python'. El argumento debe apuntar a una cadena de caracteres anchos terminada en cero en almace-
namiento estático cuyo contenido no cambiará mientras dure la ejecución del programa. Ningún código en el
intérprete de Python cambiará el contenido de este almacenamiento.
Use Py_DecodeLocale() to decode a bytes string to get a wchar_* string.
Obsoleto desde la versión 3.11.

9.4. Parámetros de todo el proceso 183

The Python/C API, Versión 3.11.0

wchar *Py_GetProgramName()
Part of the Stable ABI. Retorna el nombre del programa establecido con Py_SetProgramName(), o el
valor predeterminado. La cadena de caracteres retornada apunta al almacenamiento estático; la persona que
llama no debe modificar su valor.
Esta función ya no se puede llamar antes de Py_Initialize(), de otra forma retornará NULL.
Distinto en la versión 3.10: Todas las siguientes funciones deben llamarse después de Py_Initialize(),
de lo contrario retornará NULL.
wchar_t *Py_GetPrefix()
Part of the Stable ABI. Retorna el prefijo prefix para los archivos instalados independientes de la platafor-
ma. Esto se deriva a través de una serie de reglas complicadas del nombre del programa establecido con
Py_SetProgramName() y algunas variables de entorno; por ejemplo, si el nombre del programa es '/
usr/local/bin/python', el prefijo es '/usr/local'. La cadena de caracteres retornada apunta
al almacenamiento estático; la persona que llama no debe modificar su valor. Esto corresponde a la variable
prefix en el archivo de nivel superior Makefile y el argumento --prefix a la secuencia de coman-
dos (script) configure en tiempo de compilación. El valor está disponible para el código de Python como
sys.prefix. Solo es útil en Unix. Ver también la siguiente función.
Esta función ya no se puede llamar antes de Py_Initialize(), de otra forma retornará NULL.
Distinto en la versión 3.10: Todas las siguientes funciones deben llamarse después de Py_Initialize(),
de lo contrario retornará NULL.
wchar_t *Py_GetExecPrefix()
Part of the Stable ABI. Retorna el exec-prefix para los archivos instalados dependientes de la platafor-
ma. Esto se deriva a través de una serie de reglas complicadas del nombre del programa establecido con
Py_SetProgramName() y algunas variables de entorno; por ejemplo, si el nombre del programa es '/
usr/local/bin/python', el prefijo exec es '/usr/local'. La cadena de caracteres retornada apun-
ta al almacenamiento estático; la persona que llama no debe modificar su valor. Esto corresponde a la variable
exec_prefix en el archivo de nivel superior Makefile y el argumento --exec-prefix a la secuen-
cia de comandos (script) configure en tiempo de compilación. El valor está disponible para el código de
Python como sys.exec_prefix. Solo es útil en Unix.
Antecedentes: el prefijo exec difiere del prefijo cuando los archivos dependientes de la plataforma (como eje-
cutables y bibliotecas compartidas) se instalan en un árbol de directorios diferente. En una instalación típica,
los archivos dependientes de la plataforma pueden instalarse en el subárbol /usr/local/plat mientras
que la plataforma independiente puede instalarse en /usr/local.
En términos generales, una plataforma es una combinación de familias de hardware y software, por ejemplo,
las máquinas Sparc que ejecutan el sistema operativo Solaris 2.x se consideran la misma plataforma, pero las
máquinas Intel que ejecutan Solaris 2.x son otra plataforma, y las máquinas Intel que ejecutan Linux son otra
plataforma más. Las diferentes revisiones importantes del mismo sistema operativo generalmente también for-
man plataformas diferentes. Los sistemas operativos que no son Unix son una historia diferente; Las estrategias
de instalación en esos sistemas son tan diferentes que el prefijo y el prefijo exec no tienen sentido y se configu-
ran en la cadena vacía. Tenga en cuenta que los archivos de bytecode compilados de Python son independientes
de la plataforma (¡pero no independientes de la versión de Python con la que fueron compilados!).
Los administradores de sistemas sabrán cómo configurar los programas mount o automount para compartir
/usr/local entre plataformas mientras que /usr/local/plat sea un sistema de archivos diferente
para cada plataforma.
Esta función ya no se puede llamar antes de Py_Initialize(), de otra forma retornará NULL.
Distinto en la versión 3.10: Todas las siguientes funciones deben llamarse después de Py_Initialize(),
de lo contrario retornará NULL.
wchar_t *Py_GetProgramFullPath()
Part of the Stable ABI. Retorna el nombre completo del programa del ejecutable de Python; esto se calcula co-
mo un efecto secundario de derivar la ruta de búsqueda predeterminada del módulo del nombre del programa
(establecido por Py_SetProgramName() arriba). La cadena de caracteres retornada apunta al almacena-

184 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

miento estático; la persona que llama no debe modificar su valor. El valor está disponible para el código de
Python como sys.executable.
Esta función ya no se puede llamar antes de Py_Initialize(), de otra forma retornará NULL.
Distinto en la versión 3.10: Todas las siguientes funciones deben llamarse después de Py_Initialize(),
de lo contrario retornará NULL.
wchar_t *Py_GetPath()
Part of the Stable ABI. Retorna la ruta de búsqueda del módulo predeterminado; esto se calcula a partir del
nombre del programa (establecido por Py_SetProgramName() antes mencionado) y algunas variables de
entorno. La cadena de caracteres retornada consiste en una serie de nombres de directorio separados por un
carácter delimitador dependiente de la plataforma. El carácter delimitador es ':' en Unix y macOS, ';'
en Windows. La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no
debe modificar su valor. La lista sys.path se inicializa con este valor en el inicio del intérprete; se puede (y
generalmente se realiza) modificar más adelante para cambiar la ruta de búsqueda para cargar módulos.
Esta función ya no se puede llamar antes de Py_Initialize(), de otra forma retornará NULL.
Distinto en la versión 3.10: Todas las siguientes funciones deben llamarse después de Py_Initialize(),
de lo contrario retornará NULL.
void Py_SetPath(const wchar_t*)
Part of the Stable ABI since version 3.7. This API is kept for backward compatibility: setting PyConfig.
module_search_paths and PyConfig.module_search_paths_set should be used instead, see
Python Initialization Configuration.
Establece la ruta de búsqueda del módulo predeterminado. Si se llama a esta función antes de
Py_Initialize(), entonces Py_GetPath() no intentará computar una ruta de búsqueda predetermi-
nada, sino que utilizará la proporcionada en su lugar. Esto es útil si Python está incrustado por una aplicación
que tiene pleno conocimiento de la ubicación de todos los módulos. Los componentes de la ruta deben estar
separados por el carácter delimitador dependiente de la plataforma, el cual es ':' en Unix y macOS, ';' en
Windows.
Esto también hace que sys.executable se configure en la ruta completa del programa (consulte
Py_GetProgramFullPath()) y para sys.prefix y sys.exec_prefix a estar vacío. Depende
de la persona que llama modificarlos si es necesario después de llamar Py_Initialize().
Use Py_DecodeLocale() to decode a bytes string to get a wchar_* string.
El argumento de ruta se copia internamente, por lo que la persona que llama puede liberarlo después de que se
complete la llamada.
Distinto en la versión 3.8: La ruta completa del programa ahora se usa para sys.executable, en lugar del
nombre del programa.
Obsoleto desde la versión 3.11.
const char *Py_GetVersion()
Part of the Stable ABI. Retorna la versión de este intérprete de Python. Esta es una cadena de caracteres que
se parece a

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

The first word (up to the first space character) is the current Python version; the first characters are the major
and minor version separated by a period. The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as sys.version.
See also the Py_Version constant.
const char *Py_GetPlatform()
Part of the Stable ABI. Retorna el identificador de plataforma para la plataforma actual. En Unix, esto se forma
a partir del nombre «oficial» del sistema operativo, convertido a minúsculas, seguido del número de revisión
principal; por ejemplo, para Solaris 2.x, que también se conoce como SunOS 5.x, el valor es 'sunos5'.
En macOS, es “ “darwin”. En Windows, es ``'win'. La cadena de caracteres retornada apunta al

9.4. Parámetros de todo el proceso 185

The Python/C API, Versión 3.11.0

almacenamiento estático; la persona que llama no debe modificar su valor. El valor está disponible para el
código de Python como sys.platform.
const char *Py_GetCopyright()
Part of the Stable ABI. Retorna la cadena de caracteres de copyright oficial para la versión actual de Python,
por ejemplo
'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'
La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar
su valor. El valor está disponible para el código de Python como sys.copyright.
const char *Py_GetCompiler()
Part of the Stable ABI. Retorna una indicación del compilador utilizado para construir la versión actual de
Python, entre corchetes, por ejemplo:

"[GCC 2.7.2.2]"

La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar
su valor. El valor está disponible para el código Python como parte de la variable sys.version.
const char *Py_GetBuildInfo()
Part of the Stable ABI. Retorna información sobre el número de secuencia y la fecha y hora de compilación de
la instancia actual de intérprete de Python, por ejemplo:

"#67, Aug 1 1997, 22:34:28"

La cadena de caracteres retornada apunta al almacenamiento estático; la persona que llama no debe modificar
su valor. El valor está disponible para el código Python como parte de la variable sys.version.
void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
Part of the Stable ABI. This API is kept for backward compatibility: setting PyConfig.argv, PyConfig.
parse_argv and PyConfig.safe_path should be used instead, see Python Initialization Configuration.
Establece sys.argv basado en argc y argv. Estos parámetros son similares a los pasados a la función del
programa main() con la diferencia de que la primera entrada debe referirse al archivo de la secuencia de
comandos (script) que se ejecutará en lugar del ejecutable que aloja el intérprete de Python. Si no se ejecuta
una secuencia de comandos (script), la primera entrada en argv puede ser una cadena de caracteres vacía. Si
esta función no puede inicializar sys.argv, una condición fatal se señala usando Py_FatalError().
Si updatepath es cero, esto es todo lo que hace la función. Si updatepath no es cero, la función también modifica
sys.path de acuerdo con el siguiente algoritmo:
• Si el nombre de una secuencia de comandos (script) existente se pasa en argv[0], la ruta absoluta del
directorio donde se encuentra el script se antepone a sys.path.
• De lo contrario (es decir, si argc es 0 o argv[0] no apunta a un nombre de archivo existente), una
cadena de caracteres vacía se antepone a sys.path, que es lo mismo que anteponer el directorio de
trabajo actual (".").
Use Py_DecodeLocale() to decode a bytes string to get a wchar_* string.
See also PyConfig.orig_argv and PyConfig.argv members of the Python Initialization Configura-
tion.

Nota: Se recomienda que las aplicaciones que incorporan el intérprete de Python para otros fines que no
sean ejecutar una sola secuencia de comandos (script) pasen 0 como updatepath y actualicen sys.path si lo
desean. Ver CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983> _.
En las versiones anteriores a 3.1.3, puede lograr el mismo efecto quitando manualmente el primer elemento
(popping) sys.path después de haber llamado PySys_SetArgv(), por ejemplo usando

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

186 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

Nuevo en la versión 3.1.3.

Obsoleto desde la versión 3.11.
void PySys_SetArgv(int argc, wchar_t **argv)
Part of the Stable ABI. This API is kept for backward compatibility: setting PyConfig.argv and
PyConfig.parse_argv should be used instead, see Python Initialization Configuration.
Esta función funciona como PySys_SetArgvEx() con updatepath establecido en 1 a menos que el intér-
prete python se haya iniciado con la opción -I.
Use Py_DecodeLocale() to decode a bytes string to get a wchar_* string.
See also PyConfig.orig_argv and PyConfig.argv members of the Python Initialization Configura-
tion.
Distinto en la versión 3.4: El valor updatepath depende de la opción -I.
Obsoleto desde la versión 3.11.
void Py_SetPythonHome(const wchar_t *home)
Part of the Stable ABI. This API is kept for backward compatibility: setting PyConfig.home should be
used instead, see Python Initialization Configuration.
Establece el directorio «inicio» («home») predeterminado, es decir, la ubicación de las bibliotecas estándar de
Python. Ver PYTHONHOME para el significado de la cadena de caracteres de argumento.
El argumento debe apuntar a una cadena de caracteres terminada en cero en el almacenamiento estático cuyo
contenido no cambiará mientras dure la ejecución del programa. Ningún código en el intérprete de Python
cambiará el contenido de este almacenamiento.
Use Py_DecodeLocale() to decode a bytes string to get a wchar_* string.
Obsoleto desde la versión 3.11.
w_char *Py_GetPythonHome()
Part of the Stable ABI. Retorna el «inicio» (home) predeterminado, es decir, el valor establecido por una
llamada anterior a Py_SetPythonHome(), o el valor de la variable de entorno PYTHONHOME si está
configurado.
Esta función ya no se puede llamar antes de Py_Initialize(), de otra forma retornará NULL.
Distinto en la versión 3.10: Todas las siguientes funciones deben llamarse después de Py_Initialize(),
de lo contrario retornará NULL.

9.5 Estado del hilo y el bloqueo global del intérprete

El intérprete de Python no es completamente seguro para hilos (thread-safe). Para admitir programas Python multi-
proceso, hay un bloqueo global, denominado global interpreter lock o GIL, que debe mantener el hilo actual antes de
que pueda acceder de forma segura a los objetos Python. Sin el bloqueo, incluso las operaciones más simples podrían
causar problemas en un programa de hilos múltiples: por ejemplo, cuando dos hilos incrementan simultáneamente el
conteo de referencias del mismo objeto, el conteo de referencias podría terminar incrementándose solo una vez en
lugar de dos veces.
Por lo tanto, existe la regla de que solo el hilo que ha adquirido GIL puede operar en objetos Python o llamar a fun-
ciones API Python/C. Para emular la concurrencia de ejecución, el intérprete regularmente intenta cambiar los hilos
(ver sys.setswitchinterval()). El bloqueo también se libera para bloquear potencialmente las operaciones
de E/S, como leer o escribir un archivo, para que otros hilos de Python puedan ejecutarse mientras tanto.
El intérprete de Python mantiene cierta información de contabilidad específica de hilos dentro de una estructura de
datos llamada PyThreadState. También hay una variable global que apunta a la actual PyThreadState: se
puede recuperar usando PyThreadState_Get().

9.5. Estado del hilo y el bloqueo global del intérprete 187

The Python/C API, Versión 3.11.0

9.5.1 Liberando el GIL del código de extensión

La mayoría del código de extensión que manipula el GIL tiene la siguiente estructura simple

Save the thread state in a local variable.

Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.

Esto es tan común que existen un par de macros para simplificarlo:

Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS

La macro Py_BEGIN_ALLOW_THREADS abre un nuevo bloque y declara una variable local oculta; la macro
Py_END_ALLOW_THREADS cierra el bloque.
El bloque anterior se expande al siguiente código:

PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);

Así es como funcionan estas funciones: el bloqueo global del intérprete se usa para proteger el puntero al estado actual
del hilo. Al liberar el bloqueo y guardar el estado del hilo, el puntero del estado del hilo actual debe recuperarse antes
de que se libere el bloqueo (ya que otro hilo podría adquirir inmediatamente el bloqueo y almacenar su propio estado
de hilo en la variable global). Por el contrario, al adquirir el bloqueo y restaurar el estado del hilo, el bloqueo debe
adquirirse antes de almacenar el puntero del estado del hilo.

Nota: Llamar a las funciones de E/S del sistema es el caso de uso más común para liberar el GIL, pero también
puede ser útil antes de llamar a cálculos de larga duración que no necesitan acceso a objetos de Python, como las
funciones de compresión o criptográficas que operan sobre memorias intermedias. Por ejemplo, los módulos estándar
zlib y hashlib liberan el GIL al comprimir o mezclar datos.

9.5.2 Hilos creados sin Python

Cuando se crean hilos utilizando las API dedicadas de Python (como el módulo threading), se les asocia auto-
máticamente un estado del hilo y, por lo tanto, el código que se muestra arriba es correcto. Sin embargo, cuando
los hilos se crean desde C (por ejemplo, por una biblioteca de terceros con su propia administración de hilos), no
contienen el GIL, ni existe una estructura de estado de hilos para ellos.
Si necesita llamar al código Python desde estos subprocesos (a menudo esto será parte de una API de devolución
de llamada proporcionada por la biblioteca de terceros mencionada anteriormente), primero debe registrar estos
subprocesos con el intérprete creando una estructura de datos de estado del subproceso, luego adquiriendo el GIL, y
finalmente almacenando su puntero de estado de hilo, antes de que pueda comenzar a usar la API Python/C Cuando
haya terminado, debe restablecer el puntero del estado del hilo, liberar el GIL y finalmente liberar la estructura de
datos del estado del hilo.
Las funciones PyGILState_Ensure() y PyGILState_Release() hacen todo lo anterior automáticamen-
te. El idioma típico para llamar a Python desde un hilo C es:

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

(continué en la próxima página)

188 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */

PyGILState_Release(gstate);

Note that the PyGILState_* functions assume there is only one global interpreter (created automatically by
Py_Initialize()). Python supports the creation of additional interpreters (using Py_NewInterpreter()),
but mixing multiple interpreters and the PyGILState_* API is unsupported.

9.5.3 Precauciones sobre fork()

Otra cosa importante a tener en cuenta sobre los hilos es su comportamiento frente a la llamada C fork(). En la
mayoría de los sistemas con fork(), después de que un proceso se bifurca, solo existirá el hilo que emitió el fork.
Esto tiene un impacto concreto tanto en cómo se deben manejar las cerraduras como en todo el estado almacenado
en el tiempo de ejecución de CPython.
El hecho de que solo permanezca al hilo «actual» significa que ningún bloqueo retenido por otros hilos nunca se
liberará. Python resuelve esto para os.fork() adquiriendo los bloqueos que usa internamente antes de la bi-
furcación (fork) y soltándolos después. Además, restablece cualquier lock-objects en el elemento secundario. Al
extender o incrustar Python, no hay forma de informar a Python de bloqueos adicionales (que no sean Python) que
deben adquirirse antes o restablecerse después de una bifurcación. Las instalaciones del sistema operativo como
pthread_atfork() tendrían que usarse para lograr lo mismo. Además, al extender o incrustar Python, llaman-
do fork() directamente en lugar de a través de os.fork() (y retornar o llamar a Python) puede resultar en un
punto muerto (deadlock) por uno de los bloqueos internos de Python. sostenido por un hilo que no funciona des-
pués del fork. PyOS_AfterFork_Child() intenta restablecer los bloqueos necesarios, pero no siempre puede
hacerlo.
El hecho de que todos los otros hilos desaparezcan también significa que el estado de ejecución de CPython
debe limpiarse correctamente, lo que os.fork() lo hace. Esto significa finalizar todos los demás objetos
PyThreadState que pertenecen al intérprete actual y todos los demás objetos PyInterpreterState. De-
bido a esto y a la naturaleza especial del intérprete «principal», fork() solo debería llamarse en el hilo «principal»
de ese intérprete, donde el CPython global el tiempo de ejecución se inicializó originalmente. La única excepción es
si exec() se llamará inmediatamente después.

9.5.4 API de alto nivel

Estos son los tipos y funciones más utilizados al escribir código de extensión C o al incrustar el intérprete de Python:
type PyInterpreterState
Part of the Limited API (as an opaque struct). Esta estructura de datos representa el estado compartido por
varios subprocesos cooperantes. Los hilos que pertenecen al mismo intérprete comparten la administración de
su módulo y algunos otros elementos internos. No hay miembros públicos en esta estructura.
Los hilos que pertenecen a diferentes intérpretes inicialmente no comparten nada, excepto el estado del proceso
como memoria disponible, descriptores de archivos abiertos y demás. El bloqueo global del intérprete también
es compartido por todos los hilos, independientemente de a qué intérprete pertenezcan.
type PyThreadState
Part of the Limited API (as an opaque struct). This data structure represents the state of a single thread. The
only public data member is interp (PyInterpreterState*), which points to this thread’s interpreter
state.
void PyEval_InitThreads()
Part of the Stable ABI. Función deprecada que no hace nada.
En Python 3.6 y versiones anteriores, esta función creaba el GIL si no existía.

9.5. Estado del hilo y el bloqueo global del intérprete 189

The Python/C API, Versión 3.11.0

Distinto en la versión 3.9: La función ahora no hace nada.

Distinto en la versión 3.7: Esta función ahora es llamada por Py_Initialize(), por lo que ya no tiene
que llamarla usted mismo.
Distinto en la versión 3.2: Esta función ya no se puede llamar antes de Py_Initialize().
Deprecated since version 3.9, removed in version 3.11.
int PyEval_ThreadsInitialized()
Part of the Stable ABI. Retorna un valor distinto de cero si se ha llamado a PyEval_InitThreads().
Esta función se puede invocar sin mantener el GIL y, por lo tanto, se puede utilizar para evitar llamadas a la
API de bloqueo cuando se ejecuta un solo hilo.
Distinto en la versión 3.7: El término GIL ahora se inicializa con Py_Initialize().
Deprecated since version 3.9, removed in version 3.11.
PyThreadState *PyEval_SaveThread()
Part of the Stable ABI. Libere el bloqueo global del intérprete (si se ha creado) y restablezca el estado del hilo
a NULL, retornando el estado del hilo anterior (que no es NULL). Si se ha creado el bloqueo, el hilo actual debe
haberlo adquirido.
void PyEval_RestoreThread(PyThreadState *tstate)
Part of the Stable ABI. Adquiera el bloqueo global del intérprete (si se ha creado) y establezca el estado del
hilo en tstate, que no debe ser NULL. Si se ha creado el bloqueo, el hilo actual no debe haberlo adquirido, de
lo contrario se produce un deadlock.

Nota: Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si
Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar
si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no
deseada.

PyThreadState *PyThreadState_Get()
Part of the Stable ABI. Retorna el estado actual del hilo. Se debe mantener el bloqueo global del intérprete.
Cuando el estado actual del hilo es NULL, esto genera un error fatal (por lo que la persona que llama no necesita
verificar NULL).
PyThreadState *PyThreadState_Swap(PyThreadState *tstate)
Part of the Stable ABI. Cambia el estado del hilo actual con el estado del hilo dado por el argumento tstate, que
puede ser NULL. El bloqueo global del intérprete debe mantenerse y no se libera.
Las siguientes funciones utilizan almacenamiento local de hilos y no son compatibles con subinterpretes:
PyGILState_STATE PyGILState_Ensure()
Part of the Stable ABI. Asegúrese de que el subproceso actual esté listo para llamar a la API de Pyt-
hon C, independientemente del estado actual de Python o del bloqueo global del intérprete. Esto se pue-
de invocar tantas veces como lo desee un subproceso siempre que cada llamada coincida con una llama-
da a PyGILState_Release(). En general, se pueden usar otras API relacionadas con subprocesos
entre PyGILState_Ensure() y PyGILState_Release() invoca siempre que el estado del sub-
proceso se restablezca a su estado anterior antes del Release(). Por ejemplo, el uso normal de las macros
Py_BEGIN_ALLOW_THREADS y Py_END_ALLOW_THREADS es aceptable.
El valor de retorno es un «identificador» opaco al estado del hilo cuando PyGILState_Ensure()
fue llamado, y debe pasarse a PyGILState_Release() para asegurar que Python se deje en el mis-
mo estado. Aunque las llamadas recursivas están permitidas, estos identificadores no pueden compartir-
se; cada llamada única a PyGILState_Ensure() debe guardar el identificador para su llamada a
PyGILState_Release().
Cuando la función regrese, el hilo actual contendrá el GIL y podrá llamar a código arbitrario de Python. El
fracaso es un error fatal.

190 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

Nota: Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si
Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar
si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no
deseada.

void PyGILState_Release(PyGILState_STATE)
Part of the Stable ABI. Libera cualquier recurso previamente adquirido. Después de esta llamada, el estado de
Python será el mismo que antes de la llamada correspondiente PyGILState_Ensure() (pero en general
este estado será desconocido para la persona que llama, de ahí el uso de la API GILState).
Cada llamada a PyGILState_Ensure() debe coincidir con una llamada a PyGILState_Release()
en el mismo hilo.
PyThreadState *PyGILState_GetThisThreadState()
Part of the Stable ABI. Obtenga el estado actual del hilo para este hilo. Puede retornar NULL si no se ha utilizado
la API GILState en el hilo actual. Tenga en cuenta que el subproceso principal siempre tiene dicho estado
de subproceso, incluso si no se ha realizado una llamada de estado de subproceso automático en el subproceso
principal. Esta es principalmente una función auxiliar y de diagnóstico.
int PyGILState_Check()
Retorna 1 si el hilo actual mantiene el GIL y 0 de lo contrario. Esta función se puede llamar desde cualquier
hilo en cualquier momento. Solo si se ha inicializado el hilo de Python y actualmente mantiene el GIL, retornará
1. Esta es principalmente una función auxiliar y de diagnóstico. Puede ser útil, por ejemplo, en contextos de
devolución de llamada o funciones de asignación de memoria cuando saber que el GIL está bloqueado puede
permitir que la persona que llama realice acciones confidenciales o se comporte de otra manera de manera
diferente.
Nuevo en la versión 3.4.
Las siguientes macros se usan normalmente sin punto y coma final; busque, por ejemplo, el uso en la distribución
fuente de Python.
Py_BEGIN_ALLOW_THREADS
Part of the Stable ABI. Esta macro se expande a {PyThreadState *_save; _save =
PyEval_SaveThread();. Tenga en cuenta que contiene una llave de apertura; debe coincidir con
la siguiente macro Py_END_ALLOW_THREADS. Ver arriba para una discusión más detallada de esta macro.
Py_END_ALLOW_THREADS
Part of the Stable ABI. Esta macro se expande a PyEval_RestoreThread(_save); }. Tenga en cuen-
ta que contiene una llave de cierre; debe coincidir con una macro anterior Py_BEGIN_ALLOW_THREADS.
Ver arriba para una discusión más detallada de esta macro.
Py_BLOCK_THREADS
Part of the Stable ABI. Esta macro se expande a PyEval_RestoreThread(_save);: es equivalente a
Py_END_ALLOW_THREADS sin la llave de cierre.
Py_UNBLOCK_THREADS
Part of the Stable ABI. Esta macro se expande a _save = PyEval_SaveThread();: es equivalente a
Py_BEGIN_ALLOW_THREADS sin la llave de apertura y la declaración de variable.

9.5. Estado del hilo y el bloqueo global del intérprete 191

The Python/C API, Versión 3.11.0

9.5.5 API de bajo nivel

Todas las siguientes funciones deben llamarse después de Py_Initialize().

Distinto en la versión 3.7: Py_Initialize() ahora inicializa el GIL.
PyInterpreterState *PyInterpreterState_New()
Part of the Stable ABI. Crea un nuevo objeto de estado de intérprete. No es necesario retener el bloqueo global
del intérprete, pero se puede retener si es necesario para serializar llamadas a esta función.
Genera un evento de auditoría python.PyInterpreterState_New sin argumentos.
void PyInterpreterState_Clear(PyInterpreterState *interp)
Part of the Stable ABI. Restablece toda la información en un objeto de estado de intérprete. Se debe mantener
el bloqueo global del intérprete.
Lanza una eventos de auditoría python.PyInterpreterState Clear sin argumentos.
void PyInterpreterState_Delete(PyInterpreterState *interp)
Part of the Stable ABI. Destruye un objeto de estado de intérprete. No es necesario mantener el blo-
queo global del intérprete. El estado del intérprete debe haberse restablecido con una llamada previa a
PyInterpreterState_Clear().
PyThreadState *PyThreadState_New(PyInterpreterState *interp)
Part of the Stable ABI. Crea un nuevo objeto de estado de hilo que pertenece al objeto de intérprete dado.
No es necesario retener el bloqueo global del intérprete, pero se puede retener si es necesario para serializar
llamadas a esta función.
void PyThreadState_Clear(PyThreadState *tstate)
Part of the Stable ABI. Restablece toda la información en un objeto de estado de hilo. Se debe mantener el
bloqueo global del intérprete.
Distinto en la versión 3.9: Esta función ahora llama a la retrollamada PyThreadState.on_delete. An-
teriormente, eso sucedía en PyThreadState_Delete().
void PyThreadState_Delete(PyThreadState *tstate)
Part of the Stable ABI. Destruye un objeto de estado de hilo. No es necesario mantener el bloqueo global del in-
térprete. El estado del hilo debe haberse restablecido con una llamada previa a PyThreadState_Clear().
void PyThreadState_DeleteCurrent(void)
Destruye un objeto de estado de hilo y suelta el bloqueo del intérprete global. Como
PyThreadState_Delete(), no es necesario mantener el bloqueo del intérprete global. El estado
del hilo debe haberse restablecido con una llamada anterior a PyThreadState_Clear().
PyFrameObject *PyThreadState_GetFrame(PyThreadState *tstate)
Part of the Stable ABI since version 3.10. Obtiene el marco actual del estado del hilo de Python tstate.
Retorna una strong reference (referencia sólida). Retorna NULL si no se está ejecutando ningún cuadro.
Vea también PyEval_GetFrame().
tstate no debe ser NULL.
Nuevo en la versión 3.9.
uint64_t PyThreadState_GetID(PyThreadState *tstate)
Part of the Stable ABI since version 3.10. Obtiene el identificador de estado de subproceso único del estado del
hilo de Python tstate.
tstate no debe ser NULL.
Nuevo en la versión 3.9.

192 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

PyInterpreterState *PyThreadState_GetInterpreter(PyThreadState *tstate)

Part of the Stable ABI since version 3.10. Obtiene el intérprete del estado del hilo de Python tstate.
tstate no debe ser NULL.
Nuevo en la versión 3.9.
void PyThreadState_EnterTracing(PyThreadState *tstate)
Suspend tracing and profiling in the Python thread state tstate.
Resume them using the PyThreadState_LeaveTracing() function.
Nuevo en la versión 3.11.
void PyThreadState_LeaveTracing(PyThreadState *tstate)
Resume tracing and profiling in the Python thread state tstate suspended by the
PyThreadState_EnterTracing() function.
See also PyEval_SetTrace() and PyEval_SetProfile() functions.
Nuevo en la versión 3.11.
PyInterpreterState *PyInterpreterState_Get(void)
Part of the Stable ABI since version 3.9. Obtiene el intérprete actual.
Emite un error fatal si no hay un estado actual del hilo de Python o no hay un intérprete actual. No puede
retornar NULL.
La persona que llama debe retener el GIL.
Nuevo en la versión 3.9.
int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
Part of the Stable ABI since version 3.7. Retorna la identificación única del intérprete. Si hubo algún error al
hacerlo, entonces se retorna -1 y se establece un error.
La persona que llama debe retener el GIL.
Nuevo en la versión 3.7.
PyObject *PyInterpreterState_GetDict(PyInterpreterState *interp)
Part of the Stable ABI since version 3.8. Retorna un diccionario en el que se pueden almacenar datos específicos
del intérprete. Si esta función retorna NULL, no se ha producido ninguna excepción y la persona que llama debe
suponer que no hay disponible una instrucción específica del intérprete.
Esto no reemplaza a PyModule_GetState(), que las extensiones deben usar para almacenar información
de estado específica del intérprete.
Nuevo en la versión 3.8.
typedef PyObject *(*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int
throwflag)
Tipo de función de evaluación de marcos.
El parámetro throwflag es usado por el método de generadores throw(): si no es cero, maneja la excepción
actual.
Distinto en la versión 3.9: La función ahora recibe un parámetro tstate.
Distinto en la versión 3.11: The frame parameter changed from PyFrameObject* to
_PyInterpreterFrame*.
_PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
Obtiene la función de evaluación de marcos.
Consulte PEP 523 «Adición de una API de evaluación de marcos a CPython».
Nuevo en la versión 3.9.

9.5. Estado del hilo y el bloqueo global del intérprete 193

The Python/C API, Versión 3.11.0

void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction

eval_frame)
Configura la función de evaluación del marco.
Consulte PEP 523 «Adición de una API de evaluación de marcos a CPython».
Nuevo en la versión 3.9.
PyObject *PyThreadState_GetDict()
Return value: Borrowed reference. Part of the Stable ABI. Retorna un diccionario en el que las extensiones
pueden almacenar información de estado específica del hilo. Cada extensión debe usar una clave única para
almacenar el estado en el diccionario. Está bien llamar a esta función cuando no hay un estado del hilo actual
disponible. Si esta función retorna NULL, no se ha producido ninguna excepción y la persona que llama debe
asumir que no hay disponible ningún estado del hilo actual.
int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
Part of the Stable ABI. Asincrónicamente lanza una excepción en un hilo. El argumento id es el id del hilo del
hilo de destino; exc es el objeto de excepción que se debe generar. Esta función no roba ninguna referencia a
exc. Para evitar el uso indebido ingenuo, debe escribir su propia extensión C para llamar a esto. Debe llamarse
con el GIL retenido. Retorna el número de estados de hilo modificados; normalmente es uno, pero será cero
si no se encuentra la identificación del hilo. Si exc es NULL, se borra la excepción pendiente (si existe) para el
hilo. Esto no lanza excepciones.
Distinto en la versión 3.7: The type of the id parameter changed from long to unsigned long.
void PyEval_AcquireThread(PyThreadState *tstate)
Part of the Stable ABI. Adquiere el bloqueo global del intérprete y establece el estado actual del hilo en tstate,
que no debe ser NULL. El bloqueo debe haber sido creado anteriormente. Si este hilo ya tiene el bloqueo, se
produce un deadlock.

Nota: Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si
Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar
si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no
deseada.

Distinto en la versión 3.8: Actualiza para ser coherente con PyEval_RestoreThread(),

Py_END_ALLOW_THREADS(), y PyGILState_Ensure(), y termina el hilo actual si se llama
mientras el intérprete está finalizando.
PyEval_RestoreThread() es una función de nivel superior que siempre está disponible (incluso cuando
los subprocesos no se han inicializado).
void PyEval_ReleaseThread(PyThreadState *tstate)
Part of the Stable ABI. Restablece el estado actual del hilo a NULL y libera el bloqueo global del intérprete. El
bloqueo debe haberse creado antes y debe estar retenido por el hilo actual. El argumento tstate, que no debe
ser NULL, solo se usa para verificar que representa el estado actual del hilo — si no lo es, se informa un error
fatal.
PyEval_SaveThread() es una función de nivel superior que siempre está disponible (incluso cuando los
hilos no se han inicializado).
void PyEval_AcquireLock()
Part of the Stable ABI. Adquiera el bloqueo global de intérprete. El bloqueo debe haber sido creado anterior-
mente. Si este hilo ya tiene el bloqueo, se produce un deadlock.
Obsoleto desde la versión 3.2: Esta función no actualiza el estado actual del hilo. Utilice
PyEval_RestoreThread() o PyEval_AcquireThread() en su lugar.

Nota: Llamar a esta función desde un hilo cuando finalice el tiempo de ejecución terminará el hilo, incluso si
Python no creó el hilo. Puede usar _Py_IsFinalizing() o sys.is_finalizing() para verificar

194 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

si el intérprete está en proceso de finalización antes de llamar a esta función para evitar una terminación no
deseada.

Distinto en la versión 3.8: Actualiza para ser coherente con PyEval_RestoreThread(),

Py_END_ALLOW_THREADS(), y PyGILState_Ensure(), y termina el hilo actual si se llama
mientras el intérprete está finalizando.
void PyEval_ReleaseLock()
Part of the Stable ABI. Libere el bloqueo global del intérprete. El bloqueo debe haber sido creado anteriormente.
Obsoleto desde la versión 3.2: Esta función no actualiza el estado actual del hilo. Utilice
PyEval_SaveThread() o PyEval_ReleaseThread() en su lugar.

9.6 Soporte de subinterprete

Si bien en la mayoría de los usos, solo incrustará un solo intérprete de Python, hay casos en los que necesita crear varios
intérpretes independientes en el mismo proceso y tal vez incluso en el mismo hilo. Los subinterpretes le permiten hacer
eso.
El intérprete «principal» es el primero creado cuando se inicializa el tiempo de ejecución. Suele ser el único intérprete
de Python en un proceso. A diferencia de los subinterpretes, el intérprete principal tiene responsabilidades globales
de proceso únicas, como el manejo de señales. También es responsable de la ejecución durante la inicialización del
tiempo de ejecución y generalmente es el intérprete activo durante la finalización del tiempo de ejecución. La función
PyInterpreterState_Main() retorna un puntero a su estado.
Puede cambiar entre subinterpretes utilizando la función PyThreadState_Swap(). Puede crearlos y destruirlos
utilizando las siguientes funciones:
PyThreadState *Py_NewInterpreter()
Part of the Stable ABI. Crea un nuevo subinterprete. Este es un entorno (casi) totalmente separado para la
ejecución de código Python. En particular, el nuevo intérprete tiene versiones separadas e independientes de
todos los módulos importados, incluidos los módulos fundamentales builtins, __main__ y sys. La tabla
de módulos cargados (sys.modules) y la ruta de búsqueda del módulo (sys.path) también están separa-
dos. El nuevo entorno no tiene variable sys.argv. Tiene nuevos objetos de archivo de flujo de E/S estándar
sys.stdin, sys.stdout y sys.stderr (sin embargo, estos se refieren a los mismos descriptores de
archivo subyacentes).
El valor de retorno apunta al primer estado del hilo creado en el nuevo subinterprete. Este estado de hilo se
realiza en el estado de hilo actual. Tenga en cuenta que no se crea ningún hilo real; vea la discusión de los
estados del hilo a continuación. Si la creación del nuevo intérprete no tiene éxito, se retorna NULL; no se
establece ninguna excepción, ya que el estado de excepción se almacena en el estado actual del hilo y es posible
que no haya un estado actual del hilo. (Al igual que todas las otras funciones de Python/C API, el bloqueo global
del intérprete debe mantenerse antes de llamar a esta función y aún se mantiene cuando regresa; sin embargo,
a diferencia de la mayoría de las otras funciones de Python/C API, no es necesario que haya un estado del hilo
actual en entrada.)
Los módulos de extensión se comparten entre (sub) intérpretes de la siguiente manera:
• Para módulos que usan inicialización multifase, por ejemplo PyModule_FromDefAndSpec(), se
crea e inicializa un objeto de módulo separado para cada intérprete. Solo las variables estáticas y globales
de nivel C se comparten entre estos objetos de módulo.
• Para módulos que utilizan inicialización monofásica, por ejemplo PyModule_Create(), la primera
vez que se importa una extensión en particular, se inicializa normalmente y una copia (superficial) del
diccionario de su módulo se guarda. Cuando otro (sub) intérprete importa la misma extensión, se inicializa
un nuevo módulo y se llena con el contenido de esta copia; no se llama a la función init de la extensión.
Los objetos en el diccionario del módulo terminan compartidos entre (sub) intérpretes, lo que puede
causar un comportamiento no deseado (ver Errores y advertencias (Bugs and caveats) a continuación).

9.6. Soporte de subinterprete 195

The Python/C API, Versión 3.11.0

Tenga en cuenta que esto es diferente de lo que sucede cuando se importa una extensión después de que el
intérprete se haya reiniciado por completo llamando a Py_FinalizeEx() y Py_Initialize();
en ese caso, la función initmodule de la extensión es llamada nuevamente. Al igual que con la inicia-
lización de múltiples fases, esto significa que solo se comparten variables estáticas y globales de nivel C
entre estos módulos.
void Py_EndInterpreter(PyThreadState *tstate)
Part of the Stable ABI. Destruye el (sub) intérprete representado por el estado del hilo dado. El estado del hilo
dado debe ser el estado del hilo actual. Vea la discusión de los estados del hilo a continuación. Cuando la llamada
regresa, el estado actual del hilo es NULL. Todos los estados de hilo asociados con este intérprete se destruyen.
(El bloqueo global del intérprete debe mantenerse antes de llamar a esta función y aún se mantiene cuando
vuelve). Py_FinalizeEx() destruirá todos los subinterpretes que no se hayan destruido explícitamente en
ese punto.

9.6.1 Errores y advertencias

Debido a que los subinterpretes (y el intérprete principal) son parte del mismo proceso, el aislamiento entre ellos no es
perfecto — por ejemplo, usando operaciones de archivos de bajo nivel como os.close() pueden (accidentalmente
o maliciosamente) afectar los archivos abiertos del otro. Debido a la forma en que las extensiones se comparten entre
(sub) intérpretes, algunas extensiones pueden no funcionar correctamente; esto es especialmente probable cuando
se utiliza la inicialización monofásica o las variables globales (estáticas). Es posible insertar objetos creados en un
subinterprete en un espacio de nombres de otro (sub) intérprete; Esto debe evitarse si es posible.
Se debe tener especial cuidado para evitar compartir funciones, métodos, instancias o clases definidas por el usua-
rio entre los subinterpretes, ya que las operaciones de importación ejecutadas por dichos objetos pueden afectar el
diccionario (sub-) intérprete incorrecto de los módulos cargados. Es igualmente importante evitar compartir objetos
desde los que se pueda acceder a lo anterior.
Also note that combining this functionality with PyGILState_* APIs is delicate, because these APIs assu-
me a bijection between Python thread states and OS-level threads, an assumption broken by the presence of
sub-interpreters. It is highly recommended that you don’t switch sub-interpreters between a pair of matching
PyGILState_Ensure() and PyGILState_Release() calls. Furthermore, extensions (such as ctypes)
using these APIs to allow calling of Python code from non-Python created threads will probably be broken when
using sub-interpreters.

9.7 Notificaciones asincrónicas

Se proporciona un mecanismo para hacer notificaciones asincrónicas al hilo principal del intérprete. Estas notifica-
ciones toman la forma de un puntero de función y un argumento de puntero nulo.
int Py_AddPendingCall(int (*func)(void*), void *arg)
Part of the Stable ABI. Programa una función para que se llame desde el hilo principal del intérprete. En caso
de éxito, se retorna 0 y se pone en cola func para ser llamado en el hilo principal. En caso de fallo, se retorna
-1 sin establecer ninguna excepción.
Cuando se puso en cola con éxito, func será eventualmente invocado desde el hilo principal del intérprete con
el argumento arg. Se llamará de forma asincrónica con respecto al código Python que se ejecuta normalmente,
pero con ambas condiciones cumplidas:
• en un límite bytecode;
• con el hilo principal que contiene el global interpreter lock (func, por lo tanto, puede usar la API C
completa).
func debe retornar 0 en caso de éxito o -1 en caso de error con una excepción establecida. func no se in-
terrumpirá para realizar otra notificación asíncrona de forma recursiva, pero aún se puede interrumpir para
cambiar hilos si se libera el bloqueo global del intérprete.
Esta función no necesita un estado de hilo actual para ejecutarse y no necesita el bloqueo global del intérprete.

196 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

Para llamar a esta función en un subinterprete, quien llama debe mantener el GIL. De lo contrario, la función
func se puede programar para que se llame desde el intérprete incorrecto.

Advertencia: Esta es una función de bajo nivel, solo útil para casos muy especiales. No hay garantía de que
func se llame lo más rápido posible. Si el hilo principal está ocupado ejecutando una llamada al sistema,
no se llamará func antes de que vuelva la llamada del sistema. Esta función generalmente no es adecuada
para llamar a código Python desde hilos C arbitrarios. En su lugar, use PyGILState API.

Distinto en la versión 3.9: Si esta función se llama en un subinterprete, la función func ahora está programada
para ser llamada desde el subinterprete, en lugar de ser llamada desde el intérprete principal. Cada subinterprete
ahora tiene su propia lista de llamadas programadas.
Nuevo en la versión 3.1.

9.8 Perfilado y Rastreo

El intérprete de Python proporciona soporte de bajo nivel para adjuntar funciones de creación de perfiles y seguimiento
de ejecución. Estos se utilizan para herramientas de análisis de perfiles, depuración y cobertura.
Esta interfaz C permite que el código de perfilado o rastreo evite la sobrecarga de llamar a través de objetos invocables
a nivel de Python, haciendo una llamada directa a la función C en su lugar. Los atributos esenciales de la instalación no
han cambiado; la interfaz permite instalar funciones de rastreo por hilos, y los eventos básicos informados a la función
de rastreo son los mismos que se informaron a las funciones de rastreo a nivel de Python en versiones anteriores.
typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
El tipo de la función de rastreo registrada usando PyEval_SetProfile() y PyEval_SetTrace().
El primer parámetro es el objeto pasado a la función de registro como obj, frame es el objeto de marco
al que pertenece el evento, what es una de las constantes PyTrace_CALL, PyTrace_EXCEPTION
, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION,
PyTrace_C_RETURN, o PyTrace_OPCODE, y arg depende de el valor de what:

Valor de what Significado de arg

PyTrace_CALL Siempre Py_None.
PyTrace_EXCEPTION Información de excepción retornada por sys.exc_info().
PyTrace_LINE Siempre Py_None.
PyTrace_RETURN Valor retornado al que llama, o NULL si es causado por una excepción.
PyTrace_C_CALL Objeto función que se llaman.
PyTrace_C_EXCEPTION Objeto función que se llaman.
PyTrace_C_RETURN Objeto función que se llaman.
PyTrace_OPCODE Siempre Py_None.

int PyTrace_CALL
El valor del parámetro what para una función Py_tracefunc cuando se informa una nueva llamada a una
función o método, o una nueva entrada en un generador. Tenga en cuenta que la creación del iterador para una
función de generador no se informa ya que no hay transferencia de control al código de bytes de Python en la
marco correspondiente.
int PyTrace_EXCEPTION
El valor del parámetro what para una función Py_tracefunc cuando se ha producido una excepción. La
función de devolución de llamada se llama con este valor para what cuando después de que se procese cualquier
bytecode, después de lo cual la excepción se establece dentro del marco que se está ejecutando. El efecto de
esto es que a medida que la propagación de la excepción hace que la pila de Python se desenrolle, el retorno de
llamada se llama al retornar a cada marco a medida que se propaga la excepción. Solo las funciones de rastreo
reciben estos eventos; el perfilador (profiler) no los necesita.

9.8. Perfilado y Rastreo 197

The Python/C API, Versión 3.11.0

int PyTrace_LINE
El valor pasado como parámetro what a una función Py_tracefunc (pero no una función de creación de
perfiles) cuando se informa un evento de número de línea. Puede deshabilitarse para un marco configurando
f_trace_lines en 0 en ese marco.
int PyTrace_RETURN
El valor para el parámetro what para Py_tracefunc funciona cuando una llamada está por regresar.
int PyTrace_C_CALL
El valor del parámetro what para Py_tracefunc funciona cuando una función C está a punto de ser invo-
cada.
int PyTrace_C_EXCEPTION
El valor del parámetro what para funciones Py_tracefunc cuando una función C ha lanzado una excepción.
int PyTrace_C_RETURN
El valor del parámetro what para Py_tracefunc funciona cuando una función C ha retornado.
int PyTrace_OPCODE
El valor del parámetro what para funciones Py_tracefunc (pero no funciones de creación de perfiles) cuan-
do un nuevo código de operación está a punto de ejecutarse. Este evento no se emite de forma predeterminada:
debe solicitarse explícitamente estableciendo f_trace_opcodes en 1 en el marco.
void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
Establece la función del generador de perfiles en func. El parámetro obj se pasa a la función como su primer
parámetro, y puede ser cualquier objeto de Python o NULL. Si la función de perfilado necesita mantener el
estado, el uso de un valor diferente para obj para cada hilo proporciona un lugar conveniente y seguro para
guardarlo. Se llama a la función de perfilado para todos los eventos supervisados, excepto PyTrace_LINE
PyTrace_OPCODE y PyTrace_EXCEPTION.
See also the sys.setprofile() function.
La persona que llama debe mantener el GIL.
void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
Establece la función de rastreo en func. Esto es similar a PyEval_SetProfile(), excepto que
la función de rastreo recibe eventos de número de línea y eventos por código de operación, pero no
recibe ningún evento relacionado con los objetos de la función C. Cualquier función de rastreo re-
gistrada con PyEval_SetTrace() no recibirá PyTrace_C_CALL, PyTrace_C_EXCEPTION o
PyTrace_C_RETURN como valor para el parámetro what.
See also the sys.settrace() function.
La persona que llama debe mantener el GIL.

9.9 Soporte avanzado del depurador

Estas funciones solo están destinadas a ser utilizadas por herramientas de depuración avanzadas.
PyInterpreterState *PyInterpreterState_Head()
Retorna el objeto de estado del intérprete al principio de la lista de todos esos objetos.
PyInterpreterState *PyInterpreterState_Main()
Retorna el objeto de estado del intérprete principal.
PyInterpreterState *PyInterpreterState_Next(PyInterpreterState *interp)
Retorna el siguiente objeto de estado de intérprete después de interp de la lista de todos esos objetos.
PyThreadState *PyInterpreterState_ThreadHead(PyInterpreterState *interp)
Retorna el puntero al primer objeto PyThreadState en la lista de hilos asociados con el intérprete interp.

198 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

PyThreadState *PyThreadState_Next(PyThreadState *tstate)

Retorna el siguiente objeto de estado del hilo después de tstate de la lista de todos los objetos que pertenecen
al mismo objeto PyInterpreterState.

9.10 Soporte de almacenamiento local de hilo

The Python interpreter provides low-level support for thread-local storage (TLS) which wraps the underlying native
TLS implementation to support the Python-level thread local storage API (threading.local). The CPython C
level APIs are similar to those offered by pthreads and Windows: use a thread key and functions to associate a void*
value per thread.
El GIL no necesita ser retenido al llamar a estas funciones; proporcionan su propio bloqueo.
Tenga en cuenta que Python.h no incluye la declaración de las API de TLS, debe incluir pythread.h para usar
el almacenamiento local de hilos.

Nota: None of these API functions handle memory management on behalf of the void* values. You need to
allocate and deallocate them yourself. If the void* values happen to be PyObject*, these functions don’t do
refcount operations on them either.

9.10.1 API de almacenamiento específico de hilo (TSS, Thread Specific Storage)

TSS API is introduced to supersede the use of the existing TLS API within the CPython interpreter. This API uses
a new type Py_tss_t instead of int to represent thread keys.
Nuevo en la versión 3.7.
Ver también:
«Una nueva C-API para Thread-Local Storage en CPython» (PEP 539)
type Py_tss_t
Esta estructura de datos representa el estado de una clave del hilo, cuya definición puede depender de la imple-
mentación de TLS subyacente, y tiene un campo interno que representa el estado de inicialización de la clave.
No hay miembros públicos en esta estructura.
Cuando Py_LIMITED_API no está definido, la asignación estática de este tipo por Py_tss_NEEDS_INIT
está permitida.
Py_tss_NEEDS_INIT
Esta macro se expande al inicializador para variables Py_tss_t. Tenga en cuenta que esta macro no se
definirá con Py_LIMITED_API.

Asignación dinámica

Asignación dinámica de Py_tss_t, requerida en los módulos de extensión construidos con Py_LIMITED_API,
donde la asignación estática de este tipo no es posible debido a que su implementación es opaca en el momento de la
compilación.
Py_tss_t *PyThread_tss_alloc()
Part of the Stable ABI since version 3.7. Retorna un valor que es el mismo estado que un valor inicializado con
Py_tss_NEEDS_INIT, o NULL en caso de falla de asignación dinámica.

9.10. Soporte de almacenamiento local de hilo 199

The Python/C API, Versión 3.11.0

void PyThread_tss_free(Py_tss_t *key)

Part of the Stable ABI since version 3.7. Free the given key allocated by PyThread_tss_alloc(), after
first calling PyThread_tss_delete() to ensure any associated thread locals have been unassigned. This
is a no-op if the key argument is NULL.

Nota: A freed key becomes a dangling pointer. You should reset the key to NULL.

Métodos

El parámetro key de estas funciones no debe ser NULL. Además, los comportamientos de PyThread_tss_set()
y PyThread_tss_get() no están definidos si el Py_tss_t dado no ha sido inicializado por
PyThread_tss_create().
int PyThread_tss_is_created(Py_tss_t *key)
Part of the Stable ABI since version 3.7. Retorna un valor distinto de cero si Py_tss_t ha sido inicializado
por PyThread_tss_create().
int PyThread_tss_create(Py_tss_t *key)
Part of the Stable ABI since version 3.7. Retorna un valor cero en la inicialización exitosa de una clave
TSS. El comportamiento no está definido si el valor señalado por el argumento key no se inicializa con
Py_tss_NEEDS_INIT. Esta función se puede invocar repetidamente en la misma tecla: llamarla a una
tecla ya inicializada es un no-op e inmediatamente retorna el éxito.
void PyThread_tss_delete(Py_tss_t *key)
Part of the Stable ABI since version 3.7. Destruye una clave TSS para olvidar los valores asociados con la clave
en todos los hilos y cambie el estado de inicialización de la clave a no inicializado. Una clave destruida se puede
inicializar nuevamente mediante PyThread_tss_create(). Esta función se puede invocar repetidamente
en la misma llave; llamarla en una llave ya destruida es un no-op.
int PyThread_tss_set(Py_tss_t *key, void *value)
Part of the Stable ABI since version 3.7. Return a zero value to indicate successfully associating a void* value
with a TSS key in the current thread. Each thread has a distinct mapping of the key to a void* value.
void *PyThread_tss_get(Py_tss_t *key)
Part of the Stable ABI since version 3.7. Return the void* value associated with a TSS key in the current
thread. This returns NULL if no value is associated with the key in the current thread.

9.10.2 API de almacenamiento local de hilos (TLS, Thread Local Storage)

Obsoleto desde la versión 3.7: Esta API es reemplazada por API de Almacenamiento Específico de Hilos (TSS, por
sus significado en inglés *Thread Specific Storage*).

Nota: Esta versión de la API no es compatible con plataformas donde la clave TLS nativa se define de una manera
que no se puede transmitir de forma segura a int. En tales plataformas, PyThread_create_key() regresará
inmediatamente con un estado de falla, y las otras funciones TLS serán no operativas en tales plataformas.

Debido al problema de compatibilidad mencionado anteriormente, esta versión de la API no debe usarse en código
nuevo.
int PyThread_create_key()
Part of the Stable ABI.
void PyThread_delete_key(int key)
Part of the Stable ABI.

200 Capítulo 9. Inicialización, Finalización e Hilos

 The Python/C API, Versión 3.11.0

int PyThread_set_key_value(int key, void *value)

Part of the Stable ABI.
void *PyThread_get_key_value(int key)
Part of the Stable ABI.
void PyThread_delete_key_value(int key)
Part of the Stable ABI.
void PyThread_ReInitTLS()
Part of the Stable ABI.

9.10. Soporte de almacenamiento local de hilo 201

The Python/C API, Versión 3.11.0

202 Capítulo 9. Inicialización, Finalización e Hilos

 CAPÍTULO 10

Configuración de inicialización de Python

Nuevo en la versión 3.8.

Python se puede inicializar con Py_InitializeFromConfig() y la estructura PyConfig. Se puede preini-
cializar con Py_PreInitialize() y la estructura PyPreConfig.
Hay dos tipos de configuración:
• The Python Configuration can be used to build a customized Python which behaves as the regular Python. For
example, environment variables and command line arguments are used to configure Python.
• The Isolated Configuration can be used to embed Python into an application. It isolates Python from the system.
For example, environment variables are ignored, the LC_CTYPE locale is left unchanged and no signal handler
is registered.
La función Py_RunMain() se puede utilizar para escribir un programa Python personalizado.
Consulte también Inicialización, finalización y subprocesos.
Ver también:
PEP 587 «Configuración de inicialización de Python».

10.1 Ejemplo

Ejemplo de Python personalizado que siempre se ejecuta en modo aislado:

int main(int argc, char **argv)

{
PyStatus status;

PyConfig config;
PyConfig_InitPythonConfig(&config);
config.isolated = 1;

/* Decode command line arguments.

Implicitly preinitialize Python (in isolated mode). */
status = PyConfig_SetBytesArgv(&config, argc, argv);
if (PyStatus_Exception(status)) {
goto exception;
(continué en la próxima página)

203
The Python/C API, Versión 3.11.0

(proviene de la página anterior)

}

status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto exception;
}
PyConfig_Clear(&config);

return Py_RunMain();

exception:
PyConfig_Clear(&config);
if (PyStatus_IsExit(status)) {
return status.exitcode;
}
/* Display the error message and exit the process with
non-zero exit code */
Py_ExitStatusException(status);
}

10.2 PyWideStringList

type PyWideStringList
Lista de cadenas de caracteres wchar_t*.
Si length no es cero, items no deben ser NULL y todas las cadenas de caracteres deben ser no NULL.
Métodos:
PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
Agregar item a list.
Python debe estar preinicializado para llamar a esta función.
PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)
Inserta item en list en index.
Si index es mayor o igual que el largo de list, agrega item a list.
index must be greater than or equal to 0.
Python debe estar preinicializado para llamar a esta función.
Campos de estructura:
Py_ssize_t length
Longitud de la lista.
wchar_t **items
Elementos de la lista.

204 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

10.3 PyStatus

type PyStatus
Estructura para almacenar el estado de una función de inicialización: éxito, error o salida.
Para un error, puede almacenar el nombre de la función C que creó el error.
Campos de estructura:
int exitcode
Código de salida El argumento pasó a exit().
const char *err_msg
Mensaje de error.
const char *func
El nombre de la función que creó un error puede ser NULL.
Funciones para crear un estado:
PyStatus PyStatus_Ok(void)
Éxito.
PyStatus PyStatus_Error(const char *err_msg)
Error de inicialización con un mensaje.
err_msg no debe ser NULL.
PyStatus PyStatus_NoMemory(void)
Error de asignación de memoria (sin memoria).
PyStatus PyStatus_Exit(int exitcode)
Sale de Python con el código de salida especificado.
Funciones para manejar un estado:
int PyStatus_Exception(PyStatus status)
¿Es el estado un error o una salida? Si es verdadero, la excepción debe ser manejada; por ejemplo llamando
a Py_ExitStatusException().
int PyStatus_IsError(PyStatus status)
¿Es el resultado un error?
int PyStatus_IsExit(PyStatus status)
¿El resultado es una salida?
void Py_ExitStatusException(PyStatus status)
Llama a exit(exitcode) si status es una salida. Imprime el mensaje de error y sale con un código de
salida distinto de cero si status es un error. Solo se debe llamar si PyStatus_Exception(status)
no es cero.

Nota: Internamente, Python usa macros que establecen PyStatus.func, mientras que las funciones para crear
un estado establecen func en NULL.

Ejemplo:

PyStatus alloc(void **ptr, size_t size)

{
*ptr = PyMem_RawMalloc(size);
if (*ptr == NULL) {
return PyStatus_NoMemory();
(continué en la próxima página)

10.3. PyStatus 205

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

}
return PyStatus_Ok();
}

int main(int argc, char **argv)

{
void *ptr;
PyStatus status = alloc(&ptr, 16);
if (PyStatus_Exception(status)) {
Py_ExitStatusException(status);
}
PyMem_Free(ptr);
return 0;
}

10.4 PyPreConfig

type PyPreConfig
Estructura utilizada para preinicializar Python.
Función para inicializar una preconfiguración:
void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
Inicializa la preconfiguración con Configuración de Python.
void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
Inicializa la preconfiguración con Configuración aislada.
Campos de estructura:
int allocator
Nombre de los asignadores de memoria de Python:
• PYMEM_ALLOCATOR_NOT_SET (0): no cambia asignadores de memoria (usa los valores prede-
terminados)
• PYMEM_ALLOCATOR_DEFAULT (1): asignadores de memoria predeterminados.
• PYMEM_ALLOCATOR_DEBUG (2): asignadores de memoria predeterminados con ganchos de de-
puración.
• PYMEM_ALLOCATOR_MALLOC (3): usa malloc() de la biblioteca C.
• PYMEM_ALLOCATOR_MALLOC_DEBUG (4): fuerza el uso de malloc() con ganchos de depu-
ración.
• PYMEM_ALLOCATOR_PYMALLOC (5): asignador de memoria pymalloc de Python
• PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): asignador de memoria pymalloc de Python con
ganchos de depuración.
PYMEM_ALLOCATOR_PYMALLOC y PYMEM_ALLOCATOR_PYMALLOC_DEBUG no son compati-
bles si Python es configurado usando --without-pymalloc.
Ver Administración de memorias.
Predeterminado: PYMEM_ALLOCATOR_NOT_SET.
int configure_locale
¿Establecer la configuración regional LC_CTYPE en la configuración regional preferida del usuario?
If equals to 0, set coerce_c_locale and coerce_c_locale_warn members to 0.

206 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

Vea el locale encoding.

Predeterminado: 1 en la configuración de Python, 0 en la configuración aislada.
int coerce_c_locale
If equals to 2, coerce the C locale.
If equals to 1, read the LC_CTYPE locale to decide if it should be coerced.
Vea el locale encoding.
Predeterminado: -1 en la configuración de Python, 0 en la configuración aislada.
int coerce_c_locale_warn
Si no es cero, emita una advertencia si la configuración regional C está coaccionada.
Predeterminado: -1 en la configuración de Python, 0 en la configuración aislada.
int dev_mode
Python Development Mode: see PyConfig.dev_mode.
Por defecto: -1 en modo Python, 0 en modo aislado.
int isolated
Modo aislado: consulte PyConfig.isolated.
Por defecto: 0 en modo Python, 1 en modo aislado.
int legacy_windows_fs_encoding
Si no es cero:
• Establezca PyPreConfig.utf8_mode en 0,
• Establezca PyConfig.filesystem_encoding en "mbcs",
• Establezca PyConfig.filesystem_errors en "replace".
Inicializado desde valor de variable de entorno PYTHONLEGACYWINDOWSFSENCODING.
Solo disponible en Windows. La macro #ifdef MS_WINDOWS se puede usar para el código específico
de Windows.
Predeterminado: 0.
int parse_argv
Si no es cero, Py_PreInitializeFromArgs() y Py_PreInitializeFromBytesArgs()
analizan su argumento argv de la misma manera que Python analiza los argumentos de la línea de
comandos: ver Argumentos de línea de comandos.
Predeterminado: 1 en la configuración de Python, 0 en la configuración aislada.
int use_environment
¿Utiliza variables de entorno? Consulte PyConfig.use_environment.
Predeterminado: 1 en la configuración de Python y 0 en la configuración aislada.
int utf8_mode
Si es distinto de cero, habilite Python UTF-8 Mode.
Set to 0 or 1 by the -X utf8 command line option and the PYTHONUTF8 environment variable.
También se pone a 1 si la configuración regional LC_CTYPE es C o POSIX.
Predeterminado: -1 en la configuración de Python y 0 en la configuración aislada.

10.4. PyPreConfig 207

The Python/C API, Versión 3.11.0

10.5 Preinicialización de Python con PyPreConfig

La preinicialización de Python:
• Establecer los asignadores de memoria de Python (PyPreConfig.allocator)
• Configurar la configuración regional LC_CTYPE (locale encoding)
• Establecer el Python UTF-8 Mode (PyPreConfig.utf8_mode)
La preconfiguración actual (tipo PyPreConfig) se almacena en _PyRuntime.preconfig.
Funciones para preinicializar Python:
PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
Preinicializa Python desde la preconfiguración preconfig.
preconfig no debe ser NULL.
PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)
Preinicializa Python desde la preconfiguración preconfig.
Analice los argumentos de la línea de comando argv (cadenas de bytes) si parse_argv de preconfig no es
cero.
preconfig no debe ser NULL.
PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)
Preinicializa Python desde la preconfiguración preconfig.
Analice los argumentos de la línea de comando argv (cadenas anchas) si parse_argv de preconfig no es
cero.
preconfig no debe ser NULL.
La persona que llama es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception()
y Py_ExitStatusException().
Para Configuración de Python (PyPreConfig_InitPythonConfig()), si Python se inicializa con argumentos
de línea de comando, los argumentos de la línea de comando también deben pasarse para preinicializar Python, ya
que tienen un efecto en la preconfiguración como codificaciones. Por ejemplo, la opción de línea de comando -X
utf8 habilita el Python UTF-8 Mode.
PyMem_SetAllocator() se puede llamar después de Py_PreInitialize() y antes
Py_InitializeFromConfig() para instalar un asignador de memoria personalizado. Se pue-
de llamar antes Py_PreInitialize() si PyPreConfig.allocator está configurado en
PYMEM_ALLOCATOR_NOT_SET.
Las funciones de asignación de memoria de Python como PyMem_RawMalloc() no deben usarse antes de la
preinicialización de Python, mientras que llamar directamente a malloc() y free() siempre es seguro. No se
debe llamar a Py_DecodeLocale() antes de la preinicialización de Python.
Ejemplo usando la preinicialización para habilitar el Python UTF-8 Mode

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
Py_ExitStatusException(status);
}

/* at this point, Python speaks UTF-8 */

(continué en la próxima página)

208 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

10.6 PyConfig

type PyConfig
Estructura que contiene la mayoría de los parámetros para configurar Python.
Cuando termine, se debe utilizar la función PyConfig_Clear() para liberar la memoria de configuración.
Métodos de estructura:
void PyConfig_InitPythonConfig(PyConfig *config)
Inicialice la configuración con la Configuración de Python.
void PyConfig_InitIsolatedConfig(PyConfig *config)
Inicialice la configuración con la Configuración Aislada.
PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)
Copia la cadena de caracteres anchos str en *config_str.
Preinicializa Python si es necesario.
PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)
Decodifique str usando Py_DecodeLocale() y establezca el resultado en *config_str.
Preinicializa Python si es necesario.
PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)
Configure los argumentos de la línea de comando (miembro argv de config) de la lista argv de cadenas
de caracteres anchas.
Preinicializa Python si es necesario.
PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)
Establezca argumentos de línea de comando (miembro argv de config) de la lista argv de cadenas de
bytes. Decodifica bytes usando Py_DecodeLocale().
Preinicializa Python si es necesario.
PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t
length, wchar_t **items)
Establece la lista de cadenas de caracteres anchas list a length y items.
Preinicializa Python si es necesario.
PyStatus PyConfig_Read(PyConfig *config)
Lee toda la configuración de Python.
Los campos que ya están inicializados no se modifican.
Los campos para la configuración de ruta ya no se calculan ni modifican al llamar a esta función, a partir
de Python 3.11.
La función PyConfig_Read() solo analiza los argumentos PyConfig.argv una vez:
PyConfig.parse_argv se establece en 2 después de analizar los argumentos. Dado que los ar-
gumentos de Python se eliminan de PyConfig.argv, analizar los argumentos dos veces analizaría las
opciones de la aplicación como opciones de Python.
Preinicializa Python si es necesario.

10.6. PyConfig 209

The Python/C API, Versión 3.11.0

Distinto en la versión 3.10: Los argumentos PyConfig.argv ahora solo se analizan una vez,
PyConfig.parse_argv se establece en 2 después de analizar los argumentos y los argumentos
solo se analizan si PyConfig.parse_argv es igual a 1.
Distinto en la versión 3.11: PyConfig_Read() ya no calcula todas las rutas, por lo que los
campos listados en Python Path Configuration ya no pueden ser actualizados hasta que se llame a
Py_InitializeFromConfig().
void PyConfig_Clear(PyConfig *config)
Libera memoria de configuración.
La mayoría de los método PyConfig preinitializan Python si es necesario. En ese caso, la configuración de
preinicialización de Python (PyPreConfig) se basa en PyConfig. Si se ajustan los campos de configura-
ción que son comunes con PyPreConfig, deben establecerse antes de llamar a un método PyConfig:
• PyConfig.dev_mode
• PyConfig.isolated
• PyConfig.parse_argv
• PyConfig.use_environment
Además, si se usa PyConfig_SetArgv() o PyConfig_SetBytesArgv(), este método debe llamar-
se antes que otros métodos, ya que la configuración de preinicialización depende de los argumentos de la línea
de comando (si parse_argv no es cero).
Quien llama de estos métodos es responsable de manejar las excepciones (error o salida) usando
PyStatus_Exception() y Py_ExitStatusException().
Campos de estructura:
PyWideStringList argv
Argumentos de la línea de comando: sys.argv.
Configure parse_argv en 1 para analizar argv de la misma manera que Python normal analiza los
argumentos de la línea de comandos de Python y luego quita los argumentos de Python de argv.
Si argv está vacío, se agrega una cadena vacía para garantizar que sys.argv siempre exista y nunca
esté vacío.
Valor predeterminado: NULL.
Consulte también el miembro orig_argv.
int safe_path
Si es igual a cero, Py_RunMain() agrega una ruta potencialmente insegura a sys.path al inicio:
• Si argv[0] es igual a L"-m" (python -m module), añade el directorio de trabajo actual.
• If running a script (python script.py), prepend the script’s directory. If it’s a symbolic link,
resolve symbolic links.
• En caso contrario (python -c code and python), añade una cadena vacía, que significa el
directorio de trabajo actual.
Set to 1 by the -P command line option and the PYTHONSAFEPATH environment variable.
Default: 0 in Python config, 1 in isolated config.
Nuevo en la versión 3.11.
wchar_t *base_exec_prefix
sys.base_exec_prefix.
Valor predeterminado: NULL.
Parte de la salida Python Path Configuration.

210 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

wchar_t *base_executable
Ejecutable base de Python: sys._base_executable.
Establecido por la variable de entorno __PYVENV_LAUNCHER__.
Establecido desde PyConfig.executable si NULL.
Valor predeterminado: NULL.
Parte de la salida Python Path Configuration.
wchar_t *base_prefix
sys.base_prefix.
Valor predeterminado: NULL.
Parte de la salida Python Path Configuration.
int buffered_stdio
If equals to 0 and configure_c_stdio is non-zero, disable buffering on the C streams stdout and
stderr.
Set to 0 by the -u command line option and the PYTHONUNBUFFERED environment variable.
stdin siempre se abre en modo de búfer.
Predeterminado: 1.
int bytes_warning
If equals to 1, issue a warning when comparing bytes or bytearray with str, or comparing bytes
with int.
If equal or greater to 2, raise a BytesWarning exception in these cases.
Incrementado por la opción de línea de comando -b.
Predeterminado: 0.
int warn_default_encoding
Si no es cero, emite una advertencia EncodingWarning cuando io.TextIOWrapper usa su co-
dificación predeterminada. Consulte io-encoding-warning para obtener más detalles.
Predeterminado: 0.
Nuevo en la versión 3.10.
int code_debug_ranges
If equals to 0, disables the inclusion of the end line and column mappings in code objects. Also disables
traceback printing carets to specific error locations.
Set to 0 by the PYTHONNODEBUGRANGES environment variable and by the -X no_debug_ranges
command line option.
Predeterminado: 1.
Nuevo en la versión 3.11.
wchar_t *check_hash_pycs_mode
Controla el comportamiento de validación de archivos .pyc basados en hash: valor de la opción de línea
de comando --check-hash-based-pycs.
Valores válidos:
• L"always": Calcula el hash el archivo fuente para invalidación independientemente del valor de
la marca “check_source”.
• L"never": suponga que los pycs basados en hash siempre son válidos.
• L"default": El indicador “check_source” en pycs basados en hash determina la invalidación.

10.6. PyConfig 211

The Python/C API, Versión 3.11.0

Predeterminado: L"default".
Consulte también PEP 552 «Pycs deterministas».
int configure_c_stdio
Si es distinto de cero, configure los flujos estándar de C:
• En Windows, configure el modo binario (O_BINARY) en stdin, stdout y stderr.
• Si buffered_stdio es igual a cero, deshabilite el almacenamiento en búfer de los flujos stdin,
stdout y stderr.
• Si interactive no es cero, habilite el almacenamiento en búfer de flujo en stdin y stdout (solo
stdout en Windows).
Predeterminado: 1 en la configuración de Python, 0 en la configuración aislada.
int dev_mode
Si es distinto de cero, habilita Modo de desarrollo de Python.
Set to 1 by the -X dev option and the PYTHONDEVMODE environment variable.
Por defecto: -1 en modo Python, 0 en modo aislado.
int dump_refs
Dump Python references?
Si no es cero, volcar todos los objetos que aún están vivos en la salida.
Establecido en 1 por la variable de entorno PYTHONDUMPREFS.
Necesita una compilación especial de Python con la macro Py_TRACE_REFS definida: consulte la
opción de configure --with-trace-refs option.
Predeterminado: 0.
wchar_t *exec_prefix
El prefijo de directorio específico del sitio donde se instalan los archivos Python dependientes de la
plataforma: sys.exec_prefix.
Valor predeterminado: NULL.
Parte de la salida Python Path Configuration.
wchar_t *executable
La ruta absoluta del binario ejecutable para el intérprete de Python: sys.executable.
Valor predeterminado: NULL.
Parte de la salida Python Path Configuration.
int faulthandler
¿Habilitar administrador de fallas?
Si no es cero, llama a faulthandler.enable() al inicio.
Establecido en 1 por -X faulthandler y la variable de entorno PYTHONFAULTHANDLER.
Por defecto: -1 en modo Python, 0 en modo aislado.
wchar_t *filesystem_encoding
Codificación del sistema de archvios: sys.getfilesystemencoding().
En macOS, Android y VxWorks: use "utf-8" de forma predeterminada.
En Windows: utilice "utf-8" de forma predeterminada o "mbcs" si
legacy_windows_fs_encoding de PyPreConfig no es cero.
Codificación predeterminada en otras plataformas:
• "utf-8" si PyPreConfig.utf8_mode es distinto de cero.

212 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

• "ascii" if Python detects that nl_langinfo(CODESET) announces the ASCII encoding,

whereas the mbstowcs() function decodes from a different encoding (usually Latin1).
• "utf-8" si nl_langinfo(CODESET) retorna una cadena vacía.
• De lo contrario, utilice el resultado locale encoding: nl_langinfo(CODESET).
Al inicio de Python, el nombre de codificación se normaliza al nombre del códec de Python. Por ejemplo,
"ANSI_X3.4-1968" se reemplaza por "ascii".
Consulte también el miembro filesystem_errors.
wchar_t *filesystem_errors
Manejador de errores del sistema de archivos: sys.getfilesystemencodeerrors().
En Windows: utilice "surrogatepass" de forma predeterminada o "replace" si
legacy_windows_fs_encoding de PyPreConfig no es cero.
En otras plataformas: utilice "surrogateescape" de forma predeterminada.
Controladores de errores admitidos:
• "strict"
• "surrogateescape"
• "surrogatepass" (solo compatible con la codificación UTF-8)
Consulte también el miembro filesystem_encoding.
unsigned long hash_seed

int use_hash_seed
Funciones de semillas aleatorias hash.
Si use_hash_seed es cero, se elige una semilla al azar en el inicio de Python y se ignora hash_seed.
Establecido por la variable de entorno PYTHONHASHSEED.
Valor predeterminado de use_hash_seed: -1 en modo Python, 0 en modo aislado.
wchar_t *home
Directorio de inicio de Python.
Si se ha llamado a Py_SetPythonHome(), use su argumento si no es NULL.
Establecido por la variable de entorno PYTHONHOME.
Valor predeterminado: NULL.
Parte de la entrada Python Path Configuration.
int import_time
Si no es cero, el tiempo de importación del perfil.
Configure el 1 mediante la opción -X importtime y la variable de entorno
PYTHONPROFILEIMPORTTIME.
Predeterminado: 0.
int inspect
Ingresa al modo interactivo después de ejecutar un script o un comando.
If greater than 0, enable inspect: when a script is passed as first argument or the -c option is used, enter
interactive mode after executing the script or the command, even when sys.stdin does not appear to
be a terminal.
Incrementado por la opción de línea de comando -i. Establecido en 1 si la variable de entorno
PYTHONINSPECT no está vacía.
Predeterminado: 0.

10.6. PyConfig 213

The Python/C API, Versión 3.11.0

int install_signal_handlers
¿Instalar controladores de señales de Python?
Por defecto: 1 en modo Python, 0 en modo aislado.
int interactive
If greater than 0, enable the interactive mode (REPL).
Incrementado por la opción de línea de comando -i.
Predeterminado: 0.
int isolated
If greater than 0, enable isolated mode:
• Poner safe_path to 1: no anteponer una ruta potencialmente insegura a sys.path al inicio de
Python.
• Set use_environment to 0.
• Set user_site_directory to 0: don’t add the user site directory to sys.path.
• Python REPL no importa readline ni habilita la configuración predeterminada de readline en
mensajes interactivos.
Set to 1 by the -I command line option.
Por defecto: 0 en modo Python, 1 en modo aislado.
Ver también PyPreConfig.isolated.
int legacy_windows_stdio
Si no es cero, usa io.FileIO en lugar de io.WindowsConsoleIO para sys.stdin, sys.
stdout y sys.stderr.
Establecido en 1 si la variable de entorno PYTHONLEGACYWINDOWSSTDIO está establecida en una
cadena no vacía.
Solo disponible en Windows. La macro #ifdef MS_WINDOWS se puede usar para el código específico
de Windows.
Predeterminado: 0.
Consulte también PEP 528 (Cambiar la codificación de la consola de Windows a UTF-8).
int malloc_stats
Si no es cero, volcar las estadísticas en Asignador de memoria Python pymalloc en la salida.
Establecido en 1 por la variable de entorno PYTHONMALLOCSTATS.
La opción se ignora si Python es configurado usando la opción
--without-pymalloc.
Predeterminado: 0.
wchar_t *platlibdir
Nombre del directorio de la biblioteca de la plataforma: sys.platlibdir.
Establecido por la variable de entorno PYTHONPLATLIBDIR.
Default: value of the PLATLIBDIR macro which is set by the configure --with-platlibdir
option (default: "lib", or "DLLs" on Windows).
Parte de la entrada Python Path Configuration.
Nuevo en la versión 3.9.
Distinto en la versión 3.11: Esta macro se utiliza ahora en Windows para localizar los módulos de exten-
sión de la biblioteca estándar, normalmente en DLLs. Sin embargo, por compatibilidad, tenga en cuenta

214 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

que este valor se ignora para cualquier disposición no estándar, incluyendo las construcciones dentro del
árbol y los entornos virtuales.
wchar_t *pythonpath_env
Rutas de búsqueda de módulos (sys.path) como una cadena separada por DELIM (os.path.
pathsep).
Establecido por la variable de entorno PYTHONPATH.
Valor predeterminado: NULL.
Parte de la entrada Python Path Configuration.
PyWideStringList module_search_paths

int module_search_paths_set
Rutas de búsqueda del módulo: sys.path.
If module_search_paths_set is equal to 0, Py_InitializeFromConfig() will replace
module_search_paths and sets module_search_paths_set to 1.
Por defecto: lista vacía (module_search_paths) y 0 (module_search_paths_set).
Parte de la salida Python Path Configuration.
int optimization_level
Nivel de optimización de compilación:
• 0: Optimizador de mirilla, configure __debug__ en True.
• 1: Nivel 0, elimina las aserciones, establece __debug__ en False.
• 2: Nivel 1, elimina docstrings.
Incrementado por la opción de línea de comando -O. Establecido en el valor de la variable de entorno
PYTHONOPTIMIZE.
Predeterminado: 0.
PyWideStringList orig_argv
La lista de los argumentos originales de la línea de comandos pasados al ejecutable de Python: sys.
orig_argv.
Si la lista orig_argv está vacía y argv no es una lista que solo contiene una cadena vacía,
PyConfig_Read() copia argv en orig_argv antes de modificar argv (si parse_argv no
es cero).
Consulte también el miembro argv y la función Py_GetArgcArgv().
Predeterminado: lista vacía.
Nuevo en la versión 3.10.
int parse_argv
¿Analizar los argumentos de la línea de comando?
Si es igual a 1, analiza argv de la misma forma que Python normal analiza argumentos de línea de
comando y elimina los argumentos de Python de argv.
La función PyConfig_Read() solo analiza los argumentos PyConfig.argv una vez:
PyConfig.parse_argv se establece en 2 después de analizar los argumentos. Dado que los ar-
gumentos de Python se eliminan de PyConfig.argv, analizar los argumentos dos veces analizaría las
opciones de la aplicación como opciones de Python.
Por defecto: 1 en modo Python, 0 en modo aislado.
Distinto en la versión 3.10: Los argumentos PyConfig.argv ahora solo se analizan si PyConfig.
parse_argv es igual a 1.

10.6. PyConfig 215

The Python/C API, Versión 3.11.0

int parser_debug
Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending on
compilation options).
Incrementado por la opción de línea de comando -d. Establecido en el valor de la variable de entorno
PYTHONDEBUG.
Predeterminado: 0.
int pathconfig_warnings
If non-zero, calculation of path configuration is allowed to log warnings into stderr. If equals to 0,
suppress these warnings.
Por defecto: 1 en modo Python, 0 en modo aislado.
Parte de la entrada Python Path Configuration.
Distinto en la versión 3.11: Ahora también se aplica en Windows.
wchar_t *prefix
El prefijo de directorio específico del sitio donde se instalan los archivos Python independientes de la
plataforma: sys.prefix.
Valor predeterminado: NULL.
Parte de la salida Python Path Configuration.
wchar_t *program_name
Nombre del programa utilizado para inicializar executable y en los primeros mensajes de error du-
rante la inicialización de Python.
• Si se ha llamado a Py_SetProgramName(), usa su argumento.
• En macOS, usa la variable de entorno PYTHONEXECUTABLE si está configurada.
• Si se define la macro WITH_NEXT_FRAMEWORK, utiliza la variable de entorno
__PYVENV_LAUNCHER__ si está configurada.
• Utiliza argv[0] de argv si está disponible y no está vacío.
• De lo contrario, utiliza L"python" en Windows o L"python3" en otras plataformas.
Valor predeterminado: NULL.
Parte de la entrada Python Path Configuration.
wchar_t *pycache_prefix
Directorio donde se escriben los archivos .pyc almacenados en caché: sys.pycache_prefix.
Establecido por la opción de línea de comando -X pycache_prefix=PATH y la variable de entorno
PYTHONPYCACHEPREFIX.
Si NULL, sys.pycache_prefix es establecido a None.
Valor predeterminado: NULL.
int quiet
Quiet mode. If greater than 0, don’t display the copyright and version at Python startup in interactive
mode.
Incrementado por la opción de línea de comando -q.
Predeterminado: 0.
wchar_t *run_command
Valor de la opción de línea de comando -c.
Usado por Py_RunMain().
Valor predeterminado: NULL.

216 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

wchar_t *run_filename
Filename passed on the command line: trailing command line argument without -c or -m. It is used by
the Py_RunMain() function.
For example, it is set to script.py by the python3 script.py arg command line.
See also the PyConfig.skip_source_first_line option.
Valor predeterminado: NULL.
wchar_t *run_module
Valor de la opción de línea de comando -m.
Usado por Py_RunMain().
Valor predeterminado: NULL.
int show_ref_count
¿Mostrar el recuento de referencia total en la salida?
Set to 1 by -X showrefcount command line option.
Necesita una compilación de depuración de Python (se debe definir la macro Py_REF_DEBUG).
Predeterminado: 0.
int site_import
¿Importar el módulo site al inicio?
Si es igual a cero, desactive la importación del sitio del módulo y las manipulaciones dependientes del
sitio de sys.path que conlleva.
También deshabilite estas manipulaciones si el módulo site se importa explícitamente más tarde (llame
a site.main() si desea que se activen).
Establecido en 0 mediante la opción de línea de comando -S.
sys.flags.no_site se establece en el valor invertido de site_import.
Predeterminado: 1.
int skip_source_first_line
Si no es cero, omita la primera línea de la fuente PyConfig.run_filename.
Permite el uso de formas de #!cmd que no son Unix. Esto está destinado únicamente a un truco específico
de DOS.
Establecido en 1 mediante la opción de línea de comando -x.
Predeterminado: 0.
wchar_t *stdio_encoding

wchar_t *stdio_errors
Codificación y errores de codificación de sys.stdin, sys.stdout y sys.stderr (pero sys.
stderr siempre usa el controlador de errores "backslashreplace").
Si se ha llamado a Py_SetStandardStreamEncoding(), utilice sus argumentos error y errors si
no son NULL.
Utilice la variable de entorno PYTHONIOENCODING si no está vacía.
Codificación predeterminada:
• "UTF-8" si PyPreConfig.utf8_mode es distinto de cero.
• De lo contrario, usa el locale encoding.
Manejador de errores predeterminado:
• En Windows: use "surrogateescape".

10.6. PyConfig 217

The Python/C API, Versión 3.11.0

• "surrogateescape" si PyPreConfig.utf8_mode no es cero o si la configuración regio-

nal LC_CTYPE es «C» o «POSIX».
• "strict" de lo contrario.
int tracemalloc
¿Habilitar tracemalloc?
Si no es cero, llama a tracemalloc.start() al inicio.
Establecido por la opción de línea de comando -X tracemalloc=N y por la variable de entorno
PYTHONTRACEMALLOC.
Por defecto: -1 en modo Python, 0 en modo aislado.
int use_environment
¿Utiliza variables de entorno?
Si es igual a cero, ignora las variables de entorno.
Set to 0 by the -E environment variable.
Predeterminado: 1 en la configuración de Python y 0 en la configuración aislada.
int user_site_directory
Si es distinto de cero, agregue el directorio del sitio del usuario a sys.path.
Establecido en 0 por las opciones de línea de comando -s y -I.
Establecido en 0 por la variable de entorno PYTHONNOUSERSITE.
Por defecto: 1 en modo Python, 0 en modo aislado.
int verbose
Verbose mode. If greater than 0, print a message each time a module is imported, showing the place
(filename or built-in module) from which it is loaded.
If greater or equal to 2, print a message for each file that is checked for when searching for a module.
Also provides information on module cleanup at exit.
Incrementado por la opción de línea de comando -v.
Establecido en el valor de la variable de entorno PYTHONVERBOSE.
Predeterminado: 0.
PyWideStringList warnoptions
Opciones del módulo warnings para crear filtros de advertencias, de menor a mayor prioridad: sys.
warnoptions.
El módulo warnings agrega sys.warnoptions en el orden inverso: el último elemento
PyConfig.warnoptions se convierte en el primer elemento de warnings.filters que es
verificado primero (máxima prioridad).
Las opciones de la línea de comando -W agregan su valor a warnoptions, se puede usar varias veces.
La variable de entorno PYTHONWARNINGS también se puede utilizar para agregar opciones de adver-
tencia. Se pueden especificar varias opciones, separadas por comas (,).
Predeterminado: lista vacía.
int write_bytecode
If equal to 0, Python won’t try to write .pyc files on the import of source modules.
Establecido en 0 por la opción de línea de comando -B y la variable de entorno
PYTHONDONTWRITEBYTECODE.
sys.dont_write_bytecode se inicializa al valor invertido de write_bytecode.
Predeterminado: 1.

218 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

PyWideStringList xoptions
Valores de las opciones de la línea de comando -X: sys._xoptions.
Predeterminado: lista vacía.
Si parse_argv no es cero, los argumentos de argv se analizan de la misma forma que Python normal analiza
argumentos de línea de comando, y los argumentos de Python se eliminan de argv.
Las opciones de xoptions se analizan para establecer otras opciones: consulte la opción de línea de comando -X.
Distinto en la versión 3.9: El campo show_alloc_count fue removido.

10.7 Inicialización con PyConfig

Función para inicializar Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)
Inicializa Python desde la configuración config.
La persona que llama es responsable de manejar las excepciones (error o salida) usando PyStatus_Exception()
y Py_ExitStatusException().
Si se utilizan PyImport_FrozenModules(), PyImport_AppendInittab() o
PyImport_ExtendInittab(), deben establecerse o llamarse después de la preinicialización de
Python y antes de la inicialización de Python. Si Python se inicializa varias veces, se debe llamar a
PyImport_AppendInittab() o PyImport_ExtendInittab() antes de cada inicialización de
Python.
La configuración actual (tipo PyConfig) se almacena en PyInterpreterState.config.
Ejemplo de configuración del nombre del programa:

void init_python(void)
{
PyStatus status;

PyConfig config;
PyConfig_InitPythonConfig(&config);

/* Set the program name. Implicitly preinitialize Python. */

status = PyConfig_SetString(&config, &config.program_name,
L"/path/to/my_program");
if (PyStatus_Exception(status)) {
goto exception;
}

status = Py_InitializeFromConfig(&config);
if (PyStatus_Exception(status)) {
goto exception;
}
PyConfig_Clear(&config);
return;

exception:
PyConfig_Clear(&config);
Py_ExitStatusException(status);
}

More complete example modifying the default configuration, read the configuration, and then override some para-
meters. Note that since 3.11, many parameters are not calculated until initialization, and so values cannot be read
from the configuration structure. Any values set before initialize is called will be left unchanged by initialization:

10.7. Inicialización con PyConfig 219

The Python/C API, Versión 3.11.0

PyStatus init_python(const char *program_name)

{
PyStatus status;

PyConfig config;
PyConfig_InitPythonConfig(&config);

/* Set the program name before reading the configuration

(decode byte string from the locale encoding).

Implicitly preinitialize Python. */

status = PyConfig_SetBytesString(&config, &config.program_name,
program_name);
if (PyStatus_Exception(status)) {
goto done;
}

/* Read all configuration at once */

status = PyConfig_Read(&config);
if (PyStatus_Exception(status)) {
goto done;
}

/* Specify sys.path explicitly */

/* If you want to modify the default set of paths, finish
initialization first and then use PySys_GetObject("path") */
config.module_search_paths_set = 1;
status = PyWideStringList_Append(&config.module_search_paths,
L"/path/to/stdlib");
if (PyStatus_Exception(status)) {
goto done;
}
status = PyWideStringList_Append(&config.module_search_paths,
L"/path/to/more/modules");
if (PyStatus_Exception(status)) {
goto done;
}

/* Override executable computed by PyConfig_Read() */

status = PyConfig_SetString(&config, &config.executable,
L"/path/to/my_executable");
if (PyStatus_Exception(status)) {
goto done;
}

status = Py_InitializeFromConfig(&config);

done:
PyConfig_Clear(&config);
return status;
}

220 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

10.8 Configuración aislada

PyPreConfig_InitIsolatedConfig() y las funciones PyConfig_InitIsolatedConfig() crean

una configuración para aislar Python del sistema. Por ejemplo, para incrustar Python en una aplicación.
This configuration ignores global configuration variables, environment variables, command line arguments
(PyConfig.argv is not parsed) and user site directory. The C standard streams (ex: stdout) and the
LC_CTYPE locale are left unchanged. Signal handlers are not installed.
Los archivos de configuración se siguen utilizando con esta configuración para determinar las rutas que no se espe-
cifican. Asegúrese de que se especifica PyConfig.home para evitar que se calcule la configuración de la ruta por
defecto.

10.9 Configuración de Python

PyPreConfig_InitPythonConfig() y las funciones PyConfig_InitPythonConfig() crean una

configuración para construir un Python personalizado que se comporta como el Python normal.
Las variables de entorno y los argumentos de la línea de comandos se utilizan para configurar Python, mientras que
las variables de configuración global se ignoran.
Esta función habilita la coerción de configuración regional C (PEP 538) y Python UTF-8 Mode (PEP 540) según la
configuración regional LC_CTYPE, las variables de entorno PYTHONUTF8 y PYTHONCOERCECLOCALE.

10.10 Configuración de la ruta de Python

PyConfig contiene múltiples campos para la configuración de ruta:

• Entradas de configuración de ruta:
– PyConfig.home
– PyConfig.platlibdir
– PyConfig.pathconfig_warnings
– PyConfig.program_name
– PyConfig.pythonpath_env
– directorio de trabajo actual: para obtener rutas absolutas
– Variable de entorno PATH para obtener la ruta completa del programa (de PyConfig.
program_name)
– Variable de entorno __PYVENV_LAUNCHER__
– (Solo Windows) Rutas de aplicación en el registro en «SoftwarePythonPythonCoreX.YPythonPath» de
HKEY_CURRENT_USER y HKEY_LOCAL_MACHINE (donde X.Y es la versión de Python).
• Campos de salida de configuración de ruta:
– PyConfig.base_exec_prefix
– PyConfig.base_executable
– PyConfig.base_prefix
– PyConfig.exec_prefix
– PyConfig.executable
– PyConfig.module_search_paths_set, PyConfig.module_search_paths
– PyConfig.prefix

10.8. Configuración aislada 221

The Python/C API, Versión 3.11.0

Si al menos un «campo de salida» no está establecido, Python calcula la configuración de la ruta para rellenar los
campos no establecidos. Si module_search_paths_set es igual a 0, module_search_paths se anula y
module_search_paths_set se establece en 1.
It is possible to completely ignore the function calculating the default path configuration by setting expli-
citly all path configuration output fields listed above. A string is considered as set even if it is non-empty.
module_search_paths is considered as set if module_search_paths_set is set to 1. In this case,
module_search_paths will be used without modification.
Set pathconfig_warnings to 0 to suppress warnings when calculating the path configuration (Unix only, Win-
dows does not log any warning).
Si base_prefix o los campos base_exec_prefix no están establecidos, heredan su valor de prefix y
exec_prefix respectivamente.
Py_RunMain() y Py_Main() modifican sys.path:
• Si run_filename está configurado y es un directorio que contiene un script __main__.py, anteponga
run_filename a sys.path.
• Si isolated es cero:
– Si run_module está configurado, anteponga el directorio actual a sys.path. No haga nada si el
directorio actual no se puede leer.
– Si run_filename está configurado, anteponga el directorio del nombre del archivo a sys.path.
– De lo contrario, anteponga una cadena de caracteres vacía a sys.path.
Si site_import no es cero, sys.path puede ser modificado por el módulo site. Si
user_site_directory no es cero y el directorio del paquete del sitio del usuario existe, el módulo
site agrega el directorio del paquete del sitio del usuario a sys.path.
La configuración de ruta utiliza los siguientes archivos de configuración:
• pyvenv.cfg
• archivo“._pth“ (ej: python._pth)
• pybuilddir.txt (sólo Unix)
Si un archivo ._pth está presente:
• Set isolated to 1.
• Set use_environment to 0.
• Set site_import to 0.
• Set safe_path to 1.
La variable de entorno __PYVENV_LAUNCHER__ se usa para establecer PyConfig.base_executable

10.11 Py_RunMain()

int Py_RunMain(void)
Ejecuta el comando (PyConfig.run_command), el script (PyConfig.run_filename) o el módulo
(PyConfig.run_module) especificado en la línea de comando o en la configuración.
Por defecto y cuando se usa la opción -i, ejecuta el REPL.
Finalmente, finaliza Python y retorna un estado de salida que se puede pasar a la función exit().
Consulte Configuración de Python para ver un ejemplo de Python personalizado que siempre se ejecuta en modo
aislado usando Py_RunMain().

222 Capítulo 10. Configuración de inicialización de Python

 The Python/C API, Versión 3.11.0

10.12 Py_GetArgcArgv()

void Py_GetArgcArgv(int *argc, wchar_t ***argv)

Obtiene los argumentos originales de la línea de comandos, antes de que Python los modificara.
Ver también el miembro PyConfig.orig_argv.

10.13 API Provisional Privada de Inicialización Multifásica

This section is a private provisional API introducing multi-phase initialization, the core feature of PEP 432:
• Fase de inicialización «Core», «Python mínimo»:
– Tipos incorporados;
– Excepciones incorporadas;
– Módulos incorporados y congelados;
– El módulo sys solo se inicializa parcialmente (por ejemplo sys.path aún no existe).
• Fase de inicialización «principal», Python está completamente inicializado:
– Instala y configura importlib;
– Aplique la Configuración de ruta;
– Instala manejadores de señal;
– Finaliza la inicialización del módulo sys (por ejemplo: crea sys.stdout y sys.path);
– Habilita características opcionales como faulthandler y tracemalloc;
– Importe el módulo site;
– etc.
API provisional privada:
• PyConfig._init_main: if set to 0, Py_InitializeFromConfig() stops at the «Core» initializa-
tion phase.
• PyConfig._isolated_interpreter: si no es cero, no permite hilos, subprocesos y bifurcaciones.
PyStatus _Py_InitializeMain(void)
Vaya a la fase de inicialización «Principal», finalice la inicialización de Python.
No se importa ningún módulo durante la fase «Core» y el módulo importlib no está configurado: la Configuración
de ruta solo se aplica durante la fase «Principal». Puede permitir personalizar Python en Python para anular o ajustar
Configuración de ruta, tal vez instale un importador personalizado sys.meta_path o un enlace de importación,
etc.
Puede ser posible calcular Configuración de ruta en Python, después de la fase Core y antes de la fase Main, que es
una de las motivaciones PEP 432.
La fase «Núcleo» no está definida correctamente: lo que debería estar y lo que no debería estar disponible en esta
fase aún no se ha especificado. La API está marcada como privada y provisional: la API se puede modificar o incluso
eliminar en cualquier momento hasta que se diseñe una API pública adecuada.
Ejemplo de ejecución de código Python entre las fases de inicialización «Core» y «Main»:
void init_python(void)
{
PyStatus status;

PyConfig config;
(continué en la próxima página)

10.12. Py_GetArgcArgv() 223

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

PyConfig_InitPythonConfig(&config);
config._init_main = 0;

/* ... customize 'config' configuration ... */

status = Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);
if (PyStatus_Exception(status)) {
Py_ExitStatusException(status);
}

/* Use sys.stderr because sys.stdout is only created

by _Py_InitializeMain() */
int res = PyRun_SimpleString(
"import sys; "
"print('Run Python code before _Py_InitializeMain', "
"file=sys.stderr)");
if (res < 0) {
exit(1);
}

/* ... put more configuration code here ... */

status = _Py_InitializeMain();
if (PyStatus_Exception(status)) {
Py_ExitStatusException(status);
}
}

224 Capítulo 10. Configuración de inicialización de Python

 CAPÍTULO 11

Gestión de la memoria

11.1 Visión general

La gestión de memoria en Python implica un montón privado que contiene todos los objetos de Python y estructu-
ras de datos. El administrador de memoria de Python garantiza internamente la gestión de este montón privado. El
administrador de memoria de Python tiene diferentes componentes que se ocupan de varios aspectos de la gestión
dinámica del almacenamiento, como compartir, segmentación, asignación previa o almacenamiento en caché.
En el nivel más bajo, un asignador de memoria sin procesar asegura que haya suficiente espacio en el montón privado
para almacenar todos los datos relacionados con Python al interactuar con el administrador de memoria del sistema
operativo. Además del asignador de memoria sin procesar, varios asignadores específicos de objeto operan en el
mismo montón e implementan políticas de administración de memoria distintas adaptadas a las peculiaridades de
cada tipo de objeto. Por ejemplo, los objetos enteros se administran de manera diferente dentro del montón que las
cadenas, tuplas o diccionarios porque los enteros implican diferentes requisitos de almacenamiento y compensaciones
de velocidad / espacio. El administrador de memoria de Python delega parte del trabajo a los asignadores específicos
de objeto, pero asegura que este último opere dentro de los límites del montón privado.
Es importante comprender que la gestión del montón de Python la realiza el propio intérprete y que el usuario no
tiene control sobre él, incluso si manipulan regularmente punteros de objetos a bloques de memoria dentro de ese
montón. El administrador de memoria de Python realiza la asignación de espacio de almacenamiento dinámico para
los objetos de Python y otros búferes internos a pedido a través de las funciones de API de Python/C enumeradas en
este documento.
Para evitar daños en la memoria, los escritores de extensiones nunca deberían intentar operar en objetos Python con
las funciones exportadas por la biblioteca C: malloc(), calloc(), realloc() y free(). Esto dará como
resultado llamadas mixtas entre el asignador de C y el administrador de memoria de Python con consecuencias fatales,
ya que implementan diferentes algoritmos y operan en diferentes montones. Sin embargo, uno puede asignar y liberar
de forma segura bloques de memoria con el asignador de la biblioteca C para fines individuales, como se muestra en
el siguiente ejemplo:

PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyBytes_FromString(buf);
(continué en la próxima página)

225
The Python/C API, Versión 3.11.0

(proviene de la página anterior)

free(buf); /* malloc'ed */
return res;

En este ejemplo, la solicitud de memoria para el búfer de E/S es manejada por el asignador de la biblioteca C. El
administrador de memoria de Python solo participa en la asignación del objeto de bytes retornado como resultado.
Sin embargo, en la mayoría de las situaciones, se recomienda asignar memoria del montón de Python específicamente
porque este último está bajo el control del administrador de memoria de Python. Por ejemplo, esto es necesario cuando
el intérprete se amplía con nuevos tipos de objetos escritos en C. Otra razón para usar el montón de Python es el deseo
de informar al administrador de memoria de Python sobre las necesidades de memoria del módulo de extensión.
Incluso cuando la memoria solicitada se usa exclusivamente para fines internos y altamente específicos, delegar todas
las solicitudes de memoria al administrador de memoria de Python hace que el intérprete tenga una imagen más
precisa de su huella de memoria en su conjunto. En consecuencia, bajo ciertas circunstancias, el administrador de
memoria de Python puede o no desencadenar acciones apropiadas, como recolección de basura, compactación de
memoria u otros procedimientos preventivos. Tenga en cuenta que al usar el asignador de la biblioteca C como se
muestra en el ejemplo anterior, la memoria asignada para el búfer de E/S escapa completamente al administrador de
memoria Python.
Ver también:
La variable de entorno PYTHONMALLOC puede usarse para configurar los asignadores de memoria utilizados por
Python.
La variable de entorno PYTHONMALLOCSTATS se puede utilizar para imprimir estadísticas de asignador de me-
moria pymalloc cada vez que se crea un nuevo escenario de objetos pymalloc, y en el apagado.

11.2 Dominios del asignador

Todas las funciones de asignación pertenecen a uno de los tres «dominios» diferentes (ver también
PyMemAllocatorDomain). Estos dominios representan diferentes estrategias de asignación y están optimiza-
dos para diferentes propósitos. Los detalles específicos sobre cómo cada dominio asigna memoria o qué funciones
internas llama cada dominio se considera un detalle de implementación, pero para fines de depuración, se puede en-
contrar una tabla simplificada en here. No existe un requisito estricto para usar la memoria retornada por las funciones
de asignación que pertenecen a un dominio dado solo para los propósitos sugeridos por ese dominio (aunque esta
es la práctica recomendada). Por ejemplo, se podría usar la memoria retornada por PyMem_RawMalloc() para
asignar objetos Python o la memoria retornada por PyObject_Malloc() para asignar memoria para búferes.
Los tres dominios de asignación son:
• Dominio sin formato: destinado a asignar memoria para búferes de memoria de uso general donde la asig-
nación debe ir al asignador del sistema o donde el asignador puede operar sin el GIL. La memoria se solicita
directamente al sistema.
• Dominio «Mem»: destinado a asignar memoria para búferes de Python y búferes de memoria de propósito
general donde la asignación debe realizarse con el GIL retenido. La memoria se toma del montículo privado de
Python.
• Dominio de objeto: destinado a asignar memoria perteneciente a objetos de Python. La memoria se toma del
montículo privado de Python.
Cuando se libera memoria previamente asignada por las funciones de asignación que pertenecen a un dominio dado,
se deben utilizar las funciones de desasignación específicas coincidentes. Por ejemplo, PyMem_Free() debe usarse
para liberar memoria asignada usando PyMem_Malloc().

226 Capítulo 11. Gestión de la memoria

 The Python/C API, Versión 3.11.0

11.3 Interfaz de memoria sin procesar

Los siguientes conjuntos de funciones son envoltorios para el asignador del sistema. Estas funciones son seguras para
subprocesos, no es necesario mantener el GIL.
El asignador de memoria sin procesar predeterminado usa las siguientes funciones: malloc(), calloc(),
realloc() y free(); llame a malloc(1) (o calloc(1, 1)) cuando solicita cero bytes.
Nuevo en la versión 3.4.
void *PyMem_RawMalloc(size_t n)
Asigna n bytes y retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla.
Solicitar cero bytes retorna un puntero distinto que no sea NULL si es posible, como si en su lugar se hubiera
llamado a PyMem_RawMalloc(1). La memoria no se habrá inicializado de ninguna manera.
void *PyMem_RawCalloc(size_t nelem, size_t elsize)
Asigna nelem elementos cada uno cuyo tamaño en bytes es elsize y retorna un puntero de tipo void* a la
memoria asignada, o NULL si la solicitud falla. La memoria se inicializa a ceros.
Solicitar elementos cero o elementos de tamaño cero bytes retorna un puntero distinto NULL si es posible,
como si en su lugar se hubiera llamado PyMem_RawCalloc(1, 1).
Nuevo en la versión 3.5.
void *PyMem_RawRealloc(void *p, size_t n)
Cambia el tamaño del bloque de memoria señalado por p a n bytes. Los contenidos no se modificarán al mínimo
de los tamaños antiguo y nuevo.
Si p es NULL, la llamada es equivalente a PyMem_RawMalloc(n); de lo contrario, si n es igual a cero, el
bloque de memoria cambia de tamaño pero no se libera, y el puntero retornado no es NULL.
A menos que p sea NULL, debe haber sido retornado por una llamada previa a PyMem_RawMalloc(),
PyMem_RawRealloc() o PyMem_RawCalloc().
Si la solicitud falla, PyMem_RawRealloc() retorna NULL y p sigue siendo un puntero válido al área de
memoria anterior.
void PyMem_RawFree(void *p)
Libera el bloque de memoria al que apunta p, que debe haber sido retornado por una llamada anterior a
PyMem_RawMalloc(), PyMem_RawRealloc() o PyMem_RawCalloc(). De lo contrario, o si se
ha llamado antes a PyMem_RawFree(p), se produce un comportamiento indefinido.
Si p es NULL, no se realiza ninguna operación.

11.4 Interfaz de memoria

Los siguientes conjuntos de funciones, modelados según el estándar ANSI C, pero que especifican el comportamiento
cuando se solicitan cero bytes, están disponibles para asignar y liberar memoria del montón de Python.
El asignador de memoria predeterminado usa el asignador de memorya pymalloc.

Advertencia: El GIL debe mantenerse cuando se utilizan estas funciones.

Distinto en la versión 3.6: El asignador predeterminado ahora es pymalloc en lugar del malloc() del sistema.
void *PyMem_Malloc(size_t n)
Part of the Stable ABI. Asigna n bytes y retorna un puntero de tipo void* a la memoria asignada, o NULL si
la solicitud falla.
Solicitar cero bytes retorna un puntero distinto que no sea NULL si es posible, como si en su lugar se hubiera
llamado a PyMem_Malloc(1). La memoria no se habrá inicializado de ninguna manera.

11.3. Interfaz de memoria sin procesar 227

The Python/C API, Versión 3.11.0

void *PyMem_Calloc(size_t nelem, size_t elsize)

Part of the Stable ABI since version 3.7. Asigna nelem elementos cada uno cuyo tamaño en bytes es elsize y
retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla. La memoria se inicializa
a ceros.
Solicitar elementos cero o elementos de tamaño cero bytes retorna un puntero distinto NULL si es posible,
como si en su lugar se hubiera llamado PyMem_Calloc(1, 1).
Nuevo en la versión 3.5.
void *PyMem_Realloc(void *p, size_t n)
Part of the Stable ABI. Cambia el tamaño del bloque de memoria señalado por p a n bytes. Los contenidos no
se modificarán al mínimo de los tamaños antiguo y nuevo.
Si p es NULL, la llamada es equivalente a PyMem_Malloc(n); de lo contrario, si n es igual a cero, el bloque
de memoria cambia de tamaño pero no se libera, y el puntero retornado no es NULL.
A menos que p sea NULL, debe haber sido retornado por una llamada previa a PyMem_Malloc(),
PyMem_Realloc() o PyMem_Calloc().
Si la solicitud falla, PyMem_Realloc() retorna NULL y p sigue siendo un puntero válido al área de memoria
anterior.
void PyMem_Free(void *p)
Part of the Stable ABI. Libera el bloque de memoria señalado por p, que debe haber sido retornado por una
llamada anterior a PyMem_Malloc(), PyMem_Realloc() o PyMem_Calloc(). De lo contrario, o si
se ha llamado antes a PyMem_Free(p), se produce un comportamiento indefinido.
Si p es NULL, no se realiza ninguna operación.
Las siguientes macros orientadas a tipos se proporcionan por conveniencia. Tenga en cuenta que TYPE se refiere a
cualquier tipo de C.
TYPE *PyMem_New(TYPE, size_t n)
Igual que PyMem_Malloc(), pero asigna (n * sizeof(TYPE)) bytes de memoria. Retorna una con-
versión de puntero a TYPE*. La memoria no se habrá inicializado de ninguna manera.
TYPE *PyMem_Resize(void *p, TYPE, size_t n)
Igual que PyMem_Realloc(), pero el bloque de memoria cambia de tamaño a (n * sizeof(TYPE))
bytes. Retorna una conversión de puntero a TYPE*. Al retornar, p será un puntero a la nueva área de memoria,
o NULL en caso de falla.
Esta es una macro de preprocesador C; p siempre se reasigna. Guarde el valor original de p para evitar perder
memoria al manejar errores.
void PyMem_Del(void *p)
La misma que PyMem_Free().
Además, se proporcionan los siguientes conjuntos de macros para llamar al asignador de memoria de Python direc-
tamente, sin involucrar las funciones de API de C mencionadas anteriormente. Sin embargo, tenga en cuenta que su
uso no conserva la compatibilidad binaria entre las versiones de Python y, por lo tanto, está en desuso en los módulos
de extensión.
• PyMem_MALLOC(size)
• PyMem_NEW(type, size)
• PyMem_REALLOC(ptr, size)
• PyMem_RESIZE(ptr, type, size)
• PyMem_FREE(ptr)
• PyMem_DEL(ptr)

228 Capítulo 11. Gestión de la memoria

 The Python/C API, Versión 3.11.0

11.5 Asignadores de objetos

Los siguientes conjuntos de funciones, modelados según el estándar ANSI C, pero que especifican el comportamiento
cuando se solicitan cero bytes, están disponibles para asignar y liberar memoria del montón de Python.

Nota: No hay garantía de que la memoria retornada por estos asignadores se pueda convertir con éxito en un ob-
jeto Python al interceptar las funciones de asignación en este dominio mediante los métodos descritos en la sección
Personalizar Asignadores de Memoria.

El asignador predeterminado de objetos usa el asignador de memoria pymalloc.

Advertencia: El GIL debe mantenerse cuando se utilizan estas funciones.

void *PyObject_Malloc(size_t n)
Part of the Stable ABI. Asigna n bytes y retorna un puntero de tipo void* a la memoria asignada, o NULL si
la solicitud falla.
Solicitar cero bytes retorna un puntero distinto que no sea NULL si es posible, como si en su lugar se hubiera
llamado a PyObject_Malloc(1). La memoria no se habrá inicializado de ninguna manera.
void *PyObject_Calloc(size_t nelem, size_t elsize)
Part of the Stable ABI since version 3.7. Asigna nelem elementos cada uno cuyo tamaño en bytes es elsize y
retorna un puntero de tipo void* a la memoria asignada, o NULL si la solicitud falla. La memoria se inicializa
a ceros.
Solicitar elementos cero o elementos de tamaño cero bytes retorna un puntero distinto NULL si es posible,
como si en su lugar se hubiera llamado PyObject_Calloc(1, 1).
Nuevo en la versión 3.5.
void *PyObject_Realloc(void *p, size_t n)
Part of the Stable ABI. Cambia el tamaño del bloque de memoria señalado por p a n bytes. Los contenidos no
se modificarán al mínimo de los tamaños antiguo y nuevo.
Si p es NULL, la llamada es equivalente a PyObject_Malloc(n); de lo contrario, si n es igual a cero, el
bloque de memoria cambia de tamaño pero no se libera, y el puntero retornado no es NULL.
A menos que p sea NULL, debe haber sido retornado por una llamada previa a PyObject_Malloc(),
PyObject_Realloc() o PyObject_Calloc().
Si la solicitud falla, PyObject_Realloc() retorna NULL y p sigue siendo un puntero válido al área de
memoria anterior.
void PyObject_Free(void *p)
Part of the Stable ABI. Libera el bloque de memoria al que apunta p, que debe haber sido retornado por una
llamada anterior a PyObject_Malloc(), PyObject_Realloc() o PyObject_Calloc(). De lo
contrario, o si se ha llamado antes a PyObject_Free(p), se produce un comportamiento indefinido.
Si p es NULL, no se realiza ninguna operación.

11.5. Asignadores de objetos 229

The Python/C API, Versión 3.11.0

11.6 Asignadores de memoria predeterminados

Asignadores de memoria predeterminados:

Configuración Nombre Py- Py- PyOb-

Mem_RawMalloc Mem_Malloc ject_Malloc
Lanzamiento de compilación "pymalloc" malloc malloc + de- malloc + de-
bug bug
Compilación de depuración "pymalloc_debug"
malloc + de- pymalloc + pymalloc +
bug debug debug
Lanzamiento de compilación, sin "malloc" malloc malloc malloc
pymalloc
Compilación de depuración, sin "malloc_debug" malloc + de- malloc + de- malloc + de-
pymalloc bug bug bug

Leyenda:
• Nombre: valor para variable de entorno PYTHONMALLOC.
• malloc: asignadores del sistema de la biblioteca C estándar, funciones C: malloc(), calloc(),
realloc() y free().
• pymalloc: asignador de memoria pymalloc.
• «+ debug»: con enlaces de depuración en los asignadores de memoria de Python.
• «Debug build»: Compilación de Python en modo de depuración.

11.7 Personalizar asignadores de memoria

Nuevo en la versión 3.4.

type PyMemAllocatorEx
Estructura utilizada para describir un asignador de bloque de memoria. La estructura tiene cuatro campos:

Campo Significado
void *ctx contexto de usuario pasado como primer
argumento
void* malloc(void *ctx, size_t size) asignar un bloque de memoria
void* calloc(void *ctx, size_t nelem, asignar un bloque de memoria inicializado
size_t elsize) con ceros
void* realloc(void *ctx, void *ptr, asignar o cambiar el tamaño de un bloque
size_t new_size) de memoria
void free(void *ctx, void *ptr) liberar un bloque de memoria

Distinto en la versión 3.5: La estructura PyMemAllocator se renombró a PyMemAllocatorEx y se

agregó un nuevo campo calloc.
type PyMemAllocatorDomain
Enum se utiliza para identificar un dominio asignador. Dominios:
PYMEM_DOMAIN_RAW
Funciones:
• PyMem_RawMalloc()
• PyMem_RawRealloc()
• PyMem_RawCalloc()

230 Capítulo 11. Gestión de la memoria

 The Python/C API, Versión 3.11.0

• PyMem_RawFree()
PYMEM_DOMAIN_MEM
Funciones:
• PyMem_Malloc(),
• PyMem_Realloc()
• PyMem_Calloc()
• PyMem_Free()
PYMEM_DOMAIN_OBJ
Funciones:
• PyObject_Malloc()
• PyObject_Realloc()
• PyObject_Calloc()
• PyObject_Free()
void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
Obtenga el asignador de bloque de memoria del dominio especificado.
void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
Establece el asignador de bloque de memoria del dominio especificado.
El nuevo asignador debe retornar un puntero distinto NULL al solicitar cero bytes.
Para el dominio PYMEM_DOMAIN_RAW, el asignador debe ser seguro para subprocesos: el GIL no se mantiene
cuando se llama al asignador.
Si el nuevo asignador no es un enlace (no llama al asignador anterior), se debe llamar a la función
PyMem_SetupDebugHooks() para reinstalar los enlaces de depuración en la parte superior del nuevo
asignador.
Vea también PyPreConfig.allocator y Preinicialización de Python con PyPreConfig.

Advertencia: PyMem_SetAllocator() does have the following contract:

• It can be called after Py_PreInitialize() and before Py_InitializeFromConfig()
to install a custom memory allocator. There are no restrictions over the installed allocator other than
the ones imposed by the domain (for instance, the Raw Domain allows the allocator to be called
without the GIL held). See the section on allocator domains for more information.
• If called after Python has finish initializing (after Py_InitializeFromConfig() has been
called) the allocator must wrap the existing allocator. Substituting the current allocator for some
other arbitrary one is not supported.

void PyMem_SetupDebugHooks(void)
Configurar enlaces de depuración en los asignadores de memoria de Python para detectar errores de memoria.

11.7. Personalizar asignadores de memoria 231

The Python/C API, Versión 3.11.0

11.8 Configurar enlaces para detectar errores en las funciones del

asignador de memoria de Python

Cuando Python está construido en modo de depuración, la función PyMem_SetupDebugHooks() se llama en

Preinicialización de Python para configurar los enlaces de depuración en Python asignadores de memoria para detectar
errores de memoria.
La variable de entorno PYTHONMALLOC se puede utilizar para instalar enlaces de depuración en un Python compi-
lado en modo de lanzamiento (por ejemplo: PYTHONMALLOC=debug).
La función PyMem_SetupDebugHooks() se puede utilizar para establecer enlaces de depuración después de
llamar a PyMem_SetAllocator().
Estos enlaces de depuración llenan bloques de memoria asignados dinámicamente con patrones de bits especiales y
reconocibles. La memoria recién asignada se llena con el byte 0xCD (PYMEM_CLEANBYTE), la memoria liberada
se llena con el byte 0xDD (PYMEM_DEADBYTE). Los bloques de memoria están rodeados por «bytes prohibidos»
rellenos con el byte 0xFD (PYMEM_FORBIDDENBYTE). Es poco probable que las cadenas de estos bytes sean
direcciones válidas, flotantes o cadenas ASCII.
Verificaciones de tiempo de ejecución:
• Detecte violaciones de API, por ejemplo: PyObject_Free() llamado en un búfer asignado por
PyMem_Malloc().
• Detectar escritura antes del inicio del búfer (desbordamiento del búfer)
• Detectar escritura después del final del búfer (desbordamiento del búfer)
• Comprueba que GIL se mantiene cuando las funciones del asignador de PYMEM_DOMAIN_OBJ (ej:
PyObject_Malloc()) y dominios PYMEM_DOMAIN_MEM (por ejemplo: PyMem_Malloc()) se lla-
man.
En caso de error, los enlaces de depuración usan el módulo tracemalloc para obtener el rastreo donde se asignó
un bloque de memoria. El rastreo solo se muestra si tracemalloc rastrea las asignaciones de memoria de Python
y se rastrea el bloque de memoria.
Sea S*=“sizeof(size_t)“. Se agregan “2*S“ bytes en cada extremo de cada bloque de *N bytes solicitados. El diseño de
la memoria es así, donde p representa la dirección retornada por una función similar a malloc o realloc (p[i:j]
significa el segmento de bytes de *(p+i) inclusive hasta *(p+j) exclusivo; tenga en cuenta que el tratamiento de
los índices negativos difiere de un segmento de Python):
p[-2*S:-S] Número de bytes solicitados originalmente. Este es un size_t, big-endian (más fácil de leer en un
volcado de memoria).
p[-S] Identificador de API (carácter ASCII):
• 'r' para PYMEM_DOMAIN_RAW.
• 'm' para PYMEM_DOMAIN_MEM.
• 'o' para PYMEM_DOMAIN_OBJ.
p[-S+1:0] Copias de PYMEM_FORBIDDENBYTE. Se utiliza para detectar suscripciones y lecturas.
p[0:N] La memoria solicitada, llena de copias de PYMEM_CLEANBYTE, utilizada para capturar la referencia a
la memoria no inicializada. Cuando se llama a una función similar a realloc solicitando un bloque de memoria
más grande, los nuevos bytes en exceso también se llenan con PYMEM_CLEANBYTE. Cuando se llama a
una función de tipo free, se sobrescriben con PYMEM_DEADBYTE, para captar la referencia a la memoria
liberada. Cuando se llama a una función similar a la realloc solicitando un bloque de memoria más pequeño,
los bytes antiguos sobrantes también se llenan con PYMEM_DEADBYTE.
p[N:N+S] Copias de PYMEM_FORBIDDENBYTE. Se utiliza para detectar sobrescrituras y lecturas.
p[N+S:N+2*S] Solo se utiliza si la macro PYMEM_DEBUG_SERIALNO está definida (no definida por defecto).

232 Capítulo 11. Gestión de la memoria

 The Python/C API, Versión 3.11.0

Un número de serie, incrementado en 1 en cada llamada a una función similar a malloc o realloc. Big-endian
size_t. Si se detecta «mala memoria» más tarde, el número de serie ofrece una excelente manera de estable-
cer un punto de interrupción en la siguiente ejecución, para capturar el instante en el que se pasó este bloque.
La función estática bumpserialno() en obmalloc.c es el único lugar donde se incrementa el número de serie, y
existe para que pueda establecer un punto de interrupción fácilmente.
Una función de tipo realloc o de tipo free primero verifica que los bytes PYMEM_FORBIDDENBYTE en cada
extremo estén intactos. Si se han modificado, la salida de diagnóstico se escribe en stderr y el programa se aborta
mediante Py_FatalError(). El otro modo de falla principal es provocar un error de memoria cuando un programa
lee uno de los patrones de bits especiales e intenta usarlo como una dirección. Si ingresa a un depurador y observa
el objeto, es probable que vea que está completamente lleno de PYMEM_DEADBYTE (lo que significa que se está
usando la memoria liberada) o PYMEM_CLEANBYTE (que significa que se está usando la memoria no inicializada).
Distinto en la versión 3.6: La función PyMem_SetupDebugHooks() ahora también funciona en Python compi-
lado en modo de lanzamiento. En caso de error, los enlaces de depuración ahora usan tracemalloc para obtener
el rastreo donde se asignó un bloque de memoria. Los enlaces de depuración ahora también comprueban si el GIL se
mantiene cuando se llaman las funciones de PYMEM_DOMAIN_OBJ y PYMEM_DOMAIN_MEM dominios.
Distinto en la versión 3.8: Los patrones de bytes 0xCB (PYMEM_CLEANBYTE), 0xDB (PYMEM_DEADBYTE) y
0xFB (PYMEM_FORBIDDENBYTE) se han reemplazado por 0xCD, 0xDD y 0xFD para usar los mismos valores
que la depuración de Windows CRT malloc() y free().

11.9 El asignador pymalloc

Python tiene un asignador pymalloc optimizado para objetos pequeños (más pequeños o iguales a 512 bytes) con
una vida útil corta. Utiliza asignaciones de memoria llamadas «arenas» con un tamaño fijo de 256 KiB. Vuelve a
PyMem_RawMalloc() y PyMem_RawRealloc() para asignaciones de más de 512 bytes.
pymalloc es el asignador por defecto de PYMEM_DOMAIN_MEM (por ejemplo: PyMem_Malloc()) y
PYMEM_DOMAIN_OBJ (por ejemplo: PyObject_Malloc()) dominios.
El asignador de arena utiliza las siguientes funciones:
• VirtualAlloc() y VirtualFree() en Windows,
• mmap() y munmap() si está disponible,
• malloc() y free() en caso contrario.
Este asignador está deshabilitado si Python está configurado con la opción --without-pymalloc. También
se puede deshabilitar en tiempo de ejecución usando la variable de entorno PYTHONMALLOC (por ejemplo:
PYTHONMALLOC=malloc).

11.9.1 Personalizar asignador de arena de pymalloc

Nuevo en la versión 3.4.

type PyObjectArenaAllocator
Estructura utilizada para describir un asignador de arena. La estructura tiene tres campos:

Campo Significado
void *ctx contexto de usuario pasado como primer ar-
gumento
void* alloc(void *ctx, size_t size) asignar una arena de bytes de tamaño
void free(void *ctx, void *ptr, liberar la arena
size_t size)

void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)

Consigue el asignador de arena.

11.9. El asignador pymalloc 233

The Python/C API, Versión 3.11.0

void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)

Establecer el asignador de arena.

11.10 tracemalloc C API

Nuevo en la versión 3.7.

int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size)
Rastree un bloque de memoria asignado en el módulo tracemalloc.
Retorna 0 en caso de éxito, retorna -1 en caso de error (no se pudo asignar memoria para almacenar la traza).
Retorna -2 si tracemalloc está deshabilitado.
Si el bloque de memoria ya está rastreado, actualice el rastreo existente.
int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr)
Descomprima un bloque de memoria asignado en el módulo tracemalloc. No haga nada si el bloque no
fue rastreado.
Retorna -2 si tracemalloc está deshabilitado; de lo contrario, retorna 0.

11.11 Ejemplos

Aquí está el ejemplo de la sección Visión general, reescrito para que el búfer de E/S se asigne desde el montón de
Python utilizando el primer conjunto de funciones:

PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;

El mismo código que utiliza el conjunto de funciones orientado a tipos:

PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;

Tenga en cuenta que en los dos ejemplos anteriores, el búfer siempre se manipula a través de funciones que pertenecen
al mismo conjunto. De hecho, es necesario usar la misma familia de API de memoria para un bloque de memoria
dado, de modo que el riesgo de mezclar diferentes asignadores se reduzca al mínimo. La siguiente secuencia de
código contiene dos errores, uno de los cuales está etiquetado como fatal porque mezcla dos asignadores diferentes
que operan en montones diferentes.:

char *buf1 = PyMem_New(char, BUFSIZ);

char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
(continué en la próxima página)

234 Capítulo 11. Gestión de la memoria

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
free(buf2); /* Right -- allocated via malloc() */
free(buf1); /* Fatal -- should be PyMem_Del() */

Además de las funciones destinadas a manejar bloques de memoria sin procesar del montón de Python, los objetos
en Python se asignan y liberan con PyObject_New(), PyObject_NewVar() y PyObject_Del() .
Esto se explicará en el próximo capítulo sobre cómo definir e implementar nuevos tipos de objetos en C.

11.11. Ejemplos 235

The Python/C API, Versión 3.11.0

236 Capítulo 11. Gestión de la memoria

 CAPÍTULO 12

Soporte de implementación de objetos

Este capítulo describe las funciones, los tipos y las macros utilizados al definir nuevos tipos de objetos.

12.1 Asignación de objetos en el montículo

PyObject *_PyObject_New(PyTypeObject *type)

Return value: New reference.
PyVarObject *_PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
Return value: New reference.
PyObject *PyObject_Init(PyObject *op, PyTypeObject *type)
Return value: Borrowed reference. Part of the Stable ABI. Initialize a newly allocated object op with its type
and initial reference. Returns the initialized object. If type indicates that the object participates in the cyclic
garbage detector, it is added to the detector’s set of observed objects. Other fields of the object are not affected.
PyVarObject *PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
Return value: Borrowed reference. Part of the Stable ABI. Esto hace todo lo que PyObject_Init() hace,
y también inicializa la información de longitud para un objeto de tamaño variable.
TYPE *PyObject_New(TYPE, PyTypeObject *type)
Return value: New reference. Asigna un nuevo objeto Python usando el tipo de estructura de C TYPE y el
objeto tipo Python type. Los campos no definidos por el encabezado del objeto Python no se inicializan;el
conteo de referencias del objeto será uno. El tamaño de la asignación de memoria se determina a partir del
campo tp_basicsize del tipo de objeto.
TYPE *PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Return value: New reference. Asigna un nuevo objeto Python usando el tipo de estructura de C TYPE y el
objeto tipo Python type. Los campos no definidos por el encabezado del objeto Python no se inicializan. La
memoria asignada permite los campos de la estructura TYPE más los campos size del tamaño dado por el campo
tp_itemsize de type. Esto es útil para implementar objetos como tuplas, que pueden determinar su tamaño
en el momento de la construcción. Incrustar el arreglo de campos en la misma asignación disminuye el número
de asignaciones, mejorando la eficiencia de la gestión de memoria.

237
The Python/C API, Versión 3.11.0

void PyObject_Del(void *op)

Libera memoria asignada a un objeto usando PyObject_New() o PyObject_NewVar(). Esto normal-
mente se llama desde el manejador tp_dealloc especificado en el tipo de objeto. No se debe acceder a los
campos del objeto después de esta llamada, ya que la memoria ya no es un objeto Python válido.
PyObject _Py_NoneStruct
Objeto que es visible en Python como None. Esto solo se debe acceder utilizando el macro Py_None, que se
evalúa como un puntero a este objeto.
Ver también:
PyModule_Create() Para asignar y crear módulos de extensión.

12.2 Estructuras de objetos comunes

Hay un gran número de estructuras que se utilizan en la definición de los tipos de objetos de Python. Esta sección
describe estas estructuras y la forma en que se utilizan.

12.2.1 Tipos objeto base y macros

En última instancia, todos los objetos de Python comparten un pequeño número de campos en el comienzo de la
representación del objeto en la memoria. Estos están representados por la PyObject y PyVarObject,que se
definen, a su vez, por las expansiones de algunos macros también se utilizan, ya sea directa o indirectamente, en la
definición de todos otros objetos de Python.
type PyObject
Part of the Limited API. (Only some members are part of the stable ABI.) All object types are extensions of this
type. This is a type which contains the information Python needs to treat a pointer to an object as an object. In
a normal «release» build, it contains only the object’s reference count and a pointer to the corresponding type
object. Nothing is actually declared to be a PyObject, but every pointer to a Python object can be cast to a
PyObject*. Access to the members must be done by using the macros Py_REFCNT and Py_TYPE.
type PyVarObject
Part of the Limited API. (Only some members are part of the stable ABI.) Esta es una extensión de PyObject
que se suma el campo ob_size. Esto sólo se utiliza para objetos que tienen cierta noción de longitud (length).
Este tipo no suele aparecer en la API Python/C. El acceso a los miembros debe hacerse mediante el uso de las
macros Py_REFCNT, Py_TYPE, y Py_SIZE.
PyObject_HEAD
Esta es una macro utilizado cuando se declara nuevos tipos que representan objetos sin una longitud variable.
La macro PyObject_HEAD se expande a:

PyObject ob_base;

Consulte la documentación de PyObject en secciones anteriores.

PyObject_VAR_HEAD
Esta es una macro utilizado cuando se declara nuevos tipos que representan objetos con una longitud que varía
de una instancia a otra instancia. La macro PyObject_VAR_HEAD se expande a:

PyVarObject ob_base;

Consulte la documentación de PyVarObject anteriormente.

int Py_Is(PyObject *x, PyObject *y)
Part of the Stable ABI since version 3.10. Prueba si el objeto x es el objeto y, lo mismo que x is y en Python.
Nuevo en la versión 3.10.

238 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

int Py_IsNone(PyObject *x)

Part of the Stable ABI since version 3.10. Prueba si un objeto es la instancia única None, lo mismo que x is
None en Python.
Nuevo en la versión 3.10.
int Py_IsTrue(PyObject *x)
Part of the Stable ABI since version 3.10. Prueba si un objeto es la instancia única True, lo mismo que x is
True en Python.
Nuevo en la versión 3.10.
int Py_IsFalse(PyObject *x)
Part of the Stable ABI since version 3.10. Prueba si un objeto es la instancia única False, lo mismo que x
is False en Python.
Nuevo en la versión 3.10.
PyTypeObject *Py_TYPE(PyObject *o)
Obtiene el tipo de objeto Python o.
Retorna una referencia prestada (borrowed reference).
Use the Py_SET_TYPE() function to set an object type.
Distinto en la versión 3.11: Py_TYPE() se cambia a una función estática inline. El tipo de parámetro ya no
es const PyObject*.
int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
Retorna un valor distinto de cero si el objeto o tipo es type. Retorna cero en caso contrario. Equivalente a:
Py_TYPE(o) == type.
Nuevo en la versión 3.9.
void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
Establece el tipo del objeto o a type.
Nuevo en la versión 3.9.
Py_ssize_t Py_REFCNT(PyObject *o)
Obtiene la cuenta de referencias del objeto Python o.
Use the Py_SET_REFCNT() function to set an object reference count.
Distinto en la versión 3.11: El tipo de parámetro ya no es const PyObject*.
Distinto en la versión 3.10: Py_REFCNT() se cambia a la función estática inline.
void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)
Establece el conteo de referencia del objeto o a refcnt.
Nuevo en la versión 3.9.
Py_ssize_t Py_SIZE(PyVarObject *o)
Obtiene el tamaño del objeto Python o.
Use the Py_SET_SIZE() function to set an object size.
Distinto en la versión 3.11: Py_SIZE() se cambia a una función estática inline. El tipo de parámetro ya no
es const PyVarObject*.
void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
Establece el tamaño del objeto o a size.
Nuevo en la versión 3.9.

12.2. Estructuras de objetos comunes 239

The Python/C API, Versión 3.11.0

PyObject_HEAD_INIT(type)
Esta es una macro que se expande para valores de inicialización para un nuevo tipo PyObject. Esta macro
expande:

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)
Esta es una macro que se expande para valores de inicialización para un nuevo tipo PyVarObject, incluyendo
el campo ob_size. Esta macro se expande a:

_PyObject_EXTRA_INIT
1, type, size,

12.2.2 Implementando funciones y métodos

type PyCFunction
Part of the Stable ABI. Type of the functions used to implement most Python callables in C. Functions of this
type take two PyObject* parameters and return one such value. If the return value is NULL, an exception
shall have been set. If not NULL, the return value is interpreted as the return value of the function as exposed
in Python. The function must return a new reference.
La firma de la función es:

PyObject *PyCFunction(PyObject *self,

PyObject *args);

type PyCFunctionWithKeywords
Part of the Stable ABI. Tipo de las funciones que se utilizan para implementar invocables Python en C con la
firma METH_VARARGS | METH_KEYWORDS. La firma de la función es:

PyObject *PyCFunctionWithKeywords(PyObject *self,

PyObject *args,
PyObject *kwargs);

type _PyCFunctionFast
Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_FASTCALL.
La firma de la función es:

PyObject *_PyCFunctionFast(PyObject *self,

PyObject *const *args,
Py_ssize_t nargs);

type _PyCFunctionFastWithKeywords
Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_FASTCALL
| METH_KEYWORDS. La firma de la función es:

PyObject *_PyCFunctionFastWithKeywords(PyObject *self,

PyObject *const *args,
Py_ssize_t nargs,
PyObject *kwnames);

type PyCMethod
Tipo de las funciones que se utilizan para implementar invocables Python en C con la firma METH_METHOD
| METH_FASTCALL | METH_KEYWORDS. La firma de la función es:

240 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

PyObject *PyCMethod(PyObject *self,

PyTypeObject *defining_class,
PyObject *const *args,
Py_ssize_t nargs,
PyObject *kwnames)

Nuevo en la versión 3.9.

type PyMethodDef
Part of the Stable ABI (including all members). Estructura utiliza para describir un método de un tipo de
extensión. Esta estructura tiene cuatro campos:

Campo Tipo C Significado

ml_name const char * nombre del método
ml_meth PyCFunction puntero a la implementación en C
ml_flags int flag bits que indican cómo debe ser construida la llamada
ml_doc const char * puntos a los contenidos del docstring

The ml_meth is a C function pointer. The functions may be of different types, but they always return PyObject*.
If the function is not of the PyCFunction, the compiler will require a cast in the method table. Even though
PyCFunction defines the first parameter as PyObject*, it is common that the method implementation uses the
specific C type of the self object.
El campo ml_flags es un campo de bits que puede incluir las siguientes flags. Las flags individuales indican o bien
una convención de llamada o una convención vinculante.
Existen estas convenciones de llamada:
METH_VARARGS
This is the typical calling convention, where the methods have the type PyCFunction. The function expects
two PyObject* values. The first one is the self object for methods; for module functions, it is the module
object. The second parameter (often called args) is a tuple object representing all arguments. This parameter
is typically processed using PyArg_ParseTuple() or PyArg_UnpackTuple().
METH_VARARGS | METH_KEYWORDS
Los métodos con estas flags deben ser del tipo PyCFunctionWithKeywords. La función espera tres
parámetros: self, args, kwargs donde kwargs es un diccionario de todos los argumentos de palabras clave o,
posiblemente, NULL si no hay argumentos de palabra clave. Los parámetros se procesan típicamente usando
PyArg_ParseTupleAndKeywords().
METH_FASTCALL
Fast calling convention supporting only positional arguments. The methods have the type
_PyCFunctionFast. The first parameter is self, the second parameter is a C array of PyObject* values
indicating the arguments and the third parameter is the number of arguments (the length of the array).
Nuevo en la versión 3.7.
Distinto en la versión 3.10: Ahora METH_FASTCALL es parte de la ABI estable.
METH_FASTCALL | METH_KEYWORDS
Extension of METH_FASTCALL supporting also keyword arguments, with methods of type
_PyCFunctionFastWithKeywords. Keyword arguments are passed the same way as in the vec-
torcall protocol: there is an additional fourth PyObject* parameter which is a tuple representing the names
of the keyword arguments (which are guaranteed to be strings) or possibly NULL if there are no keywords.
The values of the keyword arguments are stored in the args array, after the positional arguments.
Nuevo en la versión 3.7.
METH_METHOD | METH_FASTCALL | METH_KEYWORDS
Extensión de METH_FASTCALL | METH_KEYWORDS que admite la clase definitoria, es decir, la clase que
contiene el método en cuestión. La clase definitoria podría ser una superclase de Py_TYPE(self).

12.2. Estructuras de objetos comunes 241

The Python/C API, Versión 3.11.0

El método debe ser de tipo PyCMethod, lo mismo que para METH_FASTCALL | METH_KEYWORDS con
el argumento defining_clase añadido después de self.
Nuevo en la versión 3.9.
METH_NOARGS
Métodos sin parámetros no tienen que comprobar si los argumentos se dan si están registrados con el flag
METH_NOARGS. Tienen que ser de tipo PyCFunction. El primer parámetro normalmente se denomina
self y llevará a cabo una referencia a la instancia módulo u objeto. En todos los casos el segundo parámetro
será NULL.
La función debe tener 2 parámetros. Dado que el segundo parámetro no se usa, Py_UNUSED se puede usar
para evitar una advertencia del compilador.
METH_O
Methods with a single object argument can be listed with the METH_O flag, instead of invoking
PyArg_ParseTuple() with a "O" argument. They have the type PyCFunction, with the self para-
meter, and a PyObject* parameter representing the single argument.
Estas dos constantes no se utilizan para indicar la convención de llamada si no la vinculación cuando su usan con
métodos de las clases. Estos no se pueden usar para funciones definidas para módulos. A lo sumo uno de estos flags
puede establecerse en un método dado.
METH_CLASS
Al método se le pasará el objeto tipo como primer parámetro, en lugar de una instancia del tipo. Esto se
utiliza para crear métodos de clase (class methods), similar a lo que se crea cuando se utiliza la función
classmethod() incorporada.
METH_STATIC
El método pasará NULL como el primer parámetro en lugar de una instancia del tipo. Esto se utiliza para crear
métodos estáticos (static methods), similar a lo que se crea cuando se utiliza la función staticmethod()
incorporada.
En otros controles constantes dependiendo si se carga un método en su lugar (in place) de otra definición con el mismo
nombre del método.
METH_COEXIST
El método se cargará en lugar de las definiciones existentes. Sin METH_COEXIST, el comportamiento pre-
determinado es saltarse las definiciones repetidas. Desde envolturas de ranura se cargan antes de la tabla
de métodos, la existencia de una ranura sq_contains, por ejemplo, generaría un método envuelto llamado
__contains__() e impediría la carga de una PyCFunction correspondiente con el mismo nombre. Con el
flag definido, la PyCFunction se cargará en lugar del objeto envoltorio y coexistirá con la ranura. Esto es útil
porque las llamadas a PyCFunctions se optimizan más que las llamadas a objetos envolvente.

12.2.3 Acceder a atributos de tipos de extensión

type PyMemberDef
Part of the Stable ABI (including all members). Estructura que describe un atributo de un tipo que corresponde
a un miembro de la estructura de C. Sus campos son:

Campo Tipo C Significado

name const char nombre del miembro
*
type int el tipo de miembro en la estructura de C
offset Py_ssize_t el desplazamiento en bytes que el miembro se encuentra en la estructura de objetos
tipo
flags int flags bits que indican si el campo debe ser de sólo lectura o de escritura
doc const char puntos a los contenidos del docstring
*

242 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

type puede ser uno de muchos macros T_ correspondientes a diversos tipos C. Cuando se accede al miembro
en Python, será convertida al tipo Python equivalente.

Nombre de la macro Tipo C

T_SHORT short
T_INT int
T_LONG long
T_FLOAT float
T_DOUBLE double
T_STRING const char *
T_OBJECT PyObject *
T_OBJECT_EX PyObject *
T_CHAR char
T_BYTE char
T_UBYTE unsigned char
T_UINT unsigned int
T_USHORT unsigned short
T_ULONG unsigned long
T_BOOL char
T_LONGLONG long long
T_ULONGLONG unsigned long long
T_PYSSIZET Py_ssize_t

T_OBJECT y T_OBJECT_EX se diferencian en que T_OBJECT retorna None si el miembro es NULL y

T_OBJECT_EX lanza un AttributeError. Trate de usar T_OBJECT_EX sobre T_OBJECT porque
T_OBJECT_EX maneja el uso de la declaración del en ese atributo más correctamente que T_OBJECT.
flags puede ser 0 para el acceso de escritura y lectura o READONLY para el acceso de sólo lectura. El uso
de T_STRING para type implica READONLY. Los datos T_STRING se interpretan como UTF-8. Sólo se
pueden eliminar T_OBJECT y miembros T_OBJECT_EX. (Se establecen a NULL).
Los tipos asignados al heap (creados usando PyType_FromSpec() o similar), PyMemberDef pue-
den contener definiciones para los miembros especiales __dictoffset__, __weaklistoffset__
y __vectorcalloffset__, correspondientes a tp_dictoffset, tp_weaklistoffset y
tp_vectorcall_offset en objetos de tipo. Estos deben definirse con T_PYSSIZET y READONLY,
por ejemplo:

static PyMemberDef spam_type_members[] = {

{"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
{NULL} /* Sentinel */
};

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

Obtiene un atributo que pertenece al objeto en la dirección obj_addr. El atributo se describe por
PyMemberDef m. Retorna NULL en caso de error.
int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
Establece un atributo que pertenece al objeto en la dirección obj_addr al objeto o. El atributo a establecer se
describe por PyMemberDef m. Retorna 0 si tiene éxito y un valor negativo si falla.
type PyGetSetDef
Part of the Stable ABI (including all members). Estructura para definir el acceso para un tipo como el de una
propiedad. Véase también la descripción de la ranura PyTypeObject.tp_getset.

12.2. Estructuras de objetos comunes 243

The Python/C API, Versión 3.11.0

Campo Tipo C Significado

nombre const nombre del atributo
char *
get getter C function to get the attribute
set setter función opcional C para establecer o eliminar el atributo, si se omite el atri-
buto es de sólo lectura
doc const docstring opcional
char *
clausura (clo- void * puntero de función opcional, proporcionar datos adicionales para getter y setter
sure)

The get function takes one PyObject* parameter (the instance) and a function pointer (the associated
closure):

typedef PyObject *(*getter)(PyObject *, void *);

Debe retornar una nueva referencia en caso de éxito o NULL con una excepción establecida en caso de error.
set functions take two PyObject* parameters (the instance and the value to be set) and a function pointer
(the associated closure):

typedef int (*setter)(PyObject *, PyObject *, void *);

En caso de que el atributo deba suprimirse el segundo parámetro es NULL. Debe retornar 0 en caso de éxito o
-1 con una excepción explícita en caso de fallo.

12.3 Objetos Tipo

Perhaps one of the most important structures of the Python object system is the structure that defines a new type: the
PyTypeObject structure. Type objects can be handled using any of the PyObject_* or PyType_* functions,
but do not offer much that’s interesting to most Python applications. These objects are fundamental to how objects
behave, so they are very important to the interpreter itself and to any extension module that implements new types.
Los objetos de tipo son bastante grandes en comparación con la mayoría de los tipos estándar. La razón del tamaño
es que cada objeto de tipo almacena una gran cantidad de valores, principalmente punteros de función C, cada uno
de los cuales implementa una pequeña parte de la funcionalidad del tipo. Los campos del objeto tipo se examinan en
detalle en esta sección. Los campos se describirán en el orden en que aparecen en la estructura.
Además de la siguiente referencia rápida, la sección Ejemplos proporciona una visión rápida del significado y uso de
PyTypeObject.

12.3.1 Referencia rápida

«ranuras tp» (tp slots)

Ranura Type métodos/atributos especiales In-

PyTypeObjectPágina 245, 1 for-
ma-
ciónPágina 245, 2
O T D I
<R> tp_name const char * __name__ X X
tp_basicsize Py_ssize_t X X X
tp_itemsize Py_ssize_t X X
tp_dealloc destructor X X X
continué en la próxima página

244 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Tabla 1 – proviene de la página anterior

Ranura Type métodos/atributos especiales In-
PyTypeObjectPágina 245, 1 for-
ma-
ciónPágina 245, 2
O T D I
tp_vectorcall_offset Py_ssize_t X X
(tp_getattr) getattrfunc __getattribute__, __getattr__ G
(tp_setattr) setattrfunc __setattr__, __delattr__ G
tp_as_async PyAsyncMethods * sub-ranuras (sub-slots) %
tp_repr reprfunc __repr__ X X X
tp_as_number PyNumberMethods * sub-ranuras (sub-slots) %
tp_as_sequence PySequenceMethods * sub-ranuras (sub-slots) %
tp_as_mapping PyMappingMethods * sub-ranuras (sub-slots) %
tp_hash hashfunc __hash__ X G
tp_call ternaryfunc __call__ X X
tp_str reprfunc __str__ X X
tp_getattro getattrofunc __getattribute__, __getattr__ X X G
tp_setattro setattrofunc __setattr__, __delattr__ X X G
tp_as_buffer PyBufferProcs * %
tp_flags unsigned long X X ?
tp_doc const char * __doc__ X X
tp_traverse traverseproc X G
tp_clear inquiry X G
tp_richcompare richcmpfunc __lt__, __le__, __eq__, __ne__, X G
__gt__, __ge__
tp_weaklistoffset Py_ssize_t X ?
tp_iter getiterfunc __iter__ X
tp_iternext iternextfunc __next__ X
tp_methods PyMethodDef [] X X
tp_members PyMemberDef [] X
tp_getset PyGetSetDef [] X X
tp_base PyTypeObject * __base__ X
tp_dict PyObject * __dict__ ?
tp_descr_get descrgetfunc __get__ X
tp_descr_set descrsetfunc __set__, __delete__ X
tp_dictoffset Py_ssize_t X ?
tp_init initproc __init__ X X X
tp_alloc allocfunc X ? ?
tp_new newfunc __new__ X X ? ?
tp_free freefunc X X ? ?
tp_is_gc inquiry X X
<tp_bases> PyObject * __bases__ ~
<tp_mro> PyObject * __mro__ ~
[tp_cache] PyObject *
[tp_subclasses] PyObject * __subclasses__
[tp_weaklist] PyObject *
(tp_del) destructor
[tp_version_tag] unsigned int
tp_finalize destructor __del__ X
tp_vectorcall vectorcallfunc

1 Un nombre de ranura entre paréntesis indica que está (efectivamente) en desuso. Los nombres entre paréntesis angulares deben tratarse como

de solo lectura. Los nombres entre corchetes son solo para uso interno. «<R>» (como prefijo) significa que el campo es obligatorio (no debe ser
NULL).
2 Columnas:

«O»: establecido en PyBaseObject_Type

«T»: establecido en PyType_Type

12.3. Objetos Tipo 245

The Python/C API, Versión 3.11.0

sub-ranuras (sub-slots)

Ranuras (Slot) Type métodos especiales

am_await unaryfunc __await__
am_aiter unaryfunc __aiter__
am_anext unaryfunc __anext__
am_send sendfunc

nb_add binaryfunc __add__ __radd__

nb_inplace_add binaryfunc __iadd__
nb_subtract binaryfunc __sub__ __rsub__
nb_inplace_subtract binaryfunc __isub__
nb_multiply binaryfunc __mul__ __rmul__
nb_inplace_multiply binaryfunc __imul__
nb_remainder binaryfunc __mod__ __rmod__
nb_inplace_remainder binaryfunc __imod__
nb_divmod binaryfunc __divmod__ __rdiv-
mod__
nb_power ternaryfunc __pow__ __rpow__
nb_inplace_power ternaryfunc __ipow__
nb_negative unaryfunc __neg__
nb_positive unaryfunc __pos__
nb_absolute unaryfunc __abs__
nb_bool inquiry __bool__
nb_invert unaryfunc __invert__
nb_lshift binaryfunc __lshift__ __rlshift__
nb_inplace_lshift binaryfunc __ilshift__
nb_rshift binaryfunc __rshift__ __rrs-
hift__
nb_inplace_rshift binaryfunc __irshift__
nb_and binaryfunc __and__ __rand__
nb_inplace_and binaryfunc __iand__
nb_xor binaryfunc __xor__ __rxor__
nb_inplace_xor binaryfunc __ixor__
nb_or binaryfunc __or__ __ror__
nb_inplace_or binaryfunc __ior__
nb_int unaryfunc __int__
nb_reserved void *
nb_float unaryfunc __float__
nb_floor_divide binaryfunc __floordiv__
nb_inplace_floor_divide binaryfunc __ifloordiv__
nb_true_divide binaryfunc __truediv__
nb_inplace_true_divide binaryfunc __itruediv__
nb_index unaryfunc __index__
nb_matrix_multiply
«D»: por defecto (si la ranura está establecida como NULL) binaryfunc __matmul__ __rmat-
mul__
X - PyType_Ready sets this value if it is NULL
nb_inplace_matrix_multiply binaryfunc __imatmul__
~ - PyType_Ready always sets this value (it should be NULL)
? - PyType_Ready may set this value depending on other slots
mp_length lenfunc __len__
Also see the inheritance column ("I"). continué en la próxima página
«I»: herencia
X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value
% - the slots of the sub-struct are inherited individually
G - inherited, but only in combination with other slots; see the slot's description
? - it's complicated; see the slot's description
Tenga en cuenta que algunos espacios se heredan efectivamente a través de la cadena de búsqueda de atributos normal.

246 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Tabla 2 – proviene de la página anterior

Ranuras (Slot) Type métodos especiales
mp_subscript binaryfunc __getitem__
mp_ass_subscript objobjargproc __setitem__, __deli-
tem__

sq_length lenfunc __len__

sq_concat binaryfunc __add__
sq_repeat ssizeargfunc __mul__
sq_item ssizeargfunc __getitem__
sq_ass_item ssizeobjargproc __setitem__ __deli-
tem__
sq_contains objobjproc __contains__
sq_inplace_concat binaryfunc __iadd__
sq_inplace_repeat ssizeargfunc __imul__

bf_getbuffer getbufferproc()
bf_releasebuffer releasebufferproc()

12.3. Objetos Tipo 247

The Python/C API, Versión 3.11.0

ranura de typedefs

typedef Tipos Parámetros Tipo de Retorno

allocfunc PyObject *
PyTypeObject *
Py_ssize_t

destructor void * void

freefunc void * void
traverseproc int
void *
visitproc
void *

newfunc PyObject *
PyObject *
PyObject *
PyObject *

initproc int
PyObject *
PyObject *
PyObject *

reprfunc PyObject * PyObject *

getattrfunc PyObject *
PyObject *
const char *

setattrfunc int
PyObject *
const char *
PyObject *

getattrofunc PyObject *
PyObject *
PyObject *

setattrofunc int
PyObject *
PyObject *
PyObject *

descrgetfunc PyObject *
PyObject *
PyObject *
PyObject *

descrsetfunc int
PyObject *
PyObject *
248 PyObjectCapítulo
* 12. Soporte de implementación de objetos

hashfunc PyObject * Py_hash_t

richcmpfunc PyObject *
 The Python/C API, Versión 3.11.0

Vea Tipo Ranura typedefs abajo para más detalles.

12.3.2 Definición de PyTypeObject

La definición de estructura para PyTypeObject se puede encontrar en Include/object.h. Por conveniencia

de referencia, esto repite la definición encontrada allí:

typedef struct _typeobject {

PyObject_VAR_HEAD
const char *tp_name; /* For printing, in format "<module>.<name>" */
Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

/* Methods to implement standard operations */

destructor tp_dealloc;
Py_ssize_t tp_vectorcall_offset;
getattrfunc tp_getattr;
setattrfunc tp_setattr;
PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
or tp_reserved (Python 3) */
reprfunc tp_repr;

/* Method suites for standard classes */

PyNumberMethods *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods *tp_as_mapping;

/* More standard operations (here for binary compatibility) */

hashfunc tp_hash;
ternaryfunc tp_call;
reprfunc tp_str;
getattrofunc tp_getattro;
setattrofunc tp_setattro;

/* Functions to access object as input/output buffer */

PyBufferProcs *tp_as_buffer;

/* Flags to define presence of optional/expanded features */

unsigned long tp_flags;

const char *tp_doc; /* Documentation string */

/* Assigned meaning in release 2.0 */

/* call function for all accessible objects */
traverseproc tp_traverse;

/* delete references to contained objects */

inquiry tp_clear;

/* Assigned meaning in release 2.1 */

/* rich comparisons */
richcmpfunc tp_richcompare;

/* weak reference enabler */

Py_ssize_t tp_weaklistoffset;

/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;
(continué en la próxima página)

12.3. Objetos Tipo 249

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

/* Attribute descriptor and subclassing stuff */

struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;
// Strong reference on a heap type, borrowed reference on a static type
struct _typeobject *tp_base;
PyObject *tp_dict;
descrgetfunc tp_descr_get;
descrsetfunc tp_descr_set;
Py_ssize_t tp_dictoffset;
initproc tp_init;
allocfunc tp_alloc;
newfunc tp_new;
freefunc tp_free; /* Low-level free-memory routine */
inquiry tp_is_gc; /* For PyObject_IS_GC */
PyObject *tp_bases;
PyObject *tp_mro; /* method resolution order */
PyObject *tp_cache;
PyObject *tp_subclasses;
PyObject *tp_weaklist;
destructor tp_del;

/* Type attribute cache version tag. Added in version 2.6 */

unsigned int tp_version_tag;

destructor tp_finalize;
vectorcallfunc tp_vectorcall;
} PyTypeObject;

12.3.3 Ranuras (Slots) PyObject

The type object structure extends the PyVarObject structure. The ob_size field is used for dynamic types (crea-
ted by type_new(), usually called from a class statement). Note that PyType_Type (the metatype) initializes
tp_itemsize, which means that its instances (i.e. type objects) must have the ob_size field.
Py_ssize_t PyObject.ob_refcnt
Part of the Stable ABI. Este es el recuento de referencias del objeto de tipo, inicializado a 1 por la macro
PyObject_HEAD_INIT. Tenga en cuenta que para objetos de tipo estáticamente asignados, las instancias del
tipo (objetos cuyo ob_type apunta al tipo) no cuentan como referencias. Pero para objetos de tipo asignados
dinámicamente, las instancias sí cuentan como referencias.
Herencia:
Este campo no es heredado por los subtipos.
PyTypeObject *PyObject.ob_type
Part of the Stable ABI. Este es el tipo del tipo, en otras palabras, su metatipo. Se inicializa mediante el ar-
gumento de la macro PyObject_HEAD_INIT, y su valor normalmente debería ser &PyType_Type. Sin
embargo, para los módulos de extensión cargables dinámicamente que deben ser utilizables en Windows (al
menos), el compilador se queja de que este no es un inicializador válido. Por lo tanto, la convención es pasar
NULL al macro PyObject_HEAD_INIT e inicializar este campo explícitamente al comienzo de la función
de inicialización del módulo, antes de hacer cualquier otra cosa. Esto normalmente se hace así:

Foo_Type.ob_type = &PyType_Type;

Esto debe hacerse antes de que se creen instancias del tipo. PyType_Ready() comprueba si ob_type es
NULL, y si es así, lo inicializa en el campo ob_type de la clase base. PyType_Ready() no cambiará este
campo si no es cero.

250 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Herencia:
Este campo es heredado por subtipos.
PyObject *PyObject._ob_next
PyObject *PyObject._ob_prev
Estos campos solo están presentes cuando se define la macro Py_TRACE_REFS (ver la opción
configure --with-trace-refs).
Their initialization to NULL is taken care of by the PyObject_HEAD_INIT macro. For statically allocated
objects, these fields always remain NULL. For dynamically allocated objects, these two fields are used to link
the object into a doubly linked list of all live objects on the heap.
Esto podría usarse para varios propósitos de depuración; actualmente, los únicos usos son la función sys.
getobjects() y para imprimir los objetos que aún están vivos al final de una ejecución cuando se establece
la variable de entorno PYTHONDUMPREFS.
Herencia:
Estos campos no son heredados por subtipos.

12.3.4 Ranuras PyVarObject

Py_ssize_t PyVarObject.ob_size
Part of the Stable ABI. Para objetos de tipo estáticamente asignados, debe inicializarse a cero. Para objetos de
tipo dinámicamente asignados, este campo tiene un significado interno especial.
Herencia:
Este campo no es heredado por los subtipos.

12.3.5 Ranuras PyTypeObject

Cada ranura tiene una sección que describe la herencia. Si PyType_Ready() puede establecer un valor cuan-
do el campo se establece en NULL, entonces también habrá una sección «Predeterminada». (Tenga en cuenta que
muchos campos establecidos en PyBaseObject_Type y PyType_Type actúan efectivamente como valores
predeterminados).
const char *PyTypeObject.tp_name
Puntero a una cadena de caracteres terminada en NULL que contiene el nombre del tipo. Para los tipos que
son accesibles como módulos globales, la cadena debe ser el nombre completo del módulo, seguido de un
punto, seguido del nombre del tipo; para los tipos integrados, debe ser solo el nombre del tipo. Si el módulo
es un submódulo de un paquete, el nombre completo del paquete es parte del nombre completo del módulo.
Por ejemplo, un tipo llamado T definido en el módulo M en el subpaquete Q en el paquete P debe tener el
inicializador tp_name "PQMT".
Para objetos de tipo dinámicamente asignados, éste debe ser sólo el nombre del tipo, y el nombre del módulo
almacenado explícitamente en el dict tipo que el valor de '__module__' clave.
Para objetos de tipo estáticamente asignados, el campo tp_name debe contener un punto. Todo lo que está antes
del último punto se hace accesible como el atributo __module__, y todo lo que está después del último punto
se hace accesible como el atributo __name__.
Si no hay ningún punto, todo el campo tp_name se hace accesible como el atributo __name__, y el atributo
__module__ no está definido (a menos que sea explícitamente establecido en el diccionario, como se explicó
anteriormente). Esto significa que su tipo será imposible de guardar como pickle. Además, no figurará en la
documentación del módulo creado con pydoc.
Este campo no debe ser NULL. Es el único campo obligatorio en PyTypeObject() (que no sea potencial-
mente tp_itemsize).
Herencia:

12.3. Objetos Tipo 251

The Python/C API, Versión 3.11.0

Este campo no es heredado por los subtipos.

Py_ssize_t PyTypeObject.tp_basicsize
Py_ssize_t PyTypeObject.tp_itemsize
Estos campos permiten calcular el tamaño en bytes de instancias del tipo.
Hay dos tipos de tipos: los tipos con instancias de longitud fija tienen un campo cero tp_itemsize, los
tipos con instancias de longitud variable tienen un campo distinto de cero tp_itemsize. Para un tipo con
instancias de longitud fija, todas las instancias tienen el mismo tamaño, dado en tp_basicsize.
Para un tipo con instancias de longitud variable, las instancias deben tener un campo ob_size, y el tamaño
de la instancia es tp_basicsize más N veces tp_itemsize, donde N es la «longitud» del objeto. El
valor de N generalmente se almacena en el campo ob_size de la instancia. Hay excepciones: por ejemplo,
los ints usan un negativo ob_size para indicar un número negativo, y N es abs(ob_size) allí. Además,
la presencia de un campo ob_size en el diseño de la instancia no significa que la estructura de la instancia
sea de longitud variable (por ejemplo, la estructura para el tipo de lista tiene instancias de longitud fija, aunque
esas instancias tienen un significativo campo ob_size).
El tamaño básico incluye los campos en la instancia declarada por el macro PyObject_HEAD o
PyObject_VAR_HEAD (lo que se use para declarar la estructura de la instancia) y esto a su vez incluye
campos _ob_prev y _ob_next si están presentes. Esto significa que la única forma correcta de obtener
un inicializador para tp_basicsize es usar el operador sizeof en la estructura utilizada para declarar
el diseño de la instancia. El tamaño básico no incluye el tamaño del encabezado del GC.
Una nota sobre la alineación: si los elementos variables requieren una alineación particular, esto debe
ser atendido por el valor de tp_basicsize. Ejemplo: supongamos que un tipo implementa un arreglo
de dobles (double). tp_itemsize es sizeof(double). Es responsabilidad del programador que
tp_basicsize es un múltiplo de sizeof(double) (suponiendo que este sea el requisito de alineación
para double).
Para cualquier tipo con instancias de longitud variable, este campo no debe ser NULL.
Herencia:
Estos campos se heredan por separado por subtipos. Si el tipo base tiene un miembro distinto de cero
tp_itemsize, generalmente no es seguro establecer tp_itemsize en un valor diferente de cero en un
subtipo ( aunque esto depende de la implementación del tipo base).
destructor PyTypeObject.tp_dealloc
Un puntero a la función destructor de instancias. Esta función debe definirse a menos que el tipo garantice que
sus instancias nunca se desasignarán (como es el caso de los singletons None y Ellipsis). La firma de la
función es:

void tp_dealloc(PyObject *self);

La función destructor es llamada por las macros Py_DECREF() y Py_XDECREF() cuando el nuevo re-
cuento de referencia es cero. En este punto, la instancia todavía existe, pero no hay referencias a ella. La
función destructor debe liberar todas las referencias que posee la instancia, liberar todos los búferes de
memoria que posee la instancia (utilizando la función de liberación correspondiente a la función de asig-
nación utilizada para asignar el búfer) y llamar a los tipos función tp_free. Si el tipo no es subtipa-
ble (no tiene establecido el bit de indicador Py_TPFLAGS_BASETYPE), está permitido llamar al ob-
jeto desasignador directamente en lugar de a través de tp_free. El objeto desasignador debe ser el
utilizado para asignar la instancia; normalmente es PyObject_Del() si la instancia se asignó usando
PyObject_New() o PyObject_VarNew(), o PyObject_GC_Del() si la instancia se asignó usando
PyObject_GC_New() o PyObject_GC_NewVar().
If the type supports garbage collection (has the Py_TPFLAGS_HAVE_GC flag bit set), the destructor should
call PyObject_GC_UnTrack() before clearing any member fields.

static void foo_dealloc(foo_object *self) {

PyObject_GC_UnTrack(self);
Py_CLEAR(self->ref);
(continué en la próxima página)

252 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

Py_TYPE(self)->tp_free((PyObject *)self);
}

Finalmente, si el tipo está asignado en el heap (Py_TPFLAGS_HEAPTYPE), el desasignador debería disminuir

el conteo de referencia para su objeto tipo después de llamar al desasignador del tipo. Para evitar punteros
colgantes, la forma recomendada de lograr esto es:

static void foo_dealloc(foo_object *self) {

PyTypeObject *tp = Py_TYPE(self);
// free references and buffers here
tp->tp_free(self);
Py_DECREF(tp);
}

Herencia:
Este campo es heredado por subtipos.
Py_ssize_t PyTypeObject.tp_vectorcall_offset
Un desplazamiento opcional a una función por instancia que implementa la llamada al objeto usando vectorcall
protocol, una alternativa más eficiente del simple tp_call.
Este campo solo se usa si se establece el flag Py_TPFLAGS_HAVE_VECTORCALL. Si es así, debe ser un
entero positivo que contenga el desplazamiento en la instancia de un puntero vectorcallfunc.
El puntero vectorcallfunc puede ser NULL, en cuyo caso la instancia se comporta como si
Py_TPFLAGS_HAVE_VECTORCALL no estuviera configurado: llamar a la instancia vuelve a tp_call.
Cualquier clase que establezca _Py_TPFLAGS_HAVE_VECTORCALL también debe establecer tp_call
y asegurarse de que su comportamiento sea coherente con la función vectorcallfunc. Esto se puede hacer con-
figurando tp_call en PyVectorcall_Call().

Advertencia: It is not recommended for mutable heap types to implement the vectorcall protocol. When
a user sets __call__ in Python code, only tp_call is updated, likely making it inconsistent with the
vectorcall function.

Distinto en la versión 3.8: Antes de la versión 3.8, este slot se llamaba tp_print. En Python 2.x, se usó para
imprimir en un archivo. En Python 3.0 a 3.7, no se usó.
Herencia:
This field is always inherited. However, the Py_TPFLAGS_HAVE_VECTORCALL flag is not always inherited.
If it’s not, then the subclass won’t use vectorcall, except when PyVectorcall_Call() is explicitly called.
This is in particular the case for types without the Py_TPFLAGS_IMMUTABLETYPE flag set (including
subclasses defined in Python).
getattrfunc PyTypeObject.tp_getattr
Un puntero opcional a la función «obtener atributo cadena de caracteres» (get-attribute-string).
Este campo está en desuso. Cuando se define, debe apuntar a una función que actúe igual que la función
tp_getattro, pero tomando una cadena de caracteres C en lugar de un objeto de cadena Python para dar
el nombre del atributo.
Herencia:
Grupo: tp_getattr, tp_getattro
Este campo es heredado por los subtipos junto con tp_getattro: un subtipo hereda ambos tp_getattr
y tp_getattro de su base escriba cuando los subtipos tp_getattr y tp_getattro son ambos NULL.

12.3. Objetos Tipo 253

The Python/C API, Versión 3.11.0

setattrfunc PyTypeObject.tp_setattr
Un puntero opcional a la función para configurar y eliminar atributos.
Este campo está en desuso. Cuando se define, debe apuntar a una función que actúe igual que la función
tp_setattro, pero tomando una cadena de caracteres C en lugar de un objeto de cadena Python para dar
el nombre del atributo.
Herencia:
Grupo: tp_setattr, tp_setattro
Este campo es heredado por los subtipos junto con tp_setattro: un subtipo hereda ambos tp_setattr
y tp_setattro de su base escriba cuando los subtipos tp_setattr y tp_setattro son ambos NULL.
PyAsyncMethods *PyTypeObject.tp_as_async
Puntero a una estructura adicional que contiene campos relevantes solo para los objetos que implementan los
protocolos «esperable» (awaitable) y «iterador asíncrono» (asynchronous iterator) en el nivel C. Ver Estructuras
de objetos asíncronos para más detalles.
Nuevo en la versión 3.5: Anteriormente conocidos como tp_compare y tp_reserved.
Herencia:
El campo tp_as_async no se hereda, pero los campos contenidos se heredan individualmente.
reprfunc PyTypeObject.tp_repr
Un puntero opcional a una función que implementa la función incorporada repr().
La firma es la misma que para PyObject_Repr():
PyObject *tp_repr(PyObject *self);

La función debe retornar una cadena de caracteres o un objeto Unicode. Idealmente, esta función debería
retornar una cadena que, cuando se pasa a eval(), dado un entorno adecuado, retorna un objeto con el
mismo valor. Si esto no es factible, debe retornar una cadena que comience con '<' y termine con '>' desde
la cual se puede deducir tanto el tipo como el valor del objeto.
Herencia:
Este campo es heredado por subtipos.
Por defecto:
Cuando este campo no está configurado, se retorna una cadena de caracteres de la forma <%s object at
%p>, donde %s se reemplaza por el nombre del tipo y %p por dirección de memoria del objeto.
PyNumberMethods *PyTypeObject.tp_as_number
Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan el pro-
tocolo numérico. Estos campos están documentados en Estructuras de Objetos de Números.
Herencia:
El campo tp_as_number no se hereda, pero los campos contenidos se heredan individualmente.
PySequenceMethods *PyTypeObject.tp_as_sequence
Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan el pro-
tocolo de secuencia. Estos campos están documentados en estructuras de secuencia.
Herencia:
El campo tp_as_sequence no se hereda, pero los campos contenidos se heredan individualmente.
PyMappingMethods *PyTypeObject.tp_as_mapping
Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan el pro-
tocolo de mapeo. Estos campos están documentados en Estructuras de Objetos Mapeo.
Herencia:
El campo tp_as_mapping no se hereda, pero los campos contenidos se heredan individualmente.

254 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

hashfunc PyTypeObject.tp_hash
Un puntero opcional a una función que implementa la función incorporada hash().
La firma es la misma que para PyObject_Hash():

Py_hash_t tp_hash(PyObject *);

El valor -1 no debe retornarse como un valor de retorno normal; Cuando se produce un error durante el cálculo
del valor hash, la función debe establecer una excepción y retornar -1.
Cuando este campo no está establecido (y tp_richcompare no está establecido), se lanza TypeError
cuando hay un intento de tomar el hash del objeto. Esto es lo mismo que establecerlo en
PyObject_HashNotImplemented().
Este campo se puede establecer explícitamente en PyObject_HashNotImplemented() para bloquear
la herencia del método hash de un tipo primario. Esto se interpreta como el equivalente de __hash__ =
None en el nivel de Python, lo que hace que isinstance(o, collections.Hashable) retor-
ne correctamente False. Tenga en cuenta que lo contrario también es cierto: establecer __hash__ =
None en una clase en el nivel de Python dará como resultado que la ranura tp_hash se establezca en
PyObject_HashNotImplemented().
Herencia:
Grupo: tp_hash, tp_richcompare
Este campo es heredado por subtipos junto con tp_richcompare: un subtipo hereda ambos
tp_richcompare y tp_hash, cuando los subtipos tp_richcompare y tp_hash son ambos NULL.
ternaryfunc PyTypeObject.tp_call
Un puntero opcional a una función que implementa la llamada al objeto. Esto debería ser NULL si el objeto no
es invocable. La firma es la misma que para PyObject_Call():

PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);

Herencia:
Este campo es heredado por subtipos.
reprfunc PyTypeObject.tp_str
Un puntero opcional a una función que implementa la operación integrada str(). (Tenga en cuenta que str
es un tipo ahora, y str() llama al constructor para ese tipo. Este constructor llama a PyObject_Str()
para hacer el trabajo real, y PyObject_Str() llamará a este controlador.)
La firma es la misma que para PyObject_Str():

PyObject *tp_str(PyObject *self);

La función debe retornar una cadena de caracteres o un objeto Unicode. Debe ser una representación de cadena
«amigable» del objeto, ya que esta es la representación que será utilizada, entre otras cosas, por la función
print().
Herencia:
Este campo es heredado por subtipos.
Por defecto:
Cuando este campo no está configurado, se llama a PyObject_Repr() para retornar una representación
de cadena de caracteres.
getattrofunc PyTypeObject.tp_getattro
Un puntero opcional a la función «obtener atributo» (get-attribute).
La firma es la misma que para PyObject_GetAttr():

12.3. Objetos Tipo 255

The Python/C API, Versión 3.11.0

PyObject *tp_getattro(PyObject *self, PyObject *attr);

Por lo general, es conveniente establecer este campo en PyObject_GenericGetAttr(), que implementa

la forma normal de buscar atributos de objeto.
Herencia:
Grupo: tp_getattr, tp_getattro
Este campo es heredado por los subtipos junto con tp_getattr: un subtipo hereda ambos tp_getattr y
tp_getattro de su base escriba cuando los subtipos tp_getattr y tp_getattro son ambos NULL.
Por defecto:
PyBaseObject_Type usa PyObject_GenericGetAttr().
setattrofunc PyTypeObject.tp_setattro
Un puntero opcional a la función para configurar y eliminar atributos.
La firma es la misma que para PyObject_SetAttr():

int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);

Además, se debe admitir la configuración de value en NULL para eliminar un atributo. Por lo general, es
conveniente establecer este campo en PyObject_GenericSetAttr(), que implementa la forma normal
de establecer los atributos del objeto.
Herencia:
Grupo: tp_setattr, tp_setattro
Los subtipos heredan este campo junto con tp_setattr: un subtipo hereda ambos tp_setattr y
tp_setattro de su base escriba cuando los subtipos tp_setattr y tp_setattro son ambos NULL.
Por defecto:
PyBaseObject_Type usa PyObject_GenericSetAttr().
PyBufferProcs *PyTypeObject.tp_as_buffer
Puntero a una estructura adicional que contiene campos relevantes solo para objetos que implementan la interfaz
del búfer. Estos campos están documentados en Estructuras de Objetos Búfer.
Herencia:
El campo tp_as_buffer no se hereda, pero los campos contenidos se heredan individualmente.
unsigned long PyTypeObject.tp_flags
Este campo es una máscara de bits de varias banderas. Algunas banderas indican semántica variante para ciertas
situaciones; otros se utilizan para indicar que ciertos campos en el tipo de objeto (o en las estructuras de ex-
tensión a las que se hace referencia a través de tp_as_number, tp_as_sequence, tp_as_mapping,
y tp_as_buffer) que históricamente no siempre estuvieron presentes son válidos; si dicho bit de bandera
está claro, no se debe acceder a los campos de tipo que protege y se debe considerar que tienen un valor cero
o NULL.
Herencia:
La herencia de este campo es complicada. La mayoría de los bits de bandera se heredan individualmente, es
decir, si el tipo base tiene un conjunto de bits de bandera, el subtipo hereda este bit de bandera. Los bits de
bandera que pertenecen a las estructuras de extensión se heredan estrictamente si la estructura de extensión
se hereda, es decir, el valor del tipo base del bit de bandera se copia en el subtipo junto con un puntero a la
estructura de extensión. El bit de bandera Py_TPFLAGS_HAVE_GC se hereda junto con tp_traverse y
tp_clear, es decir, si el bit de bandera Py_TPFLAGS_HAVE_GC está claro en el subtipo y los campos
tp_traverse y tp_clear en el subtipo existen y tienen valores NULL.
Por defecto:
PyBaseObject_Type usa Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE.

256 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Máscaras de bits:
Las siguientes máscaras de bits están definidas actualmente; estos se pueden unidos por OR usando el operador
| para formar el valor del campo tp_flags. El macro PyType_HasFeature() toma un tipo y un valor
de banderas, tp y f, y comprueba si tp->tp_flags & f no es cero.
Py_TPFLAGS_HEAPTYPE
Este bit se establece cuando el objeto de tipo se asigna en el heap, por ejemplo, los tipos creados di-
námicamente usando PyType_FromSpec(). En este caso, el campo ob_type de sus instancias se
considera una referencia al tipo, y el objeto de tipo se llama INCREF cuando se crea una nueva instancia,
y DECREF cuando se destruye una instancia (esto hace no se aplica a instancias de subtipos; solo el tipo
al que hace referencia el ob_type de la instancia obtiene INCREF o DECREF).
Herencia:
???
Py_TPFLAGS_BASETYPE
Este bit se establece cuando el tipo se puede usar como el tipo base de otro tipo. Si este bit es claro, el
tipo no puede subtiparse (similar a una clase «final» en Java).
Herencia:
???
Py_TPFLAGS_READY
Este bit se establece cuando el objeto tipo ha sido completamente inicializado por PyType_Ready().
Herencia:
???
Py_TPFLAGS_READYING
Este bit se establece mientras PyType_Ready() está en el proceso de inicialización del objeto tipo.
Herencia:
???
Py_TPFLAGS_HAVE_GC
Este bit se establece cuando el objeto admite la recolección de elementos no utilizados. Si se es-
tablece este bit, las instancias deben crearse usando PyObject_GC_New() y destruirse usando
PyObject_GC_Del(). Más información en la sección Apoyo a la recolección de basura cíclica. Este
bit también implica que los campos relacionados con GC tp_traverse y tp_clear están presentes
en el objeto de tipo.
Herencia:
Grupo: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear
El bit de indicador Py_TPFLAGS_HAVE_GC se hereda junto con los campos tp_traverse y
tp_clear, es decir, si el bit de indicador Py_TPFLAGS_HAVE_GC está claro en el subtipo y los
campos tp_traverse y tp_clear en el subtipo existen y tienen valores NULL.
Py_TPFLAGS_DEFAULT
Esta es una máscara de bits de todos los bits que pertenecen a la existencia de ciertos cam-
pos en el objeto de tipo y sus estructuras de extensión. Actualmente, incluye los siguientes bits:
Py_TPFLAGS_HAVE_STACKLESS_EXTENSION.
Herencia:
???
Py_TPFLAGS_METHOD_DESCRIPTOR
Este bit indica que los objetos se comportan como métodos independientes.
Si este indicador está configurado para type(meth), entonces:

12.3. Objetos Tipo 257

The Python/C API, Versión 3.11.0

• meth.__get__(obj, cls)(*args, **kwds) (con obj no None) debe ser equivalente

a meth(obj, *args, **kwds).
• meth.__get__(None, cls)(*args, **kwds) debe ser equivalente a meth(*args,
**kwds).
Este indicador (flag) permite una optimización para llamadas a métodos típicos como obj.meth():
evita crear un objeto temporal de «método vinculado» para obj.meth.
Nuevo en la versión 3.8.
Herencia:
This flag is never inherited by types without the Py_TPFLAGS_IMMUTABLETYPE flag set. For exten-
sion types, it is inherited whenever tp_descr_get is inherited.
Py_TPFLAGS_LONG_SUBCLASS

Py_TPFLAGS_LIST_SUBCLASS

Py_TPFLAGS_TUPLE_SUBCLASS

Py_TPFLAGS_BYTES_SUBCLASS

Py_TPFLAGS_UNICODE_SUBCLASS

Py_TPFLAGS_DICT_SUBCLASS

Py_TPFLAGS_BASE_EXC_SUBCLASS

Py_TPFLAGS_TYPE_SUBCLASS
Estas marcas son utilizadas por funciones como PyLong_Check() para determinar rápidamente si un
tipo es una subclase de un tipo incorporado; dichos controles específicos son más rápidos que un control
genérico, como PyObject_IsInstance(). Los tipos personalizados que heredan de los elementos
integrados deben tener su tp_flags configurado correctamente, o el código que interactúa con dichos
tipos se comportará de manera diferente dependiendo del tipo de verificación que se use.
Py_TPFLAGS_HAVE_FINALIZE
Este bit se establece cuando la ranura tp_finalize está presente en la estructura de tipo.
Nuevo en la versión 3.4.
Obsoleto desde la versión 3.8: Este indicador ya no es necesario, ya que el intérprete asume que: el espacio
tp_finalize siempre está presente en la estructura de tipos.
Py_TPFLAGS_HAVE_VECTORCALL
Este bit se establece cuando la clase implementa protocolo vectorcall. Consulte
tp_vectorcall_offset para obtener más detalles.
Herencia:
This bit is inherited for types with the Py_TPFLAGS_IMMUTABLETYPE flag set, if tp_call is also
inherited.
Nuevo en la versión 3.9.
Py_TPFLAGS_IMMUTABLETYPE
Este bit se establece para objetos de tipo que son inmutables: los atributos de tipo no se pueden establecer
ni eliminar.
PyType_Ready() aplica automáticamente este indicador a static types.
Herencia:
Este flag no se hereda.
Nuevo en la versión 3.10.

258 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Py_TPFLAGS_DISALLOW_INSTANTIATION
No permita la creación de instancias del tipo: establezca tp_new en NULL y no cree la clave __new__
en el diccionario de tipos.
La bandera debe establecerse antes de crear el tipo, no después. Por ejemplo, debe establecerse antes de
que se llame a PyType_Ready() en el tipo.
La bandera se establece automáticamente en static types si tp_base es NULL o
&PyBaseObject_Type y tp_new es NULL.
Herencia:
This flag is not inherited. However, subclasses will not be instantiable unless they provide a non-NULL
tp_new (which is only possible via the C API).

Nota: To disallow instantiating a class directly but allow instantiating its subclasses (e.g. for an abstract
base class), do not use this flag. Instead, make tp_new only succeed for subclasses.

Nuevo en la versión 3.10.

Py_TPFLAGS_MAPPING
Este bit indica que las instancias de la clase pueden coincidir con los patrones de correspondencia cuando
se utilizan como sujeto de un bloque match. Se configura automáticamente al registrar o subclasificar
collections.abc.Mapping, y se desarma al registrar collections.abc.Sequence.

Nota: Py_TPFLAGS_MAPPING and Py_TPFLAGS_SEQUENCE are mutually exclusive; it is an error

to enable both flags simultaneously.

Herencia:
Esta bandera la heredan los tipos que aún no configuran Py_TPFLAGS_SEQUENCE.
Ver también:
PEP 634 - Coincidencia de patrones estructurales: especificación
Nuevo en la versión 3.10.
Py_TPFLAGS_SEQUENCE
Este bit indica que las instancias de la clase pueden coincidir con los patrones de secuencia cuando se
utilizan como sujeto de un bloque match. Se configura automáticamente al registrar o subclasificar
collections.abc.Sequence, y se desarma al registrar collections.abc.Mapping.

Nota: Py_TPFLAGS_MAPPING and Py_TPFLAGS_SEQUENCE are mutually exclusive; it is an error

to enable both flags simultaneously.

Herencia:
Esta bandera la heredan los tipos que aún no configuran Py_TPFLAGS_MAPPING.
Ver también:
PEP 634 - Coincidencia de patrones estructurales: especificación
Nuevo en la versión 3.10.
const char *PyTypeObject.tp_doc
Un puntero opcional a una cadena de caracteres de C terminada en NULL que proporciona la cadena de docu-
mentación para este tipo de objeto. Esto se expone como el atributo __doc__ en el tipo y las instancias del
tipo.
Herencia:

12.3. Objetos Tipo 259

The Python/C API, Versión 3.11.0

Este campo es no heredado por los subtipos.

traverseproc PyTypeObject.tp_traverse
Un puntero opcional a una función transversal para el recolector de basura. Esto solo se usa si se establece el
bit de la bandera (flag) Py_TPFLAGS_HAVE_GC. La firma es:

int tp_traverse(PyObject *self, visitproc visit, void *arg);

Se puede encontrar más información sobre el esquema de recolección de basura de Python en la sección Apoyo
a la recolección de basura cíclica.
El puntero tp_traverse es utilizado por el recolector de basura para detectar ciclos de referencia. Una
implementación típica de un tp_traverse simplemente llama a Py_VISIT() en cada uno de los miem-
bros de la instancia que son objetos de Python que posee la instancia. Por ejemplo, esta es la función
local_traverse() del módulo de extensión _thread:

static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
Py_VISIT(self->args);
Py_VISIT(self->kw);
Py_VISIT(self->dict);
return 0;
}

Tenga en cuenta que Py_VISIT() solo se llama a aquellos miembros que pueden participar en los ciclos de
referencia. Aunque también hay un miembro self->key, solo puede ser NULL o una cadena de caracteres
de Python y, por lo tanto, no puede ser parte de un ciclo de referencia.
Por otro lado, incluso si sabe que un miembro nunca puede ser parte de un ciclo, como ayuda para la depuración
puede visitarlo de todos modos solo para que la función get_referents() del módulo gc lo incluirá.

Advertencia: Al implementar tp_traverse, solo se deben visitar los miembros que tienen la instancia
owns (por tener referencias fuertes). Por ejemplo, si un objeto admite referencias débiles a través de la ranura
tp_weaklist, el puntero que respalda la lista vinculada (a lo que apunta tp_weaklist) no debe visitarse
ya que la instancia no posee directamente las referencias débiles a sí misma (la lista de referencias débiles
está ahí para respaldar la maquinaria de referencia débil, pero la instancia no tiene una fuerte referencia a
los elementos dentro de ella, ya que pueden eliminarse incluso si la instancia todavía está viva).

Tenga en cuenta que Py_VISIT() requiere los parámetros visit y arg para local_traverse() para
tener estos nombres específicos; no les llames de ninguna manera.
Las instancias de heap-allocated types contienen una referencia a su tipo. Por lo tanto, su función transver-
sal debe visitar Py_TYPE(self) o delegar esta responsabilidad llamando a tp_traverse de otro tipo
asignado al heap (como una superclase asignada al heap). Si no es así, es posible que el objeto de tipo no se
recolecte como basura.
Distinto en la versión 3.9: Se espera que los tipos asignados al heap visiten Py_TYPE(self) en
tp_traverse. En versiones anteriores de Python, debido al bug 40217, hacer esto puede provocar fallas en
las subclases.
Herencia:
Grupo: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear
Este campo es heredado por los subtipos junto con tp_clear y el Py_TPFLAGS_HAVE_GC bit de bandera:
el bit de bandera, tp_traverse, y tp_clear se heredan todos del tipo base si todos son cero en el subtipo.
inquiry PyTypeObject.tp_clear
Un puntero opcional a una función de limpieza (clear function) para el recolector de basura. Esto solo se usa
si se establece el bit de bandera Py_TPFLAGS_HAVE_GC. La firma es:

260 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

int tp_clear(PyObject *);

La función miembro tp_clear se usa para romper los ciclos de referencia en la basura cíclica detectada
por el recolector de basura. En conjunto, todas las funciones tp_clear en el sistema deben combinarse para
romper todos los ciclos de referencia. Esto es sutil y, en caso de duda, proporcione una función tp_clear.
Por ejemplo, el tipo de tupla no implementa una función tp_clear, porque es posible demostrar que ningún
ciclo de referencia puede estar compuesto completamente de tuplas. Por lo tanto, las funciones tp_clear de
otros tipos deben ser suficientes para romper cualquier ciclo que contenga una tupla. Esto no es inmediatamente
obvio, y rara vez hay una buena razón para evitar la implementación de tp_clear.
Las implementaciones de tp_clear deberían descartar las referencias de la instancia a las de sus miembros
que pueden ser objetos de Python, y establecer sus punteros a esos miembros en NULL, como en el siguiente
ejemplo:

static int
local_clear(localobject *self)
{
Py_CLEAR(self->key);
Py_CLEAR(self->args);
Py_CLEAR(self->kw);
Py_CLEAR(self->dict);
return 0;
}

Se debe utilizar el macro Py_CLEAR(), porque borrar las referencias es delicado: la referencia al objeto
contenido no se debe disminuir hasta después de que el puntero al objeto contenido se establezca en NULL.
Esto se debe a que la disminución del conteo de referencias puede hacer que el objeto contenido se convierta en
basura, lo que desencadena una cadena de actividad de recuperación que puede incluir la invocación de código
arbitrario de Python (debido a finalizadores o devoluciones de llamada de reflujo débil, asociadas con el objeto
contenido). Si es posible que dicho código haga referencia a self nuevamente, es importante que el puntero al
objeto contenido sea NULL en ese momento, de modo que self sepa que el objeto contenido ya no se puede
usar. El macro Py_CLEAR() realiza las operaciones en un orden seguro.
Tenga en cuenta que tp_clear no se llama siempre antes de que se desasigne una instancia. Por ejemplo,
cuando el recuento de referencias es suficiente para determinar que un objeto ya no se utiliza, el recolector de
basura cíclico no está involucrado y se llama directamente a tp_dealloc.
Debido a que el objetivo de tp_clear es romper los ciclos de referencia, no es necesario borrar objetos
contenidos como cadenas de caracteres de Python o enteros de Python, que no pueden participar en los ciclos
de referencia. Por otro lado, puede ser conveniente borrar todos los objetos Python contenidos y escribir la
función tp_dealloc para invocar tp_clear.
Se puede encontrar más información sobre el esquema de recolección de basura de Python en la sección Apoyo
a la recolección de basura cíclica.
Herencia:
Grupo: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear
Este campo es heredado por subtipos junto con tp_traverse y el Py_TPFLAGS_HAVE_GC bit de ban-
dera: el bit de bandera, tp_traverse, y tp_clear se heredan todos del tipo base si todos son cero en el
subtipo.
richcmpfunc PyTypeObject.tp_richcompare
Un puntero opcional a la función de comparación enriquecida, cuya firma es:

PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);

Se garantiza que el primer parámetro será una instancia del tipo definido por PyTypeObject.
La función debería retornar el resultado de la comparación (generalmente Py_True o Py_False). Si la
comparación no está definida, debe retornar Py_NotImplemented, si se produce otro error, debe retornar
NULL y establecer una condición de excepción.

12.3. Objetos Tipo 261

The Python/C API, Versión 3.11.0

Las siguientes constantes se definen para ser utilizadas como el tercer argumento para tp_richcompare y
para PyObject_RichCompare():

Constante Comparación
Py_LT <
Py_LE <=
Py_EQ ==
Py_NE !=
Py_GT >
Py_GE >=

El siguiente macro está definido para facilitar la escritura de funciones de comparación enriquecidas:
Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)
Retorna Py_True o Py_False de la función, según el resultado de una comparación. VAL_A y
VAL_B deben ser ordenados por operadores de comparación C (por ejemplo, pueden ser enteros
o punto flotantes de C). El tercer argumento especifica la operación solicitada, como por ejemplo
PyObject_RichCompare().
El conteo de referencia del valor de retorno se incrementa correctamente.
En caso de error, establece una excepción y retorna NULL de la función.
Nuevo en la versión 3.7.
Herencia:
Grupo: tp_hash, tp_richcompare
Este campo es heredado por subtipos junto con tp_hash: un subtipo hereda tp_richcompare y
tp_hash cuando el subtipo tp_richcompare y tp_hash son ambos NULL.
Por defecto:
PyBaseObject_Type proporciona una implementación tp_richcompare, que puede ser heredada.
Sin embargo, si solo se define tp_hash, ni siquiera se utiliza la función heredada y las instancias del tipo no
podrán participar en ninguna comparación.
Py_ssize_t PyTypeObject.tp_weaklistoffset
If the instances of this type are weakly referenceable, this field is greater than zero and contains the offset in
the instance structure of the weak reference list head (ignoring the GC header, if present); this offset is used
by PyObject_ClearWeakRefs() and the PyWeakref_* functions. The instance structure needs to
include a field of type PyObject* which is initialized to NULL.
No confunda este campo con tp_weaklist; ese es el encabezado de la lista para referencias débiles al objeto
de tipo en sí.
Herencia:
Este campo es heredado por subtipos, pero consulte las reglas que se enumeran a continuación. Un subtipo
puede anular este desplazamiento; Esto significa que el subtipo utiliza un encabezado de lista de referen-
cia débil diferente que el tipo base. Dado que el encabezado de la lista siempre se encuentra a través de
tp_weaklistoffset, esto no debería ser un problema.
Cuando un tipo definido por una declaración de clase no tiene __slots__ declaración, y ninguno de sus
tipos base es débilmente referenciable, el tipo se hace débilmente referenciable al agregar una ranura de en-
cabezado de lista de referencia débil al diseño de la instancia y configurando tp_weaklistoffset del
desplazamiento de esa ranura.
Cuando la declaración de un tipo __slots__ contiene un espacio llamado __weakref__, ese espacio se
convierte en el encabezado de la lista de referencia débil para las instancias del tipo, y el desplazamiento del
espacio se almacena en el tipo tp_weaklistoffset.
Cuando la declaración de un tipo __slots__ no contiene un espacio llamado __weakref__, el tipo hereda
su tp_weaklistoffset de su tipo base.

262 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

getiterfunc PyTypeObject.tp_iter
An optional pointer to a function that returns an iterator for the object. Its presence normally signals that the
instances of this type are iterable (although sequences may be iterable without this function).
Esta función tiene la misma firma que PyObject_GetIter():

PyObject *tp_iter(PyObject *self);

Herencia:
Este campo es heredado por subtipos.
iternextfunc PyTypeObject.tp_iternext
An optional pointer to a function that returns the next item in an iterator. The signature is:

PyObject *tp_iternext(PyObject *self);

Cuando el iterador está agotado, debe retornar NULL; a la excepción StopIteration puede o no estable-
cerse. Cuando se produce otro error, también debe retornar NULL. Su presencia indica que las instancias de
este tipo son iteradores.
Los tipos de iterador también deberían definir la función tp_iter, y esa función debería retornar la instancia
de iterador en sí (no una nueva instancia de iterador).
Esta función tiene la misma firma que PyIter_Next().
Herencia:
Este campo es heredado por subtipos.
struct PyMethodDef *PyTypeObject.tp_methods
Un puntero opcional a un arreglo estático terminado en NULL de estructuras PyMethodDef, declarando
métodos regulares de este tipo.
Para cada entrada en el arreglo, se agrega una entrada al diccionario del tipo (ver tp_dict a continuación)
que contiene un descriptor method.
Herencia:
Los subtipos no heredan este campo (los métodos se heredan mediante un mecanismo diferente).
struct PyMemberDef *PyTypeObject.tp_members
Un puntero opcional a un arreglo estático terminado en NULL de estructuras PyMemberDef, declarando
miembros de datos regulares (campos o ranuras) de instancias de este tipo.
Para cada entrada en el arreglo, se agrega una entrada al diccionario del tipo (ver tp_dict a continuación)
que contiene un descriptor member.
Herencia:
Los subtipos no heredan este campo (los miembros se heredan mediante un mecanismo diferente).
struct PyGetSetDef *PyTypeObject.tp_getset
Un puntero opcional a un arreglo estático terminado en NULL de estructuras PyGetSetDef, declarando
atributos calculados de instancias de este tipo.
Para cada entrada en el arreglo, se agrega una entrada al diccionario del tipo (ver tp_dict a continuación)
que contiene un descriptor getset.
Herencia:
Este campo no es heredado por los subtipos (los atributos computados se heredan a través de un mecanismo
diferente).

12.3. Objetos Tipo 263

The Python/C API, Versión 3.11.0

PyTypeObject *PyTypeObject.tp_base
Un puntero opcional a un tipo base del que se heredan las propiedades de tipo. En este nivel, solo se admite
una herencia única; La herencia múltiple requiere la creación dinámica de un objeto tipo llamando al metatipo.

Nota: La inicialización de ranuras está sujeta a las reglas de inicialización de globales. C99 re-
quiere que los inicializadores sean «constantes de dirección». Los designadores de funciones como
PyType_GenericNew(), con conversión implícita a un puntero, son constantes de dirección C99 váli-
das.
Sin embargo, el operador unario “&” aplicado a una variable no estática como PyBaseObject_Type()
no es necesario para producir una dirección constante. Los compiladores pueden admitir esto (gcc lo hace),
MSVC no. Ambos compiladores son estrictamente estándar conforme a este comportamiento particular.
En consecuencia, tp_base debe establecerse en la función init del módulo de extensión.

Herencia:
Este campo no es heredado por los subtipos (obviamente).
Por defecto:
Este campo predeterminado es &PyBaseObject_Type (que para los programadores de Python se conoce
como el tipo objeto).
PyObject *PyTypeObject.tp_dict
El diccionario del tipo se almacena aquí por PyType_Ready().
Este campo normalmente debe inicializarse a NULL antes de llamar a PyType_Ready; también se puede
inicializar en un diccionario que contiene atributos iniciales para el tipo. Una vez PyType_Ready() ha
inicializado el tipo, los atributos adicionales para el tipo pueden agregarse a este diccionario solo si no corres-
ponden a operaciones sobrecargadas (como __add__()).
Herencia:
Este campo no es heredado por los subtipos (aunque los atributos definidos aquí se heredan a través de un
mecanismo diferente).
Por defecto:
Si este campo es NULL, PyType_Ready() le asignará un nuevo diccionario.

Advertencia: No es seguro usar PyDict_SetItem() en o modificar de otra manera a tp_dict con

el diccionario C-API.

descrgetfunc PyTypeObject.tp_descr_get
Un puntero opcional a una función «obtener descriptor» (descriptor ger).
La firma de la función es:

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

Herencia:
Este campo es heredado por subtipos.
descrsetfunc PyTypeObject.tp_descr_set
Un puntero opcional a una función para configurar y eliminar el valor de un descriptor.
La firma de la función es:

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

264 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

El argumento value se establece a NULL para borrar el valor.

Herencia:
Este campo es heredado por subtipos.
Py_ssize_t PyTypeObject.tp_dictoffset
Si las instancias de este tipo tienen un diccionario que contiene variables de instancia, este campo no es cero
y contiene el desplazamiento en las instancias del tipo del diccionario de variables de instancia; este desplaza-
miento es utilizado por PyObject_GenericGetAttr().
No confunda este campo con tp_dict; ese es el diccionario para los atributos del tipo de objeto en sí.
Si el valor de este campo es mayor que cero, especifica el desplazamiento desde el inicio de la estructura de
la instancia. Si el valor es menor que cero, especifica el desplazamiento desde el end de la estructura de la
instancia. Un desplazamiento negativo es más costoso de usar y solo debe usarse cuando la estructura de la
instancia contiene una parte de longitud variable. Esto se utiliza, por ejemplo, para agregar un diccionario de
variables de instancia a los subtipos de str o tuple. Tenga en cuenta que el campo tp_basicsize debe
tener en cuenta el diccionario agregado al final en ese caso, aunque el diccionario no esté incluido en el diseño
básico del objeto. En un sistema con un tamaño de puntero de 4 bytes, tp_dictoffset debe establecerse
en -4 para indicar que el diccionario está al final de la estructura.
The tp_dictoffset should be regarded as write-only. To get the pointer to the dictionary call
PyObject_GenericGetDict(). Calling PyObject_GenericGetDict() may need to allocate
memory for the dictionary, so it is may be more efficient to call PyObject_GetAttr() when accessing
an attribute on the object.
Herencia:
Este campo es heredado por subtipos, pero consulte las reglas que se enumeran a continuación. Un subtipo
puede anular este desplazamiento; Esto significa que las instancias de subtipo almacenan el diccionario en
un desplazamiento de diferencia que el tipo base. Dado que el diccionario siempre se encuentra a través de
tp_dictoffset, esto no debería ser un problema.
Cuando un tipo definido por una declaración de clase no tiene __slots__ declaración, y ninguno de sus tipos
base tiene un diccionario de variable de instancia, se agrega un espacio de diccionario al diseño de la instancia
y el tp_dictoffset está configurado para el desplazamiento de esa ranura.
Cuando un tipo definido por una declaración de clase tiene una declaración __slots__, el tipo hereda su
tp_dictoffset de su tipo base.
(Agrega un espacio llamado __dict__ a la declaración __slots__ no tiene el efecto esperado, solo causa
confusión. Quizás esto debería agregarse como una característica como __weakref__ aunque.)
Por defecto:
Esta ranura no tiene ningún valor predeterminado. Para tipos estáticos, si el campo es NULL, no se crea ningún
__dict__ para las instancias.
initproc PyTypeObject.tp_init
Un puntero opcional a una función de inicialización de instancia.
Esta función corresponde al método de clases __init__(). Como __init__(), es posible crear una
instancia sin llamar a __init__(), y es posible reinicializar una instancia llamando de nuevo a su método
__init__().
La firma de la función es:

int tp_init(PyObject *self, PyObject *args, PyObject *kwds);

El argumento propio es la instancia que se debe inicializar; los argumentos args y kwds representan argumentos
posicionales y de palabras clave de la llamada a __init__().
La función tp_init, si no es NULL, se llama cuando una instancia se crea normalmente llamando a su tipo,
después de la función tp_new del tipo ha retornado una instancia del tipo. Si la función tp_new retorna

12.3. Objetos Tipo 265

The Python/C API, Versión 3.11.0

una instancia de otro tipo que no es un subtipo del tipo original, no se llama la función tp_init; if tp_new
retorna una instancia de un subtipo del tipo original, se llama al subtipo tp_init.
Retorna 0 en caso de éxito, -1 y establece una excepción en caso de error.
Herencia:
Este campo es heredado por subtipos.
Por defecto:
Para tipos estáticos, este campo no tiene un valor predeterminado.
allocfunc PyTypeObject.tp_alloc
Un puntero opcional a una función de asignación de instancia.
La firma de la función es:

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);

Herencia:
Este campo es heredado por subtipos estáticos, pero no por subtipos dinámicos (subtipos creados por una
declaración de clase).
Por defecto:
Para subtipos dinámicos, este campo siempre se establece en PyType_GenericAlloc(), para forzar una
estrategia de asignación de heap estándar.
Para subtipos estáticos, PyBaseObject_Type utiliza PyType_GenericAlloc(). Ese es el valor re-
comendado para todos los tipos definidos estáticamente.
newfunc PyTypeObject.tp_new
Un puntero opcional a una función de creación de instancias.
La firma de la función es:

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);

El argumento subtype es el tipo de objeto que se está creando; los argumentos args y kwds representan argu-
mentos posicionales y de palabras clave de la llamada al tipo. Tenga en cuenta que subtype no tiene que ser igual
al tipo cuya función tp_new es llamada; puede ser un subtipo de ese tipo (pero no un tipo no relacionado).
La función tp_new debería llamar a subtype->tp_alloc(subtype, nitems) para asignar espacio
para el objeto, y luego hacer solo la inicialización adicional que sea absolutamente necesaria. La inicialización
que se puede ignorar o repetir de forma segura debe colocarse en el controlador tp_init. Una buena regla
general es que para los tipos inmutables, toda la inicialización debe tener lugar en tp_new, mientras que para
los tipos mutables, la mayoría de las inicializaciones se deben diferir a tp_init.
Configure la marca Py_TPFLAGS_DISALLOW_INSTANTIATION para no permitir la creación de instan-
cias del tipo en Python.
Herencia:
Este campo se hereda por subtipos, excepto que no lo heredan tipos estáticos cuyo tp_base es NULL o
&PyBaseObject_Type.
Por defecto:
Para tipos estáticos, este campo no tiene ningún valor predeterminado. Esto significa que si la ranura se define
como NULL, no se puede llamar al tipo para crear nuevas instancias; presumiblemente hay alguna otra forma
de crear instancias, como una función de fábrica.
freefunc PyTypeObject.tp_free
Un puntero opcional a una función de desasignación de instancia. Su firma es:

266 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

void tp_free(void *self);

Un inicializador que es compatible con esta firma es PyObject_Free().

Herencia:
Este campo es heredado por subtipos estáticos, pero no por subtipos dinámicos (subtipos creados por una
declaración de clase)
Por defecto:
En los subtipos dinámicos, este campo se establece en un desasignador adecuado para que coincida con
PyType_GenericAlloc() y el valor del bit de bandera Py_TPFLAGS_HAVE_GC.
Para subtipos estáticos, PyBaseObject_Type usa PyObject_Del.
inquiry PyTypeObject.tp_is_gc
Un puntero opcional a una función llamada por el recolector de basura.
El recolector de basura necesita saber si un objeto en particular es coleccionable o no. Normalmente, es sufi-
ciente mirar el el campo tp_flags del tipo objeto , y verificar el bit de bandera Py_TPFLAGS_HAVE_GC.
Pero algunos tipos tienen una mezcla de instancias asignadas estáticamente y dinámicamente, y las instancias
asignadas estáticamente no son coleccionables. Tales tipos deberían definir esta función; debería retornar 1
para una instancia coleccionable y 0 para una instancia no coleccionable. La firma es:

int tp_is_gc(PyObject *self);

(El único ejemplo de esto son los tipos en sí. El metatipo, PyType_Type, define esta función para distinguir
entre tipos estática y dinámicamente asignados).
Herencia:
Este campo es heredado por subtipos.
Por defecto:
Esta ranura no tiene valor predeterminado. Si este campo es NULL, se utiliza Py_TPFLAGS_HAVE_GC como
el equivalente funcional.
PyObject *PyTypeObject.tp_bases
Tupla de tipos base.
Esto se establece para los tipos creados por una declaración de clase. Debería ser NULL para los tipos estáti-
camente definidos.
Herencia:
Este campo no se hereda.
PyObject *PyTypeObject.tp_mro
Tupla que contiene el conjunto expandido de tipos base, comenzando con el tipo en sí y terminando con
object, en orden de resolución de método.
Herencia:
Este campo no se hereda; se calcula fresco por PyType_Ready().
PyObject *PyTypeObject.tp_cache
No usado. Solo para uso interno.
Herencia:
Este campo no se hereda.

12.3. Objetos Tipo 267

The Python/C API, Versión 3.11.0

PyObject *PyTypeObject.tp_subclasses
Lista de referencias débiles a subclases. Solo para uso interno.
Herencia:
Este campo no se hereda.
PyObject *PyTypeObject.tp_weaklist
Cabecera de lista de referencia débil, para referencias débiles a este tipo de objeto. No heredado Solo para uso
interno.
Herencia:
Este campo no se hereda.
destructor PyTypeObject.tp_del
Este campo está en desuso. Use tp_finalize en su lugar.
unsigned int PyTypeObject.tp_version_tag
Se usa para indexar en el caché de métodos. Solo para uso interno.
Herencia:
Este campo no se hereda.
destructor PyTypeObject.tp_finalize
Un puntero opcional a una función de finalización de instancia. Su firma es:
void tp_finalize(PyObject *self);

Si tp_finalize está configurado, el intérprete lo llama una vez cuando finaliza una instancia. Se llama
desde el recolector de basura (si la instancia es parte de un ciclo de referencia aislado) o justo antes de que el
objeto se desasigne. De cualquier manera, se garantiza que se invocará antes de intentar romper los ciclos de
referencia, asegurando que encuentre el objeto en un estado sano.
tp_finalize no debe mutar el estado de excepción actual; por lo tanto, una forma recomendada de escribir
un finalizador no trivial es:
static void
local_finalize(PyObject *self)
{
PyObject *error_type, *error_value, *error_traceback;

/* Save the current exception, if any. */

PyErr_Fetch(&error_type, &error_value, &error_traceback);

/* ... */

/* Restore the saved exception. */

PyErr_Restore(error_type, error_value, error_traceback);
}

Además, tenga en cuenta que, en un Python que ha recolectado basura, se puede llamar a tp_dealloc desde
cualquier hilo de Python, no solo el hilo que creó el objeto (si el objeto se convierte en parte de un ciclo de
conteo de referencias, ese ciclo puede ser recogido por una recolección de basura en cualquier hilo). Esto no
es un problema para las llamadas a la API de Python, ya que el hilo en el que se llama tp_dealloc será
el propietario del Bloqueo Global del Intérprete (GIL, por sus siglas en inglés Global Interpreter Lock). Sin
embargo, si el objeto que se destruye a su vez destruye objetos de alguna otra biblioteca C o C++, se debe tener
cuidado para garantizar que la destrucción de esos objetos en el hilo que se llama tp_dealloc no violará
ningún supuesto de la biblioteca.
Herencia:
Este campo es heredado por subtipos.
Nuevo en la versión 3.4.

268 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Distinto en la versión 3.8: Before version 3.8 it was necessary to set the Py_TPFLAGS_HAVE_FINALIZE
flags bit in order for this field to be used. This is no longer required.
Ver también:
«Finalización segura de objetos» (PEP 442)
vectorcallfunc PyTypeObject.tp_vectorcall
Función Vectorcall a utilizar para llamadas de este tipo de objeto. En otras palabras, se usa para implementar
vectorcall para type.__call__. Si tp_vectorcall es NULL, se usa la implementación de llamada
predeterminada usando __new__ y __init__.
Herencia:
Este campo nunca se hereda.
Nuevo en la versión 3.9: (el campo existe desde 3.8 pero solo se usa desde 3.9)

12.3.6 Tipos estáticos

Tradicionalmente, los tipos definidos en el código C son static, es decir, una estructura estática PyTypeObject se
define directamente en el código y se inicializa usando PyType_Ready().
Esto da como resultado tipos que están limitados en relación con los tipos definidos en Python:
• Los tipos estáticos están limitados a una base, es decir, no pueden usar herencia múltiple.
• Los objetos de tipo estático (pero no necesariamente sus instancias) son inmutables. No es posible agregar o
modificar los atributos del objeto tipo desde Python.
• Los objetos de tipo estático se comparten en sub intérpretes, por lo que no deben incluir ningún estado específico
del sub interpretador.
Also, since PyTypeObject is only part of the Limited API as an opaque struct, any extension modules using static
types must be compiled for a specific Python minor version.

12.3.7 Tipos Heap

Una alternativa a tipos estáticos es heap-allocated types, o tipos heap para abreviar, que se corresponden estrecha-
mente con las clases creadas por la declaración class de Python. Los tipos de heap tienen establecida la bandera
Py_TPFLAGS_HEAPTYPE.
Esto se hace llenando una estructura PyType_Spec y llamando a PyType_FromSpec(),
PyType_FromSpecWithBases() o PyType_FromModuleAndSpec().

12.4 Estructuras de Objetos de Números

type PyNumberMethods
Esta estructura contiene punteros a las funciones que utiliza un objeto para implementar el protocolo numérico.
Cada función es utilizada por la función de un nombre similar documentado en la sección Protocolo de números.
Aquí está la definición de la estructura:

typedef struct {
binaryfunc nb_add;
binaryfunc nb_subtract;
binaryfunc nb_multiply;
binaryfunc nb_remainder;
binaryfunc nb_divmod;
ternaryfunc nb_power;
(continué en la próxima página)

12.4. Estructuras de Objetos de Números 269

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

unaryfunc nb_negative;
unaryfunc nb_positive;
unaryfunc nb_absolute;
inquiry nb_bool;
unaryfunc nb_invert;
binaryfunc nb_lshift;
binaryfunc nb_rshift;
binaryfunc nb_and;
binaryfunc nb_xor;
binaryfunc nb_or;
unaryfunc nb_int;
void *nb_reserved;
unaryfunc nb_float;

binaryfunc nb_inplace_add;
binaryfunc nb_inplace_subtract;
binaryfunc nb_inplace_multiply;
binaryfunc nb_inplace_remainder;
ternaryfunc nb_inplace_power;
binaryfunc nb_inplace_lshift;
binaryfunc nb_inplace_rshift;
binaryfunc nb_inplace_and;
binaryfunc nb_inplace_xor;
binaryfunc nb_inplace_or;

binaryfunc nb_floor_divide;
binaryfunc nb_true_divide;
binaryfunc nb_inplace_floor_divide;
binaryfunc nb_inplace_true_divide;

unaryfunc nb_index;

binaryfunc nb_matrix_multiply;
binaryfunc nb_inplace_matrix_multiply;
} PyNumberMethods;

Nota: Las funciones binarias y ternarias deben verificar el tipo de todos sus operandos e implementar las con-
versiones necesarias (al menos uno de los operandos es una instancia del tipo definido). Si la operación no está
definida para los operandos dados, las funciones binarias y ternarias deben retornar Py_NotImplemented,
si se produce otro error, deben retornar NULL y establecer una excepción.

Nota: El campo nb_reserved siempre debe ser NULL. Anteriormente se llamaba nb_long, y se renom-
bró en Python 3.0.1.

binaryfunc PyNumberMethods.nb_add

binaryfunc PyNumberMethods.nb_subtract

binaryfunc PyNumberMethods.nb_multiply

binaryfunc PyNumberMethods.nb_remainder

binaryfunc PyNumberMethods.nb_divmod

ternaryfunc PyNumberMethods.nb_power

unaryfunc PyNumberMethods.nb_negative

270 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

unaryfunc PyNumberMethods.nb_positive

unaryfunc PyNumberMethods.nb_absolute

inquiry PyNumberMethods.nb_bool

unaryfunc PyNumberMethods.nb_invert

binaryfunc PyNumberMethods.nb_lshift

binaryfunc PyNumberMethods.nb_rshift

binaryfunc PyNumberMethods.nb_and

binaryfunc PyNumberMethods.nb_xor

binaryfunc PyNumberMethods.nb_or

unaryfunc PyNumberMethods.nb_int

void *PyNumberMethods.nb_reserved

unaryfunc PyNumberMethods.nb_float

binaryfunc PyNumberMethods.nb_inplace_add

binaryfunc PyNumberMethods.nb_inplace_subtract

binaryfunc PyNumberMethods.nb_inplace_multiply

binaryfunc PyNumberMethods.nb_inplace_remainder

ternaryfunc PyNumberMethods.nb_inplace_power

binaryfunc PyNumberMethods.nb_inplace_lshift

binaryfunc PyNumberMethods.nb_inplace_rshift

binaryfunc PyNumberMethods.nb_inplace_and

binaryfunc PyNumberMethods.nb_inplace_xor

binaryfunc PyNumberMethods.nb_inplace_or

binaryfunc PyNumberMethods.nb_floor_divide

binaryfunc PyNumberMethods.nb_true_divide

binaryfunc PyNumberMethods.nb_inplace_floor_divide

binaryfunc PyNumberMethods.nb_inplace_true_divide

unaryfunc PyNumberMethods.nb_index

binaryfunc PyNumberMethods.nb_matrix_multiply

binaryfunc PyNumberMethods.nb_inplace_matrix_multiply

12.4. Estructuras de Objetos de Números 271

The Python/C API, Versión 3.11.0

12.5 Estructuras de Objetos Mapeo

type PyMappingMethods
Esta estructura contiene punteros a las funciones que utiliza un objeto para implementar el protocolo de mapeo.
Tiene tres miembros:
lenfunc PyMappingMethods.mp_length
Esta función es utilizada por PyMapping_Size() y PyObject_Size(), y tiene la misma firma. Esta
ranura puede establecerse en NULL si el objeto no tiene una longitud definida.
binaryfunc PyMappingMethods.mp_subscript
Esta función es utilizada por PyObject_GetItem() y PySequence_GetSlice(), y tie-
ne la misma firma que PyObject_GetItem(). Este espacio debe llenarse para que la función
PyMapping_Check() retorna 1, de lo contrario puede ser NULL.
objobjargproc PyMappingMethods.mp_ass_subscript
Esta función es utilizada por PyObject_SetItem(), PyObject_DelItem(),
PyObject_SetSlice() y PyObject_DelSlice(). Tiene la misma firma que
PyObject_SetItem(), pero v también se puede establecer en NULL para eliminar un elemento.
Si este espacio es NULL, el objeto no admite la asignación y eliminación de elementos.

12.6 Estructuras de objetos secuencia

type PySequenceMethods
Esta estructura contiene punteros a las funciones que utiliza un objeto para implementar el protocolo de se-
cuencia.
lenfunc PySequenceMethods.sq_length
Esta función es utilizada por PySequence_Size() y PyObject_Size(), y tiene la misma firma. Tam-
bién se usa para manejar índices negativos a través de los espacios sq_item y sq_ass_item.
binaryfunc PySequenceMethods.sq_concat
Esta función es utilizada por PySequence_Concat() y tiene la misma firma. También es utilizado por el
operador +, después de intentar la suma numérica a través de la ranura nb_add.
ssizeargfunc PySequenceMethods.sq_repeat
Esta función es utilizada por PySequence_Repeat() y tiene la misma firma. También es utilizado por el
operador *, después de intentar la multiplicación numérica a través de la ranura nb_multiply.
ssizeargfunc PySequenceMethods.sq_item
Esta función es utilizada por PySequence_GetItem() y tiene la misma firma. También es utilizado por
PyObject_GetItem(), después de intentar la suscripción a través de la ranura mp_subscript. Este
espacio debe llenarse para que la función PySequence_Check() retorna 1, de lo contrario puede ser
NULL.
Los índices negativos se manejan de la siguiente manera: si se llena el espacio sq_length, se llama y la
longitud de la secuencia se usa para calcular un índice positivo que se pasa a sq_item. Si sq_length es
NULL, el índice se pasa como es a la función.
ssizeobjargproc PySequenceMethods.sq_ass_item
Esta función es utilizada por PySequence_SetItem() y tiene la misma firma. También lo usan
PyObject_SetItem() y PyObject_DelItem(), después de intentar la asignación y eliminación del
elemento a través de la ranura mp_ass_subscript. Este espacio puede dejarse en NULL si el objeto no
admite la asignación y eliminación de elementos.

272 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

objobjproc PySequenceMethods.sq_contains
Esta función puede ser utilizada por PySequence_Contains() y tiene la misma firma. Este espacio puede
dejarse en NULL, en este caso PySequence_Contains() simplemente atraviesa la secuencia hasta que
encuentra una coincidencia.
binaryfunc PySequenceMethods.sq_inplace_concat
Esta función es utilizada por PySequence_InPlaceConcat() y tiene la misma firma. Debe-
ría modificar su primer operando y retornarlo. Este espacio puede dejarse en NULL, en este caso
PySequence_InPlaceConcat() volverá a PySequence_Concat(). También es utilizado por
la asignación aumentada +=, después de intentar la suma numérica en el lugar a través de la ranura
nb_inplace_add.
ssizeargfunc PySequenceMethods.sq_inplace_repeat
Esta función es utilizada por PySequence_InPlaceRepeat() y tiene la misma firma. Debe-
ría modificar su primer operando y retornarlo. Este espacio puede dejarse en NULL, en este caso
PySequence_InPlaceRepeat() volverá a PySequence_Repeat(). También es utilizado por la
asignación aumentada *=, después de intentar la multiplicación numérica en el lugar a través de la ranura
nb_inplace_multiply.

12.7 Estructuras de Objetos Búfer

type PyBufferProcs
Esta estructura contiene punteros a las funciones requeridas por Buffer protocol. El protocolo define cómo un
objeto exportador puede exponer sus datos internos a objetos de consumo.
getbufferproc PyBufferProcs.bf_getbuffer
La firma de esta función es:

int (PyObject *exporter, Py_buffer *view, int flags);

Maneja una solicitud a exporter para completar view según lo especificado por flags. Excepto por el punto (3),
una implementación de esta función DEBE seguir estos pasos:
(1) Check if the request can be met. If not, raise PyExc_BufferError, set view->obj to NULL and
return -1.
(2) Rellene los campos solicitados.
(3) Incrementa un contador interno para el número de exportaciones (exports).
(4) Set view->obj to exporter and increment view->obj.
(5) Retorna 0.
Si exporter es parte de una cadena o árbol de proveedores de búfer, se pueden usar dos esquemas principales:
• Re-export: Each member of the tree acts as the exporting object and sets view->obj to a new reference
to itself.
• Redirect: The buffer request is redirected to the root object of the tree. Here, view->obj will be a new
reference to the root object.
Los campos individuales de view se describen en la sección Estructura de búfer, las reglas sobre cómo debe
reaccionar un exportador a solicitudes específicas se encuentran en la sección Tipos de solicitud de búfer.
Toda la memoria señalada en la estructura Py_buffer pertenece al exportador y debe permanecer válida
hasta que no queden consumidores. format, shape, strides, suboffsets y internal son de solo
lectura para el consumidor.
PyBuffer_FillInfo() proporciona una manera fácil de exponer un búfer de bytes simple mientras se
trata correctamente con todos los tipos de solicitud.
PyObject_GetBuffer() es la interfaz para el consumidor que envuelve esta función.

12.7. Estructuras de Objetos Búfer 273

The Python/C API, Versión 3.11.0

releasebufferproc PyBufferProcs.bf_releasebuffer
La firma de esta función es:

void (PyObject *exporter, Py_buffer *view);

Maneja una solicitud para liberar los recursos del búfer. Si no es necesario liberar recursos,
PyBufferProcs.bf_releasebuffer puede ser NULL. De lo contrario, una implementación están-
dar de esta función tomará estos pasos opcionales:
(1) Disminuir un contador interno para el número de exportaciones.
(2) Si el contador es 0, libera toda la memoria asociada con view.
El exportador DEBE utilizar el campo internal para realizar un seguimiento de los recursos específicos del
búfer. Se garantiza que este campo permanecerá constante, mientras que un consumidor PUEDE pasar una
copia del búfer original como argumento view.
This function MUST NOT decrement view->obj, since that is done automatically in
PyBuffer_Release() (this scheme is useful for breaking reference cycles).
PyBuffer_Release() es la interfaz para el consumidor que envuelve esta función.

12.8 Estructuras de objetos asíncronos

Nuevo en la versión 3.5.

type PyAsyncMethods
Esta estructura contiene punteros a las funciones requeridas para implementar objetos «esperable» (awaitable)
y «iterador asincrónico» (asynchronous iterator).
Aquí está la definición de la estructura:

typedef struct {
unaryfunc am_await;
unaryfunc am_aiter;
unaryfunc am_anext;
sendfunc am_send;
} PyAsyncMethods;

unaryfunc PyAsyncMethods.am_await
La firma de esta función es:

PyObject *am_await(PyObject *self);

The returned object must be an iterator, i.e. PyIter_Check() must return 1 for it.
Este espacio puede establecerse en NULL si un objeto no es awaitable.
unaryfunc PyAsyncMethods.am_aiter
La firma de esta función es:

PyObject *am_aiter(PyObject *self);

Must return an asynchronous iterator object. See __anext__() for details.

Este espacio puede establecerse en NULL si un objeto no implementa el protocolo de iteración asincrónica.
unaryfunc PyAsyncMethods.am_anext
La firma de esta función es:

PyObject *am_anext(PyObject *self);

274 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

Debe retornar un objeto «esperable» (awaitable). Ver __anext__() para más detalles. Esta ranura puede
establecerse en NULL.
sendfunc PyAsyncMethods.am_send
La firma de esta función es:
PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);

Consulte PyIter_Send() para obtener más detalles. Esta ranura se puede establecer en NULL.
Nuevo en la versión 3.10.

12.9 Tipo Ranura typedefs

typedef PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems)

Part of the Stable ABI. El propósito de esta función es separar la asignación de memoria de la inicialización de
memoria. Debería retornar un puntero a un bloque de memoria de longitud adecuada para la instancia, adecua-
damente alineado e inicializado a ceros, pero con ob_refcnt establecido en 1 y ob_type establecido en ar-
gumento de tipo. Si el tipo tp_itemsize no es cero, el campo del objeto ob_size debe inicializarse en ni-
tems y la longitud del bloque de memoria asignado debe ser tp_basicsize + nitems*tp_itemsize,
redondeado a un múltiplo de sizeof(void*); de lo contrario, nitems no se usa y la longitud del bloque
debe ser tp_basicsize.
Esta función no debe hacer ninguna otra instancia de inicialización, ni siquiera para asignar memoria adicional;
eso debe ser realizado por tp_new.
typedef void (*destructor)(PyObject*)
Part of the Stable ABI.
typedef void (*freefunc)(void*)
Consulte tp_free.
typedef PyObject *(*newfunc)(PyObject*, PyObject*, PyObject*)
Part of the Stable ABI. Consulte tp_new.
typedef int (*initproc)(PyObject*, PyObject*, PyObject*)
Part of the Stable ABI. Consulte tp_init.
typedef PyObject *(*reprfunc)(PyObject*)
Part of the Stable ABI. Consulte tp_repr.
typedef PyObject *(*getattrfunc)(PyObject *self, char *attr)
Part of the Stable ABI. Retorna el valor del atributo nombrado para el objeto.
typedef int (*setattrfunc)(PyObject *self, char *attr, PyObject *value)
Part of the Stable ABI. Establece el valor del atributo nombrado para el objeto. El argumento del valor se
establece en NULL para eliminar el atributo.
typedef PyObject *(*getattrofunc)(PyObject *self, PyObject *attr)
Part of the Stable ABI. Retorna el valor del atributo nombrado para el objeto.
Consulte tp_getattro.
typedef int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value)
Part of the Stable ABI. Establece el valor del atributo nombrado para el objeto. El argumento del valor se
establece en NULL para eliminar el atributo.
Consulte tp_setattro.
typedef PyObject *(*descrgetfunc)(PyObject*, PyObject*, PyObject*)
Part of the Stable ABI. See tp_descr_get.

12.9. Tipo Ranura typedefs 275

The Python/C API, Versión 3.11.0

typedef int (*descrsetfunc)(PyObject*, PyObject*, PyObject*)

Part of the Stable ABI. See tp_descr_set.
typedef Py_hash_t (*hashfunc)(PyObject*)
Part of the Stable ABI. Consulte tp_hash.
typedef PyObject *(*richcmpfunc)(PyObject*, PyObject*, int)
Part of the Stable ABI. Consulte tp_richcompare.
typedef PyObject *(*getiterfunc)(PyObject*)
Part of the Stable ABI. Consulte tp_iter.
typedef PyObject *(*iternextfunc)(PyObject*)
Part of the Stable ABI. Consulte tp_iternext.
typedef Py_ssize_t (*lenfunc)(PyObject*)
Part of the Stable ABI.
typedef int (*getbufferproc)(PyObject*, Py_buffer*, int)

typedef void (*releasebufferproc)(PyObject*, Py_buffer*)

typedef PyObject *(*unaryfunc)(PyObject*)

Part of the Stable ABI.
typedef PyObject *(*binaryfunc)(PyObject*, PyObject*)
Part of the Stable ABI.
typedef PySendResult (*sendfunc)(PyObject*, PyObject*, PyObject**)
Consulte am_send.
typedef PyObject *(*ternaryfunc)(PyObject*, PyObject*, PyObject*)
Part of the Stable ABI.
typedef PyObject *(*ssizeargfunc)(PyObject*, Py_ssize_t)
Part of the Stable ABI.
typedef int (*ssizeobjargproc)(PyObject*, Py_ssize_t)
Part of the Stable ABI.
typedef int (*objobjproc)(PyObject*, PyObject*)
Part of the Stable ABI.
typedef int (*objobjargproc)(PyObject*, PyObject*, PyObject*)
Part of the Stable ABI.

12.10 Ejemplos

Los siguientes son ejemplos simples de definiciones de tipo Python. Incluyen el uso común que puede encontrar.
Algunos demuestran casos difíciles de esquina (corner cases). Para obtener más ejemplos, información práctica y un
tutorial, consulte «definiendo nuevos tipos» (defining-new-types) y «tópicos de nuevos tipos (new-types-topics).
Un tipo estático básico:

typedef struct {
PyObject_HEAD
const char *data;
} MyObject;

static PyTypeObject MyObject_Type = {

(continué en la próxima página)

276 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

PyVarObject_HEAD_INIT(NULL, 0)
.tp_name = "mymod.MyObject",
.tp_basicsize = sizeof(MyObject),
.tp_doc = PyDoc_STR("My objects"),
.tp_new = myobj_new,
.tp_dealloc = (destructor)myobj_dealloc,
.tp_repr = (reprfunc)myobj_repr,
};

También puede encontrar código más antiguo (especialmente en la base de código CPython) con un inicializador más
detallado:

static PyTypeObject MyObject_Type = {

PyVarObject_HEAD_INIT(NULL, 0)
"mymod.MyObject", /* tp_name */
sizeof(MyObject), /* tp_basicsize */
0, /* tp_itemsize */
(destructor)myobj_dealloc, /* tp_dealloc */
0, /* tp_vectorcall_offset */
0, /* tp_getattr */
0, /* tp_setattr */
0, /* tp_as_async */
(reprfunc)myobj_repr, /* tp_repr */
0, /* tp_as_number */
0, /* tp_as_sequence */
0, /* tp_as_mapping */
0, /* tp_hash */
0, /* tp_call */
0, /* tp_str */
0, /* tp_getattro */
0, /* tp_setattro */
0, /* tp_as_buffer */
0, /* tp_flags */
PyDoc_STR("My objects"), /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
0, /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
0, /* tp_methods */
0, /* tp_members */
0, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
0, /* tp_init */
0, /* tp_alloc */
myobj_new, /* tp_new */
};

Un tipo que admite referencias débiles, instancias de diccionarios (dicts) y hashing:

typedef struct {
PyObject_HEAD
const char *data;
PyObject *inst_dict;
PyObject *weakreflist;
} MyObject;
(continué en la próxima página)

12.10. Ejemplos 277

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

static PyTypeObject MyObject_Type = {

PyVarObject_HEAD_INIT(NULL, 0)
.tp_name = "mymod.MyObject",
.tp_basicsize = sizeof(MyObject),
.tp_doc = PyDoc_STR("My objects"),
.tp_weaklistoffset = offsetof(MyObject, weakreflist),
.tp_dictoffset = offsetof(MyObject, inst_dict),
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
.tp_new = myobj_new,
.tp_traverse = (traverseproc)myobj_traverse,
.tp_clear = (inquiry)myobj_clear,
.tp_alloc = PyType_GenericNew,
.tp_dealloc = (destructor)myobj_dealloc,
.tp_repr = (reprfunc)myobj_repr,
.tp_hash = (hashfunc)myobj_hash,
.tp_richcompare = PyBaseObject_Type.tp_richcompare,
};

Una subclase str que no se puede subclasificar y no se puede llamar para crear instancias (por ejemplo, usa una función
de fábrica separada) usando el indicador Py_TPFLAGS_DISALLOW_INSTANTIATION:

typedef struct {
PyUnicodeObject raw;
char *extra;
} MyStr;

static PyTypeObject MyStr_Type = {

PyVarObject_HEAD_INIT(NULL, 0)
.tp_name = "mymod.MyStr",
.tp_basicsize = sizeof(MyStr),
.tp_base = NULL, // set to &PyUnicode_Type in module init
.tp_doc = PyDoc_STR("my custom str"),
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,
.tp_repr = (reprfunc)myobj_repr,
};

El tipo estático más simple con instancias de longitud fija:

typedef struct {
PyObject_HEAD
} MyObject;

static PyTypeObject MyObject_Type = {

PyVarObject_HEAD_INIT(NULL, 0)
.tp_name = "mymod.MyObject",
};

El tipo estático más simple con instancias de longitud variable:

typedef struct {
PyObject_VAR_HEAD
const char *data[1];
} MyObject;

static PyTypeObject MyObject_Type = {

PyVarObject_HEAD_INIT(NULL, 0)
.tp_name = "mymod.MyObject",
.tp_basicsize = sizeof(MyObject) - sizeof(char *),
.tp_itemsize = sizeof(char *),
};

278 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

12.11 Apoyo a la recolección de basura cíclica

El soporte de Python para detectar y recolectar basura que involucra referencias circulares requiere el soporte de
tipos de objetos que son «contenedores» para otros objetos que también pueden ser contenedores. Los tipos que no
almacenan referencias a otros objetos, o que solo almacenan referencias a tipos atómicos (como números o cadenas),
no necesitan proporcionar ningún soporte explícito para la recolección de basura.
Para crear un tipo de contenedor, el campo tp_flags del objeto tipo debe incluir Py_TPFLAGS_HAVE_GC y
proporcionar una implementación del manejador tp_traverse . Si las instancias del tipo son mutables, también
se debe proporcionar una implementación a tp_clear.
Py_TPFLAGS_HAVE_GC
Los objetos con un tipo con este indicador establecido deben cumplir con las reglas documentadas aquí. Por
conveniencia, estos objetos se denominarán objetos contenedor.
Los constructores para tipos de contenedores deben cumplir con dos reglas:
1. La memoria para el objeto debe asignarse usando PyObject_GC_New() o PyObject_GC_NewVar().
2. Una vez que se inicializan todos los campos que pueden contener referencias a otros contenedores, debe llamar
a PyObject_GC_Track().
Del mismo modo, el desasignador (deallocator) para el objeto debe cumplir con un par similar de reglas:
1. Antes de invalidar los campos que se refieren a otros contenedores, debe llamarse
PyObject_GC_UnTrack().
2. La memoria del objeto debe ser desasignada (deallocated) usando PyObject_GC_Del().

Advertencia: Si un tipo añade el Py_TPFLAGS_HAVE_GC, entonces must implementar al menos un

manejado tp_traverse o usar explícitamente uno de su subclase o subclases.
Al llamar a PyType_Ready() o alguna de las APIs que indirectamente lo llaman como
PyType_FromSpecWithBases() o PyType_FromSpec() el intérprete automáticamente lle-
nara los campos tp_flags, tp_traverse y tp_clear si el tipo si el tipo hereda de una cla-
se que implementa el protocolo del recolector de basura y la clase secundaria no incluye el flag
Py_TPFLAGS_HAVE_GC.

TYPE *PyObject_GC_New(TYPE, PyTypeObject *type)

Análogo a PyObject_New() pero para objetos de contenedor con el flag Py_TPFLAGS_HAVE_GC es-
tablecido.
TYPE *PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Análogo a PyObject_NewVar() pero para objetos de contenedor con el flag Py_TPFLAGS_HAVE_GC
establecido.
TYPE *PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
Cambia el tamaño de un objeto asignado por PyObject_NewVar(). Retorna el objeto redimensionado o
NULL en caso de falla. op aún no debe ser rastreado por el recolector de basura.
void PyObject_GC_Track(PyObject *op)
Part of the Stable ABI. Agrega el objeto op al conjunto de objetos contenedor seguidos por el recolector de
basura. El recolector puede ejecutarse en momentos inesperados, por lo que los objetos deben ser válidos
durante el seguimiento. Esto debería llamarse una vez que todos los campos seguidos por tp_traverse se
vuelven válidos, generalmente cerca del final del constructor.
int PyObject_IS_GC(PyObject *obj)
Retorna un valor distinto de cero si el objeto implementa el protocolo del recolector de basura; de lo contrario,
retorna 0.
El recolector de basura no puede rastrear el objeto si esta función retorna 0.

12.11. Apoyo a la recolección de basura cíclica 279

The Python/C API, Versión 3.11.0

int PyObject_GC_IsTracked(PyObject *op)

Part of the Stable ABI since version 3.9. Retorna 1 si el tipo de objeto de op implementa el protocolo GC y el
recolector de basura está rastreando op y 0 en caso contrario.
Esto es análogo a la función de Python gc.is_tracked().
Nuevo en la versión 3.9.
int PyObject_GC_IsFinalized(PyObject *op)
Part of the Stable ABI since version 3.9. Retorna 1 si el tipo de objeto de op implementa el protocolo GC y op
ya ha sido finalizado por el recolector de basura y 0 en caso contrario.
Esto es análogo a la función de Python gc.is_finalized().
Nuevo en la versión 3.9.
void PyObject_GC_Del(void *op)
Part of the Stable ABI. Libera memoria asignada a un objeto usando PyObject_GC_New() o
PyObject_GC_NewVar().
void PyObject_GC_UnTrack(void *op)
Part of the Stable ABI. Elimina el objeto op del conjunto de objetos contenedor rastreados por el recolector de
basura. Tenga en cuenta que PyObject_GC_Track() puede ser llamado nuevamente en este objeto para
agregarlo nuevamente al conjunto de objetos rastreados. El desasignador (el manejador tp_dealloc) debería
llamarlo para el objeto antes de que cualquiera de los campos utilizados por el manejador tp_traverse no
sea válido.
Distinto en la versión 3.8: Los macros _PyObject_GC_TRACK() y _PyObject_GC_UNTRACK() se han
eliminado de la API pública de C.
El manejador tp_traverse acepta un parámetro de función de este tipo:
typedef int (*visitproc)(PyObject *object, void *arg)
Part of the Stable ABI. Tipo de la función visitante que se pasa al manejador tp_traverse. La función debe
llamarse con un objeto para atravesar como object y el tercer parámetro para el manejador tp_traverse
como arg. El núcleo de Python utiliza varias funciones visitantes para implementar la detección de basura
cíclica; No se espera que los usuarios necesiten escribir sus propias funciones visitante.
El manejador tp_traverse debe tener el siguiente tipo:
typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
Part of the Stable ABI. Función transversal para un objeto contenedor. Las implementaciones deben llamar a la
función visit para cada objeto directamente contenido por self, siendo los parámetros a visit el objeto contenido
y el valor arg pasado al controlador. La función visit no debe llamarse con un argumento de objeto NULL. Si
visit retorna un valor distinto de cero, ese valor debe retornarse inmediatamente.
Para simplificar la escritura de los manejadores tp_traverse, se proporciona un macro a Py_VISIT(). Para
usar este macro, la implementación tp_traverse debe nombrar sus argumentos exactamente visit y arg:
void Py_VISIT(PyObject *o)
Si o no es NULL, llama a la devolución de llamada (callback) visit, con argumentos o y arg. Si visit retorna
un valor distinto de cero, lo retorna. Usando este macro, los manejadores tp_traverse tienen el siguiente
aspecto:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
Py_VISIT(self->foo);
Py_VISIT(self->bar);
return 0;
}

El manejador tp_clear debe ser del tipo query, o NULL si el objeto es inmutable.

280 Capítulo 12. Soporte de implementación de objetos

 The Python/C API, Versión 3.11.0

typedef int (*inquiry)(PyObject *self)

Part of the Stable ABI. Descarta referencias que pueden haber creado ciclos de referencia. Los objetos inmu-
tables no tienen que definir este método ya que nunca pueden crear directamente ciclos de referencia. Tenga
en cuenta que el objeto aún debe ser válido después de llamar a este método (no solo llame a Py_DECREF()
en una referencia). El recolector de basura llamará a este método si detecta que este objeto está involucrado
en un ciclo de referencia.

12.11.1 Controlar el estado del recolector de basura

La C-API proporciona las siguientes funciones para controlar las ejecuciones de recolección de basura.
Py_ssize_t PyGC_Collect(void)
Part of the Stable ABI. Realiza una recolección de basura completa, si el recolector de basura está habilitado.
(Tenga en cuenta que gc.collect() lo ejecuta incondicionalmente).
Retorna el número de objetos recolectados e inalcanzables que no se pueden recolectar. Si el recolector de
basura está deshabilitado o ya está recolectando, retorna 0 inmediatamente. Los errores durante la recolección
de basura se pasan a sys.unraisablehook. Esta función no genera excepciones.
int PyGC_Enable(void)
Part of the Stable ABI since version 3.10. Habilita el recolector de basura: similar a gc.enable(). Retorna
el estado anterior, 0 para deshabilitado y 1 para habilitado.
Nuevo en la versión 3.10.
int PyGC_Disable(void)
Part of the Stable ABI since version 3.10. Deshabilita el recolector de basura: similar a gc.disable().
Retorna el estado anterior, 0 para deshabilitado y 1 para habilitado.
Nuevo en la versión 3.10.
int PyGC_IsEnabled(void)
Part of the Stable ABI since version 3.10. Consulta el estado del recolector de basura: similar a gc.
isenabled(). Retorna el estado actual, 0 para deshabilitado y 1 para habilitado.
Nuevo en la versión 3.10.

12.11. Apoyo a la recolección de basura cíclica 281

The Python/C API, Versión 3.11.0

282 Capítulo 12. Soporte de implementación de objetos

 CAPÍTULO 13

Versiones de API y ABI

CPython expone su número de versión en las siguientes macros. Tenga en cuenta que estos corresponden a la versión
con la que se construye el código, no necesariamente la versión utilizada en tiempo de ejecución.
Consulte Estabilidad de la API en C para obtener una discusión sobre la estabilidad de API y ABI en todas las
versiones.
PY_MAJOR_VERSION
El 3 en 3.4.1a2.
PY_MINOR_VERSION
El 4 en 3.4.1a2.
PY_MICRO_VERSION
El 1 en 3.4.1a2.
PY_RELEASE_LEVEL
La a en 3.4.1a2. Puede ser 0xA para la versión alfa, 0xB para la versión beta, 0xC para la versión candidata
o 0xF para la versión final.
PY_RELEASE_SERIAL
El 2 en 3.4.1a2, cero para lanzamientos finales.
PY_VERSION_HEX
El número de versión de Python codificado en un solo entero.
La información de la versión subyacente se puede encontrar tratándola como un número de 32 bits de la si-
guiente manera:

Bytes Bits (orden big-endian) Significado Valor para 3.4.1a2

1 1-8 PY_MAJOR_VERSION 0x03
2 9-16 PY_MINOR_VERSION 0x04
3 17-24 PY_MICRO_VERSION 0x01
4 25-28 PY_RELEASE_LEVEL 0xA
29-32 PY_RELEASE_SERIAL 0x2

Así, 3.4.1a2 es la hexadecimal 0x030401a2 y 3.10.0 es la hexadecimal 0x030a00f0.

Esta versión también está disponible a través del símbolo Py_Version.

283
The Python/C API, Versión 3.11.0

const unsigned long Py_Version

Part of the Stable ABI since version 3.11. El número de versión de Python en tiempo de ejecución codificado
en un único entero constante, con el mismo formato que la macro PY_VERSION_HEX. Contiene la versión
de Python utilizada en tiempo de ejecución.
Nuevo en la versión 3.11.
Todas las macros dadas se definen en Include/patchlevel.h.

284 Capítulo 13. Versiones de API y ABI

 APÉNDICE A

Glosario

>>> El prompt en el shell interactivo de Python por omisión. Frecuentemente vistos en ejemplos de código que
pueden ser ejecutados interactivamente en el intérprete.
... Puede referirse a:
• El prompt en el shell interactivo de Python por omisión cuando se ingresa código para un bloque indentado
de código, y cuando se encuentra entre dos delimitadores que emparejan (paréntesis, corchetes, llaves o
comillas triples), o después de especificar un decorador.
• La constante incorporada Ellipsis.
2to3 Una herramienta que intenta convertir código de Python 2.x a Python 3.x arreglando la mayoría de las incom-
patibilidades que pueden ser detectadas analizando el código y recorriendo el árbol de análisis sintáctico.
2to3 está disponible en la biblioteca estándar como lib2to3; un punto de entrada independiente es provisto
como Tools/scripts/2to3. Vea 2to3-reference.
clase base abstracta Las clases base abstractas (ABC, por sus siglas en inglés Abstract Base Class) complementan
al duck-typing brindando un forma de definir interfaces con técnicas como hasattr() que serían confusas
o sutilmente erróneas (por ejemplo con magic methods). Las ABC introduce subclases virtuales, las cuales son
clases que no heredan desde una clase pero aún así son reconocidas por isinstance() y issubclass();
vea la documentación del módulo abc. Python viene con muchas ABC incorporadas para las estructuras de
datos( en el módulo collections.abc), números (en el módulo numbers ) , flujos de datos (en el módulo
io ) , buscadores y cargadores de importaciones (en el módulo importlib.abc ) . Puede crear sus propios
ABCs con el módulo abc.
anotación Una etiqueta asociada a una variable, atributo de clase, parámetro de función o valor de retorno, usado
por convención como un type hint.
Las anotaciones de variables no pueden ser accedidas en tiempo de ejecución, pero las anotaciones de variables
globales, atributos de clase, y funciones son almacenadas en el atributo especial __annotations__ de
módulos, clases y funciones, respectivamente.
Consulte variable annotation, function annotation, PEP 484 y PEP 526, que describen esta funcionalidad.
Consulte también annotations-howto para conocer las mejores prácticas sobre cómo trabajar con anotaciones.
argumento Un valor pasado a una function (o method) cuando se llama a la función. Hay dos clases de argumentos:
• argumento nombrado: es un argumento precedido por un identificador (por ejemplo, nombre=) en una
llamada a una función o pasado como valor en un diccionario precedido por **. Por ejemplo 3 y 5 son
argumentos nombrados en las llamadas a complex():

285
The Python/C API, Versión 3.11.0

complex(real=3, imag=5)
complex(**{'real': 3, 'imag': 5})

• argumento posicional son aquellos que no son nombrados. Los argumentos posicionales deben aparecer
al principio de una lista de argumentos o ser pasados como elementos de un iterable precedido por *. Por
ejemplo, 3 y 5 son argumentos posicionales en las siguientes llamadas:

complex(3, 5)
complex(*(3, 5))

Los argumentos son asignados a las variables locales en el cuerpo de la función. Vea en la sección calls las
reglas que rigen estas asignaciones. Sintácticamente, cualquier expresión puede ser usada para representar un
argumento; el valor evaluado es asignado a la variable local.
Vea también el parameter en el glosario, la pregunta frecuente la diferencia entre argumentos y parámetros, y
PEP 362.
administrador asincrónico de contexto Un objeto que controla el entorno visible en un sentencia async with
al definir los métodos __aenter__() __aexit__(). Introducido por PEP 492.
generador asincrónico Una función que retorna un asynchronous generator iterator. Es similar a una función co-
rrutina definida con async def excepto que contiene expresiones yield para producir series de variables
usadas en un ciclo async for.
Usualmente se refiere a una función generadora asincrónica, pero puede referirse a un iterador generador
asincrónico en ciertos contextos. En aquellos casos en los que el significado no está claro, usar los términos
completos evita la ambigüedad.
Una función generadora asincrónica puede contener expresiones await así como sentencias async for, y
async with.
iterador generador asincrónico Un objeto creado por una función asynchronous generator.
Este es un asynchronous iterator el cual cuando es llamado usa el método __anext__() retornando un
objeto a la espera (awaitable) el cual ejecutará el cuerpo de la función generadora asincrónica hasta la siguiente
expresión yield.
Cada yield suspende temporalmente el procesamiento, recordando el estado local de ejecución (incluyendo
a las variables locales y las sentencias try pendientes). Cuando el iterador del generador asincrónico vuelve
efectivamente con otro objeto a la espera (awaitable) retornado por el método __anext__(), retoma donde
lo dejó. Vea PEP 492 y PEP 525.
iterable asincrónico Un objeto, que puede ser usado en una sentencia async for. Debe retornar un asynchronous
iterator de su método __aiter__(). Introducido por PEP 492.
iterador asincrónico Un objeto que implementa los métodos __aiter__() y __anext__(). __anext__
debe retornar un objeto awaitable. async for resuelve los esperables retornados por un método de iterador
asincrónico __anext__() hasta que lanza una excepción StopAsyncIteration. Introducido por PEP
492.
atributo A value associated with an object which is usually referenced by name using dotted expressions. For exam-
ple, if an object o has an attribute a it would be referenced as o.a.
It is possible to give an object an attribute whose name is not an identifier as defined by identifiers, for example
using setattr(), if the object allows it. Such an attribute will not be accessible using a dotted expression,
and would instead need to be retrieved with getattr().
a la espera Es un objeto a la espera (awaitable) que puede ser usado en una expresión await. Puede ser una
coroutine o un objeto con un método __await__(). Vea también PEP 492.
BDFL Sigla de Benevolent Dictator For Life, benevolente dictador vitalicio, es decir Guido van Rossum, el creador
de Python.
archivo binario Un file object capaz de leer y escribir objetos tipo binarios. Ejemplos de archivos binarios son los
abiertos en modo binario ('rb', 'wb' o 'rb+'), sys.stdin.buffer, sys.stdout.buffer, e
instancias de io.BytesIO y de gzip.GzipFile.

286 Apéndice A. Glosario

 The Python/C API, Versión 3.11.0

Vea también text file para un objeto archivo capaz de leer y escribir objetos str.
referencia prestada En la API C de Python, una referencia prestada es una referencia a un objeto. No modifica el
recuento de referencias de objetos. Se convierte en un puntero colgante si se destruye el objeto. Por ejemplo,
una recolección de basura puede eliminar el último strong reference del objeto y así destruirlo.
Se recomienda llamar a Py_INCREF() en la referencia prestada para convertirla en una referencia fuerte in
situ, excepto cuando el objeto no se puede destruir antes del último uso de la referencia prestada. La función
Py_NewRef() se puede utilizar para crear una nueva referencia fuerte.
objetos tipo binarios Un objeto que soporta Protocolo Búfer y puede exportar un búfer C-contiguous. Esto in-
cluye todas los objetos bytes, bytearray, y array.array, así como muchos objetos comunes
memoryview. Los objetos tipo binarios pueden ser usados para varias operaciones que usan datos binarios;
éstas incluyen compresión, salvar a archivos binarios, y enviarlos a través de un socket.
Algunas operaciones necesitan que los datos binarios sean mutables. La documentación frecuentemente se re-
fiere a éstos como «objetos tipo binario de lectura y escritura». Ejemplos de objetos de búfer mutables incluyen
a bytearray y memoryview de la bytearray. Otras operaciones que requieren datos binarios alma-
cenados en objetos inmutables («objetos tipo binario de sólo lectura»); ejemplos de éstos incluyen bytes y
memoryview del objeto bytes.
bytecode El código fuente Python es compilado en bytecode, la representación interna de un programa python en el
intérprete CPython. El bytecode también es guardado en caché en los archivos .pyc de tal forma que ejecutar
el mismo archivo es más fácil la segunda vez (la recompilación desde el código fuente a bytecode puede ser
evitada). Este «lenguaje intermedio» deberá corren en una virtual machine que ejecute el código de máquina
correspondiente a cada bytecode. Note que los bytecodes no tienen como requisito trabajar en las diversas
máquina virtuales de Python, ni de ser estable entre versiones Python.
Una lista de las instrucciones en bytecode está disponible en la documentación de el módulo dis.
callable A callable is an object that can be called, possibly with a set of arguments (see argument), with the following
syntax:

callable(argument1, argument2, ...)

A function, and by extension a method, is a callable. An instance of a class that implements the __call__()
method is also a callable.
retrollamada Una función de subrutina que se pasa como un argumento para ejecutarse en algún momento en el
futuro.
clase Una plantilla para crear objetos definidos por el usuario. Las definiciones de clase normalmente contienen
definiciones de métodos que operan una instancia de la clase.
variable de clase Una variable definida en una clase y prevista para ser modificada sólo a nivel de clase (es decir, no
en una instancia de la clase).
número complejo Una extensión del sistema familiar de número reales en el cual los números son expresados como
la suma de una parte real y una parte imaginaria. Los números imaginarios son múltiplos de la unidad imaginaria
(la raíz cuadrada de -1), usualmente escrita como i en matemáticas o j en ingeniería. Python tiene soporte
incorporado para números complejos, los cuales son escritos con la notación mencionada al final.; la parte
imaginaria es escrita con un sufijo j, por ejemplo, 3+1j. Para tener acceso a los equivalentes complejos del
módulo math module, use cmath. El uso de números complejos es matemática bastante avanzada. Si no le
parecen necesarios, puede ignorarlos sin inconvenientes.
administrador de contextos Un objeto que controla el entorno en la sentencia with definiendo los métodos
__enter__() y __exit__(). Vea PEP 343.
variable de contexto Una variable que puede tener diferentes valores dependiendo del contexto. Esto es similar a
un almacenamiento de hilo local Thread-Local Storage en el cual cada hilo de ejecución puede tener valores
diferentes para una variable. Sin embargo, con las variables de contexto, podría haber varios contextos en un
hilo de ejecución y el uso principal de las variables de contexto es mantener registro de las variables en tareas
concurrentes asíncronas. Vea contextvars.

287
The Python/C API, Versión 3.11.0

contiguo Un búfer es considerado contiguo con precisión si es C-contiguo o Fortran contiguo. Los búferes cero
dimensionales con C y Fortran contiguos. En los arreglos unidimensionales, los ítems deben ser dispuestos en
memoria uno siguiente al otro, ordenados por índices que comienzan en cero. En arreglos unidimensionales
C-contiguos, el último índice varía más velozmente en el orden de las direcciones de memoria. Sin embargo,
en arreglos Fortran contiguos, el primer índice vería más rápidamente.
corrutina Las corrutinas son una forma más generalizadas de las subrutinas. A las subrutinas se ingresa por un
punto y se sale por otro punto. Las corrutinas pueden se iniciadas, finalizadas y reanudadas en muchos puntos
diferentes. Pueden ser implementadas con la sentencia async def. Vea además PEP 492.
función corrutina Un función que retorna un objeto coroutine . Una función corrutina puede ser definida con la
sentencia async def, y puede contener las palabras claves await, async for, y async with. Las
mismas son introducidas en PEP 492.
CPython La implementación canónica del lenguaje de programación Python, como se distribuye en python.org.
El término «CPython» es usado cuando es necesario distinguir esta implementación de otras como Jython o
IronPython.
decorador Una función que retorna otra función, usualmente aplicada como una función de transformación
empleando la sintaxis @envoltorio. Ejemplos comunes de decoradores son classmethod() y
staticmethod().
La sintaxis del decorador es meramente azúcar sintáctico, las definiciones de las siguientes dos funciones son
semánticamente equivalentes:

def f(arg):
...
f = staticmethod(f)

@staticmethod
def f(arg):
...

El mismo concepto existe para clases, pero son menos usadas. Vea la documentación de function definitions y
class definitions para mayor detalle sobre decoradores.
descriptor Cualquier objeto que define los métodos __get__(), __set__(), o __delete__(). Cuando
un atributo de clase es un descriptor, su conducta enlazada especial es disparada durante la búsqueda del
atributo. Normalmente, usando a.b para consultar, establecer o borrar un atributo busca el objeto llamado b en
el diccionario de clase de a, pero si b es un descriptor, el respectivo método descriptor es llamado. Entender
descriptores es clave para lograr una comprensión profunda de Python porque son la base de muchas de las
capacidades incluyendo funciones, métodos, propiedades, métodos de clase, métodos estáticos, y referencia a
súper clases.
Para obtener más información sobre los métodos de los descriptores, consulte descriptors o Guía práctica de
uso de los descriptores.
diccionario Un arreglo asociativo, con claves arbitrarias que son asociadas a valores. Las claves pueden ser cualquier
objeto con los métodos __hash__() y __eq__() . Son llamadas hash en Perl.
comprensión de diccionarios Una forma compacta de procesar todos o parte de los elementos en un iterable y re-
tornar un diccionario con los resultados. results = {n: n ** 2 for n in range(10)} genera
un diccionario que contiene la clave n asignada al valor n ** 2. Ver comprehensions.
vista de diccionario Los objetos retornados por los métodos dict.keys(), dict.values(), y dict.
items() son llamados vistas de diccionarios. Proveen una vista dinámica de las entradas de un dicciona-
rio, lo que significa que cuando el diccionario cambia, la vista refleja éstos cambios. Para forzar a la vista de
diccionario a convertirse en una lista completa, use list(dictview). Vea dict-views.
docstring Una cadena de caracteres literal que aparece como la primera expresión en una clase, función o módulo.
Aunque es ignorada cuando se ejecuta, es reconocida por el compilador y puesta en el atributo __doc__ de
la clase, función o módulo comprendida. Como está disponible mediante introspección, es el lugar canónico
para ubicar la documentación del objeto.

288 Apéndice A. Glosario

 The Python/C API, Versión 3.11.0

tipado de pato Un estilo de programación que no revisa el tipo del objeto para determinar si tiene la interfaz correcta;
en vez de ello, el método o atributo es simplemente llamado o usado («Si se ve como un pato y grazna como un
pato, debe ser un pato»). Enfatizando las interfaces en vez de hacerlo con los tipos específicos, un código bien
diseñado pues tener mayor flexibilidad permitiendo la sustitución polimórfica. El tipado de pato duck-typing
evita usar pruebas llamando a type() o isinstance(). (Nota: si embargo, el tipado de pato puede ser
complementado con abstract base classes. En su lugar, generalmente pregunta con hasattr() o EAFP.
EAFP Del inglés Easier to ask for forgiveness than permission, es más fácil pedir perdón que pedir permiso. Este
estilo de codificación común en Python asume la existencia de claves o atributos válidos y atrapa las excepciones
si esta suposición resulta falsa. Este estilo rápido y limpio está caracterizado por muchas sentencias try y
except. Esta técnica contrasta con estilo LBYL usual en otros lenguajes como C.
expresión Una construcción sintáctica que puede ser evaluada, hasta dar un valor. En otras palabras, una expresión
es una acumulación de elementos de expresión tales como literales, nombres, accesos a atributos, operadores
o llamadas a funciones, todos ellos retornando valor. A diferencia de otros lenguajes, no toda la sintaxis del
lenguaje son expresiones. También hay statements que no pueden ser usadas como expresiones, como la while.
Las asignaciones también son sentencias, no expresiones.
módulo de extensión Un módulo escrito en C o C++, usando la API para C de Python para interactuar con el núcleo
y el código del usuario.
f-string Son llamadas f-strings las cadenas literales que usan el prefijo 'f' o 'F', que es una abreviatura para
formatted string literals. Vea también PEP 498.
objeto archivo Un objeto que expone una API orientada a archivos (con métodos como read() o write()) al
objeto subyacente. Dependiendo de la forma en la que fue creado, un objeto archivo, puede mediar el acceso
a un archivo real en el disco u otro tipo de dispositivo de almacenamiento o de comunicación (por ejemplo,
entrada/salida estándar, búfer de memoria, sockets, pipes, etc.). Los objetos archivo son también denominados
objetos tipo archivo o flujos.
Existen tres categorías de objetos archivo: crudos raw archivos binarios, con búfer archivos binarios y archivos
de texto. Sus interfaces son definidas en el módulo io. La forma canónica de crear objetos archivo es usando
la función open().
objetos tipo archivo Un sinónimo de file object.
codificación del sistema de archivos y manejador de errores Controlador de errores y codificación utilizado por
Python para decodificar bytes del sistema operativo y codificar Unicode en el sistema operativo.
La codificación del sistema de archivos debe garantizar la decodificación exitosa de todos los bytes por debajo
de 128. Si la codificación del sistema de archivos no proporciona esta garantía, las funciones de API pueden
lanzar UnicodeError.
Las funciones sys.getfilesystemencoding() y sys.getfilesystemencodeerrors() se
pueden utilizar para obtener la codificación del sistema de archivos y el controlador de errores.
La codificación del sistema de archivos y el manejador de errores se configuran al inicio de Pyt-
hon mediante la función PyConfig_Read(): consulte los miembros filesystem_encoding y
filesystem_errors de PyConfig.
See also the locale encoding.
buscador Un objeto que trata de encontrar el loader para el módulo que está siendo importado.
Desde la versión 3.3 de Python, existen dos tipos de buscadores: meta buscadores de ruta para usar con sys.
meta_path, y buscadores de entradas de rutas para usar con sys.path_hooks.
Vea PEP 302, PEP 420 y PEP 451 para mayores detalles.
división entera Una división matemática que se redondea hacia el entero menor más cercano. El operador de la
división entera es //. Por ejemplo, la expresión 11 // 4 evalúa 2 a diferencia del 2.75 retornado por la
verdadera división de números flotantes. Note que (-11) // 4 es -3 porque es -2.75 redondeado para
abajo. Ver PEP 238.
función Una serie de sentencias que retornan un valor al que las llama. También se le puede pasar cero o más
argumentos los cuales pueden ser usados en la ejecución de la misma. Vea también parameter, method, y la
sección function.

289
The Python/C API, Versión 3.11.0

anotación de función Una annotation del parámetro de una función o un valor de retorno.
Las anotaciones de funciones son usadas frecuentemente para indicadores de tipo, por ejemplo, se espera que
una función tome dos argumentos de clase int y también se espera que retorne dos valores int:

def sum_two_numbers(a: int, b: int) -> int:

return a + b

La sintaxis de las anotaciones de funciones son explicadas en la sección function.

Consulte variable annotation y PEP 484, que describen esta funcionalidad. Consulte también annotations-
howto para conocer las mejores prácticas sobre cómo trabajar con anotaciones.
__future__ Un future statement, from __future__ import <feature>, indica al compilador que com-
pile el módulo actual utilizando una sintaxis o semántica que se convertirá en estándar en una versión futura
de Python. El módulo __future__ documenta los posibles valores de feature. Al importar este módulo y
evaluar sus variables, puede ver cuándo se agregó por primera vez una nueva característica al lenguaje y cuándo
se convertirá (o se convirtió) en la predeterminada:

>>> import __future__

>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)

recolección de basura El proceso de liberar la memoria de lo que ya no está en uso. Python realiza recolección de
basura (garbage collection) llevando la cuenta de las referencias, y el recogedor de basura cíclico es capaz de
detectar y romper las referencias cíclicas. El recogedor de basura puede ser controlado mediante el módulo gc
.
generador Una función que retorna un generator iterator. Luce como una función normal excepto que contiene la
expresión yield para producir series de valores utilizables en un bucle for o que pueden ser obtenidas una
por una con la función next().
Usualmente se refiere a una función generadora, pero puede referirse a un iterador generador en ciertos contex-
tos. En aquellos casos en los que el significado no está claro, usar los términos completos evita la ambigüedad.
iterador generador Un objeto creado por una función generator.
Cada yield suspende temporalmente el procesamiento, recordando el estado de ejecución local (incluyendo
las variables locales y las sentencias try pendientes). Cuando el «iterador generado» vuelve, retoma donde ha
dejado, a diferencia de lo que ocurre con las funciones que comienzan nuevamente con cada invocación.
expresión generadora Una expresión que retorna un iterador. Luce como una expresión normal seguida por la cláu-
sula for definiendo así una variable de bucle, un rango y una cláusula opcional if. La expresión combinada
genera valores para la función contenedora:

>>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81

285

función genérica Una función compuesta de muchas funciones que implementan la misma operación para diferentes
tipos. Qué implementación deberá ser usada durante la llamada a la misma es determinado por el algoritmo de
despacho.
Vea también la entrada de glosario single dispatch, el decorador functools.singledispatch(), y
PEP 443.
tipos genéricos A type that can be parameterized; typically a container class such as list or dict. Used for type
hints and annotations.
For more details, see generic alias types, PEP 483, PEP 484, PEP 585, and the typing module.
GIL Vea global interpreter lock.
bloqueo global del intérprete Mecanismo empleado por el intérprete CPython para asegurar que sólo un hilo eje-
cute el bytecode Python por vez. Esto simplifica la implementación de CPython haciendo que el modelo de

290 Apéndice A. Glosario

 The Python/C API, Versión 3.11.0

objetos (incluyendo algunos críticos como dict) están implícitamente a salvo de acceso concurrente. Blo-
queando el intérprete completo se simplifica hacerlo multi-hilos, a costa de mucho del paralelismo ofrecido
por las máquinas con múltiples procesadores.
However, some extension modules, either standard or third-party, are designed so as to release the GIL when
doing computationally intensive tasks such as compression or hashing. Also, the GIL is always released when
doing I/O.
Esfuerzos previos hechos para crear un intérprete «sin hilos» (uno que bloquee los datos compartidos con una
granularidad mucho más fina) no han sido exitosos debido a que el rendimiento sufrió para el caso más común
de un solo procesador. Se cree que superar este problema de rendimiento haría la implementación mucho más
compleja y por tanto, más costosa de mantener.
hash-based pyc Un archivo cache de bytecode que usa el hash en vez de usar el tiempo de la última modificación
del archivo fuente correspondiente para determinar su validez. Vea pyc-invalidation.
hashable Un objeto es hashable si tiene un valor de hash que nunca cambiará durante su tiempo de vida (necesita
un método __hash__() ), y puede ser comparado con otro objeto (necesita el método __eq__() ). Los
objetos hashables que se comparan iguales deben tener el mismo número hash.
Ser hashable hace a un objeto utilizable como clave de un diccionario y miembro de un set, porque éstas
estructuras de datos usan los valores de hash internamente.
La mayoría de los objetos inmutables incorporados en Python son hashables; los contenedores mutables (como
las listas o los diccionarios) no lo son; los contenedores inmutables (como tuplas y conjuntos frozensets) son
hashables si sus elementos son hashables . Los objetos que son instancias de clases definidas por el usuario son
hashables por defecto. Todos se comparan como desiguales (excepto consigo mismos), y su valor de hash está
derivado de su función id().
IDLE An Integrated Development and Learning Environment for Python. idle is a basic editor and interpreter en-
vironment which ships with the standard distribution of Python.
inmutable Un objeto con un valor fijo. Los objetos inmutables son números, cadenas y tuplas. Éstos objetos no
pueden ser alterados. Un nuevo objeto debe ser creado si un valor diferente ha de ser guardado. Juegan un rol
importante en lugares donde es necesario un valor de hash constante, por ejemplo como claves de un diccionario.
ruta de importación Una lista de las ubicaciones (o entradas de ruta) que son revisadas por path based finder al
importar módulos. Durante la importación, ésta lista de localizaciones usualmente viene de sys.path, pero
para los subpaquetes también puede incluir al atributo __path__ del paquete padre.
importar El proceso mediante el cual el código Python dentro de un módulo se hace alcanzable desde otro código
Python en otro módulo.
importador Un objeto que buscan y lee un módulo; un objeto que es tanto finder como loader.
interactivo Python tiene un intérprete interactivo, lo que significa que puede ingresar sentencias y expresiones en
el prompt del intérprete, ejecutarlos de inmediato y ver sus resultados. Sólo ejecute python sin argumentos
(podría seleccionarlo desde el menú principal de su computadora). Es una forma muy potente de probar nuevas
ideas o inspeccionar módulos y paquetes (recuerde help(x)).
interpretado Python es un lenguaje interpretado, a diferencia de uno compilado, a pesar de que la distinción puede
ser difusa debido al compilador a bytecode. Esto significa que los archivos fuente pueden ser corridos direc-
tamente, sin crear explícitamente un ejecutable que es corrido luego. Los lenguajes interpretados típicamente
tienen ciclos de desarrollo y depuración más cortos que los compilados, sin embargo sus programas suelen
correr más lentamente. Vea también interactive.
apagado del intérprete Cuando se le solicita apagarse, el intérprete Python ingresa a un fase especial en la cual
gradualmente libera todos los recursos reservados, como módulos y varias estructuras internas críticas. Tam-
bién hace varias llamadas al recolector de basura. Esto puede disparar la ejecución de código de destructores
definidos por el usuario o weakref callbacks. El código ejecutado durante la fase de apagado puede encontrar
varias excepciones debido a que los recursos que necesita pueden no funcionar más (ejemplos comunes son los
módulos de bibliotecas o los artefactos de advertencias warnings machinery)
La principal razón para el apagado del intérpreter es que el módulo __main__ o el script que estaba corriendo
termine su ejecución.

291
The Python/C API, Versión 3.11.0

iterable An object capable of returning its members one at a time. Examples of iterables include all sequence ty-
pes (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of
any classes you define with an __iter__() method or with a __getitem__() method that implements
sequence semantics.
Los iterables pueden ser usados en el bucle for y en muchos otros sitios donde una secuencia es necesa-
ria (zip(), map(), …). Cuando un objeto iterable es pasado como argumento a la función incorporada
iter(), retorna un iterador para el objeto. Este iterador pasa así el conjunto de valores. Cuando se usan
iterables, normalmente no es necesario llamar a la función iter() o tratar con los objetos iteradores usted
mismo. La sentencia for lo hace automáticamente por usted, creando un variable temporal sin nombre para
mantener el iterador mientras dura el bucle. Vea también iterator, sequence, y generator.
iterador Un objeto que representa un flujo de datos. Llamadas repetidas al método __next__() del iterador (o al
pasar la función incorporada next()) retorna ítems sucesivos del flujo. Cuando no hay más datos disponibles,
una excepción StopIteration es disparada. En este momento, el objeto iterador está exhausto y cualquier
llamada posterior al método __next__() sólo dispara otra vez StopIteration. Los iteradores necesitan
tener un método __iter__() que retorna el objeto iterador mismo así cada iterador es también un iterable
y puede ser usado en casi todos los lugares donde los iterables son aceptados. Una excepción importante es
el código que intenta múltiples pases de iteración. Un objeto contenedor (como la list) produce un nuevo
iterador cada vez que pasa a una función iter() o se usa en un bucle for. Intentar ésto con un iterador
simplemente retornaría el mismo objeto iterador exhausto usado en previas iteraciones, haciéndolo aparecer
como un contenedor vacío.
Puede encontrar más información en typeiter.
Detalles de implementación de CPython: CPython does not consistently apply the requirement that an ite-
rator define __iter__().
función clave Una función clave o una función de colación es un invocable que retorna un valor usado para el orde-
namiento o clasificación. Por ejemplo, locale.strxfrm() es usada para producir claves de ordenamiento
que se adaptan a las convenciones específicas de ordenamiento de un locale.
Cierta cantidad de herramientas de Python aceptan funciones clave para controlar como los elementos son
ordenados o agrupados. Incluyendo a min(), max(), sorted(), list.sort(), heapq.merge(),
heapq.nsmallest(), heapq.nlargest(), y itertools.groupby().
There are several ways to create a key function. For example. the str.lower() method can serve as a key
function for case insensitive sorts. Alternatively, a key function can be built from a lambda expression such
as lambda r: (r[0], r[2]). Also, operator.attrgetter(), operator.itemgetter(),
and operator.methodcaller() are three key function constructors. See the Sorting HOW TO for
examples of how to create and use key functions.
argumento nombrado Vea argument.
lambda Una función anónima de una línea consistente en un sola expression que es evaluada cuando la función es
llamada. La sintaxis para crear una función lambda es lambda [parameters]: expression
LBYL Del inglés Look before you leap, «mira antes de saltar». Es un estilo de codificación que prueba explícitamente
las condiciones previas antes de hacer llamadas o búsquedas. Este estilo contrasta con la manera EAFP y está
caracterizado por la presencia de muchas sentencias if.
En entornos multi-hilos, el método LBYL tiene el riesgo de introducir condiciones de carrera entre los hilos que
están «mirando» y los que están «saltando». Por ejemplo, el código, if key in mapping: return mapping[key]‘
puede fallar si otro hilo remueve key de mapping después del test, pero antes de retornar el valor. Este problema
puede ser resuelto usando bloqueos o empleando el método EAFP.
codificación de la configuración regional On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
locale.setlocale(locale.LC_CTYPE, new_locale).
On Windows, it is the ANSI code page (ex: "cp1252").
On Android and VxWorks, Python uses "utf-8" as the locale encoding.
locale.getencoding() can be used to get the locale encoding.
See also the filesystem encoding and error handler.

292 Apéndice A. Glosario

 The Python/C API, Versión 3.11.0

lista Es una sequence Python incorporada. A pesar de su nombre es más similar a un arreglo en otros lenguajes que
a una lista enlazada porque el acceso a los elementos es O(1).
comprensión de listas Una forma compacta de procesar todos o parte de los elementos en una secuencia y retornar
una lista como resultado. result = ['{:#04x}'.format(x) for x in range(256) if x
% 2 == 0] genera una lista de cadenas conteniendo números hexadecimales (0x..) entre 0 y 255. La cláusula
if es opcional. Si es omitida, todos los elementos en range(256) son procesados.
cargador Un objeto que carga un módulo. Debe definir el método llamado load_module(). Un cargador es
normalmente retornados por un finder. Vea PEP 302 para detalles y importlib.abc.Loader para una
abstract base class.
método mágico Una manera informal de llamar a un special method.
mapeado A container object that supports arbitrary key lookups and implements the methods specified in
the collections.abc.Mapping or collections.abc.MutableMapping abstract base clas-
ses. Examples include dict, collections.defaultdict, collections.OrderedDict and
collections.Counter.
meta buscadores de ruta Un finder retornado por una búsqueda de sys.meta_path. Los meta buscadores de
ruta están relacionados a buscadores de entradas de rutas, pero son algo diferente.
Vea en importlib.abc.MetaPathFinder los métodos que los meta buscadores de ruta implementan.
metaclase La clase de una clase. Las definiciones de clases crean nombres de clase, un diccionario de clase, y una
lista de clases base. Las metaclases son responsables de tomar estos tres argumentos y crear la clase. La mayo-
ría de los objetos de un lenguaje de programación orientado a objetos provienen de una implementación por
defecto. Lo que hace a Python especial que es posible crear metaclases a medida. La mayoría de los usuario
nunca necesitarán esta herramienta, pero cuando la necesidad surge, las metaclases pueden brindar soluciones
poderosas y elegantes. Han sido usadas para loggear acceso de atributos, agregar seguridad a hilos, rastrear la
creación de objetos, implementar singletons, y muchas otras tareas.
Más información hallará en metaclasses.
método Una función que es definida dentro del cuerpo de una clase. Si es llamada como un atributo de una ins-
tancia de otra clase, el método tomará el objeto instanciado como su primer argument (el cual es usualmente
denominado self). Vea function y nested scope.
orden de resolución de métodos Orden de resolución de métodos es el orden en el cual una clase base es busca-
da por un miembro durante la búsqueda. Mire en The Python 2.3 Method Resolution Order los detalles del
algoritmo usado por el intérprete Python desde la versión 2.3.
módulo Un objeto que sirve como unidad de organización del código Python. Los módulos tienen espacios de nom-
bres conteniendo objetos Python arbitrarios. Los módulos son cargados en Python por el proceso de importing.
Vea también package.
especificador de módulo Un espacio de nombres que contiene la información relacionada a la importación usada al
leer un módulo. Una instancia de importlib.machinery.ModuleSpec.
MRO Vea method resolution order.
mutable Los objetos mutables pueden cambiar su valor pero mantener su id(). Vea también immutable.
tupla nombrada La denominación «tupla nombrada» se aplica a cualquier tipo o clase que hereda de una tupla y
cuyos elementos indexables son también accesibles usando atributos nombrados. Este tipo o clase puede tener
además otras capacidades.
Varios tipos incorporados son tuplas nombradas, incluyendo los valores retornados por time.localtime()
y os.stat(). Otro ejemplo es sys.float_info:

>>> sys.float_info[1] # indexed access

1024
>>> sys.float_info.max_exp # named field access
1024
>>> isinstance(sys.float_info, tuple) # kind of tuple
True

293
The Python/C API, Versión 3.11.0

Algunas tuplas nombradas con tipos incorporados (como en los ejemplo precedentes). También puede ser crea-
da con una definición regular de clase que hereda de la clase tuple y que define campos nombrados. Una clase
como esta puede ser hechas personalizadamente o puede ser creada con la función factoría collections.
namedtuple(). Esta última técnica automáticamente brinda métodos adicionales que pueden no estar pre-
sentes en las tuplas nombradas personalizadas o incorporadas.
espacio de nombres El lugar donde la variable es almacenada. Los espacios de nombres son implementados como
diccionarios. Hay espacio de nombre local, global, e incorporado así como espacios de nombres anidados en
objetos (en métodos). Los espacios de nombres soportan modularidad previniendo conflictos de nombramiento.
Por ejemplo, las funciones builtins.open y os.open() se distinguen por su espacio de nombres. Los
espacios de nombres también ayuda a la legibilidad y mantenibilidad dejando claro qué módulo implementa
una función. Por ejemplo, escribiendo random.seed() o itertools.islice() queda claro que éstas
funciones están implementadas en los módulos random y itertools, respectivamente.
paquete de espacios de nombres Un PEP 420 package que sirve sólo para contener subpaquetes. Los paquetes de
espacios de nombres pueden no tener representación física, y específicamente se diferencian de los regular
package porque no tienen un archivo __init__.py.
Vea también module.
alcances anidados La habilidad de referirse a una variable dentro de una definición encerrada. Por ejemplo, una
función definida dentro de otra función puede referir a variables en la función externa. Note que los alcances
anidados por defecto sólo funcionan para referencia y no para asignación. Las variables locales leen y escriben
sólo en el alcance más interno. De manera semejante, las variables globales pueden leer y escribir en el espacio
de nombres global. Con nonlocal se puede escribir en alcances exteriores.
clase de nuevo estilo Vieja denominación usada para el estilo de clases ahora empleado en todos los objetos de clase.
En versiones más tempranas de Python, sólo las nuevas clases podían usar capacidades nuevas y versátiles
de Python como __slots__, descriptores, propiedades, __getattribute__(), métodos de clase y
métodos estáticos.
objeto Cualquier dato con estado (atributo o valor) y comportamiento definido (métodos). También es la más básica
clase base para cualquier new-style class.
paquete A Python module which can contain submodules or recursively, subpackages. Technically, a package is a
Python module with a __path__ attribute.
Vea también regular package y namespace package.
parámetro Una entidad nombrada en una definición de una function (o método) que especifica un argument (o en
algunos casos, varios argumentos) que la función puede aceptar. Existen cinco tipos de argumentos:
• posicional o nombrado: especifica un argumento que puede ser pasado tanto como posicional o como
nombrado. Este es el tipo por defecto de parámetro, como foo y bar en el siguiente ejemplo:

def func(foo, bar=None): ...

• sólo posicional: especifica un argumento que puede ser pasado sólo por posición. Los parámetros sólo
posicionales pueden ser definidos incluyendo un carácter / en la lista de parámetros de la función después
de ellos, como posonly1 y posonly2 en el ejemplo que sigue:

def func(posonly1, posonly2, /, positional_or_keyword): ...

• sólo nombrado: especifica un argumento que sólo puede ser pasado por nombre. Los parámetros sólo por
nombre pueden ser definidos incluyendo un parámetro posicional de una sola variable o un simple *`
antes de ellos en la lista de parámetros en la definición de la función, como kw_only1 y kw_only2 en el
ejemplo siguiente:

def func(arg, *, kw_only1, kw_only2): ...

• variable posicional: especifica una secuencia arbitraria de argumentos posicionales que pueden ser brin-
dados (además de cualquier argumento posicional aceptado por otros parámetros). Este parámetro puede
ser definido anteponiendo al nombre del parámetro *, como a args en el siguiente ejemplo:

294 Apéndice A. Glosario

 The Python/C API, Versión 3.11.0

def func(*args, **kwargs): ...

• variable nombrado: especifica que arbitrariamente muchos argumentos nombrados pueden ser brindados
(además de cualquier argumento nombrado ya aceptado por cualquier otro parámetro). Este parámetro
puede ser definido anteponiendo al nombre del parámetro con **, como kwargs en el ejemplo precedente.
Los parámetros puede especificar tanto argumentos opcionales como requeridos, así como valores por defecto
para algunos argumentos opcionales.
Vea también el glosario de argument, la pregunta respondida en la diferencia entre argumentos y parámetros,
la clase inspect.Parameter, la sección function , y PEP 362.
entrada de ruta Una ubicación única en el import path que el path based finder consulta para encontrar los módulos
a importar.
buscador de entradas de ruta Un finder retornado por un invocable en sys.path_hooks (esto es, un path entry
hook) que sabe cómo localizar módulos dada una path entry.
Vea en importlib.abc.PathEntryFinder los métodos que los buscadores de entradas de ruta im-
plementan.
gancho a entrada de ruta Un invocable en la lista sys.path_hook que retorna un path entry finder si éste sabe
cómo encontrar módulos en un path entry específico.
buscador basado en ruta Uno de los meta buscadores de ruta por defecto que busca un import path para los mó-
dulos.
objeto tipo ruta Un objeto que representa una ruta del sistema de archivos. Un objeto tipo ruta puede ser tanto una
str como un bytes representando una ruta, o un objeto que implementa el protocolo os.PathLike. Un
objeto que soporta el protocolo os.PathLike puede ser convertido a ruta del sistema de archivo de clase
str o bytes usando la función os.fspath(); os.fsdecode() os.fsencode() pueden emplearse
para garantizar que retorne respectivamente str o bytes. Introducido por PEP 519.
PEP Propuesta de mejora de Python, del inglés Python Enhancement Proposal. Un PEP es un documento de diseño
que brinda información a la comunidad Python, o describe una nueva capacidad para Python, sus procesos o
entorno. Los PEPs deberían dar una especificación técnica concisa y una fundamentación para las capacidades
propuestas.
Los PEPs tienen como propósito ser los mecanismos primarios para proponer nuevas y mayores capacidad,
para recoger la opinión de la comunidad sobre un tema, y para documentar las decisiones de diseño que se han
hecho en Python. El autor del PEP es el responsable de lograr consenso con la comunidad y documentar las
opiniones disidentes.
Vea PEP 1.
porción Un conjunto de archivos en un único directorio (posiblemente guardo en un archivo comprimido zip) que
contribuye a un espacio de nombres de paquete, como está definido en PEP 420.
argumento posicional Vea argument.
API provisional Una API provisoria es aquella que deliberadamente fue excluida de las garantías de compatibilidad
hacia atrás de la biblioteca estándar. Aunque no se esperan cambios fundamentales en dichas interfaces, como
están marcadas como provisionales, los cambios incompatibles hacia atrás (incluso remover la misma interfaz)
podrían ocurrir si los desarrolladores principales lo estiman. Estos cambios no se hacen gratuitamente – solo
ocurrirán si fallas fundamentales y serias son descubiertas que no fueron vistas antes de la inclusión de la API.
Incluso para APIs provisorias, los cambios incompatibles hacia atrás son vistos como una «solución de último
recurso» - se intentará todo para encontrar una solución compatible hacia atrás para los problemas identificados.
Este proceso permite que la biblioteca estándar continúe evolucionando con el tiempo, sin bloquearse por
errores de diseño problemáticos por períodos extensos de tiempo. Vea PEP 411 para más detalles.
paquete provisorio Vea provisional API.
Python 3000 Apodo para la fecha de lanzamiento de Python 3.x (acuñada en un tiempo cuando llegar a la versión
3 era algo distante en el futuro.) También se lo abrevió como Py3k.

295
The Python/C API, Versión 3.11.0

Pythónico Una idea o pieza de código que sigue ajustadamente la convenciones idiomáticas comunes del lenguaje
Python, en vez de implementar código usando conceptos comunes a otros lenguajes. Por ejemplo, una conven-
ción común en Python es hacer bucles sobre todos los elementos de un iterable con la sentencia for. Muchos
otros lenguajes no tienen este tipo de construcción, así que los que no están familiarizados con Python podrían
usar contadores numéricos:

for i in range(len(food)):
print(food[i])

En contraste, un método Pythónico más limpio:

for piece in food:

print(piece)

nombre calificado Un nombre con puntos mostrando la ruta desde el alcance global del módulo a la clase, función o
método definido en dicho módulo, como se define en PEP 3155. Para las funciones o clases de más alto nivel,
el nombre calificado es el igual al nombre del objeto:

>>> class C:
... class D:
... def meth(self):
... pass
...
>>> C.__qualname__
'C'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__qualname__
'C.D.meth'

Cuando es usado para referirse a los módulos, nombre completamente calificado significa la ruta con puntos
completo al módulo, incluyendo cualquier paquete padre, por ejemplo, email.mime.text‘:

>>> import email.mime.text

>>> email.mime.text.__name__
'email.mime.text'

contador de referencias The number of references to an object. When the reference count of an object drops to
zero, it is deallocated. Reference counting is generally not visible to Python code, but it is a key element of the
CPython implementation. Programmers can call the sys.getrefcount() function to return the reference
count for a particular object.
paquete regular Un package tradicional, como aquellos con un directorio conteniendo el archivo __init__.py.
Vea también namespace package.
__slots__ Es una declaración dentro de una clase que ahorra memoria predeclarando espacio para las atributos de la
instancia y eliminando diccionarios de la instancia. Aunque es popular, esta técnica es algo dificultosa de lograr
correctamente y es mejor reservarla para los casos raros en los que existen grandes cantidades de instancias en
aplicaciones con uso crítico de memoria.
secuencia Un iterable que logra un acceso eficiente a los elementos usando índices enteros a través del método
especial __getitem__() y que define un método __len__() que retorna la longitud de la secuencia.
Algunas de las secuencias incorporadas son list, str, tuple, y bytes. Observe que dict también
soporta __getitem__() y __len__(), pero es considerada un mapeo más que una secuencia porque las
búsquedas son por claves arbitraria immutable y no por enteros.
La clase abstracta base collections.abc.Sequence define una interfaz mucho más rica que va más
allá de sólo __getitem__() y __len__(), agregando count(), index(), __contains__(), y
__reversed__(). Los tipos que implementan esta interfaz expandida pueden ser registrados explícita-
mente usando register().

296 Apéndice A. Glosario

 The Python/C API, Versión 3.11.0

comprensión de conjuntos Una forma compacta de procesar todos o parte de los elementos en un iterable y retor-
nar un conjunto con los resultados. results = {c for c in 'abracadabra' if c not in
'abc'} genera el conjunto de cadenas {'r', 'd'}. Ver comprehensions.
despacho único Una forma de despacho de una generic function donde la implementación es elegida a partir del tipo
de un sólo argumento.
rebanada Un objeto que contiene una porción de una sequence. Una rebanada es creada usando la no-
tación de suscripto, [] con dos puntos entre los números cuando se ponen varios, como en
nombre_variable[1:3:5]. La notación con corchete (suscrito) usa internamente objetos slice.
método especial Un método que es llamado implícitamente por Python cuando ejecuta ciertas operaciones en un
tipo, como la adición. Estos métodos tienen nombres que comienzan y terminan con doble barra baja. Los
métodos especiales están documentados en specialnames.
sentencia Una sentencia es parte de un conjunto (un «bloque» de código). Una sentencia tanto es una expression
como alguna de las varias sintaxis usando una palabra clave, como if, while o for.
referencia fuerte En la API C de Python, una referencia fuerte es una referencia a un objeto que incrementa el
recuento de referencias del objeto cuando se crea y disminuye el recuento de referencias del objeto cuando se
elimina.
La función Py_NewRef() se puede utilizar para crear una referencia fuerte a un objeto. Por lo general, se
debe llamar a la función Py_DECREF() en la referencia fuerte antes de salir del alcance de la referencia
fuerte, para evitar filtrar una referencia.
Consulte también borrowed reference.
codificación de texto A string in Python is a sequence of Unicode code points (in range U+0000–U+10FFFF).
To store or transfer a string, it needs to be serialized as a sequence of bytes.
Serializing a string into a sequence of bytes is known as «encoding», and recreating the string from the sequence
of bytes is known as «decoding».
There are a variety of different text serialization codecs, which are collectively referred to as «text encodings».
archivo de texto Un file object capaz de leer y escribir objetos str. Frecuentemente, un archivo de texto también
accede a un flujo de datos binario y maneja automáticamente el text encoding. Ejemplos de archivos de texto que
son abiertos en modo texto ('r' o 'w'), sys.stdin, sys.stdout, y las instancias de io.StringIO.
Vea también binary file por objeto de archivos capaces de leer y escribir objeto tipo binario.
cadena con triple comilla Una cadena que está enmarcada por tres instancias de comillas (») o apostrofes (“). Aun-
que no brindan ninguna funcionalidad que no está disponible usando cadenas con comillas simple, son útiles
por varias razones. Permiten incluir comillas simples o dobles sin escapar dentro de las cadenas y pueden abar-
car múltiples líneas sin el uso de caracteres de continuación, haciéndolas particularmente útiles para escribir
docstrings.
tipo El tipo de un objeto Python determina qué tipo de objeto es; cada objeto tiene un tipo. El tipo de un objeto
puede ser accedido por su atributo __class__ o puede ser conseguido usando type(obj).
alias de tipos Un sinónimo para un tipo, creado al asignar un tipo a un identificador.
Los alias de tipos son útiles para simplificar los indicadores de tipo. Por ejemplo:

def remove_gray_shades(
colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
pass

podría ser más legible así:

Color = tuple[int, int, int]

def remove_gray_shades(colors: list[Color]) -> list[Color]:

pass

Vea typing y PEP 484, que describen esta funcionalidad.

297
The Python/C API, Versión 3.11.0

indicador de tipo Una annotation que especifica el tipo esperado para una variable, un atributo de clase, un pará-
metro para una función o un valor de retorno.
Los indicadores de tipo son opcionales y no son obligados por Python pero son útiles para las herramientas de
análisis de tipos estático, y ayuda a las IDE en el completado del código y la refactorización.
Los indicadores de tipo de las variables globales, atributos de clase, y funciones, no de variables locales, pueden
ser accedidos usando typing.get_type_hints().
Vea typing y PEP 484, que describen esta funcionalidad.
saltos de líneas universales Una manera de interpretar flujos de texto en la cual son reconocidos como finales
de línea todas siguientes formas: la convención de Unix para fin de línea '\n', la convención de Win-
dows '\r\n', y la vieja convención de Macintosh '\r'. Vea PEP 278 y PEP 3116, además de bytes.
splitlines() para usos adicionales.
anotación de variable Una annotation de una variable o un atributo de clase.
Cuando se anota una variable o un atributo de clase, la asignación es opcional:

class C:
field: 'annotation'

Las anotaciones de variables son frecuentemente usadas para type hints: por ejemplo, se espera que esta variable
tenga valores de clase int:

count: int = 0

La sintaxis de la anotación de variables está explicada en la sección annassign.

Consulte function annotation, PEP 484 y PEP 526, que describen esta funcionalidad. Consulte también
annotations-howto para conocer las mejores prácticas sobre cómo trabajar con anotaciones.
entorno virtual Un entorno cooperativamente aislado de ejecución que permite a los usuarios de Python y a las
aplicaciones instalar y actualizar paquetes de distribución de Python sin interferir con el comportamiento de
otras aplicaciones de Python en el mismo sistema.
Vea también venv.
máquina virtual Una computadora definida enteramente por software. La máquina virtual de Python ejecuta el
bytecode generado por el compilador de bytecode.
Zen de Python Un listado de los principios de diseño y la filosofía de Python que son útiles para entender y usar el
lenguaje. El listado puede encontrarse ingresando «import this» en la consola interactiva.

298 Apéndice A. Glosario

 APÉNDICE B

Acerca de estos documentos

Estos documentos son generados por reStructuredText desarrollado por Sphinx, un procesador de documentos espe-
cíficamente escrito para la documentación de Python.
El desarrollo de la documentación y su cadena de herramientas es un esfuerzo enteramente voluntario, al igual que
Python. Si tu quieres contribuir, por favor revisa la página reporting-bugs para más información de cómo hacerlo.
Los nuevos voluntarios son siempre bienvenidos!
Agradecemos a:
• Fred L. Drake, Jr., el creador original de la documentación del conjunto de herramientas de Python y escritor
de gran parte del contenido;
• the Docutils project for creating reStructuredText and the Docutils suite;
• Fredrik Lundh for his Alternative Python Reference project from which Sphinx got many good ideas.

B.1 Contribuidores de la documentación de Python

Muchas personas han contribuido para el lenguaje de Python, la librería estándar de Python, y la documentación de
Python. Revisa Misc/ACKS la distribución de Python para una lista parcial de contribuidores.
Es solamente con la aportación y contribuciones de la comunidad de Python que Python tiene tan fantástica docu-
mentación – Muchas gracias!

299
The Python/C API, Versión 3.11.0

300 Apéndice B. Acerca de estos documentos

 APÉNDICE C

Historia y Licencia

C.1 Historia del software

Python fue creado a principios de la década de 1990 por Guido van Rossum en Stichting Mathematisch Centrum
(CWI, ver https://www.cwi.nl/) en los Países Bajos como sucesor de un idioma llamado ABC. Guido sigue siendo el
autor principal de Python, aunque incluye muchas contribuciones de otros.
En 1995, Guido continuó su trabajo en Python en la Corporation for National Research Initiatives (CNRI, consulte
https://www.cnri.reston.va.us/) en Reston, Virginia, donde lanzó varias versiones del software.
En mayo de 2000, Guido y el equipo de desarrollo central de Python se trasladaron a BeOpen.com para formar el
equipo de BeOpen PythonLabs. En octubre del mismo año, el equipo de PythonLabs se trasladó a Digital Creations
(ahora Zope Corporation; consulte https://www.zope.org/). En 2001, se formó la Python Software Foundation (PSF,
consulte https://www.python.org/psf/), una organización sin fines de lucro creada específicamente para poseer la
propiedad intelectual relacionada con Python. Zope Corporation es miembro patrocinador del PSF.
Todas las versiones de Python son de código abierto (consulte https://opensource.org/ para conocer la definición de
código abierto). Históricamente, la mayoría de las versiones de Python, pero no todas, también han sido compatibles
con GPL; la siguiente tabla resume las distintas versiones.

Lanzamiento Derivado de Año Dueño/a ¿compatible con GPL?

0.9.0 hasta 1.2 n/a 1991-1995 CWI sí
1.3 hasta 1.5.2 1.2 1995-1999 CNRI sí
1.6 1.5.2 2000 CNRI no
2.0 1.6 2000 BeOpen.com no
1.6.1 1.6 2001 CNRI no
2.1 2.0+1.6.1 2001 PSF no
2.0.1 2.0+1.6.1 2001 PSF sí
2.1.1 2.1+2.0.1 2001 PSF sí
2.1.2 2.1.1 2002 PSF sí
2.1.3 2.1.2 2002 PSF sí
2.2 y superior 2.1.1 2001-ahora PSF sí

Nota: Compatible con GPL no significa que estemos distribuyendo Python bajo la GPL. Todas las licencias de
Python, a diferencia de la GPL, le permiten distribuir una versión modificada sin que los cambios sean de código

301
The Python/C API, Versión 3.11.0

abierto. Las licencias compatibles con GPL permiten combinar Python con otro software que se publica bajo la GPL;
los otros no lo hacen.

Gracias a los muchos voluntarios externos que han trabajado bajo la dirección de Guido para hacer posibles estos
lanzamientos.

C.2 Términos y condiciones para acceder o usar Python

El software y la documentación de Python están sujetos a Acuerdo de licencia de PSF.

A partir de Python 3.8.6, los ejemplos, recetas y otros códigos de la documentación tienen licencia doble según el
Acuerdo de licencia de PSF y la Licencia BSD de cláusula cero.
Parte del software incorporado en Python está bajo diferentes licencias. Las licencias se enumeran con el código
correspondiente a esa licencia. Consulte Licencias y reconocimientos para software incorporado para obtener una lista
incompleta de estas licencias.

C.2.1 ACUERDO DE LICENCIA DE PSF PARA PYTHON | lanzamiento |

1. This LICENSE AGREEMENT is between the Python Software Foundation␣

,→("PSF"), and

the Individual or Organization ("Licensee") accessing and otherwise␣

,→using Python

3.11.0 software in source or binary form and its associated␣

,→documentation.

2. Subject to the terms and conditions of this License Agreement, PSF␣

,→hereby

grants Licensee a nonexclusive, royalty-free, world-wide license to␣

,→reproduce,

analyze, test, perform and/or display publicly, prepare derivative␣

,→works,

distribute, and otherwise use Python 3.11.0 alone or in any derivative

version, provided, however, that PSF's License Agreement and PSF's␣
,→notice of

copyright, i.e., "Copyright © 2001-2022 Python Software Foundation; All␣

,→Rights

Reserved" are retained in Python 3.11.0 alone or in any derivative␣

,→version

prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or

incorporates Python 3.11.0 or any part thereof, and wants to make the
derivative work available to others as provided herein, then Licensee␣
,→hereby

agrees to include in any such work a brief summary of the changes made␣
,→to Python

3.11.0.

4. PSF is making Python 3.11.0 available to Licensee on an "AS IS" basis.

PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY␣
,→OF

EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY␣

,→REPRESENTATION OR

WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR␣

,→THAT THE

302 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

USE OF PYTHON 3.11.0 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.11.0
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A␣
,→RESULT OF

MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.11.0, OR ANY␣

,→DERIVATIVE

THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material␣

,→breach of

its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any␣

,→relationship

of agency, partnership, or joint venture between PSF and Licensee. ␣

,→This License

Agreement does not grant permission to use PSF trademarks or trade name␣
,→in a

trademark sense to endorse or promote products or services of Licensee,␣

,→or any

third party.

8. By copying, installing or otherwise using Python 3.11.0, Licensee agrees

to be bound by the terms and conditions of this License Agreement.

C.2.2 ACUERDO DE LICENCIA DE BEOPEN.COM PARA PYTHON 2.0

ACUERDO DE LICENCIA DE CÓDIGO ABIERTO DE BEOPEN PYTHON VERSIÓN 1

1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at
160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization
("Licensee") accessing and otherwise using this software in source or binary
form and its associated documentation ("the Software").

2. Subject to the terms and conditions of this BeOpen Python License Agreement,
BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license
to reproduce, analyze, test, perform and/or display publicly, prepare derivative
works, distribute, and otherwise use the Software alone or in any derivative
version, provided, however, that the BeOpen Python License is retained in the
Software, alone or in any derivative version prepared by Licensee.

3. BeOpen is making the Software available to Licensee on an "AS IS" basis.

BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR
ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING,
MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF
ADVISED OF THE POSSIBILITY THEREOF.

5. This License Agreement will automatically terminate upon a material breach of

its terms and conditions.

6. This License Agreement shall be governed by and interpreted in all respects

by the law of the State of California, excluding conflict of law provisions.
Nothing in this License Agreement shall be deemed to create any relationship of
(continué en la próxima página)

C.2. Términos y condiciones para acceder o usar Python 303

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

agency, partnership, or joint venture between BeOpen and Licensee. This License
Agreement does not grant permission to use BeOpen trademarks or trade names in a
trademark sense to endorse or promote products or services of Licensee, or any
third party. As an exception, the "BeOpen Python" logos available at
http://www.pythonlabs.com/logos.html may be used according to the permissions
granted on that web page.

7. By copying, installing or otherwise using the software, Licensee agrees to be

bound by the terms and conditions of this License Agreement.

C.2.3 ACUERDO DE LICENCIA CNRI PARA PYTHON 1.6.1

1. This LICENSE AGREEMENT is between the Corporation for National Research

Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191
("CNRI"), and the Individual or Organization ("Licensee") accessing and
otherwise using Python 1.6.1 software in source or binary form and its
associated documentation.

2. Subject to the terms and conditions of this License Agreement, CNRI hereby
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
analyze, test, perform and/or display publicly, prepare derivative works,
distribute, and otherwise use Python 1.6.1 alone or in any derivative version,
provided, however, that CNRI's License Agreement and CNRI's notice of copyright,
i.e., "Copyright © 1995-2001 Corporation for National Research Initiatives; All
Rights Reserved" are retained in Python 1.6.1 alone or in any derivative version
prepared by Licensee. Alternately, in lieu of CNRI's License Agreement,
Licensee may substitute the following text (omitting the quotes): "Python 1.6.1
is made available subject to the terms and conditions in CNRI's License
Agreement. This Agreement together with Python 1.6.1 may be located on the
internet using the following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server on the
internet using the following URL: http://hdl.handle.net/1895.22/1013."

3. In the event Licensee prepares a derivative work that is based on or

incorporates Python 1.6.1 or any part thereof, and wants to make the derivative
work available to others as provided herein, then Licensee hereby agrees to
include in any such work a brief summary of the changes made to Python 1.6.1.

4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis. CNRI
MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE,
BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY
OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR
ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of

its terms and conditions.

7. This License Agreement shall be governed by the federal intellectual property

law of the United States, including without limitation the federal copyright
law, and, to the extent such U.S. federal law does not apply, by the law of the
Commonwealth of Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based on Python
1.6.1 that incorporate non-separable material that was previously distributed
under the GNU General Public License (GPL), the law of the Commonwealth of
(continué en la próxima página)

304 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

Virginia shall govern this License Agreement only as to issues arising under or
with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in
this License Agreement shall be deemed to create any relationship of agency,
partnership, or joint venture between CNRI and Licensee. This License Agreement
does not grant permission to use CNRI trademarks or trade name in a trademark
sense to endorse or promote products or services of Licensee, or any third
party.

8. By clicking on the "ACCEPT" button where indicated, or by copying, installing

or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and
conditions of this License Agreement.

C.2.4 ACUERDO DE LICENCIA CWI PARA PYTHON 0.9.0 HASTA 1.2

Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The

Netherlands. All rights reserved.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided that
the above copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation, and that
the name of Stichting Mathematisch Centrum or CWI not be used in advertising or
publicity pertaining to distribution of the software without specific, written
prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS

SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

C.2.5 LICENCIA BSD DE CLÁUSULA CERO PARA CÓDIGO EN EL PYTHON |

lanzamiento | DOCUMENTACIÓN

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

C.2. Términos y condiciones para acceder o usar Python 305

The Python/C API, Versión 3.11.0

C.3 Licencias y reconocimientos para software incorporado

Esta sección es una lista incompleta, pero creciente, de licencias y reconocimientos para software de terceros incor-
porado en la distribución de Python.

C.3.1 Mersenne Twister

El módulo _random incluye código basado en una descarga de http://www.math.sci.hiroshima-u.ac.jp/~m-mat/

MT/MT2002/emt19937ar.html. Los siguientes son los comentarios textuales del código original:

A C-program for MT19937, with initialization improved 2002/1/26.

Coded by Takuji Nishimura and Makoto Matsumoto.

Before using, initialize the state by using init_genrand(seed)

or init_by_array(init_key, key_length).

Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

3. The names of its contributors may not be used to endorse or promote

products derived from this software without specific prior written
permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Any feedback is very welcome.

http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
email: m-mat @ math.sci.hiroshima-u.ac.jp (remove space)

306 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

C.3.2 Sockets

The socket module uses the functions, getaddrinfo(), and getnameinfo(), which are coded in separate
source files from the WIDE Project, https://www.wide.ad.jp/.

Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

C.3.3 Servicios de socket asincrónicos

Los módulos asynchat y asyncore contienen el siguiente aviso:

Copyright 1996 by Sam Rushing

All Rights Reserved

Permission to use, copy, modify, and distribute this software and

its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of Sam
Rushing not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.

SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,

INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

C.3. Licencias y reconocimientos para software incorporado 307

The Python/C API, Versión 3.11.0

C.3.4 Gestión de cookies

El módulo http.cookies contiene el siguiente aviso:

Copyright 2000 by Timothy O'Malley <[email protected]>

All Rights Reserved

Permission to use, copy, modify, and distribute this software

and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Timothy O'Malley not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS

SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

C.3.5 Seguimiento de ejecución

El módulo trace contiene el siguiente aviso:

portions copyright 2001, Autonomous Zones Industries, Inc., all rights...

err... reserved and offered to the public under the terms of the
Python 2.2 license.
Author: Zooko O'Whielacronx
http://zooko.com/
mailto:[email protected]

Copyright 2000, Mojam Media, Inc., all rights reserved.

Author: Skip Montanaro

Copyright 1999, Bioreason, Inc., all rights reserved.

Author: Andrew Dalke

Copyright 1995-1997, Automatrix, Inc., all rights reserved.

Author: Skip Montanaro

Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.

Permission to use, copy, modify, and distribute this Python software and
its associated documentation for any purpose without fee is hereby
granted, provided that the above copyright notice appears in all copies,
and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of neither Automatrix,
Bioreason or Mojam Media be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

308 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

C.3.6 funciones UUencode y UUdecode

El módulo uu contiene el siguiente aviso:

Copyright 1994 by Lance Ellinghouse

Cathedral City, California Republic, United States of America.
All Rights Reserved
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Lance Ellinghouse
not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.
LANCE ELLINGHOUSE DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL LANCE ELLINGHOUSE CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Modified by Jack Jansen, CWI, July 1995:

- Use binascii module to do the actual line-by-line conversion
between ascii and binary. This results in a 1000-fold speedup. The C
version is still 5 times faster, though.
- Arguments more compliant with Python standard

C.3.7 Llamadas a procedimientos remotos XML

El módulo xmlrpc.client contiene el siguiente aviso:

The XML-RPC client interface is

Copyright (c) 1999-2002 by Secret Labs AB

Copyright (c) 1999-2002 by Fredrik Lundh

By obtaining, using, and/or copying this software and/or its

associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:

Permission to use, copy, modify, and distribute this software and

its associated documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appears in
all copies, and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Secret Labs AB or the author not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.

C.3. Licencias y reconocimientos para software incorporado 309

The Python/C API, Versión 3.11.0

C.3.8 test_epoll

El módulo test_epoll contiene el siguiente aviso:

Copyright (c) 2001-2006 Twisted Matrix Laboratories.

Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be

included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

C.3.9 Seleccionar kqueue

El módulo select contiene el siguiente aviso para la interfaz kqueue:

Copyright (c) 2000 Doug White, 2006 James Knight, 2007 Christian Heimes
All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

310 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

C.3.10 SipHash24

El archivo Python/pyhash.c contiene la implementación de Marek Majkowski del algoritmo SipHash24 de Dan
Bernstein. Contiene la siguiente nota:

<MIT License>
Copyright (c) 2013 Marek Majkowski <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</MIT License>

Original location:
https://github.com/majek/csiphash/

Solution inspired by code from:

Samuel Neves (supercop/crypto_auth/siphash24/little)
djb (supercop/crypto_auth/siphash24/little2)
Jean-Philippe Aumasson (https://131002.net/siphash/siphash24.c)

C.3.11 strtod y dtoa

The file Python/dtoa.c, which supplies C functions dtoa and strtod for conversion of C doubles to and from
strings, is derived from the file of the same name by David M. Gay, currently available from https://web.archive.org/
web/20220517033456/http://www.netlib.org/fp/dtoa.c. The original file, as retrieved on March 16, 2009, contains
the following copyright and licensing notice:

/****************************************************************
*
* The author of this software is David M. Gay.
*
* Copyright (c) 1991, 2000, 2001 by Lucent Technologies.
*
* Permission to use, copy, modify, and distribute this software for any
* purpose without fee is hereby granted, provided that this entire notice
* is included in all copies of any software which is or includes a copy
* or modification of this software and in all copies of the supporting
* documentation for such software.
*
* THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
* WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY
* REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
* OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
*
***************************************************************/

C.3. Licencias y reconocimientos para software incorporado 311

The Python/C API, Versión 3.11.0

C.3.12 OpenSSL

Los módulos hashlib, posix, ssl, crypt utilizan la biblioteca OpenSSL para un rendimiento adicional si el
sistema operativo la pone a disposición. Además, los instaladores de Windows y macOS para Python pueden incluir
una copia de las bibliotecas de OpenSSL, por lo que incluimos una copia de la licencia de OpenSSL aquí:

LICENSE ISSUES
==============

The OpenSSL toolkit stays under a dual license, i.e. both the conditions of
the OpenSSL License and the original SSLeay license apply to the toolkit.
See below for the actual license texts. Actually both licenses are BSD-style
Open Source licenses. In case of any license issues related to OpenSSL
please contact [email protected].

OpenSSL License
---------------

/* ====================================================================
* Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. All advertising materials mentioning features or use of this
* software must display the following acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* [email protected].
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
(continué en la próxima página)

312 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* ([email protected]). This product includes software written by Tim
* Hudson ([email protected]).
*
*/

Original SSLeay License

-----------------------

/* Copyright (C) 1995-1998 Eric Young ([email protected])

* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young ([email protected]).
* The implementation was written so as to conform with Netscapes SSL.
*
* This library is free for commercial and non-commercial use as long as
* the following conditions are aheared to. The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code. The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson ([email protected]).
*
* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given attribution
* as the author of the parts of the library used.
* This can be in the form of a textual message at program startup or
* in documentation (online or textual) provided with the package.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
* must display the following acknowledgement:
* "This product includes cryptographic software written by
* Eric Young ([email protected])"
* The word 'cryptographic' can be left out if the rouines from the library
* being used are not cryptographic related :-).
* 4. If you include any Windows specific code (or a derivative thereof) from
* the apps directory (application code) you must include an acknowledgement:
* "This product includes software written by Tim Hudson ([email protected])"
*
* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
(continué en la próxima página)

C.3. Licencias y reconocimientos para software incorporado 313

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* The licence and distribution terms for any publically available version or
* derivative of this code cannot be changed. i.e. this code cannot simply be
* copied and put under another distribution licence
* [including the GNU Public Licence.]
*/

C.3.13 expat

La extensión pyexpat se construye usando una copia incluida de las fuentes de expatriados a menos que la cons-
trucción esté configurada --with-system-expat:

Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
and Clark Cooper

Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

C.3.14 libffi

La extensión _ctypes se construye usando una copia incluida de las fuentes de libffi a menos que la construcción
esté configurada --with-system-libffi:

Copyright (c) 1996-2008 Red Hat, Inc and others.

Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
(continué en la próxima página)

314 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

C.3.15 zlib

La extensión zlib se crea utilizando una copia incluida de las fuentes de zlib si la versión de zlib encontrada en el
sistema es demasiado antigua para ser utilizada para la compilación:

Copyright (C) 1995-2011 Jean-loup Gailly and Mark Adler

This software is provided 'as-is', without any express or implied

warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,

including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Jean-loup Gailly Mark Adler

[email protected] [email protected]

C.3.16 cfuhash

La implementación de la tabla hash utilizada por tracemalloc se basa en el proyecto cfuhash:

Copyright (c) 2005 Don Owens

All rights reserved.

This code is released under the BSD license:

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:

* Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above

copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.

* Neither the name of the author nor the names of its

contributors may be used to endorse or promote products derived
(continué en la próxima página)

C.3. Licencias y reconocimientos para software incorporado 315

The Python/C API, Versión 3.11.0

(proviene de la página anterior)

from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.

C.3.17 libmpdec

El módulo _decimal se construye usando una copia incluida de la biblioteca libmpdec a menos que la construcción
esté configurada --with-system-libmpdec:

Copyright (c) 2008-2020 Stefan Krah. All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

C.3.18 Conjunto de pruebas W3C C14N

El conjunto de pruebas C14N 2.0 en el paquete test (Lib/test/xmltestdata/c14n-20/) se recuperó

del sitio web de W3C en https://www.w3.org/TR/xml-c14n2-testcases/ y se distribuye bajo la licencia BSD de 3
cláusulas:

Copyright (c) 2013 W3C(R) (MIT, ERCIM, Keio, Beihang),

All Rights Reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:
(continué en la próxima página)

316 Apéndice C. Historia y Licencia

 The Python/C API, Versión 3.11.0

(proviene de la página anterior)

* Redistributions of works must retain the original copyright notice,

this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the original copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the W3C nor the names of its contributors may be
used to endorse or promote products derived from this work without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

C.3.19 Audioop

The audioop module uses the code base in g771.c file of the SoX project:: Programming the AdLib/Sound
Blaster FM Music Chips Version 2.0 (24 Feb 1992) Copyright (c) 1991, 1992 by Jeffrey S. Lee
[email protected] Warranty and Copyright Policy This document is provided on an «as-is» basis, and
its author makes no warranty or representation, express or implied, with respect to its quality performance
or fitness for a particular purpose. In no event will the author of this document be liable for direct, indirect,
special, incidental, or consequential damages arising out of the use or inability to use the information contained
within. Use of this document is at your own risk. This file may be used and copied freely so long as the
applicable copyright notices are retained, and no modifications are made to the text of the document. No
money shall be charged for its distribution beyond reasonable shipping, handling and duplication costs, nor
shall proprietary changes be made to this document so that it cannot be distributed freely. This document may
not be included in published material or commercial packages without the written consent of its author.

C.3. Licencias y reconocimientos para software incorporado 317

The Python/C API, Versión 3.11.0

318 Apéndice C. Historia y Licencia

 APÉNDICE D

Derechos de autor

Python y esta documentación es:

Copyright © 2001-2022 Python Software Foundation. All rights reserved.
Derechos de autor © 2000 BeOpen.com. Todos los derechos reservados.
Derechos de autor © 1995-2000 Corporation for National Research Initiatives. Todos los derechos reservados.
Derechos de autor © 1991-1995 Stichting Mathematisch Centrum. Todos los derechos reservados.

Consulte Historia y Licencia para obtener información completa sobre licencias y permisos.

319
The Python/C API, Versión 3.11.0

320 Apéndice D. Derechos de autor

 Índice

No alfabético A
..., 285 a la espera, 286
2to3, 285 abort(), 68
>>>, 285 abs
__all__ (package variable), 68 función incorporada, 95
__dict__ (module attribute), 158 administrador asincrónico de
__doc__ (module attribute), 157 contexto, 286
__file__ (module attribute), 157, 158 administrador de contextos, 287
__future__, 290 alcances anidados, 294
__import__ alias de tipos, 297
función incorporada, 69 allocfunc (C type), 275
__loader__ (module attribute), 157 anotación, 285
__main__ anotación de función, 290
módulo, 12, 182, 195 anotación de variable, 298
__name__ (module attribute), 157, 158 apagado del intérprete, 291
__package__ (module attribute), 157 API provisional, 295
__PYVENV_LAUNCHER__, 211, 216 archivo binario, 286
__slots__, 296 archivo de texto, 297
_frozen (C struct), 71 argumento, 285
_inittab (C struct), 72 argumento nombrado, 292
_Py_c_diff (C function), 121 argumento posicional, 295
_Py_c_neg (C function), 121 argv (in module sys), 186
_Py_c_pow (C function), 121 ascii
_Py_c_prod (C function), 121 función incorporada, 87
_Py_c_quot (C function), 121 atributo, 286
_Py_c_sum (C function), 121
_Py_InitializeMain (C function), 223 B
_Py_NoneStruct (C var), 238 BDFL, 286
_PyBytes_Resize (C function), 124 binaryfunc (C type), 276
_PyCFunctionFast (C type), 240 bloqueo global del intérprete, 290
_PyCFunctionFastWithKeywords (C type), 240 buffer interface
_PyFrameEvalFunction (C type), 193 (see buffer protocol), 101
_PyInterpreterState_GetEvalFrameFunc buffer object
(C function), 193 (see buffer protocol), 101
_PyInterpreterState_SetEvalFrameFunc buffer protocol, 101
(C function), 193 builtins
_PyObject_GetDictPtr (C function), 87 módulo, 12, 182, 195
_PyObject_New (C function), 237 buscador, 289
_PyObject_NewVar (C function), 237 buscador basado en ruta, 295
_PyTuple_Resize (C function), 144 buscador de entradas de ruta, 295
_thread bytearray
módulo, 190 objeto, 124
bytecode, 287
bytes

321
The Python/C API, Versión 3.11.0

función incorporada, 87 EOFError (built-in exception), 156

objeto, 122 espacio de nombres, 294
especificador de módulo, 293
C exc_info() (in module sys), 11
cadena con triple comilla, 297 exec_prefix, 4
callable, 287 executable (in module sys), 184
calloc(), 225 exit(), 68
Capsule expresión, 289
objeto, 169 expresión generadora, 290
cargador, 293
C-contiguous, 104, 288 F
clase, 287 f-string, 289
clase base abstracta, 285 file
clase de nuevo estilo, 294 objeto, 156
classmethod float
función incorporada, 242 función incorporada, 96
cleanup functions, 68 floating point
close() (in module os), 196 objeto, 119
CO_FUTURE_DIVISION (C var), 45 Fortran contiguous, 104, 288
code object, 154 free(), 225
codificación de la configuración freefunc (C type), 275
regional, 292 freeze utility, 71
codificación de texto, 297 frozenset
codificación del sistema de archivos objeto, 150
y manejador de errores, 289 función, 289
compile función clave, 292
función incorporada, 70 función corrutina, 288
complex number función genérica, 290
objeto, 121 función incorporada
comprensión de conjuntos, 297 __import__, 69
comprensión de diccionarios, 288 abs, 95
comprensión de listas, 293 ascii, 87
contador de referencias, 296 bytes, 87
contiguo, 288 classmethod, 242
contiguous, 104 compile, 70
copyright (in module sys), 186 divmod, 94
corrutina, 288 float, 96
CPython, 288 hash, 88, 255
int, 96
D len, 88, 97, 99, 146, 149, 151
decorador, 288 pow, 94, 96
descrgetfunc (C type), 275 repr, 87, 254
descriptor, 288 staticmethod, 242
descrsetfunc (C type), 275 tuple, 98, 147
despacho único, 297 type, 88
destructor (C type), 275 function
diccionario, 288 objeto, 152
dictionary
objeto, 147 G
división entera, 289 gancho a entrada de ruta, 295
divmod generador, 290
función incorporada, 94 generador asincrónico, 286
docstring, 288 generator, 290
generator expression, 290
E getattrfunc (C type), 275
EAFP, 289 getattrofunc (C type), 275
entorno virtual, 298 getbufferproc (C type), 276
entrada de ruta, 295 getiterfunc (C type), 276

322 Índice
 The Python/C API, Versión 3.11.0

GIL, 290 main(), 183, 186

global interpreter lock, 187 malloc(), 225
mapeado, 293
H mapping
hash objeto, 147
función incorporada, 88, 255 máquina virtual, 298
hash-based pyc, 291 memoryview
hashable, 291 objeto, 167
hashfunc (C type), 276 meta buscadores de ruta, 293
metaclase, 293
I METH_CLASS (variable incorporada), 242
IDLE, 291 METH_COEXIST (variable incorporada), 242
importador, 291 METH_FASTCALL (variable incorporada), 241
importar, 291 METH_NOARGS (variable incorporada), 242
incr_item(), 11, 12 METH_O (variable incorporada), 242
indicador de tipo, 298 METH_STATIC (variable incorporada), 242
initproc (C type), 275 METH_VARARGS (variable incorporada), 241
inmutable, 291 method
inquiry (C type), 280 magic, 293
instancemethod objeto, 153
objeto, 153 special, 297
int MethodType (in module types), 152, 153
función incorporada, 96 método, 293
integer método especial, 297
objeto, 115 método mágico, 293
interactivo, 291 module
interpretado, 291 objeto, 157
interpreter lock, 187 search path, 12, 182, 185
iterable, 292 modules (in module sys), 68, 182
iterable asincrónico, 286 ModuleType (in module types), 157
iterador, 292 módulo, 293
iterador asincrónico, 286 __main__, 12, 182, 195
iterador generador, 290 _thread, 190
iterador generador asincrónico, 286 builtins, 12, 182, 195
iternextfunc (C type), 276 signal, 56
sys, 12, 182, 195
K módulo de extensión, 289
MRO, 293
KeyboardInterrupt (built-in exception), 56 mutable, 293
L N
lambda, 292 newfunc (C type), 275
LBYL, 292 nombre calificado, 296
len None
función incorporada, 88, 97, 99, 146, 149, objeto, 115
151 numeric
lenfunc (C type), 276 objeto, 115
list número complejo, 287
objeto, 146
lista, 293 O
lock, interpreter, 187
object
long integer
code, 154
objeto, 115
objeto, 294
LONG_MAX, 116
bytearray, 124
M bytes, 122
Capsule, 169
magic complex number, 121
method, 293 dictionary, 147

Índice 323
The Python/C API, Versión 3.11.0

file, 156 Py_buffer.len (C member), 102

floating point, 119 Py_buffer.ndim (C member), 103
frozenset, 150 Py_buffer.obj (C member), 102
function, 152 Py_buffer.readonly (C member), 102
instancemethod, 153 Py_buffer.shape (C member), 103
integer, 115 Py_buffer.strides (C member), 103
list, 146 Py_buffer.suboffsets (C member), 103
long integer, 115 Py_BuildValue (C function), 79
mapping, 147 Py_BytesMain (C function), 41
memoryview, 167 Py_BytesWarningFlag (C var), 180
method, 153 Py_CHARMASK (C macro), 5
module, 157 Py_CLEAR (C function), 48
None, 115 Py_CompileString (C function), 43
numeric, 115 Py_CompileString(), 44, 45
sequence, 122 Py_CompileStringExFlags (C function), 44
set, 150 Py_CompileStringFlags (C function), 43
tuple, 143 Py_CompileStringObject (C function), 44
type, 7, 111 Py_complex (C type), 121
objeto archivo, 289 Py_DebugFlag (C var), 180
objeto tipo ruta, 295 Py_DecodeLocale (C function), 64
objetos tipo archivo, 289 Py_DecRef (C function), 48
objetos tipo binarios, 287 Py_DECREF (C function), 48
objobjargproc (C type), 276 Py_DECREF(), 7
objobjproc (C type), 276 Py_DEPRECATED (C macro), 5
orden de resolución de métodos, 293 Py_DontWriteBytecodeFlag (C var), 180
OverflowError (built-in exception), 116118 Py_Ellipsis (C var), 167
Py_EncodeLocale (C function), 65
P Py_END_ALLOW_THREADS, 188
package variable Py_END_ALLOW_THREADS (C macro), 191
__all__, 68 Py_EndInterpreter (C function), 196
paquete, 294 Py_EnterRecursiveCall (C function), 59
paquete de espacios de nombres, 294 Py_eval_input (C var), 44
paquete provisorio, 295 Py_Exit (C function), 68
paquete regular, 296 Py_False (C var), 118
parámetro, 294 Py_FatalError (C function), 68
path Py_FatalError(), 186
module search, 12, 182, 185 Py_FdIsInteractive (C function), 63
PATH, 12 Py_file_input (C var), 44
path (in module sys), 12, 182, 185 Py_Finalize (C function), 183
PEP, 295 Py_FinalizeEx (C function), 182
platform (in module sys), 185 Py_FinalizeEx(), 68, 182, 195, 196
porción, 295 Py_FrozenFlag (C var), 180
pow Py_GenericAlias (C function), 177
función incorporada, 94, 96 Py_GenericAliasType (C var), 177
prefix, 4 Py_GetArgcArgv (C function), 223
Py_ABS (C macro), 4 Py_GetBuildInfo (C function), 186
Py_AddPendingCall (C function), 196 Py_GetCompiler (C function), 186
Py_AddPendingCall(), 196 Py_GetCopyright (C function), 186
Py_ALWAYS_INLINE (C macro), 4 Py_GETENV (C macro), 5
Py_AtExit (C function), 68 Py_GetExecPrefix (C function), 184
Py_BEGIN_ALLOW_THREADS, 188 Py_GetExecPrefix(), 12
Py_BEGIN_ALLOW_THREADS (C macro), 191 Py_GetPath (C function), 185
Py_BLOCK_THREADS (C macro), 191 Py_GetPath(), 12, 183, 185
Py_buffer (C type), 102 Py_GetPlatform (C function), 185
Py_buffer.buf (C member), 102 Py_GetPrefix (C function), 184
Py_buffer.format (C member), 102 Py_GetPrefix(), 12
Py_buffer.internal (C member), 103 Py_GetProgramFullPath (C function), 184
Py_buffer.itemsize (C member), 102 Py_GetProgramFullPath(), 12

324 Índice
 The Python/C API, Versión 3.11.0

Py_GetProgramName (C function), 183 Py_RETURN_FALSE (C macro), 119

Py_GetPythonHome (C function), 187 Py_RETURN_NONE (C macro), 115
Py_GetVersion (C function), 185 Py_RETURN_NOTIMPLEMENTED (C macro), 85
Py_HashRandomizationFlag (C var), 180 Py_RETURN_TRUE (C macro), 119
Py_IgnoreEnvironmentFlag (C var), 180 Py_RunMain (C function), 222
Py_IncRef (C function), 48 Py_SET_REFCNT (C function), 239
Py_INCREF (C function), 47 Py_SET_SIZE (C function), 239
Py_INCREF(), 7 Py_SET_TYPE (C function), 239
Py_Initialize (C function), 182 Py_SetPath (C function), 185
Py_Initialize(), 12, 183, 195 Py_SetPath(), 185
Py_InitializeEx (C function), 182 Py_SetProgramName (C function), 183
Py_InitializeFromConfig (C function), 219 Py_SetProgramName(), 12, 182, 184
Py_InspectFlag (C var), 181 Py_SetPythonHome (C function), 187
Py_InteractiveFlag (C var), 181 Py_SetStandardStreamEncoding (C function),
Py_Is (C function), 238 183
Py_IS_TYPE (C function), 239 Py_single_input (C var), 45
Py_IsFalse (C function), 239 Py_SIZE (C function), 239
Py_IsInitialized (C function), 182 Py_ssize_t (C type), 10
Py_IsInitialized(), 12 PY_SSIZE_T_MAX, 117
Py_IsNone (C function), 238 Py_STRINGIFY (C macro), 5
Py_IsolatedFlag (C var), 181 Py_TPFLAGS_BASE_EXC_SUBCLASS (variable in-
Py_IsTrue (C function), 239 corporada), 258
Py_LeaveRecursiveCall (C function), 59 Py_TPFLAGS_BASETYPE (variable incorporada),
Py_LegacyWindowsFSEncodingFlag (C var), 257
181 Py_TPFLAGS_BYTES_SUBCLASS (variable incorpo-
Py_LegacyWindowsStdioFlag (C var), 181 rada), 258
Py_LIMITED_API (C macro), 15 Py_TPFLAGS_DEFAULT (variable incorporada), 257
Py_Main (C function), 41 Py_TPFLAGS_DICT_SUBCLASS (variable incorpo-
PY_MAJOR_VERSION (C macro), 283 rada), 258
Py_MAX (C macro), 5 Py_TPFLAGS_DISALLOW_INSTANTIATION (va-
Py_MEMBER_SIZE (C macro), 5 riable incorporada), 258
PY_MICRO_VERSION (C macro), 283 Py_TPFLAGS_HAVE_FINALIZE (variable incorpo-
Py_MIN (C macro), 5 rada), 258
PY_MINOR_VERSION (C macro), 283 Py_TPFLAGS_HAVE_GC (variable incorporada), 257
Py_mod_create (C macro), 161 Py_TPFLAGS_HAVE_VECTORCALL (variable incor-
Py_mod_create.create_module (C function), porada), 258
161 Py_TPFLAGS_HEAPTYPE (variable incorporada),
Py_mod_exec (C macro), 161 257
Py_mod_exec.exec_module (C function), 161 Py_TPFLAGS_IMMUTABLETYPE (variable incorpo-
Py_NewInterpreter (C function), 195 rada), 258
Py_NewRef (C function), 47 Py_TPFLAGS_LIST_SUBCLASS (variable incorpo-
Py_NO_INLINE (C macro), 5 rada), 258
Py_None (C var), 115 Py_TPFLAGS_LONG_SUBCLASS (variable incorpo-
Py_NoSiteFlag (C var), 181 rada), 258
Py_NotImplemented (C var), 85 Py_TPFLAGS_MAPPING (variable incorporada), 259
Py_NoUserSiteDirectory (C var), 181 Py_TPFLAGS_METHOD_DESCRIPTOR (variable in-
Py_OptimizeFlag (C var), 181 corporada), 257
Py_PreInitialize (C function), 208 Py_TPFLAGS_READY (variable incorporada), 257
Py_PreInitializeFromArgs (C function), 208 Py_TPFLAGS_READYING (variable incorporada),
Py_PreInitializeFromBytesArgs (C fun- 257
ction), 208 Py_TPFLAGS_SEQUENCE (variable incorporada),
Py_PRINT_RAW, 157 259
Py_QuietFlag (C var), 181 Py_TPFLAGS_TUPLE_SUBCLASS (variable incorpo-
Py_REFCNT (C function), 239 rada), 258
PY_RELEASE_LEVEL (C macro), 283 Py_TPFLAGS_TYPE_SUBCLASS (variable incorpo-
PY_RELEASE_SERIAL (C macro), 283 rada), 258
Py_ReprEnter (C function), 59 Py_TPFLAGS_UNICODE_SUBCLASS (variable in-
Py_ReprLeave (C function), 59 corporada), 258

Índice 325
The Python/C API, Versión 3.11.0

Py_tracefunc (C type), 197 PyArg_VaParseTupleAndKeywords (C fun-

Py_True (C var), 118 ction), 78
Py_tss_NEEDS_INIT (C macro), 199 PyASCIIObject (C type), 126
Py_tss_t (C type), 199 PyAsyncMethods (C type), 274
Py_TYPE (C function), 239 PyAsyncMethods.am_aiter (C member), 274
Py_UCS1 (C type), 126 PyAsyncMethods.am_anext (C member), 274
Py_UCS2 (C type), 126 PyAsyncMethods.am_await (C member), 274
Py_UCS4 (C type), 126 PyAsyncMethods.am_send (C member), 275
Py_UNBLOCK_THREADS (C macro), 191 PyBool_Check (C function), 118
Py_UnbufferedStdioFlag (C var), 182 PyBool_FromLong (C function), 119
Py_UNICODE (C type), 126 PyBUF_ANY_CONTIGUOUS (C macro), 105
Py_UNICODE_IS_HIGH_SURROGATE (C macro), PyBUF_C_CONTIGUOUS (C macro), 105
129 PyBUF_CONTIG (C macro), 105
Py_UNICODE_IS_LOW_SURROGATE (C macro), PyBUF_CONTIG_RO (C macro), 105
129 PyBUF_F_CONTIGUOUS (C macro), 105
Py_UNICODE_IS_SURROGATE (C macro), 129 PyBUF_FORMAT (C macro), 104
Py_UNICODE_ISALNUM (C function), 128 PyBUF_FULL (C macro), 105
Py_UNICODE_ISALPHA (C function), 128 PyBUF_FULL_RO (C macro), 105
Py_UNICODE_ISDECIMAL (C function), 128 PyBUF_INDIRECT (C macro), 104
Py_UNICODE_ISDIGIT (C function), 128 PyBUF_ND (C macro), 104
Py_UNICODE_ISLINEBREAK (C function), 128 PyBUF_RECORDS (C macro), 105
Py_UNICODE_ISLOWER (C function), 128 PyBUF_RECORDS_RO (C macro), 105
Py_UNICODE_ISNUMERIC (C function), 128 PyBUF_SIMPLE (C macro), 104
Py_UNICODE_ISPRINTABLE (C function), 129 PyBUF_STRIDED (C macro), 105
Py_UNICODE_ISSPACE (C function), 128 PyBUF_STRIDED_RO (C macro), 105
Py_UNICODE_ISTITLE (C function), 128 PyBUF_STRIDES (C macro), 104
Py_UNICODE_ISUPPER (C function), 128 PyBUF_WRITABLE (C macro), 104
Py_UNICODE_JOIN_SURROGATES (C macro), 129 PyBuffer_FillContiguousStrides (C fun-
Py_UNICODE_TODECIMAL (C function), 129 ction), 108
Py_UNICODE_TODIGIT (C function), 129 PyBuffer_FillInfo (C function), 108
Py_UNICODE_TOLOWER (C function), 129 PyBuffer_FromContiguous (C function), 107
Py_UNICODE_TONUMERIC (C function), 129 PyBuffer_GetPointer (C function), 107
Py_UNICODE_TOTITLE (C function), 129 PyBuffer_IsContiguous (C function), 107
Py_UNICODE_TOUPPER (C function), 129 PyBuffer_Release (C function), 107
Py_UNREACHABLE (C macro), 5 PyBuffer_SizeFromFormat (C function), 107
Py_UNUSED (C macro), 6 PyBuffer_ToContiguous (C function), 107
Py_VaBuildValue (C function), 80 PyBufferProcs, 101
PY_VECTORCALL_ARGUMENTS_OFFSET (C ma- PyBufferProcs (C type), 273
cro), 90 PyBufferProcs.bf_getbuffer (C member),
Py_VerboseFlag (C var), 182 273
Py_Version (C var), 283 PyBufferProcs.bf_releasebuffer (C mem-
PY_VERSION_HEX (C macro), 283 ber), 273
Py_VISIT (C function), 280 PyByteArray_AS_STRING (C function), 125
Py_XDECREF (C function), 48 PyByteArray_AsString (C function), 125
Py_XDECREF(), 12 PyByteArray_Check (C function), 124
Py_XINCREF (C function), 47 PyByteArray_CheckExact (C function), 124
Py_XNewRef (C function), 47 PyByteArray_Concat (C function), 124
PyAIter_Check (C function), 100 PyByteArray_FromObject (C function), 124
PyAnySet_Check (C function), 150 PyByteArray_FromStringAndSize (C fun-
PyAnySet_CheckExact (C function), 150 ction), 124
PyArg_Parse (C function), 78 PyByteArray_GET_SIZE (C function), 125
PyArg_ParseTuple (C function), 78 PyByteArray_Resize (C function), 125
PyArg_ParseTupleAndKeywords (C function), PyByteArray_Size (C function), 125
78 PyByteArray_Type (C var), 124
PyArg_UnpackTuple (C function), 78 PyByteArrayObject (C type), 124
PyArg_ValidateKeywordArguments (C fun- PyBytes_AS_STRING (C function), 123
ction), 78 PyBytes_AsString (C function), 123
PyArg_VaParse (C function), 78 PyBytes_AsStringAndSize (C function), 123

326 Índice
 The Python/C API, Versión 3.11.0

PyBytes_Check (C function), 122 PyCodec_Encode (C function), 83

PyBytes_CheckExact (C function), 122 PyCodec_Encoder (C function), 83
PyBytes_Concat (C function), 124 PyCodec_IgnoreErrors (C function), 84
PyBytes_ConcatAndDel (C function), 124 PyCodec_IncrementalDecoder (C function), 83
PyBytes_FromFormat (C function), 122 PyCodec_IncrementalEncoder (C function), 83
PyBytes_FromFormatV (C function), 123 PyCodec_KnownEncoding (C function), 83
PyBytes_FromObject (C function), 123 PyCodec_LookupError (C function), 84
PyBytes_FromString (C function), 122 PyCodec_NameReplaceErrors (C function), 84
PyBytes_FromStringAndSize (C function), 122 PyCodec_Register (C function), 83
PyBytes_GET_SIZE (C function), 123 PyCodec_RegisterError (C function), 84
PyBytes_Size (C function), 123 PyCodec_ReplaceErrors (C function), 84
PyBytes_Type (C var), 122 PyCodec_StreamReader (C function), 83
PyBytesObject (C type), 122 PyCodec_StreamWriter (C function), 83
PyCallable_Check (C function), 94 PyCodec_StrictErrors (C function), 84
PyCallIter_Check (C function), 165 PyCodec_Unregister (C function), 83
PyCallIter_New (C function), 165 PyCodec_XMLCharRefReplaceErrors (C fun-
PyCallIter_Type (C var), 165 ction), 84
PyCapsule (C type), 169 PyCodeObject (C type), 154
PyCapsule_CheckExact (C function), 169 PyCompactUnicodeObject (C type), 126
PyCapsule_Destructor (C type), 169 PyCompilerFlags (C struct), 45
PyCapsule_GetContext (C function), 169 PyCompilerFlags.cf_feature_version (C
PyCapsule_GetDestructor (C function), 169 member), 45
PyCapsule_GetName (C function), 169 PyCompilerFlags.cf_flags (C member), 45
PyCapsule_GetPointer (C function), 169 PyComplex_AsCComplex (C function), 122
PyCapsule_Import (C function), 170 PyComplex_Check (C function), 121
PyCapsule_IsValid (C function), 170 PyComplex_CheckExact (C function), 121
PyCapsule_New (C function), 169 PyComplex_FromCComplex (C function), 121
PyCapsule_SetContext (C function), 170 PyComplex_FromDoubles (C function), 122
PyCapsule_SetDestructor (C function), 170 PyComplex_ImagAsDouble (C function), 122
PyCapsule_SetName (C function), 170 PyComplex_RealAsDouble (C function), 122
PyCapsule_SetPointer (C function), 170 PyComplex_Type (C var), 121
PyCell_Check (C function), 154 PyComplexObject (C type), 121
PyCell_Get (C function), 154 PyConfig (C type), 209
PyCell_GET (C function), 154 PyConfig.argv (C member), 210
PyCell_New (C function), 154 PyConfig.base_exec_prefix (C member), 210
PyCell_Set (C function), 154 PyConfig.base_executable (C member), 210
PyCell_SET (C function), 154 PyConfig.base_prefix (C member), 211
PyCell_Type (C var), 154 PyConfig.buffered_stdio (C member), 211
PyCellObject (C type), 154 PyConfig.bytes_warning (C member), 211
PyCFunction (C type), 240 PyConfig.check_hash_pycs_mode (C mem-
PyCFunctionWithKeywords (C type), 240 ber), 211
PyCMethod (C type), 240 PyConfig.code_debug_ranges (C member),
PyCode_Addr2Line (C function), 155 211
PyCode_Addr2Location (C function), 155 PyConfig.configure_c_stdio (C member),
PyCode_Check (C function), 154 212
PyCode_GetCellvars (C function), 156 PyConfig.dev_mode (C member), 212
PyCode_GetCode (C function), 155 PyConfig.dump_refs (C member), 212
PyCode_GetFreevars (C function), 156 PyConfig.exec_prefix (C member), 212
PyCode_GetNumFree (C function), 154 PyConfig.executable (C member), 212
PyCode_GetVarnames (C function), 155 PyConfig.faulthandler (C member), 212
PyCode_New (C function), 155 PyConfig.filesystem_encoding (C member),
PyCode_NewEmpty (C function), 155 212
PyCode_NewWithPosOnlyArgs (C function), 155 PyConfig.filesystem_errors (C member),
PyCode_Type (C var), 154 213
PyCodec_BackslashReplaceErrors (C fun- PyConfig.hash_seed (C member), 213
ction), 84 PyConfig.home (C member), 213
PyCodec_Decode (C function), 83 PyConfig.import_time (C member), 213
PyCodec_Decoder (C function), 83 PyConfig.inspect (C member), 213

Índice 327
The Python/C API, Versión 3.11.0

PyConfig.install_signal_handlers (C PyConfig.write_bytecode (C member), 218

member), 213 PyConfig.xoptions (C member), 218
PyConfig.interactive (C member), 214 PyContext (C type), 172
PyConfig.isolated (C member), 214 PyContext_CheckExact (C function), 173
PyConfig.legacy_windows_stdio (C mem- PyContext_Copy (C function), 173
ber), 214 PyContext_CopyCurrent (C function), 173
PyConfig.malloc_stats (C member), 214 PyContext_Enter (C function), 173
PyConfig.module_search_paths (C member), PyContext_Exit (C function), 173
215 PyContext_New (C function), 173
PyConfig.module_search_paths_set (C PyContext_Type (C var), 173
member), 215 PyContextToken (C type), 173
PyConfig.optimization_level (C member), PyContextToken_CheckExact (C function), 173
215 PyContextToken_Type (C var), 173
PyConfig.orig_argv (C member), 215 PyContextVar (C type), 172
PyConfig.parse_argv (C member), 215 PyContextVar_CheckExact (C function), 173
PyConfig.parser_debug (C member), 215 PyContextVar_Get (C function), 173
PyConfig.pathconfig_warnings (C member), PyContextVar_New (C function), 173
216 PyContextVar_Reset (C function), 174
PyConfig.platlibdir (C member), 214 PyContextVar_Set (C function), 174
PyConfig.prefix (C member), 216 PyContextVar_Type (C var), 173
PyConfig.program_name (C member), 216 PyCoro_CheckExact (C function), 172
PyConfig.pycache_prefix (C member), 216 PyCoro_New (C function), 172
PyConfig.PyConfig_Clear (C function), 210 PyCoro_Type (C var), 172
PyConfig.PyConfig_InitIsolatedConfig PyCoroObject (C type), 172
(C function), 209 PyDate_Check (C function), 174
PyConfig.PyConfig_InitPythonConfig (C PyDate_CheckExact (C function), 174
function), 209 PyDate_FromDate (C function), 175
PyConfig.PyConfig_Read (C function), 209 PyDate_FromTimestamp (C function), 177
PyConfig.PyConfig_SetArgv (C function), 209 PyDateTime_Check (C function), 174
PyConfig.PyConfig_SetBytesArgv (C fun- PyDateTime_CheckExact (C function), 174
ction), 209 PyDateTime_DATE_GET_FOLD (C function), 176
PyConfig.PyConfig_SetBytesString (C PyDateTime_DATE_GET_HOUR (C function), 176
function), 209 PyDateTime_DATE_GET_MICROSECOND (C fun-
PyConfig.PyConfig_SetString (C function), ction), 176
209 PyDateTime_DATE_GET_MINUTE (C function),
PyConfig.PyConfig_SetWideStringList (C 176
function), 209 PyDateTime_DATE_GET_SECOND (C function),
PyConfig.pythonpath_env (C member), 215 176
PyConfig.quiet (C member), 216 PyDateTime_DATE_GET_TZINFO (C function),
PyConfig.run_command (C member), 216 176
PyConfig.run_filename (C member), 216 PyDateTime_DELTA_GET_DAYS (C function), 176
PyConfig.run_module (C member), 217 PyDateTime_DELTA_GET_MICROSECONDS (C
PyConfig.safe_path (C member), 210 function), 177
PyConfig.show_ref_count (C member), 217 PyDateTime_DELTA_GET_SECONDS (C function),
PyConfig.site_import (C member), 217 176
PyConfig.skip_source_first_line (C mem- PyDateTime_FromDateAndTime (C function),
ber), 217 175
PyConfig.stdio_encoding (C member), 217 PyDateTime_FromDateAndTimeAndFold (C
PyConfig.stdio_errors (C member), 217 function), 175
PyConfig.tracemalloc (C member), 218 PyDateTime_FromTimestamp (C function), 177
PyConfig.use_environment (C member), 218 PyDateTime_GET_DAY (C function), 176
PyConfig.use_hash_seed (C member), 213 PyDateTime_GET_MONTH (C function), 175
PyConfig.user_site_directory (C member), PyDateTime_GET_YEAR (C function), 175
218 PyDateTime_TIME_GET_FOLD (C function), 176
PyConfig.verbose (C member), 218 PyDateTime_TIME_GET_HOUR (C function), 176
PyConfig.warn_default_encoding (C mem- PyDateTime_TIME_GET_MICROSECOND (C fun-
ber), 211 ction), 176
PyConfig.warnoptions (C member), 218

328 Índice
 The Python/C API, Versión 3.11.0

PyDateTime_TIME_GET_MINUTE (C function), PyErr_NewExceptionWithDoc (C function), 57

176 PyErr_NoMemory (C function), 50
PyDateTime_TIME_GET_SECOND (C function), PyErr_NormalizeException (C function), 54
176 PyErr_Occurred (C function), 54
PyDateTime_TIME_GET_TZINFO (C function), PyErr_Occurred(), 10
176 PyErr_Print (C function), 50
PyDateTime_TimeZone_UTC (C var), 174 PyErr_PrintEx (C function), 49
PyDelta_Check (C function), 174 PyErr_ResourceWarning (C function), 53
PyDelta_CheckExact (C function), 174 PyErr_Restore (C function), 54
PyDelta_FromDSU (C function), 175 PyErr_SetExcFromWindowsErr (C function), 51
PyDescr_IsData (C function), 165 PyErr_SetExcFromWindowsErrWithFilename
PyDescr_NewClassMethod (C function), 165 (C function), 52
PyDescr_NewGetSet (C function), 165 PyErr_SetExcFromWindowsErrWithFilenameObject
PyDescr_NewMember (C function), 165 (C function), 51
PyDescr_NewMethod (C function), 165 PyErr_SetExcFromWindowsErrWithFilenameObjects
PyDescr_NewWrapper (C function), 165 (C function), 51
PyDict_Check (C function), 147 PyErr_SetExcInfo (C function), 55
PyDict_CheckExact (C function), 147 PyErr_SetFromErrno (C function), 50
PyDict_Clear (C function), 147 PyErr_SetFromErrnoWithFilename (C fun-
PyDict_Contains (C function), 148 ction), 51
PyDict_Copy (C function), 148 PyErr_SetFromErrnoWithFilenameObject
PyDict_DelItem (C function), 148 (C function), 51
PyDict_DelItemString (C function), 148 PyErr_SetFromErrnoWithFilenameObjects
PyDict_GetItem (C function), 148 (C function), 51
PyDict_GetItemString (C function), 148 PyErr_SetFromWindowsErr (C function), 51
PyDict_GetItemWithError (C function), 148 PyErr_SetFromWindowsErrWithFilename (C
PyDict_Items (C function), 148 function), 51
PyDict_Keys (C function), 149 PyErr_SetHandledException (C function), 55
PyDict_Merge (C function), 149 PyErr_SetImportError (C function), 52
PyDict_MergeFromSeq2 (C function), 150 PyErr_SetImportErrorSubclass (C function),
PyDict_New (C function), 147 52
PyDict_Next (C function), 149 PyErr_SetInterrupt (C function), 56
PyDict_SetDefault (C function), 148 PyErr_SetInterruptEx (C function), 56
PyDict_SetItem (C function), 148 PyErr_SetNone (C function), 50
PyDict_SetItemString (C function), 148 PyErr_SetObject (C function), 50
PyDict_Size (C function), 149 PyErr_SetString (C function), 50
PyDict_Type (C var), 147 PyErr_SetString(), 10
PyDict_Update (C function), 150 PyErr_SyntaxLocation (C function), 52
PyDict_Values (C function), 149 PyErr_SyntaxLocationEx (C function), 52
PyDictObject (C type), 147 PyErr_SyntaxLocationObject (C function), 52
PyDictProxy_New (C function), 147 PyErr_WarnEx (C function), 53
PyDoc_STR (C macro), 6 PyErr_WarnExplicit (C function), 53
PyDoc_STRVAR (C macro), 6 PyErr_WarnExplicitObject (C function), 53
PyErr_BadArgument (C function), 50 PyErr_WarnFormat (C function), 53
PyErr_BadInternalCall (C function), 52 PyErr_WriteUnraisable (C function), 50
PyErr_CheckSignals (C function), 56 PyEval_AcquireLock (C function), 194
PyErr_Clear (C function), 49 PyEval_AcquireThread (C function), 194
PyErr_Clear(), 10, 12 PyEval_AcquireThread(), 189
PyErr_ExceptionMatches (C function), 54 PyEval_EvalCode (C function), 44
PyErr_ExceptionMatches(), 12 PyEval_EvalCodeEx (C function), 44
PyErr_Fetch (C function), 54 PyEval_EvalFrame (C function), 44
PyErr_Format (C function), 50 PyEval_EvalFrameEx (C function), 44
PyErr_FormatV (C function), 50 PyEval_GetBuiltins (C function), 82
PyErr_GetExcInfo (C function), 55 PyEval_GetFrame (C function), 82
PyErr_GetHandledException (C function), 55 PyEval_GetFuncDesc (C function), 82
PyErr_GivenExceptionMatches (C function), PyEval_GetFuncName (C function), 82
54 PyEval_GetGlobals (C function), 82
PyErr_NewException (C function), 57 PyEval_GetLocals (C function), 82

Índice 329
The Python/C API, Versión 3.11.0

PyEval_InitThreads (C function), 189 PyExc_RuntimeError, 60

PyEval_InitThreads(), 182 PyExc_RuntimeWarning, 61
PyEval_MergeCompilerFlags (C function), 44 PyExc_StopAsyncIteration, 60
PyEval_ReleaseLock (C function), 195 PyExc_StopIteration, 60
PyEval_ReleaseThread (C function), 194 PyExc_SyntaxError, 60
PyEval_ReleaseThread(), 189 PyExc_SyntaxWarning, 61
PyEval_RestoreThread (C function), 190 PyExc_SystemError, 60
PyEval_RestoreThread(), 188, 189 PyExc_SystemExit, 60
PyEval_SaveThread (C function), 190 PyExc_TabError, 60
PyEval_SaveThread(), 188, 189 PyExc_TimeoutError, 60
PyEval_SetProfile (C function), 198 PyExc_TypeError, 60
PyEval_SetTrace (C function), 198 PyExc_UnboundLocalError, 60
PyEval_ThreadsInitialized (C function), 190 PyExc_UnicodeDecodeError, 60
PyExc_ArithmeticError, 60 PyExc_UnicodeEncodeError, 60
PyExc_AssertionError, 60 PyExc_UnicodeError, 60
PyExc_AttributeError, 60 PyExc_UnicodeTranslateError, 60
PyExc_BaseException, 60 PyExc_UnicodeWarning, 61
PyExc_BlockingIOError, 60 PyExc_UserWarning, 61
PyExc_BrokenPipeError, 60 PyExc_ValueError, 60
PyExc_BufferError, 60 PyExc_Warning, 61
PyExc_BytesWarning, 61 PyExc_WindowsError, 61
PyExc_ChildProcessError, 60 PyExc_ZeroDivisionError, 60
PyExc_ConnectionAbortedError, 60 PyException_GetCause (C function), 57
PyExc_ConnectionError, 60 PyException_GetContext (C function), 57
PyExc_ConnectionRefusedError, 60 PyException_GetTraceback (C function), 57
PyExc_ConnectionResetError, 60 PyException_SetCause (C function), 58
PyExc_DeprecationWarning, 61 PyException_SetContext (C function), 57
PyExc_EnvironmentError, 61 PyException_SetTraceback (C function), 57
PyExc_EOFError, 60 PyFile_FromFd (C function), 156
PyExc_Exception, 60 PyFile_GetLine (C function), 156
PyExc_FileExistsError, 60 PyFile_SetOpenCodeHook (C function), 156
PyExc_FileNotFoundError, 60 PyFile_WriteObject (C function), 157
PyExc_FloatingPointError, 60 PyFile_WriteString (C function), 157
PyExc_FutureWarning, 61 PyFloat_AS_DOUBLE (C function), 119
PyExc_GeneratorExit, 60 PyFloat_AsDouble (C function), 119
PyExc_ImportError, 60 PyFloat_Check (C function), 119
PyExc_ImportWarning, 61 PyFloat_CheckExact (C function), 119
PyExc_IndentationError, 60 PyFloat_FromDouble (C function), 119
PyExc_IndexError, 60 PyFloat_FromString (C function), 119
PyExc_InterruptedError, 60 PyFloat_GetInfo (C function), 119
PyExc_IOError, 61 PyFloat_GetMax (C function), 119
PyExc_IsADirectoryError, 60 PyFloat_GetMin (C function), 119
PyExc_KeyboardInterrupt, 60 PyFloat_Pack2 (C function), 120
PyExc_KeyError, 60 PyFloat_Pack4 (C function), 120
PyExc_LookupError, 60 PyFloat_Pack8 (C function), 120
PyExc_MemoryError, 60 PyFloat_Type (C var), 119
PyExc_ModuleNotFoundError, 60 PyFloat_Unpack2 (C function), 120
PyExc_NameError, 60 PyFloat_Unpack4 (C function), 120
PyExc_NotADirectoryError, 60 PyFloat_Unpack8 (C function), 120
PyExc_NotImplementedError, 60 PyFloatObject (C type), 119
PyExc_OSError, 60 PyFrame_GetBack (C function), 170
PyExc_OverflowError, 60 PyFrame_GetBuiltins (C function), 171
PyExc_PendingDeprecationWarning, 61 PyFrame_GetCode (C function), 171
PyExc_PermissionError, 60 PyFrame_GetGenerator (C function), 171
PyExc_ProcessLookupError, 60 PyFrame_GetGlobals (C function), 171
PyExc_RecursionError, 60 PyFrame_GetLasti (C function), 171
PyExc_ReferenceError, 60 PyFrame_GetLineNumber (C function), 171
PyExc_ResourceWarning, 61 PyFrame_GetLocals (C function), 171

330 Índice
 The Python/C API, Versión 3.11.0

PyFrameObject (C type), 170 PyImport_ImportModuleEx (C function), 69

PyFrozenSet_Check (C function), 150 PyImport_ImportModuleLevel (C function), 69
PyFrozenSet_CheckExact (C function), 151 PyImport_ImportModuleLevelObject (C
PyFrozenSet_New (C function), 151 function), 69
PyFrozenSet_Type (C var), 150 PyImport_ImportModuleNoBlock (C function),
PyFunction_Check (C function), 152 68
PyFunction_GetAnnotations (C function), 152 PyImport_ReloadModule (C function), 69
PyFunction_GetClosure (C function), 152 PyIndex_Check (C function), 97
PyFunction_GetCode (C function), 152 PyInstanceMethod_Check (C function), 153
PyFunction_GetDefaults (C function), 152 PyInstanceMethod_Function (C function), 153
PyFunction_GetGlobals (C function), 152 PyInstanceMethod_GET_FUNCTION (C fun-
PyFunction_GetModule (C function), 152 ction), 153
PyFunction_New (C function), 152 PyInstanceMethod_New (C function), 153
PyFunction_NewWithQualName (C function), PyInstanceMethod_Type (C var), 153
152 PyInterpreterState (C type), 189
PyFunction_SetAnnotations (C function), 153 PyInterpreterState_Clear (C function), 192
PyFunction_SetClosure (C function), 152 PyInterpreterState_Delete (C function), 192
PyFunction_SetDefaults (C function), 152 PyInterpreterState_Get (C function), 193
PyFunction_Type (C var), 152 PyInterpreterState_GetDict (C function),
PyFunctionObject (C type), 152 193
PyGC_Collect (C function), 281 PyInterpreterState_GetID (C function), 193
PyGC_Disable (C function), 281 PyInterpreterState_Head (C function), 198
PyGC_Enable (C function), 281 PyInterpreterState_Main (C function), 198
PyGC_IsEnabled (C function), 281 PyInterpreterState_New (C function), 192
PyGen_Check (C function), 171 PyInterpreterState_Next (C function), 198
PyGen_CheckExact (C function), 172 PyInterpreterState_ThreadHead (C fun-
PyGen_New (C function), 172 ction), 198
PyGen_NewWithQualName (C function), 172 PyIter_Check (C function), 100
PyGen_Type (C var), 171 PyIter_Next (C function), 100
PyGenObject (C type), 171 PyIter_Send (C function), 101
PyGetSetDef (C type), 243 PyList_Append (C function), 147
PyGILState_Check (C function), 191 PyList_AsTuple (C function), 147
PyGILState_Ensure (C function), 190 PyList_Check (C function), 146
PyGILState_GetThisThreadState (C fun- PyList_CheckExact (C function), 146
ction), 191 PyList_GET_ITEM (C function), 146
PyGILState_Release (C function), 191 PyList_GET_SIZE (C function), 146
PyImport_AddModule (C function), 70 PyList_GetItem (C function), 146
PyImport_AddModuleObject (C function), 69 PyList_GetItem(), 9
PyImport_AppendInittab (C function), 71 PyList_GetSlice (C function), 147
PyImport_ExecCodeModule (C function), 70 PyList_Insert (C function), 146
PyImport_ExecCodeModuleEx (C function), 70 PyList_New (C function), 146
PyImport_ExecCodeModuleObject (C fun- PyList_Reverse (C function), 147
ction), 70 PyList_SET_ITEM (C function), 146
PyImport_ExecCodeModuleWithPathnames PyList_SetItem (C function), 146
(C function), 70 PyList_SetItem(), 8
PyImport_ExtendInittab (C function), 72 PyList_SetSlice (C function), 147
PyImport_FrozenModules (C var), 71 PyList_Size (C function), 146
PyImport_GetImporter (C function), 71 PyList_Sort (C function), 147
PyImport_GetMagicNumber (C function), 70 PyList_Type (C var), 146
PyImport_GetMagicTag (C function), 70 PyListObject (C type), 146
PyImport_GetModule (C function), 71 PyLong_AsDouble (C function), 118
PyImport_GetModuleDict (C function), 71 PyLong_AsLong (C function), 116
PyImport_Import (C function), 69 PyLong_AsLongAndOverflow (C function), 116
PyImport_ImportFrozenModule (C function), PyLong_AsLongLong (C function), 117
71 PyLong_AsLongLongAndOverflow (C function),
PyImport_ImportFrozenModuleObject (C 117
function), 71 PyLong_AsSize_t (C function), 117
PyImport_ImportModule (C function), 68 PyLong_AsSsize_t (C function), 117

Índice 331
The Python/C API, Versión 3.11.0

PyLong_AsUnsignedLong (C function), 117 PyMem_Malloc (C function), 227

PyLong_AsUnsignedLongLong (C function), 117 PyMem_New (C function), 228
PyLong_AsUnsignedLongLongMask (C fun- PyMem_RawCalloc (C function), 227
ction), 118 PyMem_RawFree (C function), 227
PyLong_AsUnsignedLongMask (C function), 118 PyMem_RawMalloc (C function), 227
PyLong_AsVoidPtr (C function), 118 PyMem_RawRealloc (C function), 227
PyLong_Check (C function), 115 PyMem_Realloc (C function), 228
PyLong_CheckExact (C function), 115 PyMem_Resize (C function), 228
PyLong_FromDouble (C function), 116 PyMem_SetAllocator (C function), 231
PyLong_FromLong (C function), 115 PyMem_SetupDebugHooks (C function), 231
PyLong_FromLongLong (C function), 116 PyMemAllocatorDomain (C type), 230
PyLong_FromSize_t (C function), 116 PyMemAllocatorDomain.PYMEM_DOMAIN_MEM
PyLong_FromSsize_t (C function), 116 (C macro), 231
PyLong_FromString (C function), 116 PyMemAllocatorDomain.PYMEM_DOMAIN_OBJ
PyLong_FromUnicodeObject (C function), 116 (C macro), 231
PyLong_FromUnsignedLong (C function), 116 PyMemAllocatorDomain.PYMEM_DOMAIN_RAW
PyLong_FromUnsignedLongLong (C function), (C macro), 230
116 PyMemAllocatorEx (C type), 230
PyLong_FromVoidPtr (C function), 116 PyMember_GetOne (C function), 243
PyLong_Type (C var), 115 PyMember_SetOne (C function), 243
PyLongObject (C type), 115 PyMemberDef (C type), 242
PyMapping_Check (C function), 99 PyMemoryView_Check (C function), 167
PyMapping_DelItem (C function), 99 PyMemoryView_FromBuffer (C function), 167
PyMapping_DelItemString (C function), 99 PyMemoryView_FromMemory (C function), 167
PyMapping_GetItemString (C function), 99 PyMemoryView_FromObject (C function), 167
PyMapping_HasKey (C function), 99 PyMemoryView_GET_BASE (C function), 168
PyMapping_HasKeyString (C function), 99 PyMemoryView_GET_BUFFER (C function), 167
PyMapping_Items (C function), 100 PyMemoryView_GetContiguous (C function),
PyMapping_Keys (C function), 100 167
PyMapping_Length (C function), 99 PyMethod_Check (C function), 153
PyMapping_SetItemString (C function), 99 PyMethod_Function (C function), 153
PyMapping_Size (C function), 99 PyMethod_GET_FUNCTION (C function), 153
PyMapping_Values (C function), 100 PyMethod_GET_SELF (C function), 154
PyMappingMethods (C type), 272 PyMethod_New (C function), 153
PyMappingMethods.mp_ass_subscript (C PyMethod_Self (C function), 153
member), 272 PyMethod_Type (C var), 153
PyMappingMethods.mp_length (C member), PyMethodDef (C type), 241
272 PyModule_AddFunctions (C function), 162
PyMappingMethods.mp_subscript (C mem- PyModule_AddIntConstant (C function), 163
ber), 272 PyModule_AddIntMacro (C function), 164
PyMarshal_ReadLastObjectFromFile (C PyModule_AddObject (C function), 163
function), 73 PyModule_AddObjectRef (C function), 162
PyMarshal_ReadLongFromFile (C function), 72 PyModule_AddStringConstant (C function),
PyMarshal_ReadObjectFromFile (C function), 164
73 PyModule_AddStringMacro (C function), 164
PyMarshal_ReadObjectFromString (C fun- PyModule_AddType (C function), 164
ction), 73 PyModule_Check (C function), 157
PyMarshal_ReadShortFromFile (C function), PyModule_CheckExact (C function), 157
72 PyModule_Create (C function), 160
PyMarshal_WriteLongToFile (C function), 72 PyModule_Create2 (C function), 160
PyMarshal_WriteObjectToFile (C function), PyModule_ExecDef (C function), 162
72 PyModule_FromDefAndSpec (C function), 161
PyMarshal_WriteObjectToString (C fun- PyModule_FromDefAndSpec2 (C function), 161
ction), 72 PyModule_GetDef (C function), 158
PyMem_Calloc (C function), 228 PyModule_GetDict (C function), 157
PyMem_Del (C function), 228 PyModule_GetFilename (C function), 158
PyMem_Free (C function), 228 PyModule_GetFilenameObject (C function),
PyMem_GetAllocator (C function), 231 158

332 Índice
 The Python/C API, Versión 3.11.0

PyModule_GetName (C function), 158 PyNumber_Subtract (C function), 94

PyModule_GetNameObject (C function), 158 PyNumber_ToBase (C function), 97
PyModule_GetState (C function), 158 PyNumber_TrueDivide (C function), 94
PyModule_New (C function), 157 PyNumber_Xor (C function), 95
PyModule_NewObject (C function), 157 PyNumberMethods (C type), 269
PyModule_SetDocString (C function), 162 PyNumberMethods.nb_absolute (C member),
PyModule_Type (C var), 157 271
PyModuleDef (C type), 158 PyNumberMethods.nb_add (C member), 270
PyModuleDef_Init (C function), 160 PyNumberMethods.nb_and (C member), 271
PyModuleDef_Slot (C type), 160 PyNumberMethods.nb_bool (C member), 271
PyModuleDef_Slot.slot (C member), 160 PyNumberMethods.nb_divmod (C member), 270
PyModuleDef_Slot.value (C member), 160 PyNumberMethods.nb_float (C member), 271
PyModuleDef.m_base (C member), 158 PyNumberMethods.nb_floor_divide (C mem-
PyModuleDef.m_clear (C member), 159 ber), 271
PyModuleDef.m_doc (C member), 158 PyNumberMethods.nb_index (C member), 271
PyModuleDef.m_free (C member), 159 PyNumberMethods.nb_inplace_add (C mem-
PyModuleDef.m_methods (C member), 159 ber), 271
PyModuleDef.m_name (C member), 158 PyNumberMethods.nb_inplace_and (C mem-
PyModuleDef.m_size (C member), 159 ber), 271
PyModuleDef.m_slots (C member), 159 PyNumberMethods.nb_inplace_floor_divide
PyModuleDef.m_slots.m_reload (C member), (C member), 271
159 PyNumberMethods.nb_inplace_lshift (C
PyModuleDef.m_traverse (C member), 159 member), 271
PyNumber_Absolute (C function), 95 PyNumberMethods.nb_inplace_matrix_multiply
PyNumber_Add (C function), 94 (C member), 271
PyNumber_And (C function), 95 PyNumberMethods.nb_inplace_multiply (C
PyNumber_AsSsize_t (C function), 97 member), 271
PyNumber_Check (C function), 94 PyNumberMethods.nb_inplace_or (C mem-
PyNumber_Divmod (C function), 94 ber), 271
PyNumber_Float (C function), 96 PyNumberMethods.nb_inplace_power (C
PyNumber_FloorDivide (C function), 94 member), 271
PyNumber_Index (C function), 96 PyNumberMethods.nb_inplace_remainder
PyNumber_InPlaceAdd (C function), 95 (C member), 271
PyNumber_InPlaceAnd (C function), 96 PyNumberMethods.nb_inplace_rshift (C
PyNumber_InPlaceFloorDivide (C function), member), 271
95 PyNumberMethods.nb_inplace_subtract (C
PyNumber_InPlaceLshift (C function), 96 member), 271
PyNumber_InPlaceMatrixMultiply (C fun- PyNumberMethods.nb_inplace_true_divide
ction), 95 (C member), 271
PyNumber_InPlaceMultiply (C function), 95 PyNumberMethods.nb_inplace_xor (C mem-
PyNumber_InPlaceOr (C function), 96 ber), 271
PyNumber_InPlacePower (C function), 96 PyNumberMethods.nb_int (C member), 271
PyNumber_InPlaceRemainder (C function), 96 PyNumberMethods.nb_invert (C member), 271
PyNumber_InPlaceRshift (C function), 96 PyNumberMethods.nb_lshift (C member), 271
PyNumber_InPlaceSubtract (C function), 95 PyNumberMethods.nb_matrix_multiply (C
PyNumber_InPlaceTrueDivide (C function), 96 member), 271
PyNumber_InPlaceXor (C function), 96 PyNumberMethods.nb_multiply (C member),
PyNumber_Invert (C function), 95 270
PyNumber_Long (C function), 96 PyNumberMethods.nb_negative (C member),
PyNumber_Lshift (C function), 95 270
PyNumber_MatrixMultiply (C function), 94 PyNumberMethods.nb_or (C member), 271
PyNumber_Multiply (C function), 94 PyNumberMethods.nb_positive (C member),
PyNumber_Negative (C function), 94 270
PyNumber_Or (C function), 95 PyNumberMethods.nb_power (C member), 270
PyNumber_Positive (C function), 95 PyNumberMethods.nb_remainder (C member),
PyNumber_Power (C function), 94 270
PyNumber_Remainder (C function), 94 PyNumberMethods.nb_reserved (C member),
PyNumber_Rshift (C function), 95 271

Índice 333
The Python/C API, Versión 3.11.0

PyNumberMethods.nb_rshift (C member), 271 PyObject_HashNotImplemented (C function),

PyNumberMethods.nb_subtract (C member), 88
270 PyObject_HEAD (C macro), 238
PyNumberMethods.nb_true_divide (C mem- PyObject_HEAD_INIT (C macro), 239
ber), 271 PyObject_Init (C function), 237
PyNumberMethods.nb_xor (C member), 271 PyObject_InitVar (C function), 237
PyObject (C type), 238 PyObject_IS_GC (C function), 279
PyObject_AsCharBuffer (C function), 108 PyObject_IsInstance (C function), 88
PyObject_ASCII (C function), 87 PyObject_IsSubclass (C function), 87
PyObject_AsFileDescriptor (C function), 156 PyObject_IsTrue (C function), 88
PyObject_AsReadBuffer (C function), 108 PyObject_Length (C function), 88
PyObject_AsWriteBuffer (C function), 108 PyObject_LengthHint (C function), 88
PyObject_Bytes (C function), 87 PyObject_Malloc (C function), 229
PyObject_Call (C function), 92 PyObject_New (C function), 237
PyObject_CallFunction (C function), 92 PyObject_NewVar (C function), 237
PyObject_CallFunctionObjArgs (C function), PyObject_Not (C function), 88
92 PyObject._ob_next (C member), 251
PyObject_CallMethod (C function), 92 PyObject._ob_prev (C member), 251
PyObject_CallMethodNoArgs (C function), 93 PyObject_Print (C function), 85
PyObject_CallMethodObjArgs (C function), 93 PyObject_Realloc (C function), 229
PyObject_CallMethodOneArg (C function), 93 PyObject_Repr (C function), 87
PyObject_CallNoArgs (C function), 92 PyObject_RichCompare (C function), 87
PyObject_CallObject (C function), 92 PyObject_RichCompareBool (C function), 87
PyObject_Calloc (C function), 229 PyObject_SetArenaAllocator (C function),
PyObject_CallOneArg (C function), 92 233
PyObject_CheckBuffer (C function), 107 PyObject_SetAttr (C function), 86
PyObject_CheckReadBuffer (C function), 108 PyObject_SetAttrString (C function), 86
PyObject_CopyData (C function), 107 PyObject_SetItem (C function), 89
PyObject_Del (C function), 237 PyObject_Size (C function), 88
PyObject_DelAttr (C function), 86 PyObject_Str (C function), 87
PyObject_DelAttrString (C function), 86 PyObject_Type (C function), 88
PyObject_DelItem (C function), 89 PyObject_TypeCheck (C function), 88
PyObject_Dir (C function), 89 PyObject_VAR_HEAD (C macro), 238
PyObject_Free (C function), 229 PyObject_Vectorcall (C function), 93
PyObject_GC_Del (C function), 280 PyObject_VectorcallDict (C function), 93
PyObject_GC_IsFinalized (C function), 280 PyObject_VectorcallMethod (C function), 93
PyObject_GC_IsTracked (C function), 279 PyObjectArenaAllocator (C type), 233
PyObject_GC_New (C function), 279 PyObject.ob_refcnt (C member), 250
PyObject_GC_NewVar (C function), 279 PyObject.ob_type (C member), 250
PyObject_GC_Resize (C function), 279 PyOS_AfterFork (C function), 64
PyObject_GC_Track (C function), 279 PyOS_AfterFork_Child (C function), 64
PyObject_GC_UnTrack (C function), 280 PyOS_AfterFork_Parent (C function), 63
PyObject_GenericGetAttr (C function), 86 PyOS_BeforeFork (C function), 63
PyObject_GenericGetDict (C function), 86 PyOS_CheckStack (C function), 64
PyObject_GenericSetAttr (C function), 86 PyOS_double_to_string (C function), 81
PyObject_GenericSetDict (C function), 86 PyOS_FSPath (C function), 63
PyObject_GetAIter (C function), 89 PyOS_getsig (C function), 64
PyObject_GetArenaAllocator (C function), PyOS_InputHook (C var), 43
233 PyOS_ReadlineFunctionPointer (C var), 43
PyObject_GetAttr (C function), 85 PyOS_setsig (C function), 64
PyObject_GetAttrString (C function), 86 PyOS_snprintf (C function), 81
PyObject_GetBuffer (C function), 107 PyOS_stricmp (C function), 82
PyObject_GetItem (C function), 89 PyOS_string_to_double (C function), 81
PyObject_GetIter (C function), 89 PyOS_strnicmp (C function), 82
PyObject_HasAttr (C function), 85 PyOS_vsnprintf (C function), 81
PyObject_HasAttrString (C function), 85 PyPreConfig (C type), 206
PyObject_Hash (C function), 88 PyPreConfig.allocator (C member), 206

334 Índice
 The Python/C API, Versión 3.11.0

PyPreConfig.coerce_c_locale (C member), PySequence_ITEM (C function), 99

207 PySequence_Length (C function), 97
PyPreConfig.coerce_c_locale_warn (C PySequence_List (C function), 98
member), 207 PySequence_Repeat (C function), 97
PyPreConfig.configure_locale (C member), PySequence_SetItem (C function), 97
206 PySequence_SetSlice (C function), 98
PyPreConfig.dev_mode (C member), 207 PySequence_Size (C function), 97
PyPreConfig.isolated (C member), 207 PySequence_Tuple (C function), 98
PyPreConfig.legacy_windows_fs_encoding PySequenceMethods (C type), 272
(C member), 207 PySequenceMethods.sq_ass_item (C mem-
PyPreConfig.parse_argv (C member), 207 ber), 272
PyPreConfig.PyPreConfig_InitIsolatedConfig PySequenceMethods.sq_concat (C member),
(C function), 206 272
PyPreConfig.PyPreConfig_InitPythonConfig PySequenceMethods.sq_contains (C mem-
(C function), 206 ber), 272
PyPreConfig.use_environment (C member), PySequenceMethods.sq_inplace_concat (C
207 member), 273
PyPreConfig.utf8_mode (C member), 207 PySequenceMethods.sq_inplace_repeat (C
PyProperty_Type (C var), 165 member), 273
PyRun_AnyFile (C function), 41 PySequenceMethods.sq_item (C member), 272
PyRun_AnyFileEx (C function), 41 PySequenceMethods.sq_length (C member),
PyRun_AnyFileExFlags (C function), 42 272
PyRun_AnyFileFlags (C function), 41 PySequenceMethods.sq_repeat (C member),
PyRun_File (C function), 43 272
PyRun_FileEx (C function), 43 PySet_Add (C function), 151
PyRun_FileExFlags (C function), 43 PySet_Check (C function), 150
PyRun_FileFlags (C function), 43 PySet_CheckExact (C function), 150
PyRun_InteractiveLoop (C function), 42 PySet_Clear (C function), 151
PyRun_InteractiveLoopFlags (C function), 42 PySet_Contains (C function), 151
PyRun_InteractiveOne (C function), 42 PySet_Discard (C function), 151
PyRun_InteractiveOneFlags (C function), 42 PySet_GET_SIZE (C function), 151
PyRun_SimpleFile (C function), 42 PySet_New (C function), 151
PyRun_SimpleFileEx (C function), 42 PySet_Pop (C function), 151
PyRun_SimpleFileExFlags (C function), 42 PySet_Size (C function), 151
PyRun_SimpleString (C function), 42 PySet_Type (C var), 150
PyRun_SimpleStringFlags (C function), 42 PySetObject (C type), 150
PyRun_String (C function), 43 PySignal_SetWakeupFd (C function), 57
PyRun_StringFlags (C function), 43 PySlice_AdjustIndices (C function), 167
PySendResult (C type), 101 PySlice_Check (C function), 166
PySeqIter_Check (C function), 165 PySlice_GetIndices (C function), 166
PySeqIter_New (C function), 165 PySlice_GetIndicesEx (C function), 166
PySeqIter_Type (C var), 165 PySlice_New (C function), 166
PySequence_Check (C function), 97 PySlice_Type (C var), 166
PySequence_Concat (C function), 97 PySlice_Unpack (C function), 166
PySequence_Contains (C function), 98 PyState_AddModule (C function), 164
PySequence_Count (C function), 98 PyState_FindModule (C function), 164
PySequence_DelItem (C function), 98 PyState_RemoveModule (C function), 164
PySequence_DelSlice (C function), 98 PyStatus (C type), 205
PySequence_Fast (C function), 98 PyStatus.err_msg (C member), 205
PySequence_Fast_GET_ITEM (C function), 98 PyStatus.exitcode (C member), 205
PySequence_Fast_GET_SIZE (C function), 98 PyStatus.func (C member), 205
PySequence_Fast_ITEMS (C function), 99 PyStatus.Py_ExitStatusException (C fun-
PySequence_GetItem (C function), 97 ction), 205
PySequence_GetItem(), 9 PyStatus.PyStatus_Error (C function), 205
PySequence_GetSlice (C function), 97 PyStatus.PyStatus_Exception (C function),
PySequence_Index (C function), 98 205
PySequence_InPlaceConcat (C function), 97 PyStatus.PyStatus_Exit (C function), 205
PySequence_InPlaceRepeat (C function), 97 PyStatus.PyStatus_IsError (C function), 205

Índice 335
The Python/C API, Versión 3.11.0

PyStatus.PyStatus_IsExit (C function), 205 PEP 498, 289

PyStatus.PyStatus_NoMemory (C function), PEP 519, 295
205 PEP 523, 193, 194
PyStatus.PyStatus_Ok (C function), 205 PEP 525, 286
PyStructSequence_Desc (C type), 145 PEP 526, 285, 298
PyStructSequence_Field (C type), 145 PEP 528, 181, 214
PyStructSequence_GET_ITEM (C function), 145 PEP 529, 135, 181
PyStructSequence_GetItem (C function), 145 PEP 538, 221
PyStructSequence_InitType (C function), 144 PEP 539, 199
PyStructSequence_InitType2 (C function), PEP 540, 221
144 PEP 552, 212
PyStructSequence_New (C function), 145 PEP 578, 68
PyStructSequence_NewType (C function), 144 PEP 585, 290
PyStructSequence_SET_ITEM (C function), 145 PEP 587, 203
PyStructSequence_SetItem (C function), 145 PEP 590, 90
PyStructSequence_UnnamedField (C var), PEP 623, 125
145 PEP 634, 259
PySys_AddAuditHook (C function), 67 PEP 3116, 298
PySys_AddWarnOption (C function), 66 PEP 3119, 88
PySys_AddWarnOptionUnicode (C function), 66 PEP 3121, 159
PySys_AddXOption (C function), 67 PEP 3147, 71
PySys_Audit (C function), 67 PEP 3151, 61
PySys_FormatStderr (C function), 67 PEP 3155, 296
PySys_FormatStdout (C function), 67 PYTHON*, 181
PySys_GetObject (C function), 66 PYTHONCOERCECLOCALE, 221
PySys_GetXOptions (C function), 67 PYTHONDEBUG, 180, 216
PySys_ResetWarnOptions (C function), 66 PYTHONDEVMODE, 212
PySys_SetArgv (C function), 187 PYTHONDONTWRITEBYTECODE, 180, 218
PySys_SetArgv(), 182 PYTHONDUMPREFS, 212, 251
PySys_SetArgvEx (C function), 186 PYTHONEXECUTABLE, 216
PySys_SetArgvEx(), 182 PYTHONFAULTHANDLER, 212
PySys_SetObject (C function), 66 PYTHONHASHSEED, 180, 213
PySys_SetPath (C function), 66 PYTHONHOME, 12, 181, 187, 213
PySys_WriteStderr (C function), 66 Pythónico, 296
PySys_WriteStdout (C function), 66 PYTHONINSPECT, 181, 213
Python 3000, 295 PYTHONIOENCODING, 183, 217
Python Enhancement Proposals PYTHONLEGACYWINDOWSFSENCODING, 181, 207
PEP 1, 295 PYTHONLEGACYWINDOWSSTDIO, 181, 214
PEP 7, 3, 6 PYTHONMALLOC, 226, 230, 232, 233
PEP 238, 45, 289 PYTHONMALLOCSTATS, 214, 226
PEP 278, 298 PYTHONNODEBUGRANGES, 211
PEP 302, 289, 293 PYTHONNOUSERSITE, 181, 218
PEP 343, 287 PYTHONOPTIMIZE, 181, 215
PEP 353, 10 PYTHONPATH, 12, 181, 215
PEP 362, 286, 295 PYTHONPLATLIBDIR, 214
PEP 383, 134, 135 PYTHONPROFILEIMPORTTIME, 213
PEP 387, 15 PYTHONPYCACHEPREFIX, 216
PEP 393, 125, 133 PYTHONSAFEPATH, 210
PEP 411, 295 PYTHONTRACEMALLOC, 218
PEP 420, 289, 294, 295 PYTHONUNBUFFERED, 182, 211
PEP 432, 223 PYTHONUTF8, 207, 221
PEP 442, 269 PYTHONVERBOSE, 182, 218
PEP 443, 290 PYTHONWARNINGS, 218
PEP 451, 161, 289 PyThread_create_key (C function), 200
PEP 483, 290 PyThread_delete_key (C function), 200
PEP 484, 285, 290, 297, 298 PyThread_delete_key_value (C function), 201
PEP 489, 161 PyThread_get_key_value (C function), 201
PEP 492, 286, 288 PyThread_ReInitTLS (C function), 201

336 Índice
 The Python/C API, Versión 3.11.0

PyThread_set_key_value (C function), 200 PyTupleObject (C type), 143

PyThread_tss_alloc (C function), 199 PyType_Check (C function), 111
PyThread_tss_create (C function), 200 PyType_CheckExact (C function), 111
PyThread_tss_delete (C function), 200 PyType_ClearCache (C function), 111
PyThread_tss_free (C function), 199 PyType_FromModuleAndSpec (C function), 113
PyThread_tss_get (C function), 200 PyType_FromSpec (C function), 114
PyThread_tss_is_created (C function), 200 PyType_FromSpecWithBases (C function), 114
PyThread_tss_set (C function), 200 PyType_GenericAlloc (C function), 112
PyThreadState, 187 PyType_GenericNew (C function), 112
PyThreadState (C type), 189 PyType_GetFlags (C function), 111
PyThreadState_Clear (C function), 192 PyType_GetModule (C function), 113
PyThreadState_Delete (C function), 192 PyType_GetModuleByDef (C function), 113
PyThreadState_DeleteCurrent (C function), PyType_GetModuleState (C function), 113
192 PyType_GetName (C function), 112
PyThreadState_EnterTracing (C function), PyType_GetQualName (C function), 112
193 PyType_GetSlot (C function), 112
PyThreadState_Get (C function), 190 PyType_HasFeature (C function), 112
PyThreadState_GetDict (C function), 194 PyType_IS_GC (C function), 112
PyThreadState_GetFrame (C function), 192 PyType_IsSubtype (C function), 112
PyThreadState_GetID (C function), 192 PyType_Modified (C function), 112
PyThreadState_GetInterpreter (C function), PyType_Ready (C function), 112
192 PyType_Slot (C type), 114
PyThreadState_LeaveTracing (C function), PyType_Slot.PyType_Slot.pfunc (C mem-
193 ber), 115
PyThreadState_New (C function), 192 PyType_Slot.PyType_Slot.slot (C member),
PyThreadState_Next (C function), 198 114
PyThreadState_SetAsyncExc (C function), 194 PyType_Spec (C type), 114
PyThreadState_Swap (C function), 190 PyType_Spec.PyType_Spec.basicsize (C
PyTime_Check (C function), 174 member), 114
PyTime_CheckExact (C function), 174 PyType_Spec.PyType_Spec.flags (C mem-
PyTime_FromTime (C function), 175 ber), 114
PyTime_FromTimeAndFold (C function), 175 PyType_Spec.PyType_Spec.itemsize (C
PyTimeZone_FromOffset (C function), 175 member), 114
PyTimeZone_FromOffsetAndName (C function), PyType_Spec.PyType_Spec.name (C member),
175 114
PyTrace_C_CALL (C var), 198 PyType_Spec.PyType_Spec.slots (C mem-
PyTrace_C_EXCEPTION (C var), 198 ber), 114
PyTrace_C_RETURN (C var), 198 PyType_Type (C var), 111
PyTrace_CALL (C var), 197 PyTypeObject (C type), 111
PyTrace_EXCEPTION (C var), 197 PyTypeObject.tp_alloc (C member), 266
PyTrace_LINE (C var), 197 PyTypeObject.tp_as_async (C member), 254
PyTrace_OPCODE (C var), 198 PyTypeObject.tp_as_buffer (C member), 256
PyTrace_RETURN (C var), 198 PyTypeObject.tp_as_mapping (C member),
PyTraceMalloc_Track (C function), 234 254
PyTraceMalloc_Untrack (C function), 234 PyTypeObject.tp_as_number (C member), 254
PyTuple_Check (C function), 143 PyTypeObject.tp_as_sequence (C member),
PyTuple_CheckExact (C function), 143 254
PyTuple_GET_ITEM (C function), 144 PyTypeObject.tp_base (C member), 263
PyTuple_GET_SIZE (C function), 144 PyTypeObject.tp_bases (C member), 267
PyTuple_GetItem (C function), 144 PyTypeObject.tp_basicsize (C member), 252
PyTuple_GetSlice (C function), 144 PyTypeObject.tp_cache (C member), 267
PyTuple_New (C function), 143 PyTypeObject.tp_call (C member), 255
PyTuple_Pack (C function), 143 PyTypeObject.tp_clear (C member), 260
PyTuple_SET_ITEM (C function), 144 PyTypeObject.tp_dealloc (C member), 252
PyTuple_SetItem (C function), 144 PyTypeObject.tp_del (C member), 268
PyTuple_SetItem(), 8 PyTypeObject.tp_descr_get (C member), 264
PyTuple_Size (C function), 143 PyTypeObject.tp_descr_set (C member), 264
PyTuple_Type (C var), 143 PyTypeObject.tp_dict (C member), 264

Índice 337
The Python/C API, Versión 3.11.0

PyTypeObject.tp_dictoffset (C member), PyUnicode_AsUCS4Copy (C function), 132

265 PyUnicode_AsUnicode (C function), 133
PyTypeObject.tp_doc (C member), 259 PyUnicode_AsUnicodeAndSize (C function),
PyTypeObject.tp_finalize (C member), 268 133
PyTypeObject.tp_flags (C member), 256 PyUnicode_AsUnicodeEscapeString (C fun-
PyTypeObject.tp_free (C member), 266 ction), 139
PyTypeObject.tp_getattr (C member), 253 PyUnicode_AsUTF8 (C function), 137
PyTypeObject.tp_getattro (C member), 255 PyUnicode_AsUTF8AndSize (C function), 137
PyTypeObject.tp_getset (C member), 263 PyUnicode_AsUTF8String (C function), 137
PyTypeObject.tp_hash (C member), 255 PyUnicode_AsUTF16String (C function), 139
PyTypeObject.tp_init (C member), 265 PyUnicode_AsUTF32String (C function), 138
PyTypeObject.tp_is_gc (C member), 267 PyUnicode_AsWideChar (C function), 136
PyTypeObject.tp_itemsize (C member), 252 PyUnicode_AsWideCharString (C function),
PyTypeObject.tp_iter (C member), 262 136
PyTypeObject.tp_iternext (C member), 263 PyUnicode_Check (C function), 126
PyTypeObject.tp_members (C member), 263 PyUnicode_CheckExact (C function), 126
PyTypeObject.tp_methods (C member), 263 PyUnicode_Compare (C function), 142
PyTypeObject.tp_mro (C member), 267 PyUnicode_CompareWithASCIIString (C
PyTypeObject.tp_name (C member), 251 function), 142
PyTypeObject.tp_new (C member), 266 PyUnicode_Concat (C function), 141
PyTypeObject.tp_repr (C member), 254 PyUnicode_Contains (C function), 143
PyTypeObject.tp_richcompare (C member), PyUnicode_CopyCharacters (C function), 132
261 PyUnicode_Count (C function), 142
PyTypeObject.tp_richcompare.Py_RETURN_RICHCOMPARE
PyUnicode_DATA (C function), 127
(C macro), 262 PyUnicode_Decode (C function), 137
PyTypeObject.tp_setattr (C member), 253 PyUnicode_DecodeASCII (C function), 140
PyTypeObject.tp_setattro (C member), 256 PyUnicode_DecodeCharmap (C function), 140
PyTypeObject.tp_str (C member), 255 PyUnicode_DecodeFSDefault (C function), 135
PyTypeObject.tp_subclasses (C member), PyUnicode_DecodeFSDefaultAndSize (C
267 function), 135
PyTypeObject.tp_traverse (C member), 260 PyUnicode_DecodeLatin1 (C function), 140
PyTypeObject.tp_vectorcall (C member), PyUnicode_DecodeLocale (C function), 134
269 PyUnicode_DecodeLocaleAndSize (C fun-
PyTypeObject.tp_vectorcall_offset (C ction), 134
member), 253 PyUnicode_DecodeMBCS (C function), 141
PyTypeObject.tp_version_tag (C member), PyUnicode_DecodeMBCSStateful (C function),
268 141
PyTypeObject.tp_weaklist (C member), 268 PyUnicode_DecodeRawUnicodeEscape (C
PyTypeObject.tp_weaklistoffset (C mem- function), 139
ber), 262 PyUnicode_DecodeUnicodeEscape (C fun-
PyTZInfo_Check (C function), 175 ction), 139
PyTZInfo_CheckExact (C function), 175 PyUnicode_DecodeUTF7 (C function), 139
PyUnicode_1BYTE_DATA (C function), 126 PyUnicode_DecodeUTF7Stateful (C function),
PyUnicode_1BYTE_KIND (C macro), 127 139
PyUnicode_2BYTE_DATA (C function), 126 PyUnicode_DecodeUTF8 (C function), 137
PyUnicode_2BYTE_KIND (C macro), 127 PyUnicode_DecodeUTF8Stateful (C function),
PyUnicode_4BYTE_DATA (C function), 126 137
PyUnicode_4BYTE_KIND (C macro), 127 PyUnicode_DecodeUTF16 (C function), 138
PyUnicode_AS_DATA (C function), 128 PyUnicode_DecodeUTF16Stateful (C fun-
PyUnicode_AS_UNICODE (C function), 128 ction), 139
PyUnicode_AsASCIIString (C function), 140 PyUnicode_DecodeUTF32 (C function), 138
PyUnicode_AsCharmapString (C function), 140 PyUnicode_DecodeUTF32Stateful (C fun-
PyUnicode_AsEncodedString (C function), 137 ction), 138
PyUnicode_AsLatin1String (C function), 140 PyUnicode_EncodeCodePage (C function), 141
PyUnicode_AsMBCSString (C function), 141 PyUnicode_EncodeFSDefault (C function), 135
PyUnicode_AsRawUnicodeEscapeString (C PyUnicode_EncodeLocale (C function), 134
function), 139 PyUnicode_Fill (C function), 132
PyUnicode_AsUCS4 (C function), 132 PyUnicode_Find (C function), 142

338 Índice
 The Python/C API, Versión 3.11.0

PyUnicode_FindChar (C function), 142 PyUnicodeDecodeError_SetReason (C fun-

PyUnicode_Format (C function), 143 ction), 59
PyUnicode_FromEncodedObject (C function), PyUnicodeDecodeError_SetStart (C fun-
131 ction), 58
PyUnicode_FromFormat (C function), 130 PyUnicodeEncodeError_GetEncoding (C
PyUnicode_FromFormatV (C function), 131 function), 58
PyUnicode_FromKindAndData (C function), 130 PyUnicodeEncodeError_GetEnd (C function),
PyUnicode_FromObject (C function), 133 58
PyUnicode_FromString (C function), 130 PyUnicodeEncodeError_GetObject (C fun-
PyUnicode_FromString(), 148 ction), 58
PyUnicode_FromStringAndSize (C function), PyUnicodeEncodeError_GetReason (C fun-
130 ction), 58
PyUnicode_FromUnicode (C function), 133 PyUnicodeEncodeError_GetStart (C fun-
PyUnicode_FromWideChar (C function), 136 ction), 58
PyUnicode_FSConverter (C function), 135 PyUnicodeEncodeError_SetEnd (C function),
PyUnicode_FSDecoder (C function), 135 58
PyUnicode_GET_DATA_SIZE (C function), 127 PyUnicodeEncodeError_SetReason (C fun-
PyUnicode_GET_LENGTH (C function), 126 ction), 59
PyUnicode_GET_SIZE (C function), 127 PyUnicodeEncodeError_SetStart (C fun-
PyUnicode_GetLength (C function), 132 ction), 58
PyUnicode_GetSize (C function), 133 PyUnicodeObject (C type), 126
PyUnicode_InternFromString (C function), PyUnicodeTranslateError_GetEnd (C fun-
143 ction), 58
PyUnicode_InternInPlace (C function), 143 PyUnicodeTranslateError_GetObject (C
PyUnicode_IsIdentifier (C function), 128 function), 58
PyUnicode_Join (C function), 142 PyUnicodeTranslateError_GetReason (C
PyUnicode_KIND (C function), 127 function), 58
PyUnicode_MAX_CHAR_VALUE (C function), 127 PyUnicodeTranslateError_GetStart (C
PyUnicode_New (C function), 130 function), 58
PyUnicode_READ (C function), 127 PyUnicodeTranslateError_SetEnd (C fun-
PyUnicode_READ_CHAR (C function), 127 ction), 58
PyUnicode_ReadChar (C function), 132 PyUnicodeTranslateError_SetReason (C
PyUnicode_READY (C function), 126 function), 59
PyUnicode_Replace (C function), 142 PyUnicodeTranslateError_SetStart (C
PyUnicode_RichCompare (C function), 142 function), 58
PyUnicode_Split (C function), 141 PyVarObject (C type), 238
PyUnicode_Splitlines (C function), 142 PyVarObject_HEAD_INIT (C macro), 240
PyUnicode_Substring (C function), 132 PyVarObject.ob_size (C member), 251
PyUnicode_Tailmatch (C function), 142 PyVectorcall_Call (C function), 91
PyUnicode_Translate (C function), 140 PyVectorcall_Function (C function), 91
PyUnicode_Type (C var), 126 PyVectorcall_NARGS (C function), 91
PyUnicode_WCHAR_KIND (C macro), 127 PyWeakref_Check (C function), 168
PyUnicode_WRITE (C function), 127 PyWeakref_CheckProxy (C function), 168
PyUnicode_WriteChar (C function), 132 PyWeakref_CheckRef (C function), 168
PyUnicodeDecodeError_Create (C function), PyWeakref_GET_OBJECT (C function), 168
58 PyWeakref_GetObject (C function), 168
PyUnicodeDecodeError_GetEncoding (C PyWeakref_NewProxy (C function), 168
function), 58 PyWeakref_NewRef (C function), 168
PyUnicodeDecodeError_GetEnd (C function), PyWideStringList (C type), 204
58 PyWideStringList.items (C member), 204
PyUnicodeDecodeError_GetObject (C fun- PyWideStringList.length (C member), 204
ction), 58 PyWideStringList.PyWideStringList_Append
PyUnicodeDecodeError_GetReason (C fun- (C function), 204
ction), 58 PyWideStringList.PyWideStringList_Insert
PyUnicodeDecodeError_GetStart (C fun- (C function), 204
ction), 58 PyWrapper_New (C function), 165
PyUnicodeDecodeError_SetEnd (C function),
58

Índice 339
The Python/C API, Versión 3.11.0

R T
realloc(), 225 ternaryfunc (C type), 276
rebanada, 297 tipado de pato, 289
recolección de basura, 290 tipo, 297
referencia fuerte, 297 tipos genéricos, 290
referencia prestada, 287 traverseproc (C type), 280
releasebufferproc (C type), 276 tupla nombrada, 293
repr tuple
función incorporada, 87, 254 función incorporada, 98, 147
reprfunc (C type), 275 objeto, 143
retrollamada, 287 type
richcmpfunc (C type), 276 función incorporada, 88
ruta de importación, 291 objeto, 7, 111

S U
saltos de líneas universales, 298 ULONG_MAX, 117
sdterr unaryfunc (C type), 276
stdin stdout, 183
search V
path, module, 12, 182, 185 variable de clase, 287
secuencia, 296 variable de contexto, 287
sendfunc (C type), 276 variables de entorno
sentencia, 297 __PYVENV_LAUNCHER__, 211, 216
sequence exec_prefix, 4
objeto, 122 PATH, 12
set prefix, 4
objeto, 150 PYTHON*, 181
set_all(), 9 PYTHONCOERCECLOCALE, 221
setattrfunc (C type), 275 PYTHONDEBUG, 180, 216
setattrofunc (C type), 275 PYTHONDEVMODE, 212
setswitchinterval() (in module sys), 187 PYTHONDONTWRITEBYTECODE, 180, 218
SIGINT, 56 PYTHONDUMPREFS, 212, 251
signal PYTHONEXECUTABLE, 216
módulo, 56 PYTHONFAULTHANDLER, 212
SIZE_MAX, 117 PYTHONHASHSEED, 180, 213
special PYTHONHOME, 12, 181, 187, 213
method, 297 PYTHONINSPECT, 181, 213
ssizeargfunc (C type), 276 PYTHONIOENCODING, 183, 217
ssizeobjargproc (C type), 276 PYTHONLEGACYWINDOWSFSENCODING, 181,
staticmethod 207
función incorporada, 242 PYTHONLEGACYWINDOWSSTDIO, 181, 214
stderr (in module sys), 195 PYTHONMALLOC, 226, 230, 232, 233
stdin PYTHONMALLOCSTATS, 214, 226
stdout sdterr, 183 PYTHONNODEBUGRANGES, 211
stdin (in module sys), 195 PYTHONNOUSERSITE, 181, 218
stdout PYTHONOPTIMIZE, 181, 215
sdterr, stdin, 183 PYTHONPATH, 12, 181, 215
stdout (in module sys), 195 PYTHONPLATLIBDIR, 214
strerror(), 51 PYTHONPROFILEIMPORTTIME, 213
string PYTHONPYCACHEPREFIX, 216
PyObject_Str (C function), 87 PYTHONSAFEPATH, 210
sum_list(), 9 PYTHONTRACEMALLOC, 218
sum_sequence(), 10, 11 PYTHONUNBUFFERED, 182, 211
sys PYTHONUTF8, 207, 221
módulo, 12, 182, 195 PYTHONVERBOSE, 182, 218
SystemError (built-in exception), 158 PYTHONWARNINGS, 218
vectorcallfunc (C type), 90
version (in module sys), 185, 186

340 Índice
 The Python/C API, Versión 3.11.0

visitproc (C type), 280

vista de diccionario, 288

Z
Zen de Python, 298

Índice 341