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

PyObject *Py_GetConstant(unsigned int constant_id)
    * Part of the Stable ABI since version 3.13.*

   Get a *strong reference* to a constant.

   Set an exception and return "NULL" if *constant_id* is invalid.

   *constant_id* must be one of these constant identifiers:

   +------------------------------------------+-------+---------------------------+
   | Constant Identifier                      | Value | Returned object           |
   |==========================================|=======|===========================|
   | Py_CONSTANT_NONE                         | "0"   | "None"                    |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_FALSE                        | "1"   | "False"                   |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_TRUE                         | "2"   | "True"                    |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_ELLIPSIS                     | "3"   | "Ellipsis"                |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_NOT_IMPLEMENTED              | "4"   | "NotImplemented"          |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_ZERO                         | "5"   | "0"                       |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_ONE                          | "6"   | "1"                       |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_EMPTY_STR                    | "7"   | "''"                      |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_EMPTY_BYTES                  | "8"   | "b''"                     |
   +------------------------------------------+-------+---------------------------+
   | Py_CONSTANT_EMPTY_TUPLE                  | "9"   | "()"                      |
   +------------------------------------------+-------+---------------------------+

   Numeric values are only given for projects which cannot use the
   constant identifiers.

   Added in version 3.13.

   **Detalles de implementación de CPython:** In CPython, all of these
   constants are *immortal*.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)
    * Part of the Stable ABI since version 3.13.*

   Similar to "Py_GetConstant()", but return a *borrowed reference*.

   This function is primarily intended for backwards compatibility:
   using "Py_GetConstant()" is recommended for new code.

   The reference is borrowed from the interpreter, and is valid until
   the interpreter finalization.

   Added in version 3.13.

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

   Properly handle returning "Py_NotImplemented" from within a C
   function (that is, create a new *strong reference* to
   "NotImplemented" and return it).

Py_PRINT_RAW

   Flag to be used with multiple functions that print the object (like
   "PyObject_Print()" and "PyFile_WriteObject()"). If passed, these
   function would use the "str()" of the object instead of the
   "repr()".

int PyObject_Print(PyObject *o, FILE *fp, int flags)

   Print an object *o*, on file *fp*.  Returns "-1" on error.  The
   flags argument is used to enable certain printing options.  The
   only option currently supported is "Py_PRINT_RAW"; if given, the
   "str()" of the object is written instead of the "repr()".

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)
    * Part of the Stable ABI since version 3.13.*

   Returns "1" if *o* has the attribute *attr_name*, and "0"
   otherwise. This is equivalent to the Python expression "hasattr(o,
   attr_name)". On failure, return "-1".

   Added in version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)
    * Part of the Stable ABI since version 3.13.*

   This is the same as "PyObject_HasAttrWithError()", but *attr_name*
   is specified as a const char* UTF-8 encoded bytes string, rather
   than a PyObject*.

   Added in version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
    * Part of the Stable ABI.*

   Returns "1" if *o* has the attribute *attr_name*, and "0"
   otherwise. This function always succeeds.

   Nota:

     Exceptions that occur when this calls "__getattr__()" and
     "__getattribute__()" methods aren't propagated, but instead given
     to "sys.unraisablehook()". For proper error handling, use
     "PyObject_HasAttrWithError()", "PyObject_GetOptionalAttr()" or
     "PyObject_GetAttr()" instead.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)
    * Part of the Stable ABI.*

   This is the same as "PyObject_HasAttr()", but *attr_name* is
   specified as a const char* UTF-8 encoded bytes string, rather than
   a PyObject*.

   Nota:

     Exceptions that occur when this calls "__getattr__()" and
     "__getattribute__()" methods or while creating the temporary
     "str" object are silently ignored. For proper error handling, use
     "PyObject_HasAttrStringWithError()",
     "PyObject_GetOptionalAttrString()" or "PyObject_GetAttrString()"
     instead.

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

   If the missing attribute should not be treated as a failure, you
   can use "PyObject_GetOptionalAttr()" instead.

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)
    *Return value: New reference.** Part of the Stable ABI.*

   This is the same as "PyObject_GetAttr()", but *attr_name* is
   specified as a const char* UTF-8 encoded bytes string, rather than
   a PyObject*.

   If the missing attribute should not be treated as a failure, you
   can use "PyObject_GetOptionalAttrString()" instead.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);
    * Part of the Stable ABI since version 3.13.*

   Variant of "PyObject_GetAttr()" which doesn't raise
   "AttributeError" if the attribute is not found.

   If the attribute is found, return "1" and set **result* to a new
   *strong reference* to the attribute. If the attribute is not found,
   return "0" and set **result* to "NULL"; the "AttributeError" is
   silenced. If an error other than "AttributeError" is raised, return
   "-1" and set **result* to "NULL".

   Added in version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);
    * Part of the Stable ABI since version 3.13.*

   This is the same as "PyObject_GetOptionalAttr()", but *attr_name*
   is specified as a const char* UTF-8 encoded bytes string, rather
   than a PyObject*.

   Added in version 3.13.

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
   Implementando descriptores, 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.*

   This is the same as "PyObject_SetAttr()", but *attr_name* is
   specified as a const char* UTF-8 encoded bytes string, rather than
   a PyObject*.

   Si *v* es "NULL", el atributo se elimina, sin embargo, esta
   característica está deprecada en favor de usar
   "PyObject_DelAttrString()".

   The number of different attribute names passed to this function
   should be kept small, usually by using a statically allocated
   string as *attr_name*. For attribute names that aren't known at
   compile time, prefer calling "PyUnicode_FromString()" and
   "PyObject_SetAttr()" directly. For more details, see
   "PyUnicode_InternFromString()", which may be used internally to
   create a key object.

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)
    * Part of the Stable ABI since version 3.13.*

   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)
    * Part of the Stable ABI since version 3.13.*

   This is the same as "PyObject_DelAttr()", but *attr_name* is
   specified as a const char* UTF-8 encoded bytes string, rather than
   a PyObject*.

   The number of different attribute names passed to this function
   should be kept small, usually by using a statically allocated
   string as *attr_name*. For attribute names that aren't known at
   compile time, prefer calling "PyUnicode_FromString()" and
   "PyObject_DelAttr()" directly. For more details, see
   "PyUnicode_InternFromString()", which may be used internally to
   create a key object for lookup.

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.

   Added in version 3.3.

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.

   Added in version 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.*

   Compare the values of *o1* and *o2* using the operation specified
   by *opid*, which must be one of "Py_LT", "Py_LE", "Py_EQ", "Py_NE",
   "Py_GT", or "Py_GE", corresponding to "<", "<=", "==", "!=", ">",
   or ">=" respectively. This is the equivalent of the Python
   expression "o1 op o2", where "op" is the operator corresponding to
   *opid*. Returns the value of the comparison on success, or "NULL"
   on failure.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
    * Part of the Stable ABI.*

   Compare the values of *o1* and *o2* using the operation specified
   by *opid*, like "PyObject_RichCompare()", but returns "-1" on
   error, "0" if the result is false, "1" otherwise.

