[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / api / intro.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.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="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="veryhigh.html" />
<link rel="prev" href="contents.html" />
<link rel="parent" href="api.html" />
<link rel="next" href="includes.html" />
<meta name='aesop' content='information' />
<title>1. Introduction </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="Contents"
  href="contents.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="Python/C API Reference Manual"
  href="api.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="1.1 Include Files"
  href="includes.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</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'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="contents.html">Contents</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="includes.html">1.1 Include Files</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION003000000000000000000"></A><A NAME="intro"></A>
<BR>
1. Introduction 
</H1>

<P>
The Application Programmer's Interface to Python gives C and
C++ programmers access to the Python interpreter at a variety of
levels.  The API is equally usable from C++, but for brevity it is
generally referred to as the Python/C API.  There are two
fundamentally different reasons for using the Python/C API.  The first
reason is to write <em>extension modules</em> for specific purposes;
these are C modules that extend the Python interpreter.  This is
probably the most common use.  The second reason is to use Python as a
component in a larger application; this technique is generally
referred to as <i class="dfn">embedding</i> Python in an application.

<P>
Writing an extension module is a relatively well-understood process, 
where a ``cookbook'' approach works well.  There are several tools 
that automate the process to some extent.  While people have embedded 
Python in other applications since its early existence, the process of 
embedding Python is less straightforward than writing an extension.  

<P>
Many API functions are useful independent of whether you're embedding 
or extending Python; moreover, most applications that embed Python 
will need to provide a custom extension as well, so it's probably a 
good idea to become familiar with writing an extension before 
attempting to embed Python in a real application.

<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="includes.html">1.1 Include Files</a>
<LI><A href="objects.html">1.2 Objects, Types and Reference Counts</a>
<UL>
<LI><A href="refcounts.html">1.2.1 Reference Counts</a>
<UL>
<LI><A href="refcountDetails.html">1.2.1.1 Reference Count Details</a>
</ul>
<LI><A href="types.html">1.2.2 Types</a>
</ul>
<LI><A href="exceptions.html">1.3 Exceptions</a>
<LI><A href="embedding.html">1.4 Embedding Python</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="Contents"
  href="contents.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="Python/C API Reference Manual"
  href="api.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="1.1 Include Files"
  href="includes.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</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'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="contents.html">Contents</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="includes.html">1.1 Include Files</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="api.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="api.html" title='Python/C API Reference Manual' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="veryhigh.html" />
	13	<link rel="prev" href="contents.html" />
	14	<link rel="parent" href="api.html" />
	15	<link rel="next" href="includes.html" />
	16	<meta name='aesop' content='information' />
	17	<title>1. Introduction </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="Contents"
	25	href="contents.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="Python/C API Reference Manual"
	28	href="api.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="1.1 Include Files"
	31	href="includes.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python/C API Reference Manual</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="contents.html">Contents</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="includes.html">1.1 Include Files</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION003000000000000000000"></A><A NAME="intro"></A>
	56	<BR>
	57	1. Introduction
	58	</H1>
	59
	60	<P>
	61	The Application Programmer's Interface to Python gives C and
	62	C++ programmers access to the Python interpreter at a variety of
	63	levels. The API is equally usable from C++, but for brevity it is
	64	generally referred to as the Python/C API. There are two
65	fundamentally different reasons for using the Python/C API. The first
66	reason is to write <em>extension modules</em> for specific purposes;
67	these are C modules that extend the Python interpreter. This is
68	probably the most common use. The second reason is to use Python as a
69	component in a larger application; this technique is generally
70	referred to as <i class="dfn">embedding</i> Python in an application.
71
72	<P>
73	Writing an extension module is a relatively well-understood process,
74	where a ``cookbook'' approach works well. There are several tools
75	that automate the process to some extent. While people have embedded
76	Python in other applications since its early existence, the process of
77	embedding Python is less straightforward than writing an extension.
78
79	<P>
80	Many API functions are useful independent of whether you're embedding
81	or extending Python; moreover, most applications that embed Python
82	will need to provide a custom extension as well, so it's probably a
83	good idea to become familiar with writing an extension before
84	attempting to embed Python in a real application.
85
86	<P>
87
88	<p><br /></p><hr class='online-navigation' />
89	<div class='online-navigation'>
90	<!--Table of Child-Links-->
91	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
92
93	<UL CLASS="ChildLinks">
94	<LI><A href="includes.html">1.1 Include Files</a>
95	<LI><A href="objects.html">1.2 Objects, Types and Reference Counts</a>
96	<UL>
97	<LI><A href="refcounts.html">1.2.1 Reference Counts</a>
98	<UL>
99	<LI><A href="refcountDetails.html">1.2.1.1 Reference Count Details</a>
100	</ul>
101	<LI><A href="types.html">1.2.2 Types</a>
102	</ul>
103	<LI><A href="exceptions.html">1.3 Exceptions</a>
104	<LI><A href="embedding.html">1.4 Embedding Python</a>
105	</ul>
106	<!--End of Table of Child-Links-->
107	</div>
108
109	<DIV CLASS="navigation">
110	<div class='online-navigation'>
111	<p></p><hr />
112	<table align="center" width="100%" cellpadding="0" cellspacing="2">
113	<tr>
114	<td class='online-navigation'><a rel="prev" title="Contents"
115	href="contents.html"><img src='../icons/previous.png'
116	border='0' height='32' alt='Previous Page' width='32' /></A></td>
117	<td class='online-navigation'><a rel="parent" title="Python/C API Reference Manual"
118	href="api.html"><img src='../icons/up.png'
119	border='0' height='32' alt='Up One Level' width='32' /></A></td>
120	<td class='online-navigation'><a rel="next" title="1.1 Include Files"
121	href="includes.html"><img src='../icons/next.png'
122	border='0' height='32' alt='Next Page' width='32' /></A></td>
123	<td align="center" width="100%">Python/C API Reference Manual</td>
124	<td class='online-navigation'><a rel="contents" title="Table of Contents"
125	href="contents.html"><img src='../icons/contents.png'
126	border='0' height='32' alt='Contents' width='32' /></A></td>
127	<td class='online-navigation'><img src='../icons/blank.png'
128	border='0' height='32' alt='' width='32' /></td>
129	<td class='online-navigation'><a rel="index" title="Index"
130	href="genindex.html"><img src='../icons/index.png'
131	border='0' height='32' alt='Index' width='32' /></A></td>
132	</tr></table>
133	<div class='online-navigation'>
134	<b class="navlabel">Previous:</b>
135	<a class="sectref" rel="prev" href="contents.html">Contents</A>
136	<b class="navlabel">Up:</b>
137	<a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A>
138	<b class="navlabel">Next:</b>
139	<a class="sectref" rel="next" href="includes.html">1.1 Include Files</A>
140	</div>
141	</div>
142	<hr />
143	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
144	</DIV>
145	<!--End of Navigation Panel-->
146	<ADDRESS>
147	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
148	</ADDRESS>
149	</BODY>
150	</HTML>