< BACKMake Note | BookmarkCONTINUE >
152015024128143245168232148039196038240039088173205162105045222218073235215104098039061

Concrete Objects Layer

The functions in this section 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; for example: to check that an object is a dictionary, use PyDict_Check(). This section is structured similar to the "family tree" of Python object types.

Fundamental Objects

This section describes Python type objects and the singleton object None.

Type Objects
							
PyTypeObject

						

The C structure of the objects used to describe built-in types.

							
PyObject* PyType_Type

						

This is the type object for type objects; it is the same object as types.TypeType in the Python layer.

							
int PyType_Check(PyObject *o)

						

Returns true if the object o is a type object.

							
int PyType_HasFeature(PyObject *o, int feature)

						

Returns true if the type object o sets the feature identified by the feature argument. Type features are denoted by single bit flags. The only defined feature flag is Py_TPFLAGS_HAVE_GETCHARBUFFER, which is described in a later section.

The None Object

Note that the PyTypeObject for None is not directly exposed in the Python/C API. Because None is a singleton, testing for object identity (using == in C) is sufficient. There is no PyNone_Check() function for the same reason.

							
PyObject* Py_None

						

The Python None object denotes lack of value. This object has no methods.

Sequence Objects

Generic operations on sequence objects were discussed in the previous subsection; this subsection deals with the specific kinds of sequence objects that are intrinsic to the Python language.

String Objects
							
PyStringObject

						

This subtype of PyObject represents a Python string object.

							
PyTypeObject PyString_Type

						

This instance of PyTypeObject represents the Python string type; it is the same object as types.TypeType in the Python layer.

							
int PyString_Check(PyObject *o)

						

Returns true if the object o is a string object.

							
PyObject* PyString_FromString(const char *v)

						

Return value: New reference. Returns a new string object with the value v on success, and NULL on failure.

							
PyObject* PyString_FromStringAndSize(const char *v, int len)

						

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

							
int PyString_Size(PyObject *string)

						

Returns the length of the string object identified by the given pointer.

							
int PyString_GET_SIZE(PyObject *string)

						

Macro form of PyString_GetSize() but without error checking.

							
char* PyString_AsString(PyObject *string)

						

Returns a null-terminated representation of the contents of string. The pointer refers to the internal buffer of string, not a copy. The data must not be modified in any way. It must not be de-allocated.

							
char* PyString_AS_STRING(PyObject *string)

						

Macro form of PyString_AsString() but without error checking.

							
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 has 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 might already be known in other parts of the code.

							
PyObject* PyString_Format(PyObject *format, PyObject *args)

						

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

						

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

						

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

Buffer Objects

Python objects implemented in C can export a group of functions called the buffer interface. These functions can be used by an object to expose its data in a raw, byte- oriented format. Clients of the object can use the buffer interface to access the object data directly, without needing to copy it first.

Two examples of objects that support the buffer interface are strings and arrays. The string object exposes the character contents in the buffer interface's byte-oriented form. An array can also expose its contents, but it should be noted that array elements can be multi-byte values.

An example user of the buffer interface is the file object's write() method. Any object that can export a series of bytes through the buffer interface can be written to a file. There are a number of format codes to PyArgs_ParseTuple() that operate against an object's buffer interface, returning data from the target object.

More information on the buffer interface is provided in the section "Buffer Object Structures," under the description for PyBufferProcs.

A buffer object is defined in the bufferobject.h header (included by Python.h). These objects look very similar to string objects at the Python programming level: They support slicing, indexing, concatenation, and some other standard string operations. However, their data can come from one of two sources: from a block of memory, or from another object that exports the buffer interface.

Buffer objects are useful as a way to expose the data from another object's buffer interface to the Python programmer. They can also be used as a zero-copy slicing mechanism. Using their ability to reference a block of memory, it is possible to expose any data to the Python programmer quite easily. The memory could be a large, constant array in a C extension, it could be a raw block of memory for manipulation before passing to an operating system library, or it could be used to pass around structured data in its native, in-memory format.

							
PyBufferObject

						

This subtype of PyObject represents a buffer object.

							
PyTypeObject PyBuffer_Type

						

The instance of PyTypeObject that represents the Python buffer type; it is the same object as types.BufferType in the Python layer.

							
int Py_END_OF_BUFFER

						

