Berker Peksag | c5f4036 | 2016-06-01 14:38:18 -0700 | [diff] [blame] | 1 | .. _tut-using: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 2 | |
| 3 | **************************** |
| 4 | Using the Python Interpreter |
| 5 | **************************** |
| 6 | |
| 7 | |
| 8 | .. _tut-invoking: |
| 9 | |
| 10 | Invoking the Interpreter |
| 11 | ======================== |
| 12 | |
Mariatta Wijaya | 77bb0f4 | 2017-02-01 20:38:55 -0800 | [diff] [blame] | 13 | The Python interpreter is usually installed as :file:`/usr/local/bin/python3.6` |
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 | |
Mariatta Wijaya | 77bb0f4 | 2017-02-01 20:38:55 -0800 | [diff] [blame] | 19 | python3.6 |
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 |
Ned Deily | ffb40e5 | 2015-05-27 22:00:46 -0700 | [diff] [blame] | 27 | :file:`C:\\Python36`, 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 | |
Ned Deily | ffb40e5 | 2015-05-27 22:00:46 -0700 | [diff] [blame] | 31 | set path=%path%;C:\python36 |
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 |
Serhiy Storchaka | 0424eaf | 2015-09-12 17:45:25 +0300 | [diff] [blame] | 41 | :kbd:`Control-P` to the first Python prompt you get. If it beeps, you have command |
R David Murray | fc1020d | 2014-04-15 20:26:54 -0400 | [diff] [blame] | 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 |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 97 | before printing the first prompt: |
| 98 | |
| 99 | .. code-block:: shell-session |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
Mariatta Wijaya | 77bb0f4 | 2017-02-01 20:38:55 -0800 | [diff] [blame] | 101 | $ python3.6 |
| 102 | Python 3.6 (default, Sep 16 2015, 09:25:04) |
Georg Brandl | 553e108 | 2014-03-23 23:03:59 +0100 | [diff] [blame] | 103 | [GCC 4.8.2] on linux |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 104 | Type "help", "copyright", "credits" or "license" for more information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | >>> |
| 106 | |
Georg Brandl | a17487b | 2009-09-18 07:27:51 +0000 | [diff] [blame] | 107 | .. XXX update for new releases |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 108 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | Continuation lines are needed when entering a multi-line construct. As an |
| 110 | example, take a look at this :keyword:`if` statement:: |
| 111 | |
Raymond Hettinger | 4ab532b | 2014-03-28 16:39:25 -0700 | [diff] [blame] | 112 | >>> the_world_is_flat = True |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | >>> if the_world_is_flat: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 114 | ... print("Be careful not to fall off!") |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 115 | ... |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | Be careful not to fall off! |
| 117 | |
| 118 | |
Senthil Kumaran | 15e4833 | 2014-09-18 21:30:28 +0800 | [diff] [blame] | 119 | For more on interactive mode, see :ref:`tut-interac`. |
| 120 | |
| 121 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | .. _tut-interp: |
| 123 | |
| 124 | The Interpreter and Its Environment |
| 125 | =================================== |
| 126 | |
| 127 | |
Éric Araujo | 9fbfe15 | 2011-06-11 10:34:19 +0200 | [diff] [blame] | 128 | .. _tut-source-encoding: |
| 129 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | Source Code Encoding |
| 131 | -------------------- |
| 132 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 133 | By default, Python source files are treated as encoded in UTF-8. In that |
| 134 | encoding, characters of most languages in the world can be used simultaneously |
| 135 | in string literals, identifiers and comments --- although the standard library |
| 136 | only uses ASCII characters for identifiers, a convention that any portable code |
| 137 | should follow. To display all these characters properly, your editor must |
| 138 | recognize that the file is UTF-8, and it must use a font that supports all the |
| 139 | characters in the file. |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 140 | |
Mariatta Wijaya | 23dcccb | 2017-02-01 20:55:47 -0800 | [diff] [blame] | 141 | To declare an encoding other than the default one, a special comment line |
| 142 | should be added as the *first* line of the file. The syntax is as follows:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 144 | # -*- coding: encoding -*- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
Mariatta Wijaya | 23dcccb | 2017-02-01 20:55:47 -0800 | [diff] [blame] | 146 | where *encoding* is one of the valid :mod:`codecs` supported by Python. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
Mariatta Wijaya | 23dcccb | 2017-02-01 20:55:47 -0800 | [diff] [blame] | 148 | For example, to declare that Windows-1252 encoding is to be used, the first |
| 149 | line of your source code file should be:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
Georg Brandl | 2d2590d | 2007-09-28 13:13:35 +0000 | [diff] [blame] | 151 | # -*- coding: cp-1252 -*- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
Mariatta Wijaya | 23dcccb | 2017-02-01 20:55:47 -0800 | [diff] [blame] | 153 | One exception to the *first line* rule is when the source code starts with a |
| 154 | :ref:`UNIX "shebang" line <tut-scripts>`. In this case, the encoding |
| 155 | declaration should be added as the second line of the file. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
Mariatta Wijaya | 23dcccb | 2017-02-01 20:55:47 -0800 | [diff] [blame] | 157 | #!/usr/bin/env python3 |
| 158 | # -*- coding: cp-1252 -*- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | .. rubric:: Footnotes |
| 161 | |
Georg Brandl | a17487b | 2009-09-18 07:27:51 +0000 | [diff] [blame] | 162 | .. [#] 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] | 163 | executable named ``python``, so that it does not conflict with a |
| 164 | simultaneously installed Python 2.x executable. |