6.1 Object Protocol
Description: Object Protocol
Keywords: api

#
6.1 Object Protocol

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_HasAttrString`( | PyObject *o, char *attr_name)

  Returns `1` if o has the attribute attr_name, and `0` otherwise. This is equivalent to the Python expression "`hasattr(o, attr_name)`". This function always succeeds.

PyObject* `PyObject_GetAttrString`( | PyObject *o, char *attr_name)

  Return value: New reference.
  Retrieve an attribute named attr_name from object o. Returns the attribute value on success, or `NULL` on failure. This is the equivalent of the Python expression "`o.attr_name`".

int `PyObject_HasAttr`( | PyObject *o, PyObject *attr_name)

  Returns `1` if o has the attribute attr_name, and `0` otherwise. This is equivalent to the Python expression "`hasattr(o, attr_name)`". This function always succeeds.

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

  Return value: New reference.
  Retrieve an attribute named attr_name from object o. Returns the attribute value on success, or `NULL` on failure. This is the equivalent of the Python expression "`o.attr_name`".

int `PyObject_SetAttrString`( | PyObject *o, char *attr_name, PyObject *v)

  Set the value of the attribute named attr_name, for object o, to the value v. Returns `-1` on failure. This is the equivalent of the Python statement "`o.attr_name = v`".

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

  Set the value of the attribute named attr_name, for object o, to the value v. Returns `-1` on failure. This is the equivalent of the Python statement "`o.attr_name = v`".

int `PyObject_DelAttrString`( | PyObject *o, char *attr_name)

  Delete attribute named attr_name, for object o. Returns `-1` on failure. This is the equivalent of the Python statement: "`del o.attr_name`".

int `PyObject_DelAttr`( | PyObject *o, PyObject *attr_name)

  Delete attribute named attr_name, for object o. Returns `-1` on failure. This is the equivalent of the Python statement "`del o.attr_name`".

PyObject* `PyObject_RichCompare`( | PyObject *o1, PyObject *o2, int opid)

  Return value: New reference.
  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)

  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. Returns `-1` on error, `0` if the result is false, `1` otherwise. This is the equivalent of the Python expression "`o1 op o2`", where `op` is the operator corresponding to opid.

int `PyObject_Cmp`( | PyObject *o1, PyObject *o2, int *result)

  Compare the values of o1 and o2 using a routine provided by o1, if one exists, otherwise with a routine provided by o2. The result of the comparison is returned in result. Returns `-1` on failure. This is the equivalent of the Python statement "`result = cmp(o1, o2)`".

int `PyObject_Compare`( | PyObject *o1, PyObject *o2)

  Compare the values of o1 and o2 using a routine provided by o1, if one exists, otherwise with a routine provided by o2. Returns the result of the comparison on success. On error, the value returned is undefined; use `PyErr_Occurred()` to detect an error. This is equivalent to the Python expression "`cmp(o1, o2)`".

PyObject* `PyObject_Repr`( | PyObject *o)

  Return value: New reference.
  Compute a string representation of object o. Returns the string representation on success, `NULL` on failure. This is the equivalent of the Python expression "`repr(o)`". Called by the `repr()` built-in function and by reverse quotes.

PyObject* `PyObject_Str`( | PyObject *o)

  Return value: New reference.
  Compute a string representation of object o. Returns the string representation on success, `NULL` on failure. This is the equivalent of the Python expression "`str(o)`". Called by the `str()` built-in function and by the `print` statement.

PyObject* `PyObject_Unicode`( | PyObject *o)

  Return value: New reference.
  Compute a Unicode string representation of object o. Returns the Unicode string representation on success, `NULL` on failure. This is the equivalent of the Python expression "`unicode(o)`". Called by the `unicode()` built-in function.

int `PyObject_IsInstance`( | PyObject *inst, PyObject *cls)

  Returns `1` if inst is an instance of the class cls or a subclass of cls, or `0` if not. On error, returns `-1` and sets an exception. If cls is a type object rather than a class object, `PyObject_IsInstance()` returns `1` if inst is of type cls. If cls is a tuple, the check will be done against every entry in cls. The result will be `1` when at least one of the checks returns `1`, otherwise it will be `0`. If inst is not a class instance and cls is neither a type object, nor a class object, nor a tuple, inst must have a `__class__` attribute -- the class relationship of the value of that attribute with cls will be used to determine the result of this function. New in version 2.1. Changed in version 2.2: Support for a tuple as the second argument added.

Subclass determination is done in a fairly straightforward way, but includes a wrinkle that implementors of extensions to the class system may want to be aware of. If `A` and `B` are class objects, `B` is a subclass of `A` if it inherits from `A` either directly or indirectly. If either is not a class object, a more general mechanism is used to determine the class relationship of the two objects. When testing if B is a subclass of A, if A is B, `PyObject_IsSubclass()` returns true. If A and B are different objects, B's `__bases__` attribute is searched in a depth-first fashion for A -- the presence of the `__bases__` attribute is considered sufficient for this determination.

int `PyObject_IsSubclass`( | PyObject *derived, PyObject *cls)

  Returns `1` if the class derived is identical to or derived from the class cls, otherwise returns `0`. In case of an error, returns `-1`. If cls is a tuple, the check will be done against every entry in cls. The result will be `1` when at least one of the checks returns `1`, otherwise it will be `0`. If either derived or cls is not an actual class object (or tuple), this function uses the generic algorithm described above. New in version 2.1. Changed in version 2.3: Older versions of Python did not support a tuple as the second argument.

int `PyCallable_Check`( | PyObject *o)

  Determine if the object o is callable. Return `1` if the object is callable and `0` otherwise. This function always succeeds.

PyObject* `PyObject_Call`( | PyObject *callable_object, PyObject *args, PyObject *kw)

  Call a callable Python object callable_object, with arguments given by the tuple args, and named arguments given by the dictionary kw. If no named arguments are needed, kw may be `NULL`. args must not be `NULL`, use an empty tuple if no arguments are needed. Returns the result of the call on success, or `NULL` on failure. This is the equivalent of the Python expression "`apply(callable_object, args, kw)`" or "`callable_object(*args, **kw)`". New in version 2.2.

PyObject* `PyObject_CallObject`( | PyObject *callable_object, PyObject *args)

  Return value: New reference.
  Call a callable Python object callable_object, with arguments given by the tuple args. If no arguments are needed, then args may be `NULL`. Returns the result of the call on success, or `NULL` on failure. This is the equivalent of the Python expression "`apply(callable_object, args)`" or "`callable_object(*args)`".

PyObject* `PyObject_CallFunction`( | PyObject *callable, char *format, ...)

  Return value: New reference.
  Call a callable Python object callable, with a variable number of C arguments. The C arguments are described using a `Py_BuildValue()` style format string. The format may be `NULL`, indicating that no arguments are provided. Returns the result of the call on success, or `NULL` on failure. This is the equivalent of the Python expression "`apply(callable, args)`" or "`callable(*args)`".

PyObject* `PyObject_CallMethod`( | PyObject *o, char *method, char *format, ...)

  Return value: New reference.
  Call the method named method of object o with a variable number of C arguments. The C arguments are described by a `Py_BuildValue()` format string. The format may be `NULL`, indicating that no arguments are provided. Returns the result of the call on success, or `NULL` on failure. This is the equivalent of the Python expression "`o.method(args)`".

PyObject* `PyObject_CallFunctionObjArgs`( | PyObject *callable, ..., `NULL`)

  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`. Returns the result of the call on success, or `NULL` on failure. New in version 2.2.