This constant can be passed as the size parameter to PyBuffer_FromObject() or PyBuffer_FromReadWriteObject(). It indicates that the new PyBufferObject should refer to the base object from the specified offset to the end of its exported buffer. Using this enables the caller to avoid querying the base object for its length.

							
int PyBuffer_Check(PyObject *p)

						

Returns true if the argument has type PyBuffer_Type.

							
PyObject* PyBuffer_FromObject(PyObject *base, int offset, int size)

						

Return value: New reference. Returns a new read-only buffer object. This raises TypeError if base doesn't support the read-only buffer protocol or doesn't provide exactly one buffer segment. It raises ValueError if offset is less than zero. The buffer will hold a reference to the base object, and the buffer's contents will refer to the base object's buffer interface, starting as position offset and extending for size bytes. If size is Py_END_OF_BUFFER, the new buffer's contents extend to the length of the base object's exported buffer data.

							
PyObject* PyBuffer_FromReadWriteObject(PyObject *base, int offset,
int size)

						

Return value: New reference. Returns a new writable buffer object. Parameters and exceptions are similar to those for PyBuffer_FromObject(). If the base object does not export the writable buffer protocol, TypeError is raised.

							
PyObject* PyBuffer_FromMemory(void *ptr, int size)

						

Return value: New reference. Returns a new read-only buffer object that reads from a specified location in memory, with a specified size. The caller is responsible for ensuring that the memory buffer, passed in as ptr, is not deallocated while the returned buffer object exists. Raises ValueError if size is less than zero. Note that Py_END_OF_BUFFER might not be passed for the size parameter; ValueError will be raised in that case.

							
PyObject* PyBuffer_FromReadWriteMemory(void *ptr, int size)

						

Return value: New reference. Similar to PyBuffer_FromMemory(), but the returned buffer is writable.

							
PyObject* PyBuffer_New(int size)

						

Return value: New reference. Returns a new writable buffer object that maintains its own memory buffer of size bytes. ValueError is returned if size is not zero or positive.

Tuple Objects
							
PyTupleObject

						

This subtype of PyObject represents a Python tuple object.

							
PyTypeObject PyTuple_Type

						

This instance of PyTypeObject represents the Python tuple type; it is the same object as types.TupleType in the Python layer.

							
int PyTuple_Check(PyObject *p)

						

Return true if the argument is a tuple object.

							
PyObject* PyTuple_New(int len)

						

Return value: New reference. Returns a new tuple object of size len, or NULL on failure.

							
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)

						

Return value: Borrowed reference. Returns the object at position pos in the tuple pointed to by p. If pos is out of bounds, it returns NULL and sets an IndexError exception.

							
PyObject* PyTuple_GET_ITEM(PyTupleObject *p, int pos)

						

Return value: Borrowed reference. Does the same, but does no checking of its arguments.

							
PyObject* PyTuple_GetSlice(PyTupleObject *p, int low, int high)

						

Return value: New reference. Takes a slice of the tuple pointed to by p from low to high and returns it as a new tuple.

							
int PyTuple_SetItem(PyObject *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.

Note

This function "steals" a reference to o.



							
void PyTuple_SET_ITEM(PyObject *p, int pos, PyObject *o)

						

Does the same, but does no error checking, and should only be used to fill in brand new tuples.

Note

This function "steals" a reference to o.



							
int _PyTuple_Resize(PyTupleObject *p, int newsize, int last_is_sticky)

						

Can be used to resize a tuple. newsize will be the new length of the tuple. Because tuples are supposed to be immutable, this should only be used if there is only one reference to the object. Do not use this if the tuple might already be known to some other part of the code. last_is_sticky is a flag—if true, 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. Returns 0 on success and -1 on failure (in which case, a MemoryError or SystemError will be raised).

List Objects
							
PyListObject

						

This subtype of PyObject represents a Python list object.

							
PyTypeObject PyList_Type

						

This instance of PyTypeObject represents the Python list type. This is the same object as types.ListType.

							
int PyList_Check(PyObject *p)

						

Returns true if its argument is a PyListObject.

							
PyObject* PyList_New(int len)

						

Return value: New reference. Returns a new list of length len on success, or NULL on failure.

							
int PyList_Size(PyObject *list)

						

Returns the length of the list object in list; this is equivalent to "len(list)" on a list object.

							
int PyList_GET_SIZE(PyObject *list)

						

Macro form of PyList_GetSize() without error checking.

							
PyObject* PyList_GetItem(PyObject *list, int index)

						

Return value: Borrowed reference. Returns the object at position pos in the list pointed to by p. If pos is out of bounds, it returns NULL and sets an IndexError exception.

							
PyObject* PyList_GET_ITEM(PyObject *list, int i)

						

Return value: Borrowed reference. Macro form of PyList_GetItem() without error checking.

							
int PyList_SetItem(PyObject *list, int index, PyObject *item)

						

Sets the item at the position identified by the integer index in the given list to the value of the object identified by the pointer called item.

Note

This function "steals" a reference to item.



							
PyObject* PyList_SET_ITEM(PyObject *list, int i, PyObject *o)

						

Return value: Borrowed reference. Macro form of PyList_SetItem() without error checking.

Note

This function "steals" a reference to item.



							
int PyList_Insert(PyObject *list, int index, PyObject *item)

						

Inserts the item called item into the list called list in front of the index called index. Returns 0 if successful; returns -1 and raises 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 the list called 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)

						