Nota:

  If *o1* and *o2* are the same object, "PyObject_RichCompareBool()"
  will always return "1" for "Py_EQ" and "0" for "Py_NE".

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)
    * Part of the Stable ABI.*

   Format *obj* using *format_spec*. This is equivalent to the Python
   expression "format(obj, format_spec)".

   *format_spec* may be "NULL". In this case the call is equivalent to
   "format(obj)". Returns the formatted string on success, "NULL" on
   failure.

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

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

   If *cls* has a "__subclasscheck__()" method, it will be called to
   determine the subclass status as described in **PEP 3119**.
   Otherwise, *derived* is a subclass of *cls* if it is a direct or
   indirect subclass, i.e. contained in "cls.__mro__".

   Normally only class objects, i.e. instances of "type" or a derived
   class, are considered classes.  However, objects can override this
   by having a "__bases__" attribute (which must be a tuple of base
   classes).

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

   If *cls* has a "__instancecheck__()" method, it will be called to
   determine the subclass status as described in **PEP 3119**.
   Otherwise, *inst* is an instance of *cls* if its class is a
   subclass of *cls*.

   An instance *inst* can override what is considered its class by
   having a "__class__" attribute.

   An object *cls* can override if it is considered a class, and what
   its base classes are, by having a "__bases__" attribute (which must
   be a tuple of base classes).

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

   Set a "TypeError" indicating that "type(o)" is not *hashable* and
   return "-1". This function receives special treatment when stored
   in a "tp_hash" slot, allowing a type to explicitly indicate to the
   interpreter that it is not 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.*

   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 creates a new *strong reference* to the
   return value. There's really no reason to use this function instead
   of the "Py_TYPE()" function, which returns a pointer of type
   PyTypeObject*, except when a new *strong reference* is needed.

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

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

   Added in version 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]".

int PyObject_DelItemString(PyObject *o, const char *key)
    * Part of the Stable ABI.*

   This is the same as "PyObject_DelItem()", but *key* is specified as
   a const char* UTF-8 encoded bytes string, rather than a PyObject*.

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_SelfIter(PyObject *obj)
    *Return value: New reference.** Part of the Stable ABI.*

   This is equivalent to the Python "__iter__(self): return self"
   method. It is intended for *iterator* types, to be used in the
   "PyTypeObject.tp_iter" slot.

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.

   Added in version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)
    * Part of the Stable ABI since version 3.12.*

   Get a pointer to subclass-specific data reserved for *cls*.

   The object *o* must be an instance of *cls*, and *cls* must have
   been created using negative "PyType_Spec.basicsize". Python does
   not check this.

   On error, set an exception and return "NULL".

   Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)
    * Part of the Stable ABI since version 3.12.*

   Return the size of the instance memory space reserved for *cls*,
   i.e. the size of the memory "PyObject_GetTypeData()" returns.

   This may be larger than requested using "-PyType_Spec.basicsize";
   it is safe to use this larger size (e.g. with "memset()").

   The type *cls* **must** have been created using negative
   "PyType_Spec.basicsize". Python does not check this.

   On error, set an exception and return a negative value.

   Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)

   Get a pointer to per-item data for a class with
   "Py_TPFLAGS_ITEMS_AT_END".

   On error, set an exception and return "NULL". "TypeError" is raised
   if *o* does not have "Py_TPFLAGS_ITEMS_AT_END" set.

   Added in version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)

   Visit the managed dictionary of *obj*.

   This function must only be called in a traverse function of the
   type which has the "Py_TPFLAGS_MANAGED_DICT" flag set.

   Added in version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)

   Clear the managed dictionary of *obj*.

   This function must only be called in a traverse function of the
   type which has the "Py_TPFLAGS_MANAGED_DICT" flag set.

   Added in version 3.13.
