Protocolo de objeto
*******************

PyObject* Py_NotImplemented

   El singleton "NotImplemented", se usa para indicar que una
   operación no está implementada para la combinació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)

   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)

   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 informes de errores,
   utilice "PyObject_GetAttrString()" en su lugar.

PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
    *Return value: New reference.*

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

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

   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
   Implementing 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
   genera un "AttributeError".

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

   Establece el valor del atributo llamado *attr_name*, para el objeto
   *o*, en el valor *v*. Genera 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á obsoleta a favor de usar "PyObject_DelAttr()".

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

   Establece el valor del atributo llamado *attr_name*, para el objeto
   *o*, en el valor *v*. Genera 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á obsoleta a favor de usar
   "PyObject_DelAttrString()".

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

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

   Una implementación genérica para obtener un descriptor "__dict__".
   Crea el diccionario si es necesario.

   Nuevo en la versión 3.3.

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

   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_RichCompare(PyObject *o1, PyObject *o2, int opid)
    *Return value: New reference.*

   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)

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

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

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

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

   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)

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

   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)

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

int PyCallable_Check(PyObject *o)

   Determina si el objeto *o* es invocable. Retorna "1" si el objeto
   es invocable y "0" de lo contrario. Esta función siempre tiene
   éxito.

PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
    *Return value: New reference.*

   Llama un objeto Python invocable *invocable*, 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 genera 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_CallObject(PyObject *callable, PyObject *args)
    *Return value: New reference.*

   Llama un objeto Python invocable *invocable*, 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 genera 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.*

   Llama un objeto Python invocable *invocable*, con un número
   variable de argumentos C. Los argumentos de C se describen
   utilizando 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 genera 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 alternative.

   Distinto en la versión 3.4: El tipo de *format* se cambió de "char
   *".

PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
    *Return value: New reference.*

   Llama al método llamado *nombre* del objeto *obj* con un número
   variable de argumentos C. Los argumentos de C se describen mediante
   una cadena de caracteres 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 genera 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 de "char *".

PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
    *Return value: New reference.*

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

   Calls 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 genera una
   excepción y retorna "NULL" en caso de error.

PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

   Llama un objeto Python invocable *invocable*, utilizando
   "vectorcall" si es posible.

   *args* es una arreglo en C con los argumentos posicionales.

   *nargsf* es el número de argumentos posicionales más,
   opcionalmente, el indicador "PY_VECTORCALL_ARGUMENTS_OFFSET" (ver
   más abajo). Para obtener el número real de argumentos, use
   "PyVectorcall_NARGS(nargsf)".

   *kwnames* puede ser "NULL" (sin argumentos de palabras clave) o una
   tupla de nombres de palabras clave. En el último caso, los valores
   de los argumentos de palabras clave se almacenan en *args* después
   de los argumentos posicionales. El número de argumentos de palabras
   clave no influye en *nargsf*.

   *kwnames* debe contener solo objetos de tipo "str" (no una
   subclase), y todas las claves deben ser únicas.

   Retorna el resultado de la llamada en caso de éxito o genera una
   excepción y retorna "NULL" en caso de error.

   Esto usa el protocolo *vectorcall* si el invocable lo admite; de lo
   contrario, los argumentos se convierten para usar "tp_call".

   Nota:

     Esta función es provisional y se espera que se haga pública en
     Python 3.9, con un nombre diferente y, posiblemente, una
     semántica cambiada. Si usa la función, planifique actualizar su
     código para Python 3.9.

   Nuevo en la versión 3.8.

PY_VECTORCALL_ARGUMENTS_OFFSET

   Si se establece en un argumento *vectorcall* *nargsf*, la persona
   que llama puede cambiar temporalmente "args[-1]". En otras
   palabras, *args* apunta al argumento 1 (no 0) en el vector
   asignado. La persona que llama debe restaurar el valor de
   "args[-1]" antes de retornar.

   Siempre que puedan hacerlo a bajo costo (sin asignación adicional),
   se recomienda a las personas que llaman que utilicen
   "PY_VECTORCALL_ARGUMENTS_OFFSET". Hacerlo permitirá que los
   invocables, como los métodos enlazados, realicen sus llamadas
   posteriores (que incluyen un argumento *self* antepuesto) a bajo
   precio.

   Nuevo en la versión 3.8.

Py_ssize_t PyVectorcall_NARGS(size_t nargsf)

   Dado un argumento *vectorcall* *nargsf*, retorna el número real de
   argumentos. Actualmente equivalente a "nargsf &
   ~PY_VECTORCALL_ARGUMENTS_OFFSET".

   Nuevo en la versión 3.8.

PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

   Igual que "_PyObject_Vectorcall()" excepto que los argumentos de
   palabras clave se pasan como un diccionario en *kwdict*. Esto puede
   ser "NULL" si no hay argumentos de palabras clave.

   Para llamadas que admiten "vectorcall", los argumentos se
   convierten internamente a la convención *vectorcall*. Por lo tanto,
   esta función agrega algunos gastos generales en comparación con
   "_PyObject_Vectorcall()". Solo debe usarse si la persona que llama
   ya tiene un diccionario listo para usar.

   Nota:

     Esta función es provisional y se espera que se haga pública en
     Python 3.9, con un nombre diferente y, posiblemente, una
     semántica cambiada. Si usa la función, planifique actualizar su
     código para Python 3.9.

   Nuevo en la versión 3.8.

Py_hash_t PyObject_Hash(PyObject *o)

   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)

   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)

   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)

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

   When *o* is non-"NULL", returns a type object corresponding to the
   object type of object *o*. On failure, raises "SystemError" and
   returns "NULL".  This is equivalent to the Python expression
   "type(o)". This function increments the reference count of the
   return value. There's really no reason to use this function instead
   of the common expression "o->ob_type", which returns a pointer of
   type "PyTypeObject*", except when the incremented reference count
   is needed.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

   Retorna verdadero si el objeto *o* es de tipo *type* o un subtipo
   de *type*. Ambos parámetros no deben ser "NULL".

Py_ssize_t PyObject_Size(PyObject *o)
Py_ssize_t PyObject_Length(PyObject *o)

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

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)

   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, default)".

   Nuevo en la versión 3.4.

PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
    *Return value: New reference.*

   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)

   Asigna el objeto *key* al valor *v*. Genera 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)

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

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

   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.
