[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / ext / node27.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="next" href="node28.html" />
<link rel="prev" href="node26.html" />
<link rel="parent" href="dnt-type-methods.html" />
<link rel="next" href="node28.html" />
<meta name='aesop' content='information' />
<title>2.2.2 Object Presentation</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.2.1 Finalization and De-allocation"
  href="node26.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.2 Type Methods"
  href="dnt-type-methods.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.3 Attribute Management"
  href="node28.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="node26.html">2.2.1 Finalization and De-allocation</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node28.html">2.2.3 Attribute Management</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION004220000000000000000">
2.2.2 Object Presentation</A>
</H2>

<P>
In Python, there are three ways to generate a textual representation
of an object: the <tt class="function">repr()</tt><a id='l2h-8' xml:id='l2h-8'></a> function (or
equivalent back-tick syntax), the <tt class="function">str()</tt><a id='l2h-9' xml:id='l2h-9'></a>function, and the <tt class="keyword">print</tt> statement.  For most objects, the
<tt class="keyword">print</tt> statement is equivalent to the <tt class="function">str()</tt>
function, but it is possible to special-case printing to a
<tt class="ctype">FILE*</tt> if necessary; this should only be done if efficiency is
identified as a problem and profiling suggests that creating a
temporary string object to be written to a file is too expensive.

<P>
These handlers are all optional, and most types at most need to
implement the <tt class="member">tp_str</tt> and <tt class="member">tp_repr</tt> handlers.

<P>
<div class="verbatim"><pre>
    reprfunc tp_repr;
    reprfunc tp_str;
    printfunc tp_print;
</pre></div>

<P>
The <tt class="member">tp_repr</tt> handler should return a string object containing
a representation of the instance for which it is called.  Here is a
simple example:

<P>
<div class="verbatim"><pre>
static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
    return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
                               obj-&gt;obj_UnderlyingDatatypePtr-&gt;size);
}
</pre></div>

<P>
If no <tt class="member">tp_repr</tt> handler is specified, the interpreter will
supply a representation that uses the type's <tt class="member">tp_name</tt> and a
uniquely-identifying value for the object.

<P>
The <tt class="member">tp_str</tt> handler is to <tt class="function">str()</tt> what the
<tt class="member">tp_repr</tt> handler described above is to <tt class="function">repr()</tt>; that
is, it is called when Python code calls <tt class="function">str()</tt> on an
instance of your object.  Its implementation is very similar to the
<tt class="member">tp_repr</tt> function, but the resulting string is intended for
human consumption.  If <tt class="member">tp_str</tt> is not specified, the
<tt class="member">tp_repr</tt> handler is used instead.

<P>
Here is a simple example:

<P>
<div class="verbatim"><pre>
static PyObject *
newdatatype_str(newdatatypeobject * obj)
{
    return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
                               obj-&gt;obj_UnderlyingDatatypePtr-&gt;size);
}
</pre></div>

<P>
The print function will be called whenever Python needs to "print" an
instance of the type.  For example, if 'node' is an instance of type
TreeNode, then the print function is called when Python code calls:

<P>
<div class="verbatim"><pre>
print node
</pre></div>

<P>
There is a flags argument and one flag, <tt class="constant">Py_PRINT_RAW</tt>, and
it suggests that you print without string quotes and possibly without
interpreting escape sequences.

<P>
The print function receives a file object as an argument. You will
likely want to write to that file object.

<P>
Here is a sample print function:

<P>
<div class="verbatim"><pre>
static int
newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
{
    if (flags &amp; Py_PRINT_RAW) {
        fprintf(fp, "&lt;{newdatatype object--size: %d}&gt;",
                obj-&gt;obj_UnderlyingDatatypePtr-&gt;size);
    }
    else {
        fprintf(fp, "\"&lt;{newdatatype object--size: %d}&gt;\"",
                obj-&gt;obj_UnderlyingDatatypePtr-&gt;size);
    }
    return 0;
}
</pre></div>

<P>

<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.2.1 Finalization and De-allocation"
  href="node26.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.2 Type Methods"
  href="dnt-type-methods.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.3 Attribute Management"
  href="node28.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="node26.html">2.2.1 Finalization and De-allocation</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node28.html">2.2.3 Attribute Management</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="next" href="node28.html" />
	12	<link rel="prev" href="node26.html" />
	13	<link rel="parent" href="dnt-type-methods.html" />
	14	<link rel="next" href="node28.html" />
	15	<meta name='aesop' content='information' />
	16	<title>2.2.2 Object Presentation</title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="2.2.1 Finalization and De-allocation"
	24	href="node26.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="2.2 Type Methods"
	27	href="dnt-type-methods.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="2.2.3 Attribute Management"
	30	href="node28.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="node26.html">2.2.1 Finalization and De-allocation</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="node28.html">2.2.3 Attribute Management</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION004220000000000000000">
	54	2.2.2 Object Presentation</A>
	55	</H2>
	56
	57	<P>
	58	In Python, there are three ways to generate a textual representation
	59	of an object: the <tt class="function">repr()</tt><a id='l2h-8' xml:id='l2h-8'></a> function (or
	60	equivalent back-tick syntax), the <tt class="function">str()</tt><a id='l2h-9' xml:id='l2h-9'></a>function, and the <tt class="keyword">print</tt> statement. For most objects, the
	61	<tt class="keyword">print</tt> statement is equivalent to the <tt class="function">str()</tt>
	62	function, but it is possible to special-case printing to a
	63	<tt class="ctype">FILE*</tt> if necessary; this should only be done if efficiency is
	64	identified as a problem and profiling suggests that creating a