PyObject* `PyObject_CallMethodObjArgs`( | PyObject *o, PyObject *name, ..., `NULL`)

  Return value: New reference.
  Calls a method of the object o, 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`. Returns the result of the call on success, or `NULL` on failure. New in version 2.2.

int `PyObject_Hash`( | PyObject *o)

  Compute and return the hash value of an object o. On failure, return `-1`. This is the equivalent of the Python expression "`hash(o)`".

int `PyObject_IsTrue`( | PyObject *o)

  Returns `1` if the object o is considered to be true, and `0` otherwise. This is equivalent to the Python expression "`not not o`". On failure, return `-1`.

int `PyObject_Not`( | PyObject *o)

  Returns `0` if the object o is considered to be true, and `1` otherwise. This is equivalent to the Python expression "`not o`". On failure, return `-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)

  Return true if the object o is of type type or a subtype of type. Both parameters must be non-`NULL`. New in version 2.2.

int `PyObject_Length`( | PyObject *o)

int `PyObject_Size`( | PyObject *o)

  Return the length of object o. If the object o provides either the sequence and mapping protocols, the sequence length is returned. On error, `-1` is returned. This is the equivalent to the Python expression "`len(o)`".

PyObject* `PyObject_GetItem`( | PyObject *o, PyObject *key)

  Return value: New reference.
  Return element of o corresponding to the object key or `NULL` on failure. This is the equivalent of the Python expression "`o[key]`".

int `PyObject_SetItem`( | PyObject *o, PyObject *key, PyObject *v)

  Map the object key to the value v. Returns `-1` on failure. This is the equivalent of the Python statement "`o[key] = v`".

int `PyObject_DelItem`( | PyObject *o, PyObject *key)

  Delete the mapping for key from o. Returns `-1` on failure. This is the equivalent of the Python statement "`del o[key]`".

int `PyObject_AsFileDescriptor`( | PyObject *o)

  Derives a file-descriptor from a Python object. If the object is an integer or long integer, its value is returned. If not, the object's `fileno()` method is called if it exists; the method must return an integer or long integer, which is returned as the file descriptor value. Returns `-1` on failure.

PyObject* `PyObject_Dir`( | PyObject *o)

  Return value: New reference.
  This is equivalent to the Python expression "`dir(o)`", returning a (possibly empty) list of strings appropriate for the object argument, or `NULL` if there was an error. If the argument is `NULL`, this is like the Python "`dir()`", returning the names of the current locals; in this case, if no execution frame is active then `NULL` is returned but `PyErr_Occurred()` will return false.

PyObject* `PyObject_GetIter`( | PyObject *o)

  Return value: New reference.
  This is equivalent to the Python expression "`iter(o)`". It returns a new iterator for the object argument, or the object itself if the object is already an iterator. Raises `TypeError` and returns `NULL` if the object cannot be iterated.