Return value: New reference. 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. This is equivalent to "list.sort()".

							
int PyList_Reverse(PyObject *list)

						

Reverses the items of list in place. Returns 0 on success, -1 on failure. This is the equivalent of "list.reverse()".

							
PyObject* PyList_AsTuple(PyObject *list)

						

Return value: New reference. Returns a new tuple object containing the contents of list; equivalent to "tuple(list)".

Mapping/Dictionary Objects

						
PyDictObject

					

This subtype of PyObject represents a Python dictionary object.

						
PyTypeObject PyDict_Type

					

This instance of PyTypeObject represents the Python dictionary type. This is exposed to Python programs as types.DictType and types.DictionaryType.

						
int PyDict_Check(PyObject *p)

					

Returns true if its argument is a PyDictObject.

						
PyObject* PyDict_New()

					

Return value: New reference. Returns a new empty dictionary, or NULL on failure.

						
void PyDict_Clear(PyObject *p)

					

Empties an existing dictionary of all key/value pairs.

						
int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

					

Inserts value into the dictionary with a key of key. key must be hashable; if it isn't, TypeError will be raised.

						
int PyDict_SetItemString(PyObject *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(PyObject *p, PyObject *key)

					

Removes the entry in dictionary p with key called key. key must be hashable; if it isn't, TypeError is raised.

						
int PyDict_DelItemString(PyObject *p, char *key)

					

Removes the entry in dictionary p which has a key specified by the string key.

						
PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

					

Return value: Borrowed reference. Returns the object from dictionary p, which has a key called key. Returns NULL if the key called key is not present, but without setting an exception.

						
PyObject* PyDict_GetItemString(PyObject *p, char *key)

					

Return value: Borrowed reference. This is the same as PyDict_GetItem(), but key is specified as a char*, rather than a PyObject*.

						
PyObject* PyDict_Items(PyObject *p)

					

Return value: New reference. Returns a PyListObject containing all the items from the dictionary, as in the dictionary method items() (see Chapter 2, "Language Review" ).

						
PyObject* PyDict_Keys(PyObject *p)

					

Return value: New reference. Returns a PyListObject containing all the keys from the dictionary, as in the dictionary method keys() (see Chapter 2).

						
PyObject* PyDict_Values(PyObject *p)

					

Return value: New reference. Returns a PyListObject containing all the values from the dictionary p, as in the dictionary method values() (see Chapter 2).

						
int PyDict_Size(PyObject *p)

					

Returns the number of items in the dictionary. This is equivalent to "len(p)" on a dictionary.

Numeric Objects

Next, you have the API function for numerical objects, which are classified in: plain integer, long integer, floating point, and complex number 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. This is the same object as types.IntType.

							
int PyInt_Check(PyObject* o)

						

Return value: Borrowed reference. Returns true if o is of type PyInt_Type.

							
PyObject* PyInt_FromLong(long ival)

						

Return value: New reference. Creates a new integer object with a value of ival.

Tip

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. It is suspected that the behavior of Python in this case is undefined.



							
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_AS_LONG(PyObject *io)

						

Returns the value of the object io. No error checking is performed.

							
long PyInt_GetMax()

						

Returns the system's idea of the largest integer it can handle (LONG_MAX, as defined in the system header files).

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. This is the same object as types.LongType.

							
int PyLong_Check(PyObject *p)

						

Returns true if its argument is a PyLongObject.

							
PyObject* PyLong_FromLong(long v)

						

Return value: New reference. Returns a new PyLongObject object from v, or NULL on failure.

							
PyObject* PyLong_FromUnsignedLong(unsigned long v)

						

Return value: New reference. Returns a new PyLongObject object from a C unsigned long, or NULL on failure.

							
PyObject* PyLong_FromDouble(double v)

						

Return value: New reference. Returns a new PyLongObject object from the integer part of v, or NULL on failure.

							
long PyLong_AsLong(PyObject *pylong)

						

Returns a C long representation of the contents of pylong. If pylong is greater than LONG_MAX, an OverflowError is raised.OverflowError.

							
unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

						

Returns a C unsigned long representation of the contents of pylong. If pylong is greater than ULONG_MAX, an OverflowError is raised.OverflowError.

							
double PyLong_AsDouble(PyObject *pylong)

						

Returns a C double representation of the contents of pylong.

							
PyObject* PyLong_FromString(char *str, char **pend, int base)

						

Return value: New reference. Returns a new PyLongObject based on the string value in str, which is interpreted according to the radix in base. If pend is non-NULL, *pend will point to the first character in str which follows the representation of the number. If base is 0, the radix will be determined based on the leading characters of str: if str starts with 0x or 0X, radix 16 will be used; if str starts with 0, radix 8 will be used; otherwise, radix 10 will be used. If base is not 0, it must be between 2 and 36, inclusive. Leading spaces are ignored. If there are no digits, ValueError will be raised.

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. This is the same object as types.FloatType.

							
int PyFloat_Check(PyObject *p)

						

Returns true if its argument is a PyFloatObject.

							
PyObject* PyFloat_FromDouble(double v)

						

Return value: New reference. Creates a PyFloatObject object from v, or NULL on failure.

							
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.

Complex Number Objects

Python's complex number objects are implemented as two distinct types when viewed from the C API: one is the Python object exposed to Python programs, and the other is a C structure that represents the actual complex number value. The API provides functions for working with both.

Complex Numbers as C Structures

Note that the functions which accept these structures as parameters and return them as results do so by value rather than dereferencing them through pointers. This is consistent throughout the API.

								
Py_complex

							

This is the C structure that 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;

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

							

Returns the sum of two complex numbers, using the C Py_complex representation.

								
Py_complex _Py_c_diff(Py_complex left, Py_complex right)

							

Returns the difference between two complex numbers, using the C Py_complex representation.

								
Py_complex _Py_c_neg(Py_complex complex)

							

Returns the negation of the complex number complex, using the C Py_complex representation.

								
Py_complex _Py_c_prod(Py_complex left, Py_complex right)

							

Returns the product of two complex numbers, using the C Py_complex representation.

								
Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

							

Returns the quotient of two complex numbers, using the C Py_complex representation.

								
Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

							

Returns the exponentiation of num by exp, using the C Py_complex representation.

Complex Numbers as Python Objects
								
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.

								
PyObject* PyComplex_FromCComplex(Py_complex v)

							

Return value: New reference. Creates a new Python complex number object from a C Py_complex value.

								
PyObject* PyComplex_FromDoubles(double real, double imag)

							

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

							

Returns the Py_complex value of the complex number op.

Other Objects

Next, you have the list of API function for all the other objects, including File, Module, and C Objects.

File Objects

Python's built-in file objects are implemented entirely on the FILE* support from the C standard library. This is an implementation detail and might change in future releases of Python.

							
PyFileObject

						

This subtype of PyObject represents a Python file object.

							
PyTypeObject PyFile_Type

						

This instance of PyTypeObject represents the Python file type. This is exposed to Python programs as types.FileType.

							
int PyFile_Check(PyObject *p)

						

Returns true if its argument is a PyFileObject.

							
PyObject* PyFile_FromString(char *filename, char *mode)

						

Return value: New reference. On success, returns a new file object that is opened on the file given by filename, with a file mode given by mode, where mode has the same semantics as the standard C routine fopen(). On failure, returns NULL.

							
PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int
(*close)(FILE*))

						

