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