Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/interpreter.rst @ 70161:1bd697cdd210 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #12057: Convert CJK encoding testcase BLOB into multiple text files
author Victor Stinner <victor.stinner@haypocalc.com>
date Mon, 16 May 2011 17:16:18 +0200
parents 8eeee9d6d32b
children 48dd027bf342
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-using:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 ****************************
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Using the Python Interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 ****************************
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. _tut-invoking:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 Invoking the Interpreter
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 ========================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 The Python interpreter is usually installed as :file:`/usr/local/bin/python` on
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 those machines where it is available; putting :file:`/usr/local/bin` in your
c62f6669ae22 Move the 2.6 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 ::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 to the shell. Since the choice of the directory where the interpreter lives is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 an installation option, other places are possible; check with your local Python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 guru or system administrator. (E.g., :file:`/usr/local/python` is a popular
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 alternative location.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 On Windows machines, the Python installation is usually placed in
60472
c00b0718fd53 #8346: update version.
Georg Brandl <georg@python.org>
parents: 56822
diff changeset
25 :file:`C:\\Python27`, though you can change this when you're running the
42603
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 command into the command prompt in a DOS box::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
60472
c00b0718fd53 #8346: update version.
Georg Brandl <georg@python.org>
parents: 56822
diff changeset
29 set path=%path%;C:\python27
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
56822
c4c429b08a57 Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50522
diff changeset
34 following command: ``quit()``.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 readline library, which adds more elaborate interactive editing and history
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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,
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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,
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 remove characters from the current line.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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;
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 and executes a *script* from that file.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
c62f6669ae22 Move the 2.6 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] ...``,
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
47397
21510cc0c2e4 Better quote with single quotes.
Georg Brandl <georg@python.org>
parents: 45600
diff changeset
54 characters that are special to the shell, it is usually advised to quote
21510cc0c2e4 Better quote with single quotes.
Georg Brandl <georg@python.org>
parents: 45600
diff changeset
55 *command* in its entirety with single quotes.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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`
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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.)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. _tut-argpassing:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 Argument Passing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
c62f6669ae22 Move the 2.6 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
67921
89d52effc30a Merged revisions 86542,87136,87216,87221,87228,87256,87337-87338,87372,87516,87571,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 60472
diff changeset
73 thereafter are turned into a list of strings and assigned to the ``argv``
89d52effc30a Merged revisions 86542,87136,87216,87221,87228,87256,87337-87338,87372,87516,87571,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 60472
diff changeset
74 variable in the ``sys`` module. You can access this list by executing ``import
89d52effc30a Merged revisions 86542,87136,87216,87221,87228,87256,87337-87338,87372,87516,87571,88164 via svnmerge from
R. David Murray <rdmurray@bitdance.com>
parents: 60472
diff changeset
75 sys``. The length of the list is at least one; when no script and no arguments
42603
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 ``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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`
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 .. _tut-interactive:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 Interactive Mode
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 ----------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 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*,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 usually three greater-than signs (``>>>``); for continuation lines it prompts
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 with the *secondary prompt*, by default three dots (``...``). The interpreter
c62f6669ae22 Move the 2.6 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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 before printing the first prompt::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 python
60472
c00b0718fd53 #8346: update version.
Georg Brandl <georg@python.org>
parents: 56822
diff changeset
98 Python 2.7 (#1, Feb 28 2010, 00:02:06)
43900
3a730f4908e3 Use a slightly more recent version than 1.5.2b2.
Neal Norwitz <nnorwitz@gmail.com>
parents: 42603
diff changeset
99 Type "help", "copyright", "credits" or "license" for more information.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 >>>
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 Continuation lines are needed when entering a multi-line construct. As an
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 example, take a look at this :keyword:`if` statement::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 >>> the_world_is_flat = 1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 >>> if the_world_is_flat:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 ... print "Be careful not to fall off!"
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49184
diff changeset
108 ...
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 Be careful not to fall off!
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 .. _tut-interp:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 The Interpreter and Its Environment
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 ===================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 .. _tut-error:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 Error Handling
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 When an error occurs, the interpreter prints an error message and a stack trace.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 In interactive mode, it then returns to the primary prompt; when input came from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 a file, it exits with a nonzero exit status after printing the stack trace.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 (Exceptions handled by an :keyword:`except` clause in a :keyword:`try` statement
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 are not errors in this context.) Some errors are unconditionally fatal and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 cause an exit with a nonzero exit; this applies to internal inconsistencies and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 some cases of running out of memory. All error messages are written to the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 standard error stream; normal output from executed commands is written to
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 standard output.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 Typing the interrupt character (usually Control-C or DEL) to the primary or
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 secondary prompt cancels the input and returns to the primary prompt. [#]_
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 Typing an interrupt while a command is executing raises the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 :exc:`KeyboardInterrupt` exception, which may be handled by a :keyword:`try`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 statement.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 .. _tut-scripts:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 Executable Python Scripts
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 -------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 On BSD'ish Unix systems, Python scripts can be made directly executable, like
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 shell scripts, by putting the line ::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 #! /usr/bin/env python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 (assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 of the script and giving the file an executable mode. The ``#!`` must be the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 first two characters of the file. On some platforms, this first line must end
49184
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 47397
diff changeset
153 with a Unix-style line ending (``'\n'``), not a Windows (``'\r\n'``) line
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 47397
diff changeset
154 ending. Note that the hash, or pound, character, ``'#'``, is used to start a
59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently.
Georg Brandl <georg@python.org>
parents: 47397
diff changeset
155 comment in Python.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 The script can be given an executable mode, or permission, using the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 :program:`chmod` command::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 $ chmod +x myscript.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
44829
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
162 On Windows systems, there is no notion of an "executable mode". The Python
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
163 installer automatically associates ``.py`` files with ``python.exe`` so that
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
164 a double-click on a Python file will run it as a script. The extension can
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
165 also be ``.pyw``, in that case, the console window that normally appears is
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
166 suppressed.
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
167
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 Source Code Encoding
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 --------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 It is possible to use encodings different than ASCII in Python source files. The
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 best way to do it is to put one more special comment line right after the ``#!``
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 line to define the source file encoding::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49184
diff changeset
176 # -*- coding: encoding -*-
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 With that declaration, all characters in the source file will be treated as
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 having the encoding *encoding*, and it will be possible to directly write
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 Unicode string literals in the selected encoding. The list of possible
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 encodings can be found in the Python Library Reference, in the section on
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 :mod:`codecs`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 For example, to write Unicode literals including the Euro currency symbol, the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 164. This script will print the value 8364 (the Unicode codepoint corresponding
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 to the Euro symbol) and then exit::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 # -*- coding: iso-8859-15 -*-
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 currency = u"€"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 print ord(currency)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 If your editor supports saving files as ``UTF-8`` with a UTF-8 *byte order mark*
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 (aka BOM), you can use that instead of an encoding declaration. IDLE supports
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 this capability if ``Options/General/Default Source Encoding/UTF-8`` is set.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 Notice that this signature is not understood in older Python releases (2.2 and
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 earlier), and also not understood by the operating system for script files with
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 ``#!`` lines (only used on Unix systems).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 By using UTF-8 (either through the signature or an encoding declaration),
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 characters of most languages in the world can be used simultaneously in string
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 literals and comments. Using non-ASCII characters in identifiers is not
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 supported. To display all these characters properly, your editor must recognize
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 that the file is UTF-8, and it must use a font that supports all the characters
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 in the file.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 .. _tut-startup:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 The Interactive Startup File
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 ----------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 When you use Python interactively, it is frequently handy to have some standard
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 commands executed every time the interpreter is started. You can do this by
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 file containing your start-up commands. This is similar to the :file:`.profile`
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 feature of the Unix shells.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 43900
diff changeset
221 .. XXX This should probably be dumped in an appendix, since most people
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 43900
diff changeset
222 don't use Python interactively in non-trivial ways.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 This file is only read in interactive sessions, not when Python reads commands
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 from a script, and not when :file:`/dev/tty` is given as the explicit source of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 commands (which otherwise behaves like an interactive session). It is executed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 in the same namespace where interactive commands are executed, so that objects
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 that it defines or imports can be used without qualification in the interactive
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 file.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 If you want to read an additional start-up file from the current directory, you
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 can program this in the global start-up file using code like ``if
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 os.path.isfile('.pythonrc.py'): execfile('.pythonrc.py')``. If you want to use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 the startup file in a script, you must do this explicitly in the script::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 import os
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 filename = os.environ.get('PYTHONSTARTUP')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 if filename and os.path.isfile(filename):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 execfile(filename)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 .. [#] A problem with the GNU Readline package may prevent this.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246