Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/interpreter.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents aba380a9d8f3
children 9225325e8e1d
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`
73250
aba380a9d8f3 remove confusing paragraph (as part of r87523); thanks to AJ Hill from docs@
Sandro Tosi <sandro.tosi@gmail.com>
parents: 71957
diff changeset
63 before the script.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
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 .. _tut-argpassing:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 Argument Passing
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 ----------------
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 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
72 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
73 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
74 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
75 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
76 ``'-'`` (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
77 :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
78 :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
79 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
80 *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
81 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
82
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 .. _tut-interactive:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 Interactive Mode
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 ----------------
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 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
90 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
91 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
92 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
93 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
94 before printing the first prompt::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 python
60472
c00b0718fd53 #8346: update version.
Georg Brandl <georg@python.org>
parents: 56822
diff changeset
97 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
98 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
99 >>>
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 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
102 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
103
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 >>> the_world_is_flat = 1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 >>> if the_world_is_flat:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 ... 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
107 ...
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 Be careful not to fall off!
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
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 .. _tut-interp:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 The Interpreter and Its Environment
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 ===================================
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 .. _tut-error:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 Error Handling
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 --------------
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 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
123 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
124 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
125 (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
126 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
127 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
128 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
129 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
130 standard output.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 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
133 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
134 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
135 :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
136 statement.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
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 .. _tut-scripts:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 Executable Python Scripts
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 -------------------------
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 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
145 shell scripts, by putting the line ::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 #! /usr/bin/env python
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 (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
150 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
151 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
152 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
153 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
154 comment in Python.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 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
157 :program:`chmod` command::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 $ chmod +x myscript.py
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
44829
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
161 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
162 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
163 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
164 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
165 suppressed.
ac970f883187 Add blurb about executable scripts on Windows. #760657.
Georg Brandl <georg@python.org>
parents: 44383
diff changeset
166
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
71582
48dd027bf342 Add missing reST target to one heading in the tutorial
Éric Araujo <merwok@netwok.org>
parents: 68015
diff changeset
168 .. _tut-source-encoding:
48dd027bf342 Add missing reST target to one heading in the tutorial
Éric Araujo <merwok@netwok.org>
parents: 68015
diff changeset
169
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 Source Code Encoding
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 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
174 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
175 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
176
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
177 # -*- coding: encoding -*-
42603
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 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
181 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
182 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
183 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
184 :mod:`codecs`.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 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
187 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
188 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
189 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
190
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 # -*- coding: iso-8859-15 -*-
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 currency = u"€"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 print ord(currency)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 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
197 (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
198 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
199 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
200 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
201 ``#!`` lines (only used on Unix systems).
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 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
204 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
205 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
206 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
207 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
208 in the file.
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 .. _tut-startup:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 The Interactive Startup File
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
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 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
217 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
218 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
219 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
220 feature of the Unix shells.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 43900
diff changeset
222 .. 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
223 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
224
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225 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
226 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
227 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
228 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
229 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
230 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
231 file.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 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
234 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
235 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
236 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
237
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 import os
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 filename = os.environ.get('PYTHONSTARTUP')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 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
241 execfile(filename)
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
71957
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
244 .. _tut-customize:
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
245
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
246 The Customization Modules
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
247 -------------------------
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
248
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
249 Python provides two hooks to let you customize it: :mod:`sitecustomize` and
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
250 :mod:`usercustomize`. To see how it works, you need first to find the location
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
251 of your user site-packages directory. Start Python and run this code:
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
252
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
253 >>> import site
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
254 >>> site.getusersitepackages()
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
255 '/home/user/.local/lib/python3.2/site-packages'
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
256
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
257 Now you can create a file named :file:`usercustomize.py` in that directory and
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
258 put anything you want in it. It will affect every invocation of Python, unless
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
259 it is started with the :option:`-s` option to disable the automatic import.
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
260
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
261 :mod:`sitecustomize` works in the same way, but is typically created by an
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
262 administrator of the computer in the global site-packages directory, and is
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
263 imported before :mod:`usercustomize`. See the documentation of the :mod:`site`
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
264 module for more details.
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
265
b3f72b6450f1 Improve documentation for PEP 370 support in site module (#8617).
Éric Araujo <merwok@netwok.org>
parents: 71598
diff changeset
266
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 .. rubric:: Footnotes
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 .. [#] A problem with the GNU Readline package may prevent this.