[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / ext / dnt-type-methods.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ext.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="dnt-basics.html" />
<link rel="parent" href="defining-new-types.html" />
<link rel="next" href="node26.html" />
<meta name='aesop' content='information' />
<title>2.2 Type Methods </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="2.1.3 Supporting cyclic garbage"
  href="node24.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="2. Defining New Types"
  href="defining-new-types.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="2.2.1 Finalization and De-allocation"
  href="node26.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node24.html">2.1.3 Supporting cyclic garbage</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="defining-new-types.html">2. Defining New Types</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node26.html">2.2.1 Finalization and De-allocation</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION004200000000000000000"></A><A NAME="dnt-type-methods"></A>
<BR>
2.2 Type Methods
         
</H1>

<P>
This section aims to give a quick fly-by on the various type methods
you can implement and what they do.

<P>
Here is the definition of <tt class="ctype">PyTypeObject</tt>, with some fields only
used in debug builds omitted:

<P>
<div class="verbatim">
<pre>typedef struct _typeobject {
    PyObject_VAR_HEAD
    char *tp_name; /* For printing, in format "&lt;module&gt;.&lt;name&gt;" */
    int tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    cmpfunc tp_compare;
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    long tp_flags;

    char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    long tp_weaklistoffset;

    /* Added in release 2.2 */
    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    long tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;

} PyTypeObject;
</pre>
<div class="footer">
<a href="typestruct.txt" type="text/plain">Download as text (original file name: <span class="file">typestruct.h</span>).</a>
</div></div>

<P>
Now that's a <em>lot</em> of methods.  Don't worry too much though - if
you have a type you want to define, the chances are very good that you
will only implement a handful of these.

<P>
As you probably expect by now, we're going to go over this and give
more information about the various handlers.  We won't go in the order
they are defined in the structure, because there is a lot of
historical baggage that impacts the ordering of the fields; be sure
your type initialization keeps the fields in the right order!  It's
often easiest to find an example that includes all the fields you need
(even if they're initialized to <code>0</code>) and then change the values
to suit your new type.

<P>
<div class="verbatim"><pre>
    char *tp_name; /* For printing */
</pre></div>

<P>
The name of the type - as mentioned in the last section, this will
appear in various places, almost entirely for diagnostic purposes.
Try to choose something that will be helpful in such a situation!

<P>
<div class="verbatim"><pre>
    int tp_basicsize, tp_itemsize; /* For allocation */
</pre></div>

<P>
These fields tell the runtime how much memory to allocate when new
objects of this type are created.  Python has some built-in support
for variable length structures (think: strings, lists) which is where
the <tt class="member">tp_itemsize</tt> field comes in.  This will be dealt with
later.

<P>
<div class="verbatim"><pre>
    char *tp_doc;
</pre></div>

<P>
Here you can put a string (or its address) that you want returned when
the Python script references <code>obj.__doc__</code> to retrieve the
doc string.

<P>
Now we come to the basic type methods--the ones most extension types
will implement.

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="node26.html">2.2.1 Finalization and De-allocation</a>
<LI><A href="node27.html">2.2.2 Object Presentation</a>
<LI><A href="node28.html">2.2.3 Attribute Management</a>
<UL>
<LI><A href="node29.html">2.2.3.1 Generic Attribute Management</a>
<LI><A href="node30.html">2.2.3.2 Type-specific Attribute Management</a>
</ul>
<LI><A href="node31.html">2.2.4 Object Comparison</a>
<LI><A href="node32.html">2.2.5 Abstract Protocol Support</a>
<LI><A href="node33.html">2.2.6 More Suggestions</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="2.1.3 Supporting cyclic garbage"
  href="node24.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="2. Defining New Types"
  href="defining-new-types.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="2.2.1 Finalization and De-allocation"
  href="node26.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node24.html">2.1.3 Supporting cyclic garbage</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="defining-new-types.html">2. Defining New Types</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node26.html">2.2.1 Finalization and De-allocation</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="ext.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="prev" href="dnt-basics.html" />
	12	<link rel="parent" href="defining-new-types.html" />
	13	<link rel="next" href="node26.html" />
	14	<meta name='aesop' content='information' />
	15	<title>2.2 Type Methods </title>
	16	</head>
	17	<body>
	18	<DIV CLASS="navigation">
	19	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	20	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	21	<tr>
	22	<td class='online-navigation'><a rel="prev" title="2.1.3 Supporting cyclic garbage"
	23	href="node24.html"><img src='../icons/previous.png'
	24	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	25	<td class='online-navigation'><a rel="parent" title="2. Defining New Types"
	26	href="defining-new-types.html"><img src='../icons/up.png'
	27	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	28	<td class='online-navigation'><a rel="next" title="2.2.1 Finalization and De-allocation"
	29	href="node26.html"><img src='../icons/next.png'
	30	border='0' height='32' alt='Next Page' width='32' /></A></td>
	31	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
	32	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	33	href="contents.html"><img src='../icons/contents.png'
	34	border='0' height='32' alt='Contents' width='32' /></A></td>
	35	<td class='online-navigation'><img src='../icons/blank.png'
	36	border='0' height='32' alt='' width='32' /></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	</tr></table>
	40	<div class='online-navigation'>
	41	<b class="navlabel">Previous:</b>
	42	<a class="sectref" rel="prev" href="node24.html">2.1.3 Supporting cyclic garbage</A>
	43	<b class="navlabel">Up:</b>
	44	<a class="sectref" rel="parent" href="defining-new-types.html">2. Defining New Types</A>
	45	<b class="navlabel">Next:</b>
	46	<a class="sectref" rel="next" href="node26.html">2.2.1 Finalization and De-allocation</A>
	47	</div>
	48	<hr /></div>
	49	</DIV>
	50	<!--End of Navigation Panel-->
	51
	52	<H1><A NAME="SECTION004200000000000000000"></A><A NAME="dnt-type-methods"></A>
	53	<BR>
	54	2.2 Type Methods
	55
	56	</H1>
	57
	58	<P>
	59	This section aims to give a quick fly-by on the various type methods
	60	you can implement and what they do.
	61
	62	<P>
	63	Here is the definition of <tt class="ctype">PyTypeObject</tt>, with some fields only
	64	used in debug builds omitted:
65
66	<P>
67	<div class="verbatim">
68	<pre>typedef struct _typeobject {
69	PyObject_VAR_HEAD
70	char tp_name; / For printing, in format "<module>.<name>" */
71	int tp_basicsize, tp_itemsize; /* For allocation */
72
73	/* Methods to implement standard operations */
74
75	destructor tp_dealloc;
76	printfunc tp_print;
77	getattrfunc tp_getattr;
78	setattrfunc tp_setattr;
79	cmpfunc tp_compare;
80	reprfunc tp_repr;
81
82	/* Method suites for standard classes */
83
84	PyNumberMethods *tp_as_number;
85	PySequenceMethods *tp_as_sequence;
86	PyMappingMethods *tp_as_mapping;
87
88	/* More standard operations (here for binary compatibility) */
89
90	hashfunc tp_hash;
91	ternaryfunc tp_call;
92	reprfunc tp_str;
93	getattrofunc tp_getattro;
94	setattrofunc tp_setattro;
95
96	/* Functions to access object as input/output buffer */
97	PyBufferProcs *tp_as_buffer;
98
99	/* Flags to define presence of optional/expanded features */
100	long tp_flags;
101
102	char tp_doc; / Documentation string */
103
104	/* Assigned meaning in release 2.0 */
105	/* call function for all accessible objects */
106	traverseproc tp_traverse;
107
108	/* delete references to contained objects */
109	inquiry tp_clear;
110
111	/* Assigned meaning in release 2.1 */
112	/* rich comparisons */
113	richcmpfunc tp_richcompare;
114
115	/* weak reference enabler */
116	long tp_weaklistoffset;
117
118	/* Added in release 2.2 */
119	/* Iterators */
120	getiterfunc tp_iter;
121	iternextfunc tp_iternext;
122
123	/* Attribute descriptor and subclassing stuff */
124	struct PyMethodDef *tp_methods;
125	struct PyMemberDef *tp_members;
126	struct PyGetSetDef *tp_getset;
127	struct _typeobject *tp_base;
128	PyObject *tp_dict;
129	descrgetfunc tp_descr_get;
130	descrsetfunc tp_descr_set;
131	long tp_dictoffset;
132	initproc tp_init;
133	allocfunc tp_alloc;
134	newfunc tp_new;
135	freefunc tp_free; /* Low-level free-memory routine */
136	inquiry tp_is_gc; /* For PyObject_IS_GC */
137	PyObject *tp_bases;
138	PyObject tp_mro; / method resolution order */
139	PyObject *tp_cache;
140	PyObject *tp_subclasses;
141	PyObject *tp_weaklist;
142
143	} PyTypeObject;
144	</pre>
145	<div class="footer">
146	<a href="typestruct.txt" type="text/plain">Download as text (original file name: <span class="file">typestruct.h</span>).</a>
147	</div></div>
148
149	<P>
150	Now that's a <em>lot</em> of methods. Don't worry too much though - if
151	you have a type you want to define, the chances are very good that you
152	will only implement a handful of these.
153
154	<P>
155	As you probably expect by now, we're going to go over this and give
156	more information about the various handlers. We won't go in the order
157	they are defined in the structure, because there is a lot of
158	historical baggage that impacts the ordering of the fields; be sure
159	your type initialization keeps the fields in the right order! It's
160	often easiest to find an example that includes all the fields you need
161	(even if they're initialized to <code>0</code>) and then change the values
162	to suit your new type.
163
164	<P>
165	<div class="verbatim"><pre>
166	char tp_name; / For printing */
167	</pre></div>
168
169	<P>
170	The name of the type - as mentioned in the last section, this will
171	appear in various places, almost entirely for diagnostic purposes.
172	Try to choose something that will be helpful in such a situation!
173
174	<P>
175	<div class="verbatim"><pre>
176	int tp_basicsize, tp_itemsize; /* For allocation */
177	</pre></div>
178
179	<P>
180	These fields tell the runtime how much memory to allocate when new
181	objects of this type are created. Python has some built-in support
182	for variable length structures (think: strings, lists) which is where
183	the <tt class="member">tp_itemsize</tt> field comes in. This will be dealt with
184	later.
185
186	<P>
187	<div class="verbatim"><pre>
188	char *tp_doc;
189	</pre></div>
190
191	<P>
192	Here you can put a string (or its address) that you want returned when
193	the Python script references <code>obj.__doc__</code> to retrieve the
194	doc string.
195
196	<P>
197	Now we come to the basic type methods--the ones most extension types
198	will implement.
199
200	<P>
201
202	<p><br /></p><hr class='online-navigation' />
203	<div class='online-navigation'>
204	<!--Table of Child-Links-->
205	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
206
207	<UL CLASS="ChildLinks">
208	<LI><A href="node26.html">2.2.1 Finalization and De-allocation</a>
209	<LI><A href="node27.html">2.2.2 Object Presentation</a>
210	<LI><A href="node28.html">2.2.3 Attribute Management</a>
211	<UL>
212	<LI><A href="node29.html">2.2.3.1 Generic Attribute Management</a>
213	<LI><A href="node30.html">2.2.3.2 Type-specific Attribute Management</a>
214	</ul>
215	<LI><A href="node31.html">2.2.4 Object Comparison</a>
216	<LI><A href="node32.html">2.2.5 Abstract Protocol Support</a>
217	<LI><A href="node33.html">2.2.6 More Suggestions</a>
218	</ul>
219	<!--End of Table of Child-Links-->
220	</div>
221
222	<DIV CLASS="navigation">
223	<div class='online-navigation'>
224	<p></p><hr />
225	<table align="center" width="100%" cellpadding="0" cellspacing="2">
226	<tr>
227	<td class='online-navigation'><a rel="prev" title="2.1.3 Supporting cyclic garbage"
228	href="node24.html"><img src='../icons/previous.png'
229	border='0' height='32' alt='Previous Page' width='32' /></A></td>
230	<td class='online-navigation'><a rel="parent" title="2. Defining New Types"
231	href="defining-new-types.html"><img src='../icons/up.png'
232	border='0' height='32' alt='Up One Level' width='32' /></A></td>
233	<td class='online-navigation'><a rel="next" title="2.2.1 Finalization and De-allocation"
234	href="node26.html"><img src='../icons/next.png'
235	border='0' height='32' alt='Next Page' width='32' /></A></td>
236	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
237	<td class='online-navigation'><a rel="contents" title="Table of Contents"
238	href="contents.html"><img src='../icons/contents.png'
239	border='0' height='32' alt='Contents' width='32' /></A></td>
240	<td class='online-navigation'><img src='../icons/blank.png'
241	border='0' height='32' alt='' width='32' /></td>
242	<td class='online-navigation'><img src='../icons/blank.png'
243	border='0' height='32' alt='' width='32' /></td>
244	</tr></table>
245	<div class='online-navigation'>
246	<b class="navlabel">Previous:</b>
247	<a class="sectref" rel="prev" href="node24.html">2.1.3 Supporting cyclic garbage</A>
248	<b class="navlabel">Up:</b>
249	<a class="sectref" rel="parent" href="defining-new-types.html">2. Defining New Types</A>
250	<b class="navlabel">Next:</b>
251	<a class="sectref" rel="next" href="node26.html">2.2.1 Finalization and De-allocation</A>
252	</div>
253	</div>
254	<hr />
255	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
256	</DIV>
257	<!--End of Navigation Panel-->
258	<ADDRESS>
259	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
260	</ADDRESS>
261	</BODY>
262	</HTML>