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="tut.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="tut.html" title='Python Tutorial' /> | |
8 | <link rel='contents' href='node2.html' title="Contents" /> | |
9 | <link rel='index' href='node19.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="node5.html" /> | |
13 | <link rel="prev" href="node3.html" /> | |
14 | <link rel="parent" href="tut.html" /> | |
15 | <link rel="next" href="node5.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>2. Using the Python Interpreter </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="1. Whetting Your Appetite" | |
25 | href="node3.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 Tutorial" | |
28 | href="tut.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="3. An Informal Introduction" | |
31 | href="node5.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 Tutorial</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="node2.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="node19.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="node3.html">1. Whetting Your Appetite</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="tut.html">Python Tutorial</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="node5.html">3. An Informal Introduction</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | <div class='online-navigation'> | |
55 | <!--Table of Child-Links--> | |
56 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
57 | ||
58 | <UL CLASS="ChildLinks"> | |
59 | <LI><A href="node4.html#SECTION004100000000000000000">2.1 Invoking the Interpreter</a> | |
60 | <UL> | |
61 | <LI><A href="node4.html#SECTION004110000000000000000">2.1.1 Argument Passing</a> | |
62 | <LI><A href="node4.html#SECTION004120000000000000000">2.1.2 Interactive Mode</a> | |
63 | </ul> | |
64 | <LI><A href="node4.html#SECTION004200000000000000000">2.2 The Interpreter and Its Environment</a> | |
65 | <UL> | |
66 | <LI><A href="node4.html#SECTION004210000000000000000">2.2.1 Error Handling</a> | |
67 | <LI><A href="node4.html#SECTION004220000000000000000">2.2.2 Executable Python Scripts</a> | |
68 | <LI><A href="node4.html#SECTION004230000000000000000">2.2.3 Source Code Encoding</a> | |
69 | <LI><A href="node4.html#SECTION004240000000000000000">2.2.4 The Interactive Startup File</a> | |
70 | </ul></ul> | |
71 | <!--End of Table of Child-Links--> | |
72 | </div> | |
73 | <HR> | |
74 | ||
75 | <H1><A NAME="SECTION004000000000000000000"></A><A NAME="using"></A> | |
76 | <BR> | |
77 | 2. Using the Python Interpreter | |
78 | </H1> | |
79 | ||
80 | <P> | |
81 | ||
82 | <H1><A NAME="SECTION004100000000000000000"></A><A NAME="invoking"></A> | |
83 | <BR> | |
84 | 2.1 Invoking the Interpreter | |
85 | </H1> | |
86 | ||
87 | <P> | |
88 | The Python interpreter is usually installed as | |
89 | <span class="file">/usr/local/bin/python</span> on those machines where it is available; | |
90 | putting <span class="file">/usr/local/bin</span> in your <span class="Unix">Unix</span> shell's search path | |
91 | makes it possible to start it by typing the command | |
92 | ||
93 | <P> | |
94 | <div class="verbatim"><pre> | |
95 | python | |
96 | </pre></div> | |
97 | ||
98 | <P> | |
99 | to the shell. Since the choice of the directory where the interpreter | |
100 | lives is an installation option, other places are possible; check with | |
101 | your local Python guru or system administrator. (E.g., | |
102 | <span class="file">/usr/local/python</span> is a popular alternative location.) | |
103 | ||
104 | <P> | |
105 | Typing an end-of-file character (<kbd>Control-D</kbd> on <span class="Unix">Unix</span>, | |
106 | <kbd>Control-Z</kbd> on Windows) at the primary prompt causes the | |
107 | interpreter to exit with a zero exit status. If that doesn't work, | |
108 | you can exit the interpreter by typing the following commands: | |
109 | "<tt class="samp">import sys; sys.exit()</tt>". | |
110 | ||
111 | <P> | |
112 | The interpreter's line-editing features usually aren't very | |
113 | sophisticated. On <span class="Unix">Unix</span>, whoever installed the interpreter may have | |
114 | enabled support for the GNU readline library, which adds more | |
115 | elaborate interactive editing and history features. Perhaps the | |
116 | quickest check to see whether command line editing is supported is | |
117 | typing Control-P to the first Python prompt you get. If it beeps, you | |
118 | have command line editing; see Appendix <A HREF="node15.html#interacting">A</A> for an | |
119 | introduction to the keys. If nothing appears to happen, or if | |
120 | <code>P</code> is echoed, command line editing isn't available; you'll | |
121 | only be able to use backspace to remove characters from the current | |
122 | line. | |
123 | ||
124 | <P> | |
125 | The interpreter operates somewhat like the <span class="Unix">Unix</span> shell: when called | |
126 | with standard input connected to a tty device, it reads and executes | |
127 | commands interactively; when called with a file name argument or with | |
128 | a file as standard input, it reads and executes a <em>script</em> from | |
129 | that file. | |
130 | ||
131 | <P> | |
132 | A second way of starting the interpreter is | |
133 | "<tt class="samp"><b class="program">python</b> <b class="programopt">-c</b> <var>command</var> [arg] ...</tt>", which | |
134 | executes the statement(s) in <var>command</var>, analogous to the shell's | |
135 | <b class="programopt">-c</b> option. Since Python statements often contain spaces | |
136 | or other characters that are special to the shell, it is best to quote | |
137 | <var>command</var> in its entirety with double quotes. | |
138 | ||
139 | <P> | |
140 | Some Python modules are also useful as scripts. These can be invoked using | |
141 | "<tt class="samp"><b class="program">python</b> <b class="programopt">-m</b> <var>module</var> [arg] ...</tt>", which | |
142 | executes the source file for <var>module</var> as if you had spelled out its | |
143 | full name on the command line. | |
144 | ||
145 | <P> | |
146 | Note that there is a difference between "<tt class="samp">python file</tt>" and | |
147 | "<tt class="samp">python <file</tt>". In the latter case, input requests from the | |
148 | program, such as calls to <tt class="function">input()</tt> and <tt class="function">raw_input()</tt>, are | |
149 | satisfied from <em>file</em>. Since this file has already been read | |
150 | until the end by the parser before the program starts executing, the | |
151 | program will encounter end-of-file immediately. In the former case | |
152 | (which is usually what you want) they are satisfied from whatever file | |
153 | or device is connected to standard input of the Python interpreter. | |
154 | ||
155 | <P> | |
156 | When a script file is used, it is sometimes useful to be able to run | |
157 | the script and enter interactive mode afterwards. This can be done by | |
158 | passing <b class="programopt">-i</b> before the script. (This does not work if the | |
159 | script is read from standard input, for the same reason as explained | |
160 | in the previous paragraph.) | |
161 | ||
162 | <P> | |
163 | ||
164 | <H2><A NAME="SECTION004110000000000000000"></A><A NAME="argPassing"></A> | |
165 | <BR> | |
166 | 2.1.1 Argument Passing | |
167 | </H2> | |
168 | ||
169 | <P> | |
170 | When known to the interpreter, the script name and additional | |
171 | arguments thereafter are passed to the script in the variable | |
172 | <code>sys.argv</code>, which is a list of strings. Its length is at least | |
173 | one; when no script and no arguments are given, <code>sys.argv[0]</code> is | |
174 | an empty string. When the script name is given as <code>'-'</code> (meaning | |
175 | standard input), <code>sys.argv[0]</code> is set to <code>'-'</code>. When | |
176 | <b class="programopt">-c</b> <var>command</var> is used, <code>sys.argv[0]</code> is set to | |
177 | <code>'-c'</code>. When <b class="programopt">-m</b> <var>module</var> is used, <code>sys.argv[0]</code> | |
178 | is set to the full name of the located module. Options found after | |
179 | <b class="programopt">-c</b> <var>command</var> or <b class="programopt">-m</b> <var>module</var> are not consumed | |
180 | by the Python interpreter's option processing but left in <code>sys.argv</code> for | |
181 | the command or module to handle. | |
182 | ||
183 | <P> | |
184 | ||
185 | <H2><A NAME="SECTION004120000000000000000"></A><A NAME="interactive"></A> | |
186 | <BR> | |
187 | 2.1.2 Interactive Mode | |
188 | </H2> | |
189 | ||
190 | <P> | |
191 | When commands are read from a tty, the interpreter is said to be in | |
192 | <em>interactive mode</em>. In this mode it prompts for the next command | |
193 | with the <em>primary prompt</em>, usually three greater-than signs | |
194 | ("<tt class="samp">><code>></code>> </tt>"); for continuation lines it prompts with the | |
195 | <em>secondary prompt</em>, by default three dots ("<tt class="samp">... </tt>"). | |
196 | The interpreter prints a welcome message stating its version number | |
197 | and a copyright notice before printing the first prompt: | |
198 | ||
199 | <P> | |
200 | <div class="verbatim"><pre> | |
201 | python | |
202 | Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06) [GCC 2.8.1] on sunos5 | |
203 | Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam | |
204 | >>> | |
205 | </pre></div> | |
206 | ||
207 | <P> | |
208 | Continuation lines are needed when entering a multi-line construct. | |
209 | As an example, take a look at this <tt class="keyword">if</tt> statement: | |
210 | ||
211 | <P> | |
212 | <div class="verbatim"><pre> | |
213 | >>> the_world_is_flat = 1 | |
214 | >>> if the_world_is_flat: | |
215 | ... print "Be careful not to fall off!" | |
216 | ... | |
217 | Be careful not to fall off! | |
218 | </pre></div> | |
219 | ||
220 | <P> | |
221 | ||
222 | <H1><A NAME="SECTION004200000000000000000"></A><A NAME="interp"></A> | |
223 | <BR> | |
224 | 2.2 The Interpreter and Its Environment | |
225 | </H1> | |
226 | ||
227 | <P> | |
228 | ||
229 | <H2><A NAME="SECTION004210000000000000000"></A><A NAME="error"></A> | |
230 | <BR> | |
231 | 2.2.1 Error Handling | |
232 | </H2> | |
233 | ||
234 | <P> | |
235 | When an error occurs, the interpreter prints an error | |
236 | message and a stack trace. In interactive mode, it then returns to | |
237 | the primary prompt; when input came from a file, it exits with a | |
238 | nonzero exit status after printing | |
239 | the stack trace. (Exceptions handled by an <tt class="keyword">except</tt> clause in a | |
240 | <tt class="keyword">try</tt> statement are not errors in this context.) Some errors are | |
241 | unconditionally fatal and cause an exit with a nonzero exit; this | |
242 | applies to internal inconsistencies and some cases of running out of | |
243 | memory. All error messages are written to the standard error stream; | |
244 | normal output from executed commands is written to standard | |
245 | output. | |
246 | ||
247 | <P> | |
248 | Typing the interrupt character (usually Control-C or DEL) to the | |
249 | primary or secondary prompt cancels the input and returns to the | |
250 | primary prompt.<A NAME="tex2html1" | |
251 | HREF="#foot123"><SUP>2.1</SUP></A>Typing an interrupt while a command is executing raises the | |
252 | <tt class="exception">KeyboardInterrupt</tt> exception, which may be handled by a | |
253 | <tt class="keyword">try</tt> statement. | |
254 | ||
255 | <P> | |
256 | ||
257 | <H2><A NAME="SECTION004220000000000000000"></A><A NAME="scripts"></A> | |
258 | <BR> | |
259 | 2.2.2 Executable Python Scripts | |
260 | </H2> | |
261 | ||
262 | <P> | |
263 | On BSD'ish <span class="Unix">Unix</span> systems, Python scripts can be made directly | |
264 | executable, like shell scripts, by putting the line | |
265 | ||
266 | <P> | |
267 | <div class="verbatim"><pre> | |
268 | #! /usr/bin/env python | |
269 | </pre></div> | |
270 | ||
271 | <P> | |
272 | (assuming that the interpreter is on the user's <a class="envvar" id='l2h-1' xml:id='l2h-1'>PATH</a>) at the | |
273 | beginning of the script and giving the file an executable mode. The | |
274 | "<tt class="samp">#!</tt>" must be the first two characters of the file. On some | |
275 | platforms, this first line must end with a <span class="Unix">Unix</span>-style line ending | |
276 | ("<tt class="character">\n</tt>"), not a Mac OS ("<tt class="character">\r</tt>") or Windows | |
277 | ("<tt class="character">\r\n</tt>") line ending. Note that | |
278 | the hash, or pound, character, "<tt class="character">#</tt>", is used to start a | |
279 | comment in Python. | |
280 | ||
281 | <P> | |
282 | The script can be given a executable mode, or permission, using the | |
283 | <b class="program">chmod</b> command: | |
284 | ||
285 | <P> | |
286 | <div class="verbatim"><pre> | |
287 | $ chmod +x myscript.py | |
288 | </pre></div> | |
289 | <P> | |
290 | ||
291 | <H2><A NAME="SECTION004230000000000000000"> | |
292 | 2.2.3 Source Code Encoding</A> | |
293 | </H2> | |
294 | ||
295 | <P> | |
296 | It is possible to use encodings different than ASCII in Python source | |
297 | files. The best way to do it is to put one more special comment line | |
298 | right after the <code>#!</code> line to define the source file encoding: | |
299 | ||
300 | <P> | |
301 | <div class="verbatim"><pre><TT> | |
302 | # -*- coding: <var>encoding</var> -*- | |
303 | </TT></pre></div> | |
304 | ||
305 | <P> | |
306 | With that declaration, all characters in the source file will be treated as | |
307 | having the encoding <var>encoding</var>, and it will be | |
308 | possible to directly write Unicode string literals in the selected | |
309 | encoding. The list of possible encodings can be found in the | |
310 | <em class="citetitle"><a | |
311 | href="../lib/lib.html" | |
312 | title="Python Library Reference" | |
313 | >Python Library Reference</a></em>, in the section | |
314 | on <a class="ulink" href="../lib/module-codecs.html" | |
315 | ><tt class="module">codecs</tt></a>. | |
316 | ||
317 | <P> | |
318 | For example, to write Unicode literals including the Euro currency | |
319 | symbol, the ISO-8859-15 encoding can be used, with the Euro symbol | |
320 | having the ordinal value 164. This script will print the value 8364 | |
321 | (the Unicode codepoint corresponding to the Euro symbol) and then | |
322 | exit: | |
323 | ||
324 | <P> | |
325 | <div class="verbatim"><pre><TT> | |
326 | # -*- coding: iso-8859-15 -*- | |
327 | ||
328 | currency = u"€" | |
329 | print ord(currency) | |
330 | </TT></pre></div> | |
331 | ||
332 | <P> | |
333 | If your editor supports saving files as <code>UTF-8</code> with a UTF-8 | |
334 | <em>byte order mark</em> (aka BOM), you can use that instead of an | |
335 | encoding declaration. IDLE supports this capability if | |
336 | <code>Options/General/Default Source Encoding/UTF-8</code> is set. Notice | |
337 | that this signature is not understood in older Python releases (2.2 | |
338 | and earlier), and also not understood by the operating system for | |
339 | script files with <code>#!</code> lines (only used on <span class="Unix">Unix</span> systems). | |
340 | ||
341 | <P> | |
342 | By using UTF-8 (either through the signature or an encoding | |
343 | declaration), characters of most languages in the world can be used | |
344 | simultaneously in string literals and comments. Using non-ASCII | |
345 | characters in identifiers is not supported. To display all these | |
346 | characters properly, your editor must recognize that the file is | |
347 | UTF-8, and it must use a font that supports all the characters in the | |
348 | file. | |
349 | ||
350 | <P> | |
351 | ||
352 | <H2><A NAME="SECTION004240000000000000000"></A><A NAME="startup"></A> | |
353 | <BR> | |
354 | 2.2.4 The Interactive Startup File | |
355 | </H2> | |
356 | ||
357 | <P> | |
358 | When you use Python interactively, it is frequently handy to have some | |
359 | standard commands executed every time the interpreter is started. You | |
360 | can do this by setting an environment variable named | |
361 | <a class="envvar" id='l2h-2' xml:id='l2h-2'>PYTHONSTARTUP</a> to the name of a file containing your start-up | |
362 | commands. This is similar to the <span class="file">.profile</span> feature of the | |
363 | <span class="Unix">Unix</span> shells. | |
364 | ||
365 | <P> | |
366 | This file is only read in interactive sessions, not when Python reads | |
367 | commands from a script, and not when <span class="file">/dev/tty</span> is given as the | |
368 | explicit source of commands (which otherwise behaves like an | |
369 | interactive session). It is executed in the same namespace where | |
370 | interactive commands are executed, so that objects that it defines or | |
371 | imports can be used without qualification in the interactive session. | |
372 | You can also change the prompts <code>sys.ps1</code> and <code>sys.ps2</code> in | |
373 | this file. | |
374 | ||
375 | <P> | |
376 | If you want to read an additional start-up file from the current | |
377 | directory, you can program this in the global start-up file using code | |
378 | like "<tt class="samp">if os.path.isfile('.pythonrc.py'): | |
379 | execfile('.pythonrc.py')</tt>". If you want to use the startup file in a | |
380 | script, you must do this explicitly in the script: | |
381 | ||
382 | <P> | |
383 | <div class="verbatim"><pre> | |
384 | import os | |
385 | filename = os.environ.get('PYTHONSTARTUP') | |
386 | if filename and os.path.isfile(filename): | |
387 | execfile(filename) | |
388 | </pre></div> | |
389 | ||
390 | <P> | |
391 | <BR><HR><H4>Footnotes</H4> | |
392 | <DL> | |
393 | <DT><A NAME="foot123">... prompt.</A><A | |
394 | HREF="node4.html#tex2html1"><SUP>2.1</SUP></A></DT> | |
395 | <DD> | |
396 | A problem with the GNU Readline package may prevent this. | |
397 | ||
398 | ||
399 | </DD> | |
400 | </DL> | |
401 | <DIV CLASS="navigation"> | |
402 | <div class='online-navigation'> | |
403 | <p></p><hr /> | |
404 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
405 | <tr> | |
406 | <td class='online-navigation'><a rel="prev" title="1. Whetting Your Appetite" | |
407 | href="node3.html"><img src='../icons/previous.png' | |
408 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
409 | <td class='online-navigation'><a rel="parent" title="Python Tutorial" | |
410 | href="tut.html"><img src='../icons/up.png' | |
411 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
412 | <td class='online-navigation'><a rel="next" title="3. An Informal Introduction" | |
413 | href="node5.html"><img src='../icons/next.png' | |
414 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
415 | <td align="center" width="100%">Python Tutorial</td> | |
416 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
417 | href="node2.html"><img src='../icons/contents.png' | |
418 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
419 | <td class='online-navigation'><img src='../icons/blank.png' | |
420 | border='0' height='32' alt='' width='32' /></td> | |
421 | <td class='online-navigation'><a rel="index" title="Index" | |
422 | href="node19.html"><img src='../icons/index.png' | |
423 | border='0' height='32' alt='Index' width='32' /></A></td> | |
424 | </tr></table> | |
425 | <div class='online-navigation'> | |
426 | <b class="navlabel">Previous:</b> | |
427 | <a class="sectref" rel="prev" href="node3.html">1. Whetting Your Appetite</A> | |
428 | <b class="navlabel">Up:</b> | |
429 | <a class="sectref" rel="parent" href="tut.html">Python Tutorial</A> | |
430 | <b class="navlabel">Next:</b> | |
431 | <a class="sectref" rel="next" href="node5.html">3. An Informal Introduction</A> | |
432 | </div> | |
433 | </div> | |
434 | <hr /> | |
435 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
436 | </DIV> | |
437 | <!--End of Navigation Panel--> | |
438 | <ADDRESS> | |
439 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
440 | </ADDRESS> | |
441 | </BODY> | |
442 | </HTML> |