Manejo de excepciones
*********************

The functions described in this chapter will let you handle and raise
Python exceptions.  It is important to understand some of the basics
of Python exception handling.  It works somewhat like the POSIX
"errno" variable: there is a global indicator (per thread) of the last
error that occurred.  Most C API functions don't clear this on
success, but will set it to indicate the cause of the error on
failure.  Most C API functions also return an error indicator, usually
"NULL" if they are supposed to return a pointer, or "-1" if they
return an integer (exception: the "PyArg_*" functions return "1" for
success and "0" for failure).

Concretamente, el indicador de error consta de tres punteros de
objeto: el tipo de excepción, el valor de la excepció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).


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

   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.


Lanzando excepciones
====================

Estas funciones lo ayudan a configurar el indicador de error del hilo
actual. Por conveniencia, algunas de estas funciones 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.*

   This is the most common way to set the error indicator.  The first
   argument specifies the exception type; it is normally one of the
   standard exceptions, e.g. "PyExc_RuntimeError".  You need not
   create a new *strong reference* to it (e.g. with "Py_INCREF()").
   The second argument is an error message; it is decoded from
   "'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.

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 comportamiento 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.*

   This is a convenience function to raise "WindowsError". If called
   with *ierr* of "0", the error code returned by a call to
   "GetLastError()" is used instead.  It calls the Win32 function
   "FormatMessage()" to retrieve the Windows description of error code
   given by *ierr* or "GetLastError()", then it constructs a tuple
   object whose first item is the *ierr* value and whose second item
   is the corresponding error message (gotten from "FormatMessage()"),
   and then calls "PyErr_SetObject(PyExc_WindowsError, object)". This
   function always returns "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 especifica el tipo de excepción que se
   lanzará.

   Disponibilidad: Windows.

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

   Like "PyErr_SyntaxLocationEx()", but the *col_offset* parameter is
   omitted.

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 Python/C API) con un argumento
   ilegal. Es principalmente para uso interno.


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 subclase 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)

   Issue a warning message with explicit control over all warning
   attributes.  This is a straightforward wrapper around the Python
   function "warnings.warn_explicit()"; see there for more
   information.  The *module* and *registry* arguments may be set to
   "NULL" to get the default effect described there.

   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.


Consultando el indicador de error
=================================

PyObject *PyErr_Occurred()
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   Test whether the error indicator is set.  If set, return the
   exception *type* (the first argument to the last call to one of the
   "PyErr_Set*" functions or to "PyErr_Restore()").  If not set,
   return "NULL".  You do not own a reference to the return value, so
   you do not need to "Py_DECREF()" it.

   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 acceso 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.*

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

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)
    * Part of the Stable ABI.*

   Bajo ciertas circunstancias, los valores retornados por
   "PyErr_Fetch()" a continuació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);
        }

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
    * Part of the Stable ABI since version 3.7.*

   Recupere 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 se planteó 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.

   Nota:

     Esta función normalmente no es utilizada por el código que quiere
     manejar excepciones. En cambio, 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.*

   Establezca 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 se planteó recientemente. Esta
   función roba las referencias de los argumentos. Para borrar el
   estado de excepción, pase "NULL" para los tres argumentos. Para ver
   las reglas generales sobre los tres argumentos, consulte
   "PyErr_Restore()".

   Nota:

     Esta función normalmente no es utilizada por el código que quiere
     manejar excepciones. En cambio, 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.


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" inmediatamente (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.

   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.


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 argumento *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.


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

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.


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 atributos *encoding*,
   *object*, *length*, *start*, *end* y *reason*. *encoding* y
   *reason* son cadenas codificadas UTF-8.

PyObject *PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
    *Return value: New reference.*

   Crea un objeto "UnicodeEncodeError" con los atributos *encoding*,
   *object*, *length*, *start*, *end* y *reason*. *encoding* y
   *reason* son cadenas codificadas UTF-8.

   Obsoleto desde la versión 3.3: 3.11"Py_UNICODE" está obsoleto desde
   Python 3.3. Migre por favor a
   "PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)".

PyObject *PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
    *Return value: New reference.*

   Crea un objeto "UnicodeTranslateError" con los atributos
   *encoding*, *object*, *length*, *start*, *end* y *reason*.
   *encoding* y *reason* son cadenas codificadas UTF-8.

   Obsoleto desde la versión 3.3: 3.11"Py_UNICODE" está obsoleto desde
   Python 3.3. Migre por favor a
   "PyObject_CallFunction(PyExc_UnicodeTranslateError, "sOnns", ...)".

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


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


Excepciones Estándar
====================

All standard Python exceptions are available as global variables whose
names are "PyExc_" followed by the Python exception name.  These have
the type "PyObject*"; they are all class objects.  For completeness,
here are all the variables:

+-------------------------------------------+-----------------------------------+------------+
| Nombre en C                               | Nombre en Python                  | Notas      |
|===========================================|===================================|============|
| "PyExc_BaseException"                     | "BaseException"                   | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_Exception"                         | "Exception"                       | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ArithmeticError"                   | "ArithmeticError"                 | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "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"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_LookupError"                       | "LookupError"                     | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_MemoryError"                       | "MemoryError"                     |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_ModuleNotFoundError"               | "ModuleNotFoundError"             |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_NameError"                         | "NameError"                       |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_NotADirectoryError"                | "NotADirectoryError"              |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_NotImplementedError"               | "NotImplementedError"             |            |
+-------------------------------------------+-----------------------------------+------------+
| "PyExc_OSError"                           | "OSError"                         | [1]        |
+-------------------------------------------+-----------------------------------+------------+
| "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"               |            |
+-------------------------------------------+-----------------------------------+------------+
| "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"                       |            |
+---------------------------------------+------------+
| "PyExc_WindowsError"                  | [2]        |
+---------------------------------------+------------+

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

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.


Categorías de advertencia estándar
==================================

All standard Python warning categories are available as global
variables whose names are "PyExc_" followed by the Python exception
name. These have the type "PyObject*"; they are all class objects. For
completeness, here are all the variables:

+--------------------------------------------+-----------------------------------+------------+
| Nombre en C                                | Nombre en Python                  | Notas      |
|============================================|===================================|============|
| "PyExc_Warning"                            | "Warning"                         | [3]        |
+--------------------------------------------+-----------------------------------+------------+
| "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:

[3] Esta es una clase base para otras categorías de advertencia
    estándar.
