[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / ext / 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="reporting-bugs.html" />
<link rel="prev" href="building-on-windows.html" />
<link rel="parent" href="ext.html" />
<link rel="next" href="high-level-embedding.html" />
<meta name='aesop' content='information' />
<title>5. Embedding Python in Another Application </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="4.3 Using DLLs in"
  href="win-dlls.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="Extending and Embedding the"
  href="ext.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.1 Very High Level"
  href="high-level-embedding.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="win-dlls.html">4.3 Using DLLs in</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="high-level-embedding.html">5.1 Very High Level</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION007000000000000000000"></A><A NAME="embedding"></A>
<BR>
5. Embedding Python in Another Application
     
</H1>

<P>
The previous chapters discussed how to extend Python, that is, how to
extend the functionality of Python by attaching a library of C
functions to it.  It is also possible to do it the other way around:
enrich your C/C++ application by embedding Python in it.  Embedding
provides your application with the ability to implement some of the
functionality of your application in Python rather than C or C++.
This can be used for many purposes; one example would be to allow
users to tailor the application to their needs by writing some scripts
in Python.  You can also use it yourself if some of the functionality
can be written in Python more easily.

<P>
Embedding Python is similar to extending it, but not quite.  The
difference is that when you extend Python, the main program of the
application is still the Python interpreter, while if you embed
Python, the main program may have nothing to do with Python --
instead, some parts of the application occasionally call the Python
interpreter to run some Python code.

<P>
So if you are embedding Python, you are providing your own main
program.  One of the things this main program has to do is initialize
the Python interpreter.  At the very least, you have to call the
function <tt class="cfunction">Py_Initialize()</tt> (on Mac OS, call
<tt class="cfunction">PyMac_Initialize()</tt> instead).  There are optional calls to
pass command line arguments to Python.  Then later you can call the
interpreter from any part of the application.

<P>
There are several different ways to call the interpreter: you can pass
a string containing Python statements to
<tt class="cfunction">PyRun_SimpleString()</tt>, or you can pass a stdio file pointer
and a file name (for identification in error messages only) to
<tt class="cfunction">PyRun_SimpleFile()</tt>.  You can also call the lower-level
operations described in the previous chapters to construct and use
Python objects.

<P>
A simple demo of embedding Python can be found in the directory
<span class="file">Demo/embed/</span> of the source distribution.

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seetitle">
    <dt><em class="citetitle"><a href="../api/api.html"
        >Python/C API Reference Manual</a></em></dt>
    <dd>The
            details of Python's C interface are given in this manual.
            A great deal of necessary information can be found here.</dd>
  </dl>
</div>

<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="high-level-embedding.html">5.1 Very High Level Embedding</a>
<LI><A href="lower-level-embedding.html">5.2 Beyond Very High Level Embedding: An overview</a>
<LI><A href="pure-embedding.html">5.3 Pure Embedding</a>
<LI><A href="extending-with-embedding.html">5.4 Extending Embedded Python</a>
<LI><A href="embeddingInCplusplus.html">5.5 Embedding Python in C++</a>
<LI><A href="link-reqs.html">5.6 Linking Requirements</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="4.3 Using DLLs in"
  href="win-dlls.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="Extending and Embedding the"
  href="ext.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.1 Very High Level"
  href="high-level-embedding.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="win-dlls.html">4.3 Using DLLs in</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="high-level-embedding.html">5.1 Very High Level</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="reporting-bugs.html" />
	12	<link rel="prev" href="building-on-windows.html" />
	13	<link rel="parent" href="ext.html" />
	14	<link rel="next" href="high-level-embedding.html" />
	15	<meta name='aesop' content='information' />
	16	<title>5. Embedding Python in Another Application </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="4.3 Using DLLs in"
	24	href="win-dlls.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="Extending and Embedding the"
	27	href="ext.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.1 Very High Level"
	30	href="high-level-embedding.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="win-dlls.html">4.3 Using DLLs in</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="high-level-embedding.html">5.1 Very High Level</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION007000000000000000000"></A><A NAME="embedding"></A>
	54	<BR>
	55	5. Embedding Python in Another Application
	56
	57	</H1>
	58
	59	<P>
	60	The previous chapters discussed how to extend Python, that is, how to
	61	extend the functionality of Python by attaching a library of C
	62	functions to it. It is also possible to do it the other way around:
	63	enrich your C/C++ application by embedding Python in it. Embedding
	64	provides your application with the ability to implement some of the
65	functionality of your application in Python rather than C or C++.
66	This can be used for many purposes; one example would be to allow
67	users to tailor the application to their needs by writing some scripts
68	in Python. You can also use it yourself if some of the functionality
69	can be written in Python more easily.
70
71	<P>
72	Embedding Python is similar to extending it, but not quite. The
73	difference is that when you extend Python, the main program of the
74	application is still the Python interpreter, while if you embed
75	Python, the main program may have nothing to do with Python --
76	instead, some parts of the application occasionally call the Python
77	interpreter to run some Python code.
78
79	<P>
80	So if you are embedding Python, you are providing your own main
81	program. One of the things this main program has to do is initialize
82	the Python interpreter. At the very least, you have to call the
83	function <tt class="cfunction">Py_Initialize()</tt> (on Mac OS, call
84	<tt class="cfunction">PyMac_Initialize()</tt> instead). There are optional calls to
85	pass command line arguments to Python. Then later you can call the
86	interpreter from any part of the application.
87
88	<P>
89	There are several different ways to call the interpreter: you can pass
90	a string containing Python statements to
91	<tt class="cfunction">PyRun_SimpleString()</tt>, or you can pass a stdio file pointer
92	and a file name (for identification in error messages only) to
93	<tt class="cfunction">PyRun_SimpleFile()</tt>. You can also call the lower-level
94	operations described in the previous chapters to construct and use
95	Python objects.
96
97	<P>
98	A simple demo of embedding Python can be found in the directory
99	<span class="file">Demo/embed/</span> of the source distribution.
100
101	<P>
102	<div class="seealso">
103	<p class="heading">See Also:</p>
104
105	<dl compact="compact" class="seetitle">
106	<dt><em class="citetitle"><a href="../api/api.html"
107	>Python/C API Reference Manual</a></em></dt>
108	<dd>The
109	details of Python's C interface are given in this manual.
110	A great deal of necessary information can be found here.</dd>
111	</dl>
112	</div>
113
114	<P>
115
116	<p><br /></p><hr class='online-navigation' />
117	<div class='online-navigation'>
118	<!--Table of Child-Links-->
119	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
120
121	<UL CLASS="ChildLinks">
122	<LI><A href="high-level-embedding.html">5.1 Very High Level Embedding</a>
123	<LI><A href="lower-level-embedding.html">5.2 Beyond Very High Level Embedding: An overview</a>
124	<LI><A href="pure-embedding.html">5.3 Pure Embedding</a>
125	<LI><A href="extending-with-embedding.html">5.4 Extending Embedded Python</a>
126	<LI><A href="embeddingInCplusplus.html">5.5 Embedding Python in C++</a>
127	<LI><A href="link-reqs.html">5.6 Linking Requirements</a>
128	</ul>
129	<!--End of Table of Child-Links-->
130	</div>
131
132	<DIV CLASS="navigation">
133	<div class='online-navigation'>
134	<p></p><hr />
135	<table align="center" width="100%" cellpadding="0" cellspacing="2">
136	<tr>
137	<td class='online-navigation'><a rel="prev" title="4.3 Using DLLs in"
138	href="win-dlls.html"><img src='../icons/previous.png'
139	border='0' height='32' alt='Previous Page' width='32' /></A></td>
140	<td class='online-navigation'><a rel="parent" title="Extending and Embedding the"
141	href="ext.html"><img src='../icons/up.png'
142	border='0' height='32' alt='Up One Level' width='32' /></A></td>
143	<td class='online-navigation'><a rel="next" title="5.1 Very High Level"
144	href="high-level-embedding.html"><img src='../icons/next.png'
145	border='0' height='32' alt='Next Page' width='32' /></A></td>
146	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
147	<td class='online-navigation'><a rel="contents" title="Table of Contents"
148	href="contents.html"><img src='../icons/contents.png'
149	border='0' height='32' alt='Contents' width='32' /></A></td>
150	<td class='online-navigation'><img src='../icons/blank.png'
151	border='0' height='32' alt='' width='32' /></td>
152	<td class='online-navigation'><img src='../icons/blank.png'
153	border='0' height='32' alt='' width='32' /></td>
154	</tr></table>
155	<div class='online-navigation'>
156	<b class="navlabel">Previous:</b>
157	<a class="sectref" rel="prev" href="win-dlls.html">4.3 Using DLLs in</A>
158	<b class="navlabel">Up:</b>
159	<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
160	<b class="navlabel">Next:</b>
161	<a class="sectref" rel="next" href="high-level-embedding.html">5.1 Very High Level</A>
162	</div>
163	</div>
164	<hr />
165	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
166	</DIV>
167	<!--End of Navigation Panel-->
168	<ADDRESS>
169	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
170	</ADDRESS>
171	</BODY>
172	</HTML>