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 | 08a9012 | 2012-09-29 09:34:13 +0200 | [diff] [blame] | 13 | The Python interpreter is usually installed as :file:`/usr/local/bin/python3.4` |
Georg Brandl | 3db38ce | 2008-08-30 09:58:30 +0000 | [diff] [blame] | 14 | on those machines where it is available; putting :file:`/usr/local/bin` in your |
Chris Jerdonek | df12f2b | 2012-09-25 04:20:29 -0700 | [diff] [blame] | 15 | Unix shell's search path makes it possible to start it by typing the command: |
| 16 | |
| 17 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Georg Brandl | 08a9012 | 2012-09-29 09:34:13 +0200 | [diff] [blame] | 19 | python3.4 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
Georg Brandl | 3db38ce | 2008-08-30 09:58:30 +0000 | [diff] [blame] | 21 | to the shell. [#]_ Since the choice of the directory where the interpreter lives |
| 22 | is an installation option, other places are possible; check with your local |
| 23 | Python guru or system administrator. (E.g., :file:`/usr/local/python` is a |
| 24 | popular alternative location.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | |
| 26 | On Windows machines, the Python installation is usually placed in |
Georg Brandl | 08a9012 | 2012-09-29 09:34:13 +0200 | [diff] [blame] | 27 | :file:`C:\\Python34`, though you can change this when you're running the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | installer. To add this directory to your path, you can type the following |
| 29 | command into the command prompt in a DOS box:: |
| 30 | |
Georg Brandl | 08a9012 | 2012-09-29 09:34:13 +0200 | [diff] [blame] | 31 | set path=%path%;C:\python34 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
| 33 | Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on |
| 34 | Windows) at the primary prompt causes the interpreter to exit with a zero exit |
| 35 | status. If that doesn't work, you can exit the interpreter by typing the |
Benjamin Peterson | 4ac9ce4 | 2009-10-04 14:49:41 +0000 | [diff] [blame] | 36 | following command: ``quit()``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
R David Murray | 0e0e391 | 2014-04-15 20:25:18 -0400 | [diff] [blame] | 38 | The interpreter's line-editing features include interactive editing, history |
R David Murray | fc1020d | 2014-04-15 20:26:54 -0400 | [diff] [blame] | 39 | substitution and code completion on systems that support readline. Perhaps the |
| 40 | quickest check to see whether command line editing is supported is typing |
| 41 | Control-P to the first Python prompt you get. If it beeps, you have command |
| 42 | line editing; see Appendix :ref:`tut-interacting` for an introduction to the |
| 43 | keys. If nothing appears to happen, or if ``^P`` is echoed, command line |
| 44 | editing isn't available; you'll only be able to use backspace to remove |
| 45 | characters from the current line. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
| 47 | The interpreter operates somewhat like the Unix shell: when called with standard |
| 48 | input connected to a tty device, it reads and executes commands interactively; |
| 49 | when called with a file name argument or with a file as standard input, it reads |
| 50 | and executes a *script* from that file. |
| 51 | |
| 52 | A second way of starting the interpreter is ``python -c command [arg] ...``, |
| 53 | which executes the statement(s) in *command*, analogous to the shell's |
| 54 | :option:`-c` option. Since Python statements often contain spaces or other |
Georg Brandl | f08a9dd | 2008-06-10 16:57:31 +0000 | [diff] [blame] | 55 | characters that are special to the shell, it is usually advised to quote |
| 56 | *command* in its entirety with single quotes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | Some Python modules are also useful as scripts. These can be invoked using |
| 59 | ``python -m module [arg] ...``, which executes the source file for *module* as |
| 60 | if you had spelled out its full name on the command line. |
| 61 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | When a script file is used, it is sometimes useful to be able to run the script |
| 63 | and enter interactive mode afterwards. This can be done by passing :option:`-i` |
Sandro Tosi | 69e59a1 | 2011-10-31 17:15:39 +0100 | [diff] [blame] | 64 | before the script. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 66 | All command line options are described in :ref:`using-on-general`. |
| 67 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
| 69 | .. _tut-argpassing: |
| 70 | |
| 71 | Argument Passing |
| 72 | ---------------- |
| 73 | |
| 74 | When known to the interpreter, the script name and additional arguments |
R. David Murray | a396463 | 2010-12-17 16:11:40 +0000 | [diff] [blame] | 75 | thereafter are turned into a list of strings and assigned to the ``argv`` |
| 76 | variable in the ``sys`` module. You can access this list by executing ``import |
| 77 | sys``. The length of the list is at least one; when no script and no arguments |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | are given, ``sys.argv[0]`` is an empty string. When the script name is given as |
| 79 | ``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When |
| 80 | :option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``. When |
| 81 | :option:`-m` *module* is used, ``sys.argv[0]`` is set to the full name of the |
| 82 | located module. Options found after :option:`-c` *command* or :option:`-m` |
| 83 | *module* are not consumed by the Python interpreter's option processing but |
| 84 | left in ``sys.argv`` for the command or module to handle. |
| 85 | |
| 86 | |
| 87 | .. _tut-interactive: |
| 88 | |
| 89 | Interactive Mode |
| 90 | ---------------- |
| 91 | |
| 92 | When commands are read from a tty, the interpreter is said to be in *interactive |
| 93 | mode*. In this mode it prompts for the next command with the *primary prompt*, |
| 94 | usually three greater-than signs (``>>>``); for continuation lines it prompts |
| 95 | with the *secondary prompt*, by default three dots (``...``). The interpreter |
| 96 | prints a welcome message stating its version number and a copyright notice |
| 97 | before printing the first prompt:: |
| 98 | |
Georg Brandl | 08a9012 | 2012-09-29 09:34:13 +0200 | [diff] [blame] | 99 | $ python3.4 |
Georg Brandl | 75c5ab4 | 2014-03-22 20:38:11 +0100 | [diff] [blame] | 100 | Python 3.4 (default, Mar 16 2014, 09:25:04) |
Georg Brandl | 553e108 | 2014-03-23 23:03:59 +0100 | [diff] [blame] | 101 | [GCC 4.8.2] on linux |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 102 | Type "help", "copyright", "credits" or "license" for more information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | >>> |
| 104 | |
Georg Brandl | a17487b | 2009-09-18 07:27:51 +0000 | [diff] [blame] | 105 | .. XXX update for new releases |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 106 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | Continuation lines are needed when entering a multi-line construct. As an |
| 108 | example, take a look at this :keyword:`if` statement:: |
| 109 | |
Raymond Hettinger | 4ab532b | 2014-03-28 16:39:25 -0700 | [diff] [blame] | 110 | >>> the_world_is_flat = True |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | >>> if the_world_is_flat: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 112 | ... print("Be careful not to fall off!") |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 113 | ... |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | Be careful not to fall off! |
| 115 | |
| 116 | |
Senthil Kumaran | 15e4833 | 2014-09-18 21:30:28 +0800 | [diff] [blame] | 117 | For more on interactive mode, see :ref:`tut-interac`. |
| 118 | |
| 119 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | .. _tut-interp: |
| 121 | |
| 122 | The Interpreter and Its Environment |
| 123 | =================================== |
| 124 | |
| 125 | |
Éric Araujo | 9fbfe15 | 2011-06-11 10:34:19 +0200 | [diff] [blame] | 126 | .. _tut-source-encoding: |
| 127 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 128 | Source Code Encoding |
| 129 | -------------------- |
| 130 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 131 | By default, Python source files are treated as encoded in UTF-8. In that |
| 132 | encoding, characters of most languages in the world can be used simultaneously |
| 133 | in string literals, identifiers and comments --- although the standard library |
| 134 | only uses ASCII characters for identifiers, a convention that any portable code |
| 135 | should follow. To display all these characters properly, your editor must |
| 136 | recognize that the file is UTF-8, and it must use a font that supports all the |
| 137 | characters in the file. |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 138 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 139 | It is also possible to specify a different encoding for source files. In order |
| 140 | to do this, put one more special comment line right after the ``#!`` line to |
| 141 | define the source file encoding:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 143 | # -*- coding: encoding -*- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 145 | With that declaration, everything in the source file will be treated as having |
| 146 | the encoding *encoding* instead of UTF-8. The list of possible encodings can be |
| 147 | found in the Python Library Reference, in the section on :mod:`codecs`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 149 | For example, if your editor of choice does not support UTF-8 encoded files and |
| 150 | insists on using some other encoding, say Windows-1252, you can write:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 152 | # -*- coding: cp-1252 -*- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 154 | and still use all characters in the Windows-1252 character set in the source |
| 155 | files. The special encoding comment must be in the *first or second* line |
| 156 | within the file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
| 158 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | .. rubric:: Footnotes |
| 160 | |
Georg Brandl | a17487b | 2009-09-18 07:27:51 +0000 | [diff] [blame] | 161 | .. [#] On Unix, the Python 3.x interpreter is by default not installed with the |
Georg Brandl | 3db38ce | 2008-08-30 09:58:30 +0000 | [diff] [blame] | 162 | executable named ``python``, so that it does not conflict with a |
| 163 | simultaneously installed Python 2.x executable. |