sam-t2/devtools/amd64/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>