| 1 |
.. _tut-using: |
| 2 |
|
| 3 |
**************************** |
| 4 |
Using the Python Interpreter |
| 5 |
**************************** |
| 6 |
|
| 7 |
|
| 8 |
.. _tut-invoking: |
| 9 |
|
| 10 |
Invoking the Interpreter |
| 11 |
======================== |
| 12 |
|
| 13 |
The Python interpreter is usually installed as |usr_local_bin_python_x_dot_y_literal| |
| 14 |
on those machines where it is available; putting :file:`/usr/local/bin` in your |
| 15 |
Unix shell's search path makes it possible to start it by typing the command: |
| 16 |
|
| 17 |
.. code-block:: text |
| 18 |
|
| 19 |
python3.14 |
| 20 |
|
| 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.) |
| 25 |
|
| 26 |
On Windows machines where you have installed Python from the :ref:`Microsoft Store |
| 27 |
<windows-store>`, the |python_x_dot_y_literal| command will be available. If you have |
| 28 |
the :ref:`py.exe launcher <launcher>` installed, you can use the :file:`py` |
| 29 |
command. See :ref:`setting-envvars` for other ways to launch Python. |
| 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 command: ``quit()``. |
| 35 |
|
| 36 |
The interpreter's line-editing features include interactive editing, history |
| 37 |
substitution and code completion on most systems. |
| 38 |
Perhaps the quickest check to see whether command line editing is supported is |
| 39 |
typing a word in on the Python prompt, then pressing Left arrow (or :kbd:`Control-b`). |
| 40 |
If the cursor moves, you have command line editing; see Appendix |
| 41 |
:ref:`tut-interacting` for an introduction to the keys. |
| 42 |
If nothing appears to happen, or if a sequence like ``^[[D`` or ``^B`` appears, |
| 43 |
command line editing isn't available; you'll only be able to use |
| 44 |
backspace to 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 |
| 54 |
characters that are special to the shell, it is usually advised to quote |
| 55 |
*command* in its entirety. |
| 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 |
|
| 61 |
When a script file is used, it is sometimes useful to be able to run the script |
| 62 |
and enter interactive mode afterwards. This can be done by passing :option:`-i` |
| 63 |
before the script. |
| 64 |
|
| 65 |
All command line options are described in :ref:`using-on-general`. |
| 66 |
|
| 67 |
|
| 68 |
.. _tut-argpassing: |
| 69 |
|
| 70 |
Argument Passing |
| 71 |
---------------- |
| 72 |
|
| 73 |
When known to the interpreter, the script name and additional arguments |
| 74 |
thereafter are turned into a list of strings and assigned to the ``argv`` |
| 75 |
variable in the ``sys`` module. You can access this list by executing ``import |
| 76 |
sys``. The length of the list is at least one; when no script and no arguments |
| 77 |
are given, ``sys.argv[0]`` is an empty string. When the script name is given as |
| 78 |
``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When |
| 79 |
:option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``. When |
| 80 |
:option:`-m` *module* is used, ``sys.argv[0]`` is set to the full name of the |
| 81 |
located module. Options found after :option:`-c` *command* or :option:`-m` |
| 82 |
*module* are not consumed by the Python interpreter's option processing but |
| 83 |
left in ``sys.argv`` for the command or module to handle. |
| 84 |
|
| 85 |
|
| 86 |
.. _tut-interactive: |
| 87 |
|
| 88 |
Interactive Mode |
| 89 |
---------------- |
| 90 |
|
| 91 |
When commands are read from a tty, the interpreter is said to be in *interactive |
| 92 |
mode*. In this mode it prompts for the next command with the *primary prompt*, |
| 93 |
usually three greater-than signs (``>>>``); for continuation lines it prompts |
| 94 |
with the *secondary prompt*, by default three dots (``...``). The interpreter |
| 95 |
prints a welcome message stating its version number and a copyright notice |
| 96 |
before printing the first prompt: |
| 97 |
|
| 98 |
.. code-block:: shell-session |
| 99 |
|
| 100 |
$ python3.14 |
| 101 |
Python 3.14 (default, April 4 2024, 09:25:04) |
| 102 |
[GCC 10.2.0] on linux |
| 103 |
Type "help", "copyright", "credits" or "license" for more information. |
| 104 |
>>> |
| 105 |
|
| 106 |
.. XXX update for new releases |
| 107 |
|
| 108 |
Continuation lines are needed when entering a multi-line construct. As an |
| 109 |
example, take a look at this :keyword:`if` statement:: |
| 110 |
|
| 111 |
>>> the_world_is_flat = True |
| 112 |
>>> if the_world_is_flat: |
| 113 |
... print("Be careful not to fall off!") |
| 114 |
... |
| 115 |
Be careful not to fall off! |
| 116 |
|
| 117 |
|
| 118 |
For more on interactive mode, see :ref:`tut-interac`. |
| 119 |
|
| 120 |
|
| 121 |
.. _tut-interp: |
| 122 |
|
| 123 |
The Interpreter and Its Environment |
| 124 |
=================================== |
| 125 |
|
| 126 |
|
| 127 |
.. _tut-source-encoding: |
| 128 |
|
| 129 |
Source Code Encoding |
| 130 |
-------------------- |
| 131 |
|
| 132 |
By default, Python source files are treated as encoded in UTF-8. In that |
| 133 |
encoding, characters of most languages in the world can be used simultaneously |
| 134 |
in string literals, identifiers and comments --- although the standard library |
| 135 |
only uses ASCII characters for identifiers, a convention that any portable code |
| 136 |
should follow. To display all these characters properly, your editor must |
| 137 |
recognize that the file is UTF-8, and it must use a font that supports all the |
| 138 |
characters in the file. |
| 139 |
|
| 140 |
To declare an encoding other than the default one, a special comment line |
| 141 |
should be added as the *first* line of the file. The syntax is as follows:: |
| 142 |
|
| 143 |
# -*- coding: encoding -*- |
| 144 |
|
| 145 |
where *encoding* is one of the valid :mod:`codecs` supported by Python. |
| 146 |
|
| 147 |
For example, to declare that Windows-1252 encoding is to be used, the first |
| 148 |
line of your source code file should be:: |
| 149 |
|
| 150 |
# -*- coding: cp1252 -*- |
| 151 |
|
| 152 |
One exception to the *first line* rule is when the source code starts with a |
| 153 |
:ref:`UNIX "shebang" line <tut-scripts>`. In this case, the encoding |
| 154 |
declaration should be added as the second line of the file. For example:: |
| 155 |
|
| 156 |
#!/usr/bin/env python3 |
| 157 |
# -*- coding: cp1252 -*- |
| 158 |
|
| 159 |
.. rubric:: Footnotes |
| 160 |
|
| 161 |
.. [#] On Unix, the Python 3.x interpreter is by default not installed with the |
| 162 |
executable named ``python``, so that it does not conflict with a |
| 163 |
simultaneously installed Python 2.x executable. |