Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/interpreter.rst @ 83447:678564fc0962 3.3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
#17789: test_random now works with unittest test discovery. Patch by Zachary Ware.
author Ezio Melotti <ezio.melotti@gmail.com>
date Fri, 19 Apr 2013 05:45:27 +0300
parents fcb5bc824e3e
children 1085b0e475d8
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
79160
d2df5bc89fc9 Issue #16015: Make welcome message more realistic in tutorial example.
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 73251
diff changeset
15 Unix shell's search path makes it possible to start it by typing the command:
d2df5bc89fc9 Issue #16015: Make welcome message more realistic in tutorial example.
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 73251
diff changeset
16
d2df5bc89fc9 Issue #16015: Make welcome message more realistic in tutorial example.
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 73251
diff changeset
17 .. code-block:: text
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
19 python3.3
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
48894
03e216dc8fec #3577: 3.0 is not installed as "python" on Unix.
Georg Brandl <georg@python.org>
parents: 47557
diff changeset
21 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
22 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
23 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
24 popular alternative location.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 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
27 :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
28 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
29 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
30
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
31 set path=%path%;C:\python33
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 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
34 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
35 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
36 following command: ``quit()``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 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
39 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
40 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
41 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
42 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
43 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
44 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
45 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
46 remove characters from the current line.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 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
49 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
50 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
51 and executes a *script* from that file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 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
54 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
55 :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
56 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
57 *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
58
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 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
60 ``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
61 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
62
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 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
64 and enter interactive mode afterwards. This can be done by passing :option:`-i`
73251
7a2877d12d52 remove confusing paragraph (as part of r87523); thanks to AJ Hill from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 71778
diff changeset
65 before the script.
42604
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 .. _tut-argpassing:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 Argument Passing
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 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
74 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
75 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
76 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
77 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
78 ``'-'`` (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
79 :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
80 :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
81 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
82 *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
83 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
84
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 .. _tut-interactive:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 Interactive Mode
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 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
92 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
93 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
94 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
95 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
96 before printing the first prompt::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
98 $ python3.3
79161
fcb5bc824e3e Issue #16015: Merge and update from 3.2.
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 73252 79160
diff changeset
99 Python 3.3 (default, Sep 24 2012, 09:25:04)
79160
d2df5bc89fc9 Issue #16015: Make welcome message more realistic in tutorial example.
Chris Jerdonek <chris.jerdonek@gmail.com>
parents: 73251
diff changeset
100 [GCC 4.6.3] on linux2
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
101 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
102 >>>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103
56062
9817915ebdeb #6935: update version.
Georg Brandl <georg@python.org>
parents: 50514
diff changeset
104 .. XXX update for new releases
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
105
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 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
107 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
108
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 >>> the_world_is_flat = 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 >>> if the_world_is_flat:
43219
655071bf6c45 Convert all print statements in the docs.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
111 ... print("Be careful not to fall off!")
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
112 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 Be careful not to fall off!
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 .. _tut-interp:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 The Interpreter and Its Environment
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 .. _tut-error:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 Error Handling
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 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
128 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
129 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
130 (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
131 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
132 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
133 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
134 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
135 standard output.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 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
138 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
139 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
140 :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
141 statement.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 .. _tut-scripts:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 Executable Python Scripts
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 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
150 shell scripts, by putting the line ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
68070
203945060baf Bump trunk to 3.3 alpha 0.
Georg Brandl <georg@python.org>
parents: 67167
diff changeset
152 #! /usr/bin/env python3.3
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 (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
155 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
156 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
157 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
158 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
159 comment in Python.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 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
162 :program:`chmod` command::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 $ chmod +x myscript.py
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
44834
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
166 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
167 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
168 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
169 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
170 suppressed.
ed33da2e74e7 Merged revisions 60143-60149 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44396
diff changeset
171
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
70795
9bfaa723a194 Add missing reST target to one heading in the tutorial
Éric Araujo <merwok@netwok.org>
parents: 68257
diff changeset
173 .. _tut-source-encoding:
9bfaa723a194 Add missing reST target to one heading in the tutorial
Éric Araujo <merwok@netwok.org>
parents: 68257
diff changeset
174
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 Source Code Encoding
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 --------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
178 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
179 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
180 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
181 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
182 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
183 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
184 characters in the file.
43219
655071bf6c45 Convert all print statements in the docs.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
185
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
186 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
187 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
188 define the source file encoding::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
190 # -*- coding: encoding -*-
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
192 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
193 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
194 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
195
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
196 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
197 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
198
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
199 # -*- coding: cp-1252 -*-
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200
43449
7fcd9945d1bf #1211, #1212, #1213: py3k fixes to the tutorial.
Georg Brandl <georg@python.org>
parents: 43219
diff changeset
201 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
202 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
203 within the file.
42604
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 .. _tut-startup:
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 The Interactive Startup File
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 ----------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 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
212 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
213 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
214 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
215 feature of the Unix shells.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43449
diff changeset
217 .. 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
218 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
219
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 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
221 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
222 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
223 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
224 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
225 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
226 file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 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
229 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
230 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
231 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
232 in the script::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 import os
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 filename = os.environ.get('PYTHONSTARTUP')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236 if filename and os.path.isfile(filename):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 exec(open(filename).read())
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239
71778
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
240 .. _tut-customize:
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
241
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
242 The Customization Modules
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
243 -------------------------
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
244
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
245 Python provides two hooks to let you customize it: :mod:`sitecustomize` and
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
246 :mod:`usercustomize`. To see how it works, you need first to find the location
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
247 of your user site-packages directory. Start Python and run this code:
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
248
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
249 >>> import site
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
250 >>> site.getusersitepackages()
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
251 '/home/user/.local/lib/python3.2/site-packages'
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
252
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
253 Now you can create a file named :file:`usercustomize.py` in that directory and
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
254 put anything you want in it. It will affect every invocation of Python, unless
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
255 it is started with the :option:`-s` option to disable the automatic import.
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
256
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
257 :mod:`sitecustomize` works in the same way, but is typically created by an
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
258 administrator of the computer in the global site-packages directory, and is
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
259 imported before :mod:`usercustomize`. See the documentation of the :mod:`site`
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
260 module for more details.
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
261
74179a79d673 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 70795
diff changeset
262
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264
56062
9817915ebdeb #6935: update version.
Georg Brandl <georg@python.org>
parents: 50514
diff changeset
265 .. [#] 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
266 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
267 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
268
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 .. [#] A problem with the GNU Readline package may prevent this.