Return value: New reference. Creates a new PyFileObject from the already-open standard C file pointer, fp. The function close will be called when the file should be closed. Returns NULL on failure.

							
FILE* PyFile_AsFile(PyFileObject *p)

						

Returns the file object associated with p as a FILE*.

							
PyObject* PyFile_GetLine(PyObject *p, int n)

						

Return value: New reference. Equivalent to p.readline([n]), this function reads one line from the object p. p can be a file object or any object with a readline() method. If n is 0, exactly one line is read, regardless of the length of the line. If n is greater than 0, no more than n bytes will be read from the file; a partial line can be returned. In both cases, an empty string is returned if the end of the file is reached immediately. If n is less than 0, however, one line is read regardless of length, but EOFError is raised if the end of the file is reached immediately.

							
PyObject* PyFile_Name(PyObject *p)

						

Return value: Borrowed reference. Returns the name of the file specified by p as a string object.

							
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(PyObject *p, int newflag)

						

This function exists for internal use by the interpreter. Sets the softspace attribute of p to newflag and returns the previous value. p does not have to be a file object for this function to work properly; any object is supported (though it's only interesting if the softspace attribute can be set). 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. The only supported flag for flags is Py_PRINT_RAW; if given, the str() of the object is written instead of the repr(). Returns 0 on success or -1 on failure; the appropriate exception will be set.

							
int PyFile_WriteString(char *s, PyFileObject *p, int flags)

						

Writes string s to file object p. Returns 0 on success or -1 on failure; the appropriate exception will be set.

Module Objects

There are only a few functions special to module objects.

							
PyTypeObject PyModule_Type

						

This instance of PyTypeObject represents the Python module type. This is exposed to Python programs as types.ModuleType.

							
int PyModule_Check(PyObject *p)

						

Returns true if its argument is a module object.

							
PyObject* PyModule_New(char *name)

						

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

						

Returns module's __name__ value. If the module does not provide one, or if it is not a string, SystemError is raised and NULL is returned.

							
char* PyModule_GetFilename(PyObject *module)

						

Returns the name of the file from which module was loaded using module's __file__ attribute. If this is not defined, or if it is not a string, raises SystemError and returns NULL.

C Objects

Refer to the document "Extending and Embedding the Python Interpreter," ("Providing a C API for an Extension Module"), for more information on using these objects. This document is part of the Python distribution. Note that it is also available on-line at the python.org.

							
PyCObject

						

This subtype of PyObject represents an opaque value, useful for C extension modules that 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.

							
int PyCObject_Check(PyObject *p)

						

Returns true if its argument is a PyCObject.

							
PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))

						

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

						

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


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

