This is Info file /home/pdm/tmp/Python-1.5.2p1/Doc/api/python-api.info, produced by Makeinfo version 1.68 from the input file api.texi. July 6, 1999 1.5.2  File: python-api.info, Node: Object Protocol, Next: Number Protocol, Prev: Abstract Objects Layer, Up: Abstract Objects Layer 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'. `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)' 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)' 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'. `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)' Compute the 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)' Compute the 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. `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_CallObject(PyObject *callable_object, PyObject *args)' 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(O, ARGS)'. `PyObject* PyObject_CallFunction(PyObject *callable_object, char *format, ...)' Call 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 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(O, ARGS)'. `PyObject* PyObject_CallMethod(PyObject *o, char *m, char *format, ...)' Call 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 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)'. 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)' 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'. This function always succeeds. `PyObject* PyObject_Type(PyObject *o)' On success, returns a type object corresponding to the object type of object O. On failure, returns `NULL'. This is equivalent to the Python expression `type(O)'. `int PyObject_Length(PyObject *o)' Return 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 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]'.  File: python-api.info, Node: Number Protocol, Next: Sequence Protocol, Prev: Object Protocol, Up: Abstract Objects Layer 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)' 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)' 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)' 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)' 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)' 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)' 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)' 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. `PyObject* PyNumber_Negative(PyObject *o)' 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)' Returns O on success, or `NULL' on failure. This is the equivalent of the Python expression `+O'. `PyObject* PyNumber_Absolute(PyObject *o)' 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)' 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)' 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)' 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)' Returns the result of "anding" O2 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)' 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)' 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)' 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)' 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)' Returns the O converted to a float object on success, or `NULL' on failure. This is the equivalent of the Python expression `float(O)'.  File: python-api.info, Node: Sequence Protocol, Next: Mapping Protocol, Prev: Number Protocol, Up: Abstract Objects Layer Sequence Protocol ================= `int PySequence_Check(PyObject *o)' Return `1' if the object provides sequence protocol, and `0' otherwise. This function always succeeds. `PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)' Return 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 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 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 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)' Assign 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)' Delete 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)' Assign 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)' Delete 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)' 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)' Return the number of occurrences of VALUE in O, that is, return the number of keys for which `O[KEY] == VALUE'. On failure, return `-1'. This is equivalent to the Python expression `O.count(VALUE)'. `int PySequence_In(PyObject *o, PyObject *value)' Determine if O contains VALUE. If an item in O is equal to VALUE, return `1', otherwise return `0'. On error, return `-1'. This is equivalent to the Python expression `VALUE in O'. `int PySequence_Index(PyObject *o, PyObject *value)' Return the first index I for which `O[I] == VALUE'. On error, return `-1'. This is equivalent to the Python expression `O.index(VALUE)'.  File: python-api.info, Node: Mapping Protocol, Next: Constructors, Prev: Sequence Protocol, Up: Abstract Objects Layer Mapping Protocol ================ `int PyMapping_Check(PyObject *o)' Return `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 sequence protocol, this is equivalent to the Python expression `len(O)'. `int PyMapping_DelItemString(PyObject *o, char *key)' Remove the mapping for object KEY from the object O. Return `-1' on failure. This is equivalent to the Python statement `del O[KEY]'. `int PyMapping_DelItem(PyObject *o, PyObject *key)' Remove the mapping for object KEY from the object O. Return `-1' on failure. This is equivalent to the Python statement `del O[KEY]'. `int PyMapping_HasKeyString(PyObject *o, char *key)' On success, return `1' if the mapping object has the key KEY 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)' Return `1' if the mapping object has the key KEY and `0' otherwise. This is equivalent to the Python expression `O.has_key(KEY)'. This function always succeeds. `PyObject* PyMapping_Keys(PyObject *o)' On success, return a list of the keys in object O. On failure, return `NULL'. This is equivalent to the Python expression `O.keys()'. `PyObject* PyMapping_Values(PyObject *o)' On success, return a list of the values in object O. On failure, return `NULL'. This is equivalent to the Python expression `O.values()'. `PyObject* PyMapping_Items(PyObject *o)' On success, return a list of the items in object O, where each item is a tuple containing a key-value pair. On failure, return `NULL'. This is equivalent to the Python expression `O.items()'. `int PyMapping_Clear(PyObject *o)' Make object O empty. Returns `1' on success and `0' on failure. This is equivalent to the Python statement `for key in O.keys(): del O[key]'. `PyObject* PyMapping_GetItemString(PyObject *o, char *key)' Return 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)' Map 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'.  File: python-api.info, Node: Constructors, Prev: Mapping Protocol, Up: Abstract Objects Layer Constructors ============ `PyObject* PyFile_FromString(char *file_name, char *mode)' On success, returns a new file object that is opened on the file given by FILE_NAME, with a file mode given by MODE, where MODE has the same semantics as the standard C routine `fopen()'. On failure, return `-1'. `PyObject* PyFile_FromFile(FILE *fp, char *file_name, char *mode, int close_on_del)' Return a new file object for an already opened standard C file pointer, FP. A file name, FILE_NAME, and open mode, MODE, must be provided as well as a flag, CLOSE_ON_DEL, that indicates whether the file is to be closed when the file object is destroyed. On failure, return `-1'. `PyObject* PyFloat_FromDouble(double v)' Returns a new float object with the value V on success, and `NULL' on failure. `PyObject* PyInt_FromLong(long v)' Returns a new int object with the value V on success, and `NULL' on failure. `PyObject* PyList_New(int len)' Returns a new list of length LEN on success, and `NULL' on failure. `PyObject* PyLong_FromLong(long v)' Returns a new long object with the value V on success, and `NULL' on failure. `PyObject* PyLong_FromDouble(double v)' Returns a new long object with the value V on success, and `NULL' on failure. `PyObject* PyDict_New()' Returns a new empty dictionary on success, and `NULL' on failure. `PyObject* PyString_FromString(char *v)' Returns a new string object with the value V on success, and `NULL' on failure. `PyObject* PyString_FromStringAndSize(char *v, int len)' Returns a new string object with the value V and length LEN on success, and `NULL' on failure. If V is `NULL', the contents of the string are uninitialized. `PyObject* PyTuple_New(int len)' Returns a new tuple of length LEN on success, and `NULL' on failure.  File: python-api.info, Node: Concrete Objects Layer, Next: Initialization, Prev: Abstract Objects Layer, Up: Top Concrete Objects Layer ********************** The functions in this chapter are specific to certain Python object types. Passing them an object of the wrong type is not a good idea; if you receive an object from a Python program and you are not sure that it has the right type, you must perform a type check first; e.g. to check that an object is a dictionary, use `PyDict_Check()'. The chapter is structured like the "family tree" of Python object types. * Menu: * Fundamental Objects:: * Sequence Objects:: * Mapping Objects:: * Numeric Objects:: * Other Objects::  File: python-api.info, Node: Fundamental Objects, Next: Sequence Objects, Prev: Concrete Objects Layer, Up: Concrete Objects Layer Fundamental Objects =================== This section describes Python type objects and the singleton object `None'. * Menu: * Type Objects:: * None Object::  File: python-api.info, Node: Type Objects, Next: None Object, Prev: Fundamental Objects, Up: Fundamental Objects Type Objects ------------ `PyTypeObject' `PyObject * PyType_Type' This is the type object for type objects; it is the same object as `types.TypeType' in the Python layer.  File: python-api.info, Node: None Object, Prev: Type Objects, Up: Fundamental Objects The None Object --------------- `PyObject * Py_None' The Python `None' object, denoting lack of value. This object has no methods.  File: python-api.info, Node: Sequence Objects, Next: Mapping Objects, Prev: Fundamental Objects, Up: Concrete Objects Layer Sequence Objects ================ Generic operations on sequence objects were discussed in the previous chapter; this section deals with the specific kinds of sequence objects that are intrinsic to the Python language. * Menu: * String Objects:: * Tuple Objects:: * List Objects::  File: python-api.info, Node: String Objects, Next: Tuple Objects, Prev: Sequence Objects, Up: Sequence Objects String Objects -------------- `PyStringObject' This subtype of `PyObject' represents a Python string object. `PyTypeObject PyString_Type' This instance of `PyTypeObject' represents the Python string type. `int PyString_Check(PyObject *o)' Returns true if the object O is a string object. `PyObject* PyString_FromStringAndSize(const char *v, int len)' Returns a new string object with the value V and length LEN on success, and `NULL' on failure. If V is `NULL', the contents of the string are uninitialized. `PyObject* PyString_FromString(const char *v)' Returns a new string object with the value V on success, and `NULL' on failure. `int PyString_Size(PyObject *string)' Returns the length of the string in string object STRING. `char* PyString_AsString(PyObject *string)' Resturns a `NULL' terminated representation of the contents of STRING. `void PyString_Concat(PyObject **string, PyObject *newpart)' Creates a new string object in *STRING containing the contents of NEWPART appended to STRING. The old value of STRING have its reference count decremented. If the new string cannot be created, the old reference to STRING will still be discarded and the value of *STRING will be set to `NULL'; the appropriate exception will be set. `void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)' Creates a new string object in *STRING containing the contents of NEWPART appended to STRING. This version decrements the reference count of NEWPART. `int _PyString_Resize(PyObject **string, int newsize)' A way to resize a string object even though it is "immutable". Only use this to build up a brand new string object; don't use this if the string may already be known in other parts of the code. `PyObject* PyString_Format(PyObject *format, PyObject *args)' Returns a new string object from FORMAT and ARGS. Analogous to `FORMAT % ARGS'. The ARGS argument must be a tuple. `void PyString_InternInPlace(PyObject **string)' Intern the argument *STRING in place. The argument must be the address of a pointer variable pointing to a Python string object. If there is an existing interned string that is the same as *STRING, it sets *STRING to it (decrementing the reference count of the old string object and incrementing the reference count of the interned string object), otherwise it leaves *STRING alone and interns it (incrementing its reference count). (Clarification: even though there is a lot of talk about reference counts, think of this function as reference-count-neutral; you own the object after the call if and only if you owned it before the call.) `PyObject* PyString_InternFromString(const char *v)' A combination of `PyString_FromString()' and `PyString_InternInPlace()', returning either a new string object that has been interned, or a new ("owned") reference to an earlier interned string object with the same value. `char* PyString_AS_STRING(PyObject *string)' Macro form of `PyString_AsString()' but without error checking. `int PyString_GET_SIZE(PyObject *string)' Macro form of `PyString_GetSize()' but without error checking.  File: python-api.info, Node: Tuple Objects, Next: List Objects, Prev: String Objects, Up: Sequence Objects Tuple Objects ------------- `PyTupleObject' This subtype of `PyObject' represents a Python tuple object. `PyTypeObject PyTuple_Type' This instance of `PyTypeObject' represents the Python tuple type. `int PyTuple_Check(PyObject *p)' Return true if the argument is a tuple object. `PyObject* PyTuple_New(int s)' Return a new tuple object of size S. `int PyTuple_Size(PyTupleObject *p)' Takes a pointer to a tuple object, and returns the size of that tuple. `PyObject* PyTuple_GetItem(PyTupleObject *p, int pos)' Returns the object at position POS in the tuple pointed to by P. If POS is out of bounds, returns `NULL' and sets an `IndexError' exception. *Note:* this function returns a "borrowed" reference. `PyObject* PyTuple_GET_ITEM(PyTupleObject *p, int pos)' Does the same, but does no checking of its arguments. `PyObject* PyTuple_GetSlice(PyTupleObject *p, int low, int high)' Takes a slice of the tuple pointed to by P from LOW to HIGH and returns it as a new tuple. `int PyTuple_SetItem(PyTupleObject *p, int pos, PyObject *o)' Inserts a reference to object O at position POS of the tuple pointed to by P. It returns `0' on success. `void PyTuple_SET_ITEM(PyTupleObject *p, int pos, PyObject *o)' Does the same, but does no error checking, and should *only* be used to fill in brand new tuples. `int _PyTuple_Resize(PyTupleObject *p, int new, int last_is_sticky)' Can be used to resize a tuple. Because tuples are *supposed* to be immutable, this should only be used if there is only one module referencing the object. Do *not* use this if the tuple may already be known to some other part of the code. LAST_IS_STICKY is a flag -- if set, the tuple will grow or shrink at the front, otherwise it will grow or shrink at the end. Think of this as destroying the old tuple and creating a new one, only more efficiently.  File: python-api.info, Node: List Objects, Prev: Tuple Objects, Up: Sequence Objects List Objects ------------ `PyListObject' This subtype of `PyObject' represents a Python list object. `PyTypeObject PyList_Type' This instance of `PyTypeObject' represents the Python list type. `int PyList_Check(PyObject *p)' Returns true if its argument is a `PyListObject'. `PyObject* PyList_New(int size)' Returns a new list of length LEN on success, and `NULL' on failure. `int PyList_Size(PyObject *list)' Returns the length of the list object in LIST. `PyObject* PyList_GetItem(PyObject *list, int index)' Returns the object at position POS in the list pointed to by P. If POS is out of bounds, returns `NULL' and sets an `IndexError' exception. *Note:* this function returns a "borrowed" reference. `int PyList_SetItem(PyObject *list, int index, PyObject *item)' Sets the item at index INDEX in list to ITEM. `int PyList_Insert(PyObject *list, int index, PyObject *item)' Inserts the item ITEM into list LIST in front of index INDEX. Returns 0 if successful; returns -1 and sets an exception if unsuccessful. Analogous to `list.insert(index, item)'. `int PyList_Append(PyObject *list, PyObject *item)' Appends the object ITEM at the end of list LIST. Returns 0 if successful; returns -1 and sets an exception if unsuccessful. Analogous to `list.append(item)'. `PyObject* PyList_GetSlice(PyObject *list, int low, int high)' Returns a list of the objects in LIST containing the objects *between* LOW and HIGH. Returns NULL and sets an exception if unsuccessful. Analogous to `list[low:high]'. `int PyList_SetSlice(PyObject *list, int low, int high, PyObject *itemlist)' Sets the slice of LIST between LOW and HIGH to the contents of ITEMLIST. Analogous to `list[low:high]=itemlist'. Returns 0 on success, -1 on failure. `int PyList_Sort(PyObject *list)' Sorts the items of LIST in place. Returns 0 on success, -1 on failure. `int PyList_Reverse(PyObject *list)' Reverses the items of LIST in place. Returns 0 on success, -1 on failure. `PyObject* PyList_AsTuple(PyObject *list)' Returns a new tuple object containing the contents of LIST. `PyObject* PyList_GET_ITEM(PyObject *list, int i)' Macro form of `PyList_GetItem()' without error checking. `PyObject* PyList_SET_ITEM(PyObject *list, int i, PyObject *o)' Macro form of `PyList_SetItem()' without error checking. `int PyList_GET_SIZE(PyObject *list)' Macro form of `PyList_GetSize()' without error checking.  File: python-api.info, Node: Mapping Objects, Next: Numeric Objects, Prev: Sequence Objects, Up: Concrete Objects Layer Mapping Objects =============== * Menu: * Dictionary Objects::  File: python-api.info, Node: Dictionary Objects, Prev: Mapping Objects, Up: Mapping Objects Dictionary Objects ------------------ `PyDictObject' This subtype of `PyObject' represents a Python dictionary object. `PyTypeObject PyDict_Type' This instance of `PyTypeObject' represents the Python dictionary type. `int PyDict_Check(PyObject *p)' Returns true if its argument is a `PyDictObject'. `PyObject* PyDict_New()' Returns a new empty dictionary. `void PyDict_Clear(PyDictObject *p)' Empties an existing dictionary of all key/value pairs. `int PyDict_SetItem(PyDictObject *p, PyObject *key, PyObject *val)' Inserts VALUE into the dictionary with a key of KEY. Both KEY and VALUE should be PyObjects, and KEY should be hashable. `int PyDict_SetItemString(PyDictObject *p, char *key, PyObject *val)' Inserts VALUE into the dictionary using KEY as a key. KEY should be a `char *'. The key object is created using `PyString_FromString(KEY)'. `int PyDict_DelItem(PyDictObject *p, PyObject *key)' Removes the entry in dictionary P with key KEY. KEY is a PyObject. `int PyDict_DelItemString(PyDictObject *p, char *key)' Removes the entry in dictionary P which has a key specified by the `char *'KEY. `PyObject* PyDict_GetItem(PyDictObject *p, PyObject *key)' Returns the object from dictionary P which has a key KEY. Returns `NULL' if the key KEY is not present, but without (!) setting an exception. *Note:* this function returns a "borrowed" reference. `PyObject* PyDict_GetItemString(PyDictObject *p, char *key)' This is the same as `PyDict_GetItem()', but KEY is specified as a `char *', rather than a `PyObject *'. `PyObject* PyDict_Items(PyDictObject *p)' Returns a `PyListObject' containing all the items from the dictionary, as in the dictinoary method `items()' (see the *Python Library Reference*). `PyObject* PyDict_Keys(PyDictObject *p)' Returns a `PyListObject' containing all the keys from the dictionary, as in the dictionary method `keys()' (see the *Python Library Reference*). `PyObject* PyDict_Values(PyDictObject *p)' Returns a `PyListObject' containing all the values from the dictionary P, as in the dictionary method `values()' (see the *Python Library Reference*). `int PyDict_Size(PyDictObject *p)' Returns the number of items in the dictionary. `int PyDict_Next(PyDictObject *p, int ppos, PyObject **pkey, PyObject **pvalue)'  File: python-api.info, Node: Numeric Objects, Next: Other Objects, Prev: Mapping Objects, Up: Concrete Objects Layer Numeric Objects =============== * Menu: * Plain Integer Objects:: * Long Integer Objects:: * Floating Point Objects:: * Complex Number Objects::  File: python-api.info, Node: Plain Integer Objects, Next: Long Integer Objects, Prev: Numeric Objects, Up: Numeric Objects Plain Integer Objects --------------------- `PyIntObject' This subtype of `PyObject' represents a Python integer object. `PyTypeObject PyInt_Type' This instance of `PyTypeObject' represents the Python plain integer type. `int PyInt_Check(PyObject *)' `PyObject* PyInt_FromLong(long ival)' Creates a new integer object with a value of IVAL. The current implementation keeps an array of integer objects for all integers between `-1' and `100', when you create an int in that range you actually just get back a reference to the existing object. So it should be possible to change the value of `1'. I suspect the behaviour of Python in this case is undefined. :-) `long PyInt_AS_LONG(PyIntObject *io)' Returns the value of the object IO. No error checking is performed. `long PyInt_AsLong(PyObject *io)' Will first attempt to cast the object to a `PyIntObject', if it is not already one, and then return its value. `long PyInt_GetMax()' Returns the systems idea of the largest integer it can handle (`LONG_MAX', as defined in the system header files).  File: python-api.info, Node: Long Integer Objects, Next: Floating Point Objects, Prev: Plain Integer Objects, Up: Numeric Objects Long Integer Objects -------------------- `PyLongObject' This subtype of `PyObject' represents a Python long integer object. `PyTypeObject PyLong_Type' This instance of `PyTypeObject' represents the Python long integer type. `int PyLong_Check(PyObject *p)' Returns true if its argument is a `PyLongObject'. `PyObject* PyLong_FromLong(long v)' Returns a new `PyLongObject' object from V. `PyObject* PyLong_FromUnsignedLong(unsigned long v)' Returns a new `PyLongObject' object from an unsigned C long. `PyObject* PyLong_FromDouble(double v)' Returns a new `PyLongObject' object from the integer part of V. `long PyLong_AsLong(PyObject *pylong)' Returns a C `long' representation of the contents of PYLONG. WHAT HAPPENS IF PYLONG is greater than `LONG_MAX'? `unsigned long PyLong_AsUnsignedLong(PyObject *pylong)' Returns a C `unsigned long' representation of the contents of PYLONG. WHAT HAPPENS IF PYLONG is greater than `ULONG_MAX'? `double PyLong_AsDouble(PyObject *pylong)' Returns a C `double' representation of the contents of PYLONG. `PyObject* PyLong_FromString(char *str, char **pend, int base)'  File: python-api.info, Node: Floating Point Objects, Next: Complex Number Objects, Prev: Long Integer Objects, Up: Numeric Objects Floating Point Objects ---------------------- `PyFloatObject' This subtype of `PyObject' represents a Python floating point object. `PyTypeObject PyFloat_Type' This instance of `PyTypeObject' represents the Python floating point type. `int PyFloat_Check(PyObject *p)' Returns true if its argument is a `PyFloatObject'. `PyObject* PyFloat_FromDouble(double v)' Creates a `PyFloatObject' object from V. `double PyFloat_AsDouble(PyObject *pyfloat)' Returns a C `double' representation of the contents of PYFLOAT. `double PyFloat_AS_DOUBLE(PyObject *pyfloat)' Returns a C `double' representation of the contents of PYFLOAT, but without error checking.  File: python-api.info, Node: Complex Number Objects, Prev: Floating Point Objects, Up: Numeric Objects Complex Number Objects ---------------------- `Py_complex' The C structure which corresponds to the value portion of a Python complex number object. Most of the functions for dealing with complex number objects use structures of this type as input or output values, as appropriate. It is defined as: typedef struct { double real; double imag; } Py_complex; `PyComplexObject' This subtype of `PyObject' represents a Python complex number object. `PyTypeObject PyComplex_Type' This instance of `PyTypeObject' represents the Python complex number type. `int PyComplex_Check(PyObject *p)' Returns true if its argument is a `PyComplexObject'. `Py_complex _Py_c_sum(Py_complex left, Py_complex right)' `Py_complex _Py_c_diff(Py_complex left, Py_complex right)' `Py_complex _Py_c_neg(Py_complex complex)' `Py_complex _Py_c_prod(Py_complex left, Py_complex right)' `Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)' `Py_complex _Py_c_pow(Py_complex num, Py_complex exp)' `PyObject* PyComplex_FromCComplex(Py_complex v)' `PyObject* PyComplex_FromDoubles(double real, double imag)' Returns a new `PyComplexObject' object from REAL and IMAG. `double PyComplex_RealAsDouble(PyObject *op)' Returns the real part of OP as a C `double'. `double PyComplex_ImagAsDouble(PyObject *op)' Returns the imaginary part of OP as a C `double'. `Py_complex PyComplex_AsCComplex(PyObject *op)'  File: python-api.info, Node: Other Objects, Prev: Numeric Objects, Up: Concrete Objects Layer Other Objects ============= * Menu: * File Objects:: * Module Objects:: * CObjects::  File: python-api.info, Node: File Objects, Next: Module Objects, Prev: Other Objects, Up: Other Objects File Objects ------------ `PyFileObject' This subtype of `PyObject' represents a Python file object. `PyTypeObject PyFile_Type' This instance of `PyTypeObject' represents the Python file type. `int PyFile_Check(PyObject *p)' Returns true if its argument is a `PyFileObject'. `PyObject* PyFile_FromString(char *name, char *mode)' Creates a new `PyFileObject' pointing to the file specified in NAME with the mode specified in MODE. `PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close))' Creates a new `PyFileObject' from the already-open FP. The function CLOSE will be called when the file should be closed. `FILE * PyFile_AsFile(PyFileObject *p)' Returns the file object associated with P as a `FILE *'. `PyObject* PyFile_GetLine(PyObject *p, int n)' undocumented as yet `PyObject* PyFile_Name(PyObject *p)' Returns the name of the file specified by P as a `PyStringObject'. `void PyFile_SetBufSize(PyFileObject *p, int n)' Available on systems with `setvbuf()' only. This should only be called immediately after file object creation. `int PyFile_SoftSpace(PyFileObject *p, int newflag)' Sets the `softspace' attribute of P to NEWFLAG. Returns the previous value. This function clears any errors, and will return `0' as the previous value if the attribute either does not exist or if there were errors in retrieving it. There is no way to detect errors from this function, but doing so should not be needed. `int PyFile_WriteObject(PyObject *obj, PyFileObject *p, int flags)' Writes object OBJ to file object P. `int PyFile_WriteString(char *s, PyFileObject *p, int flags)' Writes string S to file object P.  File: python-api.info, Node: Module Objects, Next: CObjects, Prev: File Objects, Up: Other Objects Module Objects -------------- There are only a few functions special to module objects. `PyObject * PyModule_New(char *name)' Return a new module object with the `__name__' attribute set to NAME. Only the module's `__doc__' and `__name__' attributes are filled in; the caller is responsible for providing a `__file__' attribute. `PyObject * PyModule_GetDict(PyObject *module)' Return the dictionary object that implements MODULE's namespace; this object is the same as the `__dict__' attribute of the module object. This function never fails. `char * PyModule_GetName(PyObject *module)' Return MODULE's `__name__' value. If the module does not provide one, `SystemError' is raised. `char * PyModule_GetFilename(PyObject *module)' Return the name of the file from which MODULE was loaded using MODULE's `__file__' attribute. If this is not defined, raise `SystemError'.  File: python-api.info, Node: CObjects, Prev: Module Objects, Up: Other Objects CObjects -------- `PyCObject' This subtype of `PyObject' represents an opaque value, useful for C extension modules who need to pass an opaque value (as a `void *' pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules. `PyObject * PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))' Creates a `PyCObject' from the `void *' COBJ. The DESTR function will be called when the object is reclaimed, unless it is `NULL'. `PyObject * PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *) )' Creates a `PyCObject' from the `void *'COBJ. The DESTR function will be called when the object is reclaimed. The DESC argument can be used to pass extra callback data for the destructor function. `void * PyCObject_AsVoidPtr(PyObject* self)' Returns the object `void *' that the `PyCObject' SELF was created with. `void * PyCObject_GetDesc(PyObject* self)' Returns the description `void *' that the `PyCObject' SELF was created with.