See All Titles |
![]() ![]() Defining New Object TypesPyObject* _PyObject_New(PyTypeObject *type) Return value: New reference. PyObject* _PyObject_NewVar(PyTypeObject *type, int size) Common Object StructuresNext, you have a list of object structures commonly used in type and method definitions. The document How to Write a Python Extension, by Michael Reilly lists and explains the prototypes of these structures. It also demonstrates how to create new Python types. http://starship.python.net/crew/arcege/extwriting/pyext.html Mapping Object StructuresPyMappingMethods Structure used to hold pointers to the functions used to implement the mapping protocol for an extension type. Number Object StructuresPyNumberMethods Structure used to hold pointers to the functions, which an extension type uses to implement the number protocol. Sequence Object StructuresPySequenceMethods Structure used to hold pointers to the functions which an object uses to implement the sequence protocol. Buffer Object StructuresThe buffer interface exports a model where an object can expose its internal data as a set of chunks of data, where each chunk is specified as a pointer/length pair. These chunks are called segments and are presumed to be non-contiguous in memory. If an object does not export the buffer interface, its tp_as_buffer member in the PyTypeObject structure should be NULL. Otherwise, the tp_as_buffer will point to a PyBufferProcs structure. Note
It is very important that your PyTypeObject structure uses Py_TPFLAGS_DEFAULT for the value of the tp_flags member rather than 0. This tells the Python runtime that your PyBufferProcs structure contains the bf_getcharbuffer slot. Older versions of Python did not have this member, so a new Python interpreter using an old extension needs to be able to test for its presence before using it. PyBufferProcs Structure used to hold the function pointers that define an implementation of the buffer protocol. The first slot is bf_getreadbuffer, of type getreadbufferproc. If this slot is NULL, the object does not support reading from the internal data. This is nonsensical, so implementers should fill this in, but callers should test that the slot contains a non-NULL value. The next slot is bf_getwritebuffer having type getwritebufferproc. This slot can be NULL if the object does not allow writing into its returned buffers. The third slot is bf_getsegcount, with type getsegcountproc. This slot must not be NULL and is used to inform the caller of how many segments the object contains. Simple objects such as PyString_Type and PyBuffer_Type contain a single segment. The last slot is bf_getcharbuffer, of type getcharbufferproc. This slot will only be present if the Py_TPFLAGS_HAVE_GETCHARBUFFER flag is present in the tp_flags field of the object's PyTypeObject. Before using this slot, the caller should test whether it is present by using the PyType_HasFeature() function. If present, it might be NULL, indicating that the object's contents cannot be used as 8-bit characters. The slot function can also raise an error if the object's contents cannot be interpreted as 8-bit characters. For example, if the object is an array that is configured to hold floating point values, an exception might be raised if a caller attempts to use bf_getcharbuffer to fetch a sequence of 8-bit characters. This notion of exporting the internal buffers as text is used to distinguish between objects that are binary in nature, and those which have character-based content. Note
The current policy seems to state that these characters might be multibyte characters. This implies that a buffer size of N does not mean that there are N characters present. Py_TPFLAGS_HAVE_GETCHARBUFFER Flag bit set in the type structure to indicate that the bf_getcharbuffer slot is known. This being set does not indicate that the object supports the buffer interface or that the bf_getcharbuffer slot is non-NULL. int (*getreadbufferproc) (PyObject *self, int segment, void **ptrptr) Returns a pointer to a readable segment of the buffer. This function is allowed to raise an exception, in which case it must return -1. The segment that is passed must be zero or positive, and strictly less than the number of segments returned by the bf_getsegcount slot function. On success, returns 0 and sets *ptrptr to a pointer to the buffer memory. int (*getwritebufferproc) (PyObject *self, int segment, void **ptrptr) Returns a pointer to a writable memory buffer in *ptrptr; the memory buffer must correspond to buffer segment called segment. Must return -1 and set an exception on error. TypeError should be raised if the object only supports read-only buffers, and SystemError should be raised when segment specifies a segment that doesn't exist. int (*getsegcountproc) (PyObject *self, int *lenp) Returns the number of memory segments that comprise the buffer. If lenp is not NULL, the implementation must report the sum of the sizes (in bytes) of all segments in *lenp. The function cannot fail.int (*getsegcountproc) (PyObject *self, int *lenp) Returns the number of memory segments that comprise the buffer. If lenp is not NULL, the implementation must report the sum of the sizes (in bytes) of all segments in *lenp. The function cannot fail.
|
Index terms contained in this sectionApplication Programmers Interface (API)Python/C defining object types 2nd 3rd buffer object structures 2nd creating object type definitions, Python/C Application Programmers Interface (API) 2nd 3rd definitions object types, Python/C Application Programmers Interface (API) 2nd 3rd functions defining object types How to Write a Python Extension interfaces Python/C Application Programmers (API) defining object types 2nd 3rd mapping object structures object types defining, Python/C Application Programmers Interface (API) 2nd 3rd Python/C Application Programmers Interface (API) defining object types 2nd 3rd Reilly, Michael structures buffer objects 2nd mapping objects |
© 2002, O'Reilly & Associates, Inc. |