[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / ext / extending-with-embedding.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="embeddingInCplusplus.html" />
<link rel="prev" href="pure-embedding.html" />
<link rel="parent" href="embedding.html" />
<link rel="next" href="embeddingInCplusplus.html" />
<meta name='aesop' content='information' />
<title>5.4 Extending Embedded Python </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="5.3 Pure Embedding"
  href="pure-embedding.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="5. Embedding Python in"
  href="embedding.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="5.5 Embedding Python in"
  href="embeddingInCplusplus.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="pure-embedding.html">5.3 Pure Embedding</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="embedding.html">5. Embedding Python in</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="embeddingInCplusplus.html">5.5 Embedding Python in</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION007400000000000000000"></A><A NAME="extending-with-embedding"></A>
<BR>
5.4 Extending Embedded Python
         
</H1>

<P>
Until now, the embedded Python interpreter had no access to
functionality from the application itself.  The Python API allows this
by extending the embedded interpreter.  That is, the embedded
interpreter gets extended with routines provided by the application.
While it sounds complex, it is not so bad.  Simply forget for a while
that the application starts the Python interpreter.  Instead, consider
the application to be a set of subroutines, and write some glue code
that gives Python access to those routines, just like you would write
a normal Python extension.  For example:

<P>
<div class="verbatim"><pre>
static int numargs=0;

/* Return the number of arguments of the application command line */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
    if(!PyArg_ParseTuple(args, ":numargs"))
        return NULL;
    return Py_BuildValue("i", numargs);
}

static PyMethodDef EmbMethods[] = {
    {"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."},
    {NULL, NULL, 0, NULL}
};
</pre></div>

<P>
Insert the above code just above the <tt class="cfunction">main()</tt> function.
Also, insert the following two statements directly after
<tt class="cfunction">Py_Initialize()</tt>:

<P>
<div class="verbatim"><pre>
    numargs = argc;
    Py_InitModule("emb", EmbMethods);
</pre></div>

<P>
These two lines initialize the <code>numargs</code> variable, and make the
<tt class="function">emb.numargs()</tt> function accessible to the embedded Python
interpreter.  With these extensions, the Python script can do things
like

<P>
<div class="verbatim"><pre>
import emb
print "Number of arguments", emb.numargs()
</pre></div>

<P>
In a real application, the methods will expose an API of the
application to Python.

<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="5.3 Pure Embedding"
  href="pure-embedding.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="5. Embedding Python in"
  href="embedding.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="5.5 Embedding Python in"
  href="embeddingInCplusplus.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="pure-embedding.html">5.3 Pure Embedding</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="embedding.html">5. Embedding Python in</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="embeddingInCplusplus.html">5.5 Embedding Python in</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
920dae64 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="embeddingInCplusplus.html" />
	12	<link rel="prev" href="pure-embedding.html" />
	13	<link rel="parent" href="embedding.html" />
	14	<link rel="next" href="embeddingInCplusplus.html" />
	15	<meta name='aesop' content='information' />
	16	<title>5.4 Extending Embedded Python </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="5.3 Pure Embedding"
	24	href="pure-embedding.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="5. Embedding Python in"
	27	href="embedding.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="5.5 Embedding Python in"
	30	href="embeddingInCplusplus.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="pure-embedding.html">5.3 Pure Embedding</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="embedding.html">5. Embedding Python in</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="embeddingInCplusplus.html">5.5 Embedding Python in</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION007400000000000000000"></A><A NAME="extending-with-embedding"></A>
	54	<BR>
	55	5.4 Extending Embedded Python
	56
	57	</H1>
	58
	59	<P>
	60	Until now, the embedded Python interpreter had no access to
	61	functionality from the application itself. The Python API allows this
	62	by extending the embedded interpreter. That is, the embedded
	63	interpreter gets extended with routines provided by the application.
	64	While it sounds complex, it is not so bad. Simply forget for a while
65	that the application starts the Python interpreter. Instead, consider
66	the application to be a set of subroutines, and write some glue code
67	that gives Python access to those routines, just like you would write
68	a normal Python extension. For example:
69
70	<P>
71	<div class="verbatim"><pre>
72	static int numargs=0;
73
74	/* Return the number of arguments of the application command line */
75	static PyObject*
76	emb_numargs(PyObject self, PyObject args)
77	{
78	if(!PyArg_ParseTuple(args, ":numargs"))
79	return NULL;
80	return Py_BuildValue("i", numargs);
81	}
82
83	static PyMethodDef EmbMethods[] = {
84	{"numargs", emb_numargs, METH_VARARGS,
85	"Return the number of arguments received by the process."},
86	{NULL, NULL, 0, NULL}
87	};
88	</pre></div>
89
90	<P>
91	Insert the above code just above the <tt class="cfunction">main()</tt> function.
92	Also, insert the following two statements directly after
93	<tt class="cfunction">Py_Initialize()</tt>:
94
95	<P>
96	<div class="verbatim"><pre>
97	numargs = argc;
98	Py_InitModule("emb", EmbMethods);
99	</pre></div>
100
101	<P>
102	These two lines initialize the <code>numargs</code> variable, and make the
103	<tt class="function">emb.numargs()</tt> function accessible to the embedded Python
104	interpreter. With these extensions, the Python script can do things
105	like
106
107	<P>
108	<div class="verbatim"><pre>
109	import emb
110	print "Number of arguments", emb.numargs()
111	</pre></div>
112
113	<P>
114	In a real application, the methods will expose an API of the
115	application to Python.
116
117	<P>
118
119	<DIV CLASS="navigation">
120	<div class='online-navigation'>
121	<p></p><hr />
122	<table align="center" width="100%" cellpadding="0" cellspacing="2">
123	<tr>
124	<td class='online-navigation'><a rel="prev" title="5.3 Pure Embedding"
125	href="pure-embedding.html"><img src='../icons/previous.png'
126	border='0' height='32' alt='Previous Page' width='32' /></A></td>
127	<td class='online-navigation'><a rel="parent" title="5. Embedding Python in"
128	href="embedding.html"><img src='../icons/up.png'
129	border='0' height='32' alt='Up One Level' width='32' /></A></td>
130	<td class='online-navigation'><a rel="next" title="5.5 Embedding Python in"
131	href="embeddingInCplusplus.html"><img src='../icons/next.png'
132	border='0' height='32' alt='Next Page' width='32' /></A></td>
133	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
134	<td class='online-navigation'><a rel="contents" title="Table of Contents"
135	href="contents.html"><img src='../icons/contents.png'
136	border='0' height='32' alt='Contents' width='32' /></A></td>
137	<td class='online-navigation'><img src='../icons/blank.png'
138	border='0' height='32' alt='' width='32' /></td>
139	<td class='online-navigation'><img src='../icons/blank.png'
140	border='0' height='32' alt='' width='32' /></td>
141	</tr></table>
142	<div class='online-navigation'>
143	<b class="navlabel">Previous:</b>
144	<a class="sectref" rel="prev" href="pure-embedding.html">5.3 Pure Embedding</A>
145	<b class="navlabel">Up:</b>
146	<a class="sectref" rel="parent" href="embedding.html">5. Embedding Python in</A>
147	<b class="navlabel">Next:</b>
148	<a class="sectref" rel="next" href="embeddingInCplusplus.html">5.5 Embedding Python in</A>
149	</div>
150	</div>
151	<hr />
152	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
153	</DIV>
154	<!--End of Navigation Panel-->
155	<ADDRESS>
156	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
157	</ADDRESS>
158	</BODY>
159	</HTML>