< BACKMake Note | BookmarkCONTINUE >
152015024128143245168232148039196038240039088173205162105045222218073235210198230006105

Abstract Objects Layer

The functions in this section interact with Python objects regardless of their type, or with wide classes of object types (for example, all numerical types, or all sequence types). When used on object types for which they do not apply, they will raise a Python exception.

Object Protocol

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

					

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

					

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

					

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

					

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

					

Deletes 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_Cmp(PyObject *o1, PyObject *o2, int *result)

					

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

					

Compares 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; uses 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. Computes a string representation of object o. Returns the string representation on success, or 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. Computes a string representation of object o. Returns the string representation on success, or 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.

						
int PyCallable_Check(PyObject *o)

					

Determines if the object o is callable. Returns 1 if the object is callable and 0 otherwise. This function always succeeds.

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

					

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

						
PyObject* PyObject_CallFunction(PyObject *callable_object, char
*format,...)

					

Return value: New reference. Calls a callable Python object callable_object, with a variable number of C arguments. The C arguments are described using a Py_BuildValue() style format string. The format might 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(o, args)".

						
PyObject* PyObject_CallMethod(PyObject *o, char *m, char *format, ...)

					

Return value: New reference. Calls the method named m of object o with a variable number of C arguments. The C arguments are described by a Py_BuildValue() format string. The format might 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)". Note that special method names, such as __add__(), __getitem__(), and so on are not supported. The specific abstract-object routines for these must be used.

						
int PyObject_Hash(PyObject *o)

					

Computes and returns the hash value of an object o. On failure, it returns -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". This function always succeeds.

						
PyObject* PyObject_Type(PyObject *o)

					

Return value: New reference. On success, returns a type object corresponding to the object type of object o. On failure, it returns NULL. This is equivalent to the Python expression "type(o)".

						
int PyObject_Length(PyObject *o)

					

Returns the length of object o. If the object o provides both 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. Returns the 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)

					

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

					

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

Number Protocol

						
int PyNumber_Check(PyObject *o)

					

Returns 1 if the object o provides numeric protocols, and false otherwise. This function always succeeds.

						
PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of adding o1 and o2, or NULL on failure. This is the equivalent of the Python expression "o1 + o2".

						
PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of subtracting o2 from o1, or NULL on failure. This is the equivalent of the Python expression "o1 - o2".

						
PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of multiplying o1 and o2, or NULL on failure. This is the equivalent of the Python expression "o1 * o2".

						
PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of dividing o1 by o2, or NULL on failure. This is the equivalent of the Python expression "o1 / o2".

						
PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the remainder of dividing o1 by o2, or NULL on failure. This is the equivalent of the Python expression "o1 % o2".

						
PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)

					

Return value: New reference. See the built-in function divmod(). Returns NULL on failure. This is the equivalent of the Python expression "divmod(o1, o2)".

						
PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)

					

Return value: New reference. See the built-in function pow(). Returns NULL on failure. This is the equivalent of the Python expression "pow(o1, o2, o3)", where o3 is optional. If o3 is to be ignored, pass Py_None in its place (passing NULL for o3 would cause an illegal memory access).

						
PyObject* PyNumber_Negative(PyObject *o)

					

Return value: New reference. Returns the negation of o on success, or NULL on failure. This is the equivalent of the Python expression "-o"

						
PyObject* PyNumber_Positive(PyObject *o)

					

Return value: New reference. Returns o on success, or NULL on failure. This is the equivalent of the Python expression "+o".

						
PyObject* PyNumber_Absolute(PyObject *o)

					

Return value: New reference. Returns the absolute value of o, or NULL on failure. This is the equivalent of the Python expression "abs(o)".

						
PyObject* PyNumber_Invert(PyObject *o)

					

Return value: New reference. Returns the bitwise negation of o on success, or NULL on failure. This is the equivalent of the Python expression "~o".

						
PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of left shifting o1 by o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 << o2".

						
PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of right shifting o1 by o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 >> o2".

						
PyObject* PyNumber_And(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of "anding" o1 and o2 on success and NULL on failure. This is the equivalent of the Python expression "o1 and o2".

						
PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the bitwise exclusive or of o1 by o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 ^ o2".

						
PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the result of o1 and o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 or o2".

						
PyObject* PyNumber_Coerce(PyObject **p1, PyObject **p2)

					

This function takes the addresses of two variables of type PyObject*. If the objects pointed to by *p1 and *p2 have the same type, increment their reference count and return 0 (success). If the objects can be converted to a common numeric type, replace *p1 and *p2 by their converted value (with new reference counts), and return 0. If no conversion is possible, or if some other error occurs, return -1 (failure) and don't increment the reference counts. The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python statement "o1, o2 = coerce(o1, o2)".

						
PyObject* PyNumber_Int(PyObject *o)

					

Return value: New reference. Returns the o converted to an integer object on success, or NULL on failure. This is the equivalent of the Python expression "int(o)".

						
PyObject* PyNumber_Long(PyObject *o)

					

Return value: New reference. Returns the o converted to a long integer object on success, or NULL on failure. This is the equivalent of the Python expression "long(o)".

						
PyObject* PyNumber_Float(PyObject *o)

					

Return value: New reference. Returns the o converted to a float object on success, or NULL on failure. This is the equivalent of the Python expression "float(o)".

Sequence Protocol

						
int PySequence_Check(PyObject *o)

					

Returns 1 if the object provides sequence protocol, and 0 otherwise. This function always succeeds.

						
int PySequence_Length(PyObject *o)

					

Returns the number of objects in sequence; o on success, and -1 on failure. For objects that do not provide sequence protocol, this is equivalent to the Python expression "len(o)".

						
PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)

					