65	temporary string object to be written to a file is too expensive.
66
67	<P>
68	These handlers are all optional, and most types at most need to
69	implement the <tt class="member">tp_str</tt> and <tt class="member">tp_repr</tt> handlers.
70
71	<P>
72	<div class="verbatim"><pre>
73	reprfunc tp_repr;
74	reprfunc tp_str;
75	printfunc tp_print;
76	</pre></div>
77
78	<P>
79	The <tt class="member">tp_repr</tt> handler should return a string object containing
80	a representation of the instance for which it is called. Here is a
81	simple example:
82
83	<P>
84	<div class="verbatim"><pre>
85	static PyObject *
86	newdatatype_repr(newdatatypeobject * obj)
87	{
88	return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
89	obj->obj_UnderlyingDatatypePtr->size);
90	}
91	</pre></div>
92
93	<P>
94	If no <tt class="member">tp_repr</tt> handler is specified, the interpreter will
95	supply a representation that uses the type's <tt class="member">tp_name</tt> and a
96	uniquely-identifying value for the object.
97
98	<P>
99	The <tt class="member">tp_str</tt> handler is to <tt class="function">str()</tt> what the
100	<tt class="member">tp_repr</tt> handler described above is to <tt class="function">repr()</tt>; that
101	is, it is called when Python code calls <tt class="function">str()</tt> on an
102	instance of your object. Its implementation is very similar to the
103	<tt class="member">tp_repr</tt> function, but the resulting string is intended for
104	human consumption. If <tt class="member">tp_str</tt> is not specified, the
105	<tt class="member">tp_repr</tt> handler is used instead.
106
107	<P>
108	Here is a simple example:
109
110	<P>
111	<div class="verbatim"><pre>
112	static PyObject *
113	newdatatype_str(newdatatypeobject * obj)
114	{
115	return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
116	obj->obj_UnderlyingDatatypePtr->size);
117	}
118	</pre></div>
119
120	<P>
121	The print function will be called whenever Python needs to "print" an
122	instance of the type. For example, if 'node' is an instance of type
123	TreeNode, then the print function is called when Python code calls:
124
125	<P>
126	<div class="verbatim"><pre>
127	print node
128	</pre></div>
129
130	<P>
131	There is a flags argument and one flag, <tt class="constant">Py_PRINT_RAW</tt>, and
132	it suggests that you print without string quotes and possibly without
133	interpreting escape sequences.
134
135	<P>
136	The print function receives a file object as an argument. You will
137	likely want to write to that file object.
138
139	<P>
140	Here is a sample print function:
141
142	<P>
143	<div class="verbatim"><pre>
144	static int
145	newdatatype_print(newdatatypeobject obj, FILE fp, int flags)
146	{
147	if (flags & Py_PRINT_RAW) {
148	fprintf(fp, "<{newdatatype object--size: %d}>",
149	obj->obj_UnderlyingDatatypePtr->size);
150	}
151	else {
152	fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
153	obj->obj_UnderlyingDatatypePtr->size);
154	}
155	return 0;
156	}
157	</pre></div>
158
159	<P>
160
161	<DIV CLASS="navigation">
162	<div class='online-navigation'>
163	<p></p><hr />
164	<table align="center" width="100%" cellpadding="0" cellspacing="2">
165	<tr>
166	<td class='online-navigation'><a rel="prev" title="2.2.1 Finalization and De-allocation"
167	href="node26.html"><img src='../icons/previous.png'
168	border='0' height='32' alt='Previous Page' width='32' /></A></td>
169	<td class='online-navigation'><a rel="parent" title="2.2 Type Methods"
170	href="dnt-type-methods.html"><img src='../icons/up.png'
171	border='0' height='32' alt='Up One Level' width='32' /></A></td>
172	<td class='online-navigation'><a rel="next" title="2.2.3 Attribute Management"
173	href="node28.html"><img src='../icons/next.png'
174	border='0' height='32' alt='Next Page' width='32' /></A></td>
175	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
176	<td class='online-navigation'><a rel="contents" title="Table of Contents"
177	href="contents.html"><img src='../icons/contents.png'
178	border='0' height='32' alt='Contents' width='32' /></A></td>
179	<td class='online-navigation'><img src='../icons/blank.png'
180	border='0' height='32' alt='' width='32' /></td>
181	<td class='online-navigation'><img src='../icons/blank.png'
182	border='0' height='32' alt='' width='32' /></td>
183	</tr></table>
184	<div class='online-navigation'>
185	<b class="navlabel">Previous:</b>
186	<a class="sectref" rel="prev" href="node26.html">2.2.1 Finalization and De-allocation</A>
187	<b class="navlabel">Up:</b>
188	<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
189	<b class="navlabel">Next:</b>
190	<a class="sectref" rel="next" href="node28.html">2.2.3 Attribute Management</A>
191	</div>
192	</div>
193	<hr />
194	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
195	</DIV>
196	<!--End of Navigation Panel-->
197	<ADDRESS>
198	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
199	</ADDRESS>
200	</BODY>
201	</HTML>