/Doc/tutorial/interpreter.rst

  1.. _tut-using:
  2
  3****************************
  4Using the Python Interpreter
  5****************************
  6
  7
  8.. _tut-invoking:
  9
 10Invoking the Interpreter
 11========================
 12
 13The Python interpreter is usually installed as :file:`/usr/local/bin/python` on
 14those machines where it is available; putting :file:`/usr/local/bin` in your
 15Unix shell's search path makes it possible to start it by typing the command ::
 16
 17   python
 18
 19to the shell.  Since the choice of the directory where the interpreter lives is
 20an installation option, other places are possible; check with your local Python
 21guru or system administrator.  (E.g., :file:`/usr/local/python` is a popular
 22alternative location.)
 23
 24On Windows machines, the Python installation is usually placed in
 25:file:`C:\\Python26`, though you can change this when you're running the
 26installer.  To add this directory to your path,  you can type the following
 27command into the command prompt in a DOS box::
 28
 29   set path=%path%;C:\python26
 30
 31Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
 32Windows) at the primary prompt causes the interpreter to exit with a zero exit
 33status.  If that doesn't work, you can exit the interpreter by typing the
 34following commands: ``import sys; sys.exit()``.
 35
 36The interpreter's line-editing features usually aren't very sophisticated.  On
 37Unix, whoever installed the interpreter may have enabled support for the GNU
 38readline library, which adds more elaborate interactive editing and history
 39features. Perhaps the quickest check to see whether command line editing is
 40supported is typing Control-P to the first Python prompt you get.  If it beeps,
 41you have command line editing; see Appendix :ref:`tut-interacting` for an
 42introduction to the keys.  If nothing appears to happen, or if ``^P`` is echoed,
 43command line editing isn't available; you'll only be able to use backspace to
 44remove characters from the current line.
 45
 46The interpreter operates somewhat like the Unix shell: when called with standard
 47input connected to a tty device, it reads and executes commands interactively;
 48when called with a file name argument or with a file as standard input, it reads
 49and executes a *script* from that file.
 50
 51A second way of starting the interpreter is ``python -c command [arg] ...``,
 52which executes the statement(s) in *command*, analogous to the shell's
 53:option:`-c` option.  Since Python statements often contain spaces or other
 54characters that are special to the shell, it is usually advised to quote
 55*command* in its entirety with single quotes.
 56
 57Some Python modules are also useful as scripts.  These can be invoked using
 58``python -m module [arg] ...``, which executes the source file for *module* as
 59if you had spelled out its full name on the command line.
 60
 61Note that there is a difference between ``python file`` and ``python <file``.
 62In the latter case, input requests from the program, such as calls to
 63:func:`input` and :func:`raw_input`, are satisfied from *file*.  Since this file
 64has already been read until the end by the parser before the program starts
 65executing, the program will encounter end-of-file immediately.  In the former
 66case (which is usually what you want) they are satisfied from whatever file or
 67device is connected to standard input of the Python interpreter.
 68
 69When a script file is used, it is sometimes useful to be able to run the script
 70and enter interactive mode afterwards.  This can be done by passing :option:`-i`
 71before the script.  (This does not work if the script is read from standard
 72input, for the same reason as explained in the previous paragraph.)
 73
 74
 75.. _tut-argpassing:
 76
 77Argument Passing
 78----------------
 79
 80When known to the interpreter, the script name and additional arguments
 81thereafter are passed to the script in the variable ``sys.argv``, which is a
 82list of strings.  Its length is at least one; when no script and no arguments
 83are given, ``sys.argv[0]`` is an empty string.  When the script name is given as
 84``'-'`` (meaning  standard input), ``sys.argv[0]`` is set to ``'-'``.  When
 85:option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``.  When
 86:option:`-m` *module* is used, ``sys.argv[0]``  is set to the full name of the
 87located module.  Options found after  :option:`-c` *command* or :option:`-m`
 88*module* are not consumed  by the Python interpreter's option processing but
 89left in ``sys.argv`` for  the command or module to handle.
 90
 91
 92.. _tut-interactive:
 93
 94Interactive Mode
 95----------------
 96
 97When commands are read from a tty, the interpreter is said to be in *interactive
 98mode*.  In this mode it prompts for the next command with the *primary prompt*,
 99usually three greater-than signs (``>>>``); for continuation lines it prompts