Return value: New reference. Returns the concatenation of o1 and o2 on success, and NULL on failure. This is the equivalent of the Python expression "o1 + o2".

						
PyObject* PySequence_Repeat(PyObject *o, int count)

					

Return value: New reference. Returns the result of repeating sequence object o count times, or NULL on failure. This is the equivalent of the Python expression "o * count".

						
PyObject* PySequence_GetItem(PyObject *o, int i)

					

Return value: New reference. Returns the ith element of o, or NULL on failure. This is the equivalent of the Python expression "o[i]".

						
PyObject* PySequence_GetSlice(PyObject *o, int i1, int i2)

					

Return value: New reference. Returns the slice of sequence object o between i1 and i2, or NULL on failure. This is the equivalent of the Python expression "o[i1:i2]".

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

					

Assigns object v to the ith element of o. Returns -1 on failure. This is the equivalent of the Python statement "o[i] = v".

						
int PySequence_DelItem(PyObject *o, int i)

					

Deletes the ith element of object v. Returns -1 on failure. This is the equivalent of the Python statement "del o[i]".

						
int PySequence_SetSlice(PyObject *o, int i1, int i2, PyObject *v)

					

Assigns the sequence object v to the slice in sequence object o from i1 to i2. This is the equivalent of the Python statement "o[i1:i2] = v".

						
int PySequence_DelSlice(PyObject *o, int i1, int i2)

					

Deletes the slice in sequence object o from i1 to i2. Returns -1 on failure. This is the equivalent of the Python statement "del o[i1:i2]".

						
PyObject* PySequence_Tuple(PyObject *o)

					

Return value: New reference. Returns the o as a tuple on success, and NULL on failure. This is equivalent to the Python expression "tuple(o)".

						
int PySequence_Count(PyObject *o, PyObject *value)

					

Returns the number of occurrences of value in o; that is, returns the number of keys for which o[key] == value. On failure, returns -1. This is equivalent to the Python expression "o.count(value)".

						
int PySequence_Contains(PyObject *o, PyObject *value)

					

Determines if o contains value. If an item in o is equal to value, returns 1, otherwise returns 0. On error, returns -1. This is equivalent to the Python expression "value in o".

						
int PySequence_Index(PyObject *o, PyObject *value)

					

Returns the first index i for which o[i] == value. On error, returns -1. This is equivalent to the Python expression "o.index(value)".

Mapping Protocol

						
int PyMapping_Check(PyObject *o)

					

Returns 1 if the object provides mapping protocol, and 0 otherwise. This function always succeeds.

						
int PyMapping_Length(PyObject *o)

					

Returns the number of keys in object o on success, and -1 on failure. For objects that do not provide mapping protocol, this is equivalent to the Python expression "len(o)".

						
int PyMapping_DelItemString(PyObject *o, char *key)

					

Removes the mapping for object key from the object o. Returns -1 on failure. This is equivalent to the Python statement "del o[key]".

						
int PyMapping_DelItem(PyObject *o, PyObject *key)

					

Removes the mapping for object key from the object o. Returns -1 on failure. This is equivalent to the Python statement "del o[key]".

						
int PyMapping_HasKeyString(PyObject *o, char *key)

					

On success, returns 1 if the mapping object has the key identified by the key pointer, and 0 otherwise. This is equivalent to the Python expression "o.has_key(key)". This function always succeeds.

						
int PyMapping_HasKey(PyObject *o, PyObject *key)

					

Returns 1 if the mapping object has the key identified by the key pointer and 0 otherwise. This is equivalent to the Python expression "o.has_key(key)". This function always succeeds.

						
PyObject* PyMapping_Keys(PyObject *o)

					

Return value: New reference. On success, returns a list of the keys in object o. On failure, returns NULL. This is equivalent to the Python expression "o.keys()".

						
PyObject* PyMapping_Values(PyObject *o)

					

Return value: New reference. On success, returns a list of the values in object o. On failure, returns NULL. This is equivalent to the Python expression "o.values()".

						
PyObject* PyMapping_Items(PyObject *o)

					

Return value: New reference. On success, returns a list of the items in object o, where each item is a tuple containing a key-value pair. On failure, returns NULL. This is equivalent to the Python expression "o.items()".

						
PyObject* PyMapping_GetItemString(PyObject *o, char *key)

					

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

						
int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)

					

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


Last updated on 1/30/2002
Python Developer's Handbook, © 2002 Sams Publishing

< BACKMake Note | BookmarkCONTINUE >

Index terms contained in this section

Abstract Objects Layer, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th
Application Programmers Interface (API)
     Python/C
            Abstract Objects Layer 2nd 3rd 4th 5th
functions
      object interactions 2nd 3rd 4th 5th 6th 7th 8th
     protocols
            mapping
            number 2nd 3rd 4th
            object
            sequence 2nd
interactions
      objects, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th
interfaces
     Python/C Application Programmers (API)
            Abstract Objects Layer 2nd 3rd 4th 5th
layers
      Abstract Objects, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th
mapping protocol
number protocol 2nd 3rd 4th
object protocol
objects
      interactions with, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th
protocols
      mapping
      number 2nd 3rd 4th
      object
      sequence 2nd
Python/C Application Programmers Interface (API)
      Abstract Objects Layer 2nd 3rd 4th 5th
sequence protocol 2nd

© 2002, O'Reilly & Associates, Inc.