< BACKMake Note | BookmarkCONTINUE >
152015024128143245168232148039196038240039088173205162105045222219255189230213165015209

Defining New Object Types

					
PyObject* _PyObject_New(PyTypeObject *type)

				

Return value: New reference.

					
PyObject* _PyObject_NewVar(PyTypeObject *type, int size)

				

Return value: New reference.

Common Object Structures

Next, you have a list of object structures commonly used in type and method definitions.

PyObject PyVarObject  
PyObject_HEAD PyObject_HEAD_INIT PyObject_VAR_HEAD
unaryfunc binaryfunc ternaryfunc
inquiry coercion intargfunc
intintargfunc intobjargproc intintobjargproc
objobjargproc destructor printfunc
getattrfunc getattrofunc setattrfunc
setattrofunc cmpfunc reprfunc
hashfunc    

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 Structures

						
PyMappingMethods

					

Structure used to hold pointers to the functions used to implement the mapping protocol for an extension type.

Number Object Structures

						
PyNumberMethods

					

Structure used to hold pointers to the functions, which an extension type uses to implement the number protocol.

Sequence Object Structures

						
PySequenceMethods

					

Structure used to hold pointers to the functions which an object uses to implement the sequence protocol.

Buffer Object Structures

The 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.


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
            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.