100with the *secondary prompt*, by default three dots (``...``). The interpreter
101prints a welcome message stating its version number and a copyright notice
102before printing the first prompt::
103
104   python
105   Python 2.6 (#1, Feb 28 2007, 00:02:06)
106   Type "help", "copyright", "credits" or "license" for more information.
107   >>>
108
109Continuation lines are needed when entering a multi-line construct. As an
110example, take a look at this :keyword:`if` statement::
111
112   >>> the_world_is_flat = 1
113   >>> if the_world_is_flat:
114   ...     print "Be careful not to fall off!"
115   ...
116   Be careful not to fall off!
117
118
119.. _tut-interp:
120
121The Interpreter and Its Environment
122===================================
123
124
125.. _tut-error:
126
127Error Handling
128--------------
129
130When an error occurs, the interpreter prints an error message and a stack trace.
131In interactive mode, it then returns to the primary prompt; when input came from
132a file, it exits with a nonzero exit status after printing the stack trace.
133(Exceptions handled by an :keyword:`except` clause in a :keyword:`try` statement
134are not errors in this context.)  Some errors are unconditionally fatal and
135cause an exit with a nonzero exit; this applies to internal inconsistencies and
136some cases of running out of memory.  All error messages are written to the
137standard error stream; normal output from executed commands is written to
138standard output.
139
140Typing the interrupt character (usually Control-C or DEL) to the primary or
141secondary prompt cancels the input and returns to the primary prompt. [#]_
142Typing an interrupt while a command is executing raises the
143:exc:`KeyboardInterrupt` exception, which may be handled by a :keyword:`try`
144statement.
145
146
147.. _tut-scripts:
148
149Executable Python Scripts
150-------------------------
151
152On BSD'ish Unix systems, Python scripts can be made directly executable, like
153shell scripts, by putting the line ::
154
155   #! /usr/bin/env python
156
157(assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning
158of the script and giving the file an executable mode.  The ``#!`` must be the
159first two characters of the file.  On some platforms, this first line must end
160with a Unix-style line ending (``'\n'``), not a Windows (``'\r\n'``) line
161ending.  Note that the hash, or pound, character, ``'#'``, is used to start a
162comment in Python.
163
164The script can be given an executable mode, or permission, using the
165:program:`chmod` command::
166
167   $ chmod +x myscript.py
168
169On Windows systems, there is no notion of an "executable mode".  The Python
170installer automatically associates ``.py`` files with ``python.exe`` so that
171a double-click on a Python file will run it as a script.  The extension can
172also be ``.pyw``, in that case, the console window that normally appears is
173suppressed.
174
175
176Source Code Encoding
177--------------------
178
179It is possible to use encodings different than ASCII in Python source files. The
180best way to do it is to put one more special comment line right after the ``#!``
181line to define the source file encoding::
182
183   # -*- coding: encoding -*-
184
185
186With that declaration, all characters in the source file will be treated as
187having the encoding *encoding*, and it will be possible to directly write
188Unicode string literals in the selected encoding.  The list of possible
189encodings can be found in the Python Library Reference, in the section on
190:mod:`codecs`.
191
192For example, to write Unicode literals including the Euro currency symbol, the
193ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value
194164.  This script will print the value 8364 (the Unicode codepoint corresponding
195to the Euro symbol) and then exit::
196
197   # -*- coding: iso-8859-15 -*-
198
199   currency = u"€"
200   print ord(currency)
201
202If your editor supports saving files as ``UTF-8`` with a UTF-8 *byte order mark*
203(aka BOM), you can use that instead of an encoding declaration. IDLE supports
204this capability if ``Options/General/Default Source Encoding/UTF-8`` is set.
205Notice that this signature is not understood in older Python releases (2.2 and
206earlier), and also not understood by the operating system for script files with
207``#!`` lines (only used on Unix systems).
208
209By using UTF-8 (either through the signature or an encoding declaration),
210characters of most languages in the world can be used simultaneously in string
211literals and comments.  Using non-ASCII characters in identifiers is not
212supported. To display all these characters properly, your editor must recognize
213that the file is UTF-8, and it must use a font that supports all the characters
214in the file.
215
216
217.. _tut-startup:
218
219The Interactive Startup File
220----------------------------
221
222When you use Python interactively, it is frequently handy to have some standard
223commands executed every time the interpreter is started.  You can do this by
224setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
225file containing your start-up commands.  This is similar to the :file:`.profile`
226feature of the Unix shells.
227
228.. XXX This should probably be dumped in an appendix, since most people
229   don't use Python interactively in non-trivial ways.
230
231This file is only read in interactive sessions, not when Python reads commands
232from a script, and not when :file:`/dev/tty` is given as the explicit source of
233commands (which otherwise behaves like an interactive session).  It is executed
234in the same namespace where interactive commands are executed, so that objects
235that it defines or imports can be used without qualification in the interactive
236session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this
237file.
238
239If you want to read an additional start-up file from the current directory, you
240can program this in the global start-up file using code like ``if
241os.path.isfile('.pythonrc.py'): execfile('.pythonrc.py')``.  If you want to use
242the startup file in a script, you must do this explicitly in the script::
243
244   import os
245   filename = os.environ.get('PYTHONSTARTUP')
246   if filename and os.path.isfile(filename):
247       execfile(filename)
248
249
250.. rubric:: Footnotes
251
252.. [#] A problem with the GNU Readline package may prevent this.
253