< BACKMake Note | BookmarkCONTINUE >

Index terms contained in this section

Application Programmers Interface (API)
     Python/C
            Concrete Objects Layer 2nd 3rd 4th 5th 6th 7th 8th 9th
arrays
      buffer interface support
buffer interface
buffer objects
bufferobject.h header file
C objects
C structures
      complex numbers as
complex number objects 2nd
Concrete Objects Layer, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th 6th 7th 8th 9th
dictionary objects
file objects
files
     header
            bufferobject.h
floating point objects
functions
      object types 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th
     objects
            buffer
            C
            complex number 2nd
            dictionary
            file
            floating point
            list 2nd
            long integer
            mapping
            module
            none
            numeric 2nd 3rd 4th
            plain integer
            sequence 2nd 3rd 4th
            string
            tuple
            type
      PyArgs_ParseTuple
header files
      bufferobject.h
interfaces
      buffer
     Python/C Application Programmers (API)
            Concrete Objects Layer 2nd 3rd 4th 5th 6th 7th 8th 9th
layers
      Concrete Objects, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th 6th 7th 8th 9th
list objects 2nd
long integer objects
mapping objects
methods
      write()
module objects
none objects
numeric objects 2nd 3rd 4th
objects
      buffer
      C
      complex number 2nd
      dictionary
      file
      floating point
      list 2nd
      long integer
      mapping
      module
      none
      numeric 2nd 3rd 4th
      passing to object types, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th 6th 7th 8th 9th
      plain integer
     Python
            complex numbers as
      sequence 2nd 3rd 4th
      string
      tuple
      type
passing
      objects to object types, Python/C Application Programmers Interface (API) 2nd 3rd 4th 5th 6th 7th 8th 9th
plain integer objects
PyArgs_ParseTuple function
Python objects
      complex numbers as
Python/C Application Programmers Interface (API)
      Concrete Objects Layer 2nd 3rd 4th 5th 6th 7th 8th 9th
sequence objects 2nd 3rd 4th
string objects
strings
      buffer interface support
structures
     C
            complex numbers as
support
      buffer interface, strings and arrays
tuple objects
type objects
write() method

© 2002, O'Reilly & Associates, Inc.