Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/interpreter.rst @ 70626:aa07c1237f4e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(Merge 3.2) Issue #12016: Reindent decoders of HK and JP codecs
author Victor Stinner <victor.stinner@haypocalc.com>
date Fri, 03 Jun 2011 23:34:32 +0200
parents b39270c6b8d1
children 7b02717d5345
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-using:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 ****************************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Using the Python Interpreter
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 ****************************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. _tut-invoking:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 Invoking the Interpreter
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 ========================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
13 The Python interpreter is usually installed as :file:`/usr/local/bin/python3.3`
48894
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
14 on those machines where it is available; putting :file:`/usr/local/bin` in your
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 Unix shell's search path makes it possible to start it by typing the command ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
17 python3.3
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
48894
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
19 to the shell. [#]_ Since the choice of the directory where the interpreter lives
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
20 is an installation option, other places are possible; check with your local
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
21 Python guru or system administrator. (E.g., :file:`/usr/local/python` is a
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
22 popular alternative location.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 On Windows machines, the Python installation is usually placed in
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
25 :file:`C:\\Python33`, though you can change this when you're running the
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 installer. To add this directory to your path, you can type the following
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 command into the command prompt in a DOS box::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
29 set path=%path%;C:\python33
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 Windows) at the primary prompt causes the interpreter to exit with a zero exit
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 status. If that doesn't work, you can exit the interpreter by typing the
56368
c9bd62efe6ce Merged revisions 75231 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 56062
diff changeset
34 following command: ``quit()``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 The interpreter's line-editing features usually aren't very sophisticated. On
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 Unix, whoever installed the interpreter may have enabled support for the GNU
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 readline library, which adds more elaborate interactive editing and history
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 features. Perhaps the quickest check to see whether command line editing is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 supported is typing Control-P to the first Python prompt you get. If it beeps,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 you have command line editing; see Appendix :ref:`tut-interacting` for an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 introduction to the keys. If nothing appears to happen, or if ``^P`` is echoed,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 command line editing isn't available; you'll only be able to use backspace to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 remove characters from the current line.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 The interpreter operates somewhat like the Unix shell: when called with standard
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 input connected to a tty device, it reads and executes commands interactively;
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 when called with a file name argument or with a file as standard input, it reads
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 and executes a *script* from that file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 A second way of starting the interpreter is ``python -c command [arg] ...``,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 which executes the statement(s) in *command*, analogous to the shell's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 :option:`-c` option. Since Python statements often contain spaces or other
47557
98827a21e352 Merged revisions 63724,63726,63732,63744,63754-63755,63757-63758,63760,63775,63781-63782,63787,63805-63808,63818-63819,63823-63824 via svnmerge from
Georg Brandl <georg@python.org>
parents: 44834
diff changeset
54 characters that are special to the shell, it is usually advised to quote
98827a21e352 Merged revisions 63724,63726,63732,63744,63754-63755,63757-63758,63760,63775,63781-63782,63787,63805-63808,63818-63819,63823-63824 via svnmerge from
Georg Brandl <georg@python.org>
parents: 44834
diff changeset
55 *command* in its entirety with single quotes.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 Some Python modules are also useful as scripts. These can be invoked using
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 ``python -m module [arg] ...``, which executes the source file for *module* as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 if you had spelled out its full name on the command line.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 When a script file is used, it is sometimes useful to be able to run the script
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 and enter interactive mode afterwards. This can be done by passing :option:`-i`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 before the script. (This does not work if the script is read from standard
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 input, for the same reason as explained in the previous paragraph.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. _tut-argpassing:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 Argument Passing
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 ----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 When known to the interpreter, the script name and additional arguments
67917
8084c668b637 Merged revisions 87136,87221,87256,87337-87338,87571,87839,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 56368
diff changeset
73 thereafter are turned into a list of strings and assigned to the ``argv``
8084c668b637 Merged revisions 87136,87221,87256,87337-87338,87571,87839,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 56368
diff changeset
74 variable in the ``sys`` module. You can access this list by executing ``import
8084c668b637 Merged revisions 87136,87221,87256,87337-87338,87571,87839,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 56368
diff changeset
75 sys``. The length of the list is at least one; when no script and no arguments
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 are given, ``sys.argv[0]`` is an empty string. When the script name is given as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 ``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 :option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``. When
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 :option:`-m` *module* is used, ``sys.argv[0]`` is set to the full name of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 located module. Options found after :option:`-c` *command* or :option:`-m`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 *module* are not consumed by the Python interpreter's option processing but
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 left in ``sys.argv`` for the command or module to handle.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 .. _tut-interactive:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 Interactive Mode
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 ----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 When commands are read from a tty, the interpreter is said to be in *interactive
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 mode*. In this mode it prompts for the next command with the *primary prompt*,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 usually three greater-than signs (``>>>``); for continuation lines it prompts
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 with the *secondary prompt*, by default three dots (``...``). The interpreter
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 prints a welcome message stating its version number and a copyright notice
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 before printing the first prompt::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
97 $ python3.3
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
98 Python 3.3 (py3k, Sep 12 2007, 12:21:02)
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
99 [GCC 3.4.6 20060404 (Red Hat 3.4.6-8)] on linux2
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
100 Type "help", "copyright", "credits" or "license" for more information.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 >>>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
56062
9817915ebdeb #6935: update version.
Georg Brandl <georg@python.org>
parents: 50514
diff changeset
103 .. XXX update for new releases
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
104
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 Continuation lines are needed when entering a multi-line construct. As an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 example, take a look at this :keyword:`if` statement::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 >>> the_world_is_flat = 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 >>> if the_world_is_flat:
43219
655071bf6c45 Convert all print statements in the docs.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
110 ... print("Be careful not to fall off!")
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
111 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 Be careful not to fall off!
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 .. _tut-interp:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 The Interpreter and Its Environment
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 ===================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 .. _tut-error:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 Error Handling
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 --------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 When an error occurs, the interpreter prints an error message and a stack trace.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 In interactive mode, it then returns to the primary prompt; when input came from
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 a file, it exits with a nonzero exit status after printing the stack trace.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 (Exceptions handled by an :keyword:`except` clause in a :keyword:`try` statement
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 are not errors in this context.) Some errors are unconditionally fatal and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 cause an exit with a nonzero exit; this applies to internal inconsistencies and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 some cases of running out of memory. All error messages are written to the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 standard error stream; normal output from executed commands is written to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 standard output.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 Typing the interrupt character (usually Control-C or DEL) to the primary or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 secondary prompt cancels the input and returns to the primary prompt. [#]_
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 Typing an interrupt while a command is executing raises the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 :exc:`KeyboardInterrupt` exception, which may be handled by a :keyword:`try`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 statement.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 .. _tut-scripts:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 Executable Python Scripts
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 -------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 On BSD'ish Unix systems, Python scripts can be made directly executable, like
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 shell scripts, by putting the line ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
151 #! /usr/bin/env python3.3
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 (assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 of the script and giving the file an executable mode. The ``#!`` must be the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 first two characters of the file. On some platforms, this first line must end
49186
47db62bf6aa7 Merged revisions 66452 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48894
diff changeset
156 with a Unix-style line ending (``'\n'``), not a Windows (``'\r\n'``) line
47db62bf6aa7 Merged revisions 66452 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48894
diff changeset
157 ending. Note that the hash, or pound, character, ``'#'``, is used to start a
47db62bf6aa7 Merged revisions 66452 via svnmerge from
Georg Brandl <georg@python.org>
parents: 48894
diff changeset
158 comment in Python.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 The script can be given an executable mode, or permission, using the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 :program:`chmod` command::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 $ chmod +x myscript.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
44834
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
165 On Windows systems, there is no notion of an "executable mode". The Python
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
166 installer automatically associates ``.py`` files with ``python.exe`` so that
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
167 a double-click on a Python file will run it as a script. The extension can
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
168 also be ``.pyw``, in that case, the console window that normally appears is
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
169 suppressed.
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
170
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 Source Code Encoding
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 --------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
175 By default, Python source files are treated as encoded in UTF-8. In that
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
176 encoding, characters of most languages in the world can be used simultaneously
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
177 in string literals, identifiers and comments --- although the standard library
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
178 only uses ASCII characters for identifiers, a convention that any portable code
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
179 should follow. To display all these characters properly, your editor must
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
180 recognize that the file is UTF-8, and it must use a font that supports all the
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
181 characters in the file.
43219
655071bf6c45 Convert all print statements in the docs.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
182
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
183 It is also possible to specify a different encoding for source files. In order
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
184 to do this, put one more special comment line right after the ``#!`` line to
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
185 define the source file encoding::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
187 # -*- coding: encoding -*-
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
189 With that declaration, everything in the source file will be treated as having
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
190 the encoding *encoding* instead of UTF-8. The list of possible encodings can be
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
191 found in the Python Library Reference, in the section on :mod:`codecs`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
193 For example, if your editor of choice does not support UTF-8 encoded files and
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
194 insists on using some other encoding, say Windows-1252, you can write::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
196 # -*- coding: cp-1252 -*-
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
198 and still use all characters in the Windows-1252 character set in the source
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
199 files. The special encoding comment must be in the *first or second* line
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
200 within the file.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 .. _tut-startup:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 The Interactive Startup File
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 ----------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 When you use Python interactively, it is frequently handy to have some standard
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 commands executed every time the interpreter is started. You can do this by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 file containing your start-up commands. This is similar to the :file:`.profile`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 feature of the Unix shells.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43449
diff changeset
214 .. XXX This should probably be dumped in an appendix, since most people
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43449
diff changeset
215 don't use Python interactively in non-trivial ways.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 This file is only read in interactive sessions, not when Python reads commands
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 from a script, and not when :file:`/dev/tty` is given as the explicit source of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 commands (which otherwise behaves like an interactive session). It is executed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 in the same namespace where interactive commands are executed, so that objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 that it defines or imports can be used without qualification in the interactive
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223 file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 If you want to read an additional start-up file from the current directory, you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 can program this in the global start-up file using code like ``if
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 If you want to use the startup file in a script, you must do this explicitly
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 in the script::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 import os
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 filename = os.environ.get('PYTHONSTARTUP')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 if filename and os.path.isfile(filename):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 exec(open(filename).read())
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
56062
9817915ebdeb #6935: update version.
Georg Brandl <georg@python.org>
parents: 50514
diff changeset
239 .. [#] On Unix, the Python 3.x interpreter is by default not installed with the
48894
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
240 executable named ``python``, so that it does not conflict with a
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
241 simultaneously installed Python 2.x executable.
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
242
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 .. [#] A problem with the GNU Readline package may prevent this.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244