Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / ref / import.html
CommitLineData
86530b38
AT
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="ref.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="ref.html" title='Python 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="global.html" />
13<link rel="prev" href="continue.html" />
14<link rel="parent" href="simple.html" />
15<link rel="next" href="future.html" />
16<meta name='aesop' content='information' />
17<title>6.12 The import statement </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="6.11 The continue statement"
25 href="continue.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="6. Simple statements"
28 href="simple.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="6.12.1 Future statements"
31 href="future.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 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="continue.html">6.11 The continue statement</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="simple.html">6. Simple statements</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="future.html">6.12.1 Future statements</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION0081200000000000000000"></A><A NAME="import"></A>
56<BR>
576.12 The <tt class="keyword">import</tt> statement
58</H1>
59<a id='l2h-529' xml:id='l2h-529'></a><a id='l2h-550' xml:id='l2h-550'></a>
60<a id='l2h-530' xml:id='l2h-530'></a><a id='l2h-531' xml:id='l2h-531'></a>
61<P>
62<dl><dd class="grammar">
63<div class="productions">
64<table>
65<tr>
66 <td><a id='tok-import_stmt' xml:id='tok-import_stmt'>import_stmt</a></td>
67 <td>::=</td>
68 <td>"import" <a class='grammartoken' href="import.html#tok-module">module</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>]
69 ( "," <a class='grammartoken' href="import.html#tok-module">module</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] )*</td></tr>
70 <tr>
71 <td></td>
72 <td></td>
73 <td><code>| "from" <a class='grammartoken' href="import.html#tok-module">module</a> "import" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a>
74 ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>]</code></td></tr>
75 <tr>
76 <td></td>
77 <td></td>
78 <td><code>&nbsp;&nbsp;( "," <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] )*</code></td></tr>
79 <tr>
80 <td></td>
81 <td></td>
82 <td><code>| "from" <a class='grammartoken' href="import.html#tok-module">module</a> "import" "(" <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a>
83 ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>]</code></td></tr>
84 <tr>
85 <td></td>
86 <td></td>
87 <td><code>&nbsp;&nbsp;( "," <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ["as" <a class='grammartoken' href="notation.html#tok-name">name</a>] )* [","] ")"</code></td></tr>
88 <tr>
89 <td></td>
90 <td></td>
91 <td><code>| "from" <a class='grammartoken' href="import.html#tok-module">module</a> "import" "*"</code></td></tr>
92 <tr>
93 <td><a id='tok-module' xml:id='tok-module'>module</a></td>
94 <td>::=</td>
95 <td>(<a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a> ".")* <a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a></td></tr>
96</table>
97</div>
98<a class="grammar-footer"
99 href="grammar.txt" type="text/plain"
100 >Download entire grammar as text.</a>
101</dd></dl>
102
103<P>
104Import statements are executed in two steps: (1) find a module, and
105initialize it if necessary; (2) define a name or names in the local
106namespace (of the scope where the <tt class="keyword">import</tt> statement occurs).
107The first form (without <tt class="keyword">from</tt>) repeats these steps for each
108identifier in the list. The form with <tt class="keyword">from</tt> performs step
109(1) once, and then performs step (2) repeatedly.
110
111<P>
112In this context, to ``initialize'' a built-in or extension module means to
113call an initialization function that the module must provide for the purpose
114(in the reference implementation, the function's name is obtained by
115prepending string ``init'' to the module's name); to ``initialize'' a
116Python-coded module means to execute the module's body.
117
118<P>
119The system maintains a table of modules that have been or are being
120initialized,
121indexed by module name. This table is
122accessible as <code>sys.modules</code>. When a module name is found in
123this table, step (1) is finished. If not, a search for a module
124definition is started. When a module is found, it is loaded. Details
125of the module searching and loading process are implementation and
126platform specific. It generally involves searching for a ``built-in''
127module with the given name and then searching a list of locations
128given as <code>sys.path</code>.
129<a id='l2h-533' xml:id='l2h-533'></a><a id='l2h-551' xml:id='l2h-551'></a>
130<a id='l2h-534' xml:id='l2h-534'></a><a id='l2h-535' xml:id='l2h-535'></a><a id='l2h-536' xml:id='l2h-536'></a><a id='l2h-552' xml:id='l2h-552'></a>
131<a id='l2h-537' xml:id='l2h-537'></a><a id='l2h-538' xml:id='l2h-538'></a>
132<P>
133If a built-in module is found,<a id='l2h-539' xml:id='l2h-539'></a> its
134built-in initialization code is executed and step (1) is finished. If
135no matching file is found,
136<tt class="exception">ImportError</tt><a id='l2h-540' xml:id='l2h-540'></a> is raised.
137<a id='l2h-553' xml:id='l2h-553'></a>If a file is found, it is parsed,
138yielding an executable code block. If a syntax error occurs,
139<tt class="exception">SyntaxError</tt><a id='l2h-541' xml:id='l2h-541'></a> is raised. Otherwise, an
140empty module of the given name is created and inserted in the module
141table, and then the code block is executed in the context of this
142module. Exceptions during this execution terminate step (1).
143
144<P>
145When step (1) finishes without raising an exception, step (2) can
146begin.
147
148<P>
149The first form of <tt class="keyword">import</tt> statement binds the module name in
150the local namespace to the module object, and then goes on to import
151the next identifier, if any. If the module name is followed by
152<tt class="keyword">as</tt>, the name following <tt class="keyword">as</tt> is used as the local
153name for the module.
154
155<P>
156The <tt class="keyword">from</tt> form does not bind the module name: it goes through the
157list of identifiers, looks each one of them up in the module found in step
158(1), and binds the name in the local namespace to the object thus found.
159As with the first form of <tt class="keyword">import</tt>, an alternate local name can be
160supplied by specifying "<tt class="keyword">as</tt> localname". If a name is not found,
161<tt class="exception">ImportError</tt> is raised. If the list of identifiers is replaced
162by a star ("<tt class="character">*</tt>"), all public names defined in the module are
163bound in the local namespace of the <tt class="keyword">import</tt> statement..
164<a id='l2h-542' xml:id='l2h-542'></a><a id='l2h-543' xml:id='l2h-543'></a>
165<P>
166The <em>public names</em> defined by a module are determined by checking
167the module's namespace for a variable named <code>__all__</code>; if
168defined, it must be a sequence of strings which are names defined or
169imported by that module. The names given in <code>__all__</code> are all
170considered public and are required to exist. If <code>__all__</code> is not
171defined, the set of public names includes all names found in the
172module's namespace which do not begin with an underscore character
173("<tt class="character">_</tt>"). <code>__all__</code> should contain the entire public API.
174It is intended to avoid accidentally exporting items that are not part
175of the API (such as library modules which were imported and used within
176the module).
177<a id='l2h-545' xml:id='l2h-545'></a>
178<P>
179The <tt class="keyword">from</tt> form with "<tt class="samp">*</tt>" may only occur in a module
180scope. If the wild card form of import -- "<tt class="samp">import *</tt>" -- is
181used in a function and the function contains or is a nested block with
182free variables, the compiler will raise a <tt class="exception">SyntaxError</tt>.
183
184<P>
185<a id='l2h-546' xml:id='l2h-546'></a><a id='l2h-547' xml:id='l2h-547'></a>
186<P>
187<strong>Hierarchical module names:</strong><a id='l2h-548' xml:id='l2h-548'></a>when the module names contains one or more dots, the module search
188path is carried out differently. The sequence of identifiers up to
189the last dot is used to find a ``package''<a id='l2h-554' xml:id='l2h-554'></a>; the final
190identifier is then searched inside the package. A package is
191generally a subdirectory of a directory on <code>sys.path</code> that has a
192file <span class="file">__init__.py</span>.<a id='l2h-555' xml:id='l2h-555'></a>
193[XXX Can't be bothered to spell this out right now; see the URL
194<a class="url" href="http://www.python.org/doc/essays/packages.html">http://www.python.org/doc/essays/packages.html</a> for more details, also
195about how the module search works from inside a package.]
196
197<P>
198The built-in function <tt class="function">__import__()</tt> is provided to support
199applications that determine which modules need to be loaded
200dynamically; refer to <a class="ulink" href="../lib/built-in-funcs.html"
201 >Built-in
202Functions</a> in the
203<em class="citetitle"><a
204 href="../lib/lib.html"
205 title="Python Library Reference"
206 >Python Library Reference</a></em> for additional
207information.
208<a id='l2h-549' xml:id='l2h-549'></a>
209<P>
210
211<p><br /></p><hr class='online-navigation' />
212<div class='online-navigation'>
213<!--Table of Child-Links-->
214<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
215
216<UL CLASS="ChildLinks">
217<LI><A href="future.html">6.12.1 Future statements</a>
218</ul>
219<!--End of Table of Child-Links-->
220</div>
221
222<DIV CLASS="navigation">
223<div class='online-navigation'>
224<p></p><hr />
225<table align="center" width="100%" cellpadding="0" cellspacing="2">
226<tr>
227<td class='online-navigation'><a rel="prev" title="6.11 The continue statement"
228 href="continue.html"><img src='../icons/previous.png'
229 border='0' height='32' alt='Previous Page' width='32' /></A></td>
230<td class='online-navigation'><a rel="parent" title="6. Simple statements"
231 href="simple.html"><img src='../icons/up.png'
232 border='0' height='32' alt='Up One Level' width='32' /></A></td>
233<td class='online-navigation'><a rel="next" title="6.12.1 Future statements"
234 href="future.html"><img src='../icons/next.png'
235 border='0' height='32' alt='Next Page' width='32' /></A></td>
236<td align="center" width="100%">Python Reference Manual</td>
237<td class='online-navigation'><a rel="contents" title="Table of Contents"
238 href="contents.html"><img src='../icons/contents.png'
239 border='0' height='32' alt='Contents' width='32' /></A></td>
240<td class='online-navigation'><img src='../icons/blank.png'
241 border='0' height='32' alt='' width='32' /></td>
242<td class='online-navigation'><a rel="index" title="Index"
243 href="genindex.html"><img src='../icons/index.png'
244 border='0' height='32' alt='Index' width='32' /></A></td>
245</tr></table>
246<div class='online-navigation'>
247<b class="navlabel">Previous:</b>
248<a class="sectref" rel="prev" href="continue.html">6.11 The continue statement</A>
249<b class="navlabel">Up:</b>
250<a class="sectref" rel="parent" href="simple.html">6. Simple statements</A>
251<b class="navlabel">Next:</b>
252<a class="sectref" rel="next" href="future.html">6.12.1 Future statements</A>
253</div>
254</div>
255<hr />
256<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
257</DIV>
258<!--End of Navigation Panel-->
259<ADDRESS>
260See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
261</ADDRESS>
262</BODY>
263</HTML>