Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1 | \documentstyle[11pt,myformat]{report} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 3 | \title{\bf Python Reference Manual} |
| 4 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 5 | \author{ |
| 6 | Guido van Rossum \\ |
| 7 | Dept. CST, CWI, Kruislaan 413 \\ |
| 8 | 1098 SJ Amsterdam, The Netherlands \\ |
| 9 | E-mail: {\tt guido@cwi.nl} |
| 10 | } |
| 11 | |
| 12 | \begin{document} |
| 13 | |
| 14 | \pagenumbering{roman} |
| 15 | |
| 16 | \maketitle |
| 17 | |
| 18 | \begin{abstract} |
| 19 | |
| 20 | \noindent |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 21 | Python is a simple, yet powerful, interpreted programming language |
| 22 | that bridges the gap between C and shell programming, and is thus |
| 23 | ideally suited for ``throw-away programming'' and rapid prototyping. |
| 24 | Its syntax is put together from constructs borrowed from a variety of |
| 25 | other languages; most prominent are influences from ABC, C, Modula-3 |
| 26 | and Icon. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 27 | |
| 28 | The Python interpreter is easily extended with new functions and data |
| 29 | types implemented in C. Python is also suitable as an extension |
| 30 | language for highly customizable C applications such as editors or |
| 31 | window managers. |
| 32 | |
| 33 | Python is available for various operating systems, amongst which |
| 34 | several flavors of {\UNIX}, Amoeba, the Apple Macintosh O.S., |
| 35 | and MS-DOS. |
| 36 | |
| 37 | This reference manual describes the syntax and ``core semantics'' of |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 38 | the language. It is terse, but attempts to be exact and complete. |
| 39 | The semantics of non-essential built-in object types and of the |
| 40 | built-in functions and modules are described in the {\em Python |
| 41 | Library Reference}. For an informal introduction to the language, see |
| 42 | the {\em Python Tutorial}. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 43 | |
| 44 | \end{abstract} |
| 45 | |
| 46 | \pagebreak |
| 47 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 48 | { |
| 49 | \parskip = 0mm |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 50 | \tableofcontents |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 51 | } |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 52 | |
| 53 | \pagebreak |
| 54 | |
| 55 | \pagenumbering{arabic} |
| 56 | |
| 57 | \chapter{Introduction} |
| 58 | |
| 59 | This reference manual describes the Python programming language. |
| 60 | It is not intended as a tutorial. |
| 61 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 62 | While I am trying to be as precise as possible, I chose to use English |
| 63 | rather than formal specifications for everything except syntax and |
| 64 | lexical analysis. This should make the document better understandable |
| 65 | to the average reader, but will leave room for ambiguities. |
| 66 | Consequently, if you were coming from Mars and tried to re-implement |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 67 | Python from this document alone, you might have to guess things and in |
| 68 | fact you would be implementing quite a different language. |
| 69 | On the other hand, if you are using |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 70 | Python and wonder what the precise rules about a particular area of |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 71 | the language are, you should definitely be able to find it here. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 72 | |
| 73 | It is dangerous to add too many implementation details to a language |
| 74 | reference document -- the implementation may change, and other |
| 75 | implementations of the same language may work differently. On the |
| 76 | other hand, there is currently only one Python implementation, and |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 77 | its particular quirks are sometimes worth being mentioned, especially |
| 78 | where the implementation imposes additional limitations. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 79 | |
| 80 | Every Python implementation comes with a number of built-in and |
| 81 | standard modules. These are not documented here, but in the separate |
| 82 | {\em Python Library Reference} document. A few built-in modules are |
| 83 | mentioned when they interact in a significant way with the language |
| 84 | definition. |
| 85 | |
| 86 | \section{Notation} |
| 87 | |
| 88 | The descriptions of lexical analysis and syntax use a modified BNF |
| 89 | grammar notation. This uses the following style of definition: |
| 90 | |
| 91 | \begin{verbatim} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 92 | name: lc_letter (lc_letter | "_")* |
| 93 | lc_letter: "a"..."z" |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 94 | \end{verbatim} |
| 95 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 96 | The first line says that a \verb\name\ is an \verb\lc_letter\ followed by |
| 97 | a sequence of zero or more \verb\lc_letter\s and underscores. An |
| 98 | \verb\lc_letter\ in turn is any of the single characters `a' through `z'. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 99 | (This rule is actually adhered to for the names defined in syntax and |
| 100 | grammar rules in this document.) |
| 101 | |
| 102 | Each rule begins with a name (which is the name defined by the rule) |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 103 | and a colon. A vertical bar |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 104 | (\verb\|\) is used to separate alternatives; it is the least binding |
| 105 | operator in this notation. A star (\verb\*\) means zero or more |
| 106 | repetitions of the preceding item; likewise, a plus (\verb\+\) means |
| 107 | one or more repetitions, and a question mark (\verb\?\) zero or one |
| 108 | (in other words, the preceding item is optional). These three |
| 109 | operators bind as tightly as possible; parentheses are used for |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 110 | grouping. Literal strings are enclosed in double quotes. White space |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 111 | is only meaningful to separate tokens. Rules are normally contained |
| 112 | on a single line; rules with many alternatives may be formatted |
| 113 | alternatively with each line after the first beginning with a |
| 114 | vertical bar. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 115 | |
| 116 | In lexical definitions (as the example above), two more conventions |
| 117 | are used: Two literal characters separated by three dots mean a choice |
| 118 | of any single character in the given (inclusive) range of ASCII |
| 119 | characters. A phrase between angular brackets (\verb\<...>\) gives an |
| 120 | informal description of the symbol defined; e.g., this could be used |
| 121 | to describe the notion of `control character' if needed. |
| 122 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 123 | Even though the notation used is almost the same, there is a big |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 124 | difference between the meaning of lexical and syntactic definitions: |
| 125 | a lexical definition operates on the individual characters of the |
| 126 | input source, while a syntax definition operates on the stream of |
| 127 | tokens generated by the lexical analysis. |
| 128 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 129 | \chapter{Lexical analysis} |
| 130 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 131 | A Python program is read by a {\em parser}. Input to the parser is a |
| 132 | stream of {\em tokens}, generated by the {\em lexical analyzer}. This |
| 133 | chapter describes how the lexical analyzer breaks a file into tokens. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 134 | |
| 135 | \section{Line structure} |
| 136 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 137 | A Python program is divided in a number of logical lines. The end of |
| 138 | a logical line is represented by the token NEWLINE. Statements cannot |
| 139 | cross logical line boundaries except where NEWLINE is allowed by the |
| 140 | syntax (e.g., between statements in compound statements). |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 141 | |
| 142 | \subsection{Comments} |
| 143 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 144 | A comment starts with a hash character (\verb\#\) that is not part of |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 145 | a string literal, and ends at the end of the physical line. A comment |
| 146 | always signifies the end of the logical line. Comments are ignored by |
| 147 | the syntax. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 148 | |
| 149 | \subsection{Line joining} |
| 150 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 151 | Two or more physical lines may be joined into logical lines using |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 152 | backslash characters (\verb/\/), as follows: when a physical line ends |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 153 | in a backslash that is not part of a string literal or comment, it is |
| 154 | joined with the following forming a single logical line, deleting the |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 155 | backslash and the following end-of-line character. For example: |
| 156 | % |
| 157 | \begin{verbatim} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 158 | moth_names = ['Januari', 'Februari', 'Maart', \ |
| 159 | 'April', 'Mei', 'Juni', \ |
| 160 | 'Juli', 'Augustus', 'September', \ |
| 161 | 'Oktober', 'November', 'December'] |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 162 | \end{verbatim} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 163 | |
| 164 | \subsection{Blank lines} |
| 165 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 166 | A logical line that contains only spaces, tabs, and possibly a |
| 167 | comment, is ignored (i.e., no NEWLINE token is generated), except that |
| 168 | during interactive input of statements, an entirely blank logical line |
| 169 | terminates a multi-line statement. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 170 | |
| 171 | \subsection{Indentation} |
| 172 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 173 | Leading whitespace (spaces and tabs) at the beginning of a logical |
| 174 | line is used to compute the indentation level of the line, which in |
| 175 | turn is used to determine the grouping of statements. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 176 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 177 | First, tabs are replaced (from left to right) by one to eight spaces |
| 178 | such that the total number of characters up to there is a multiple of |
| 179 | eight (this is intended to be the same rule as used by UNIX). The |
| 180 | total number of spaces preceding the first non-blank character then |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 181 | determines the line's indentation. Indentation cannot be split over |
| 182 | multiple physical lines using backslashes. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 183 | |
| 184 | The indentation levels of consecutive lines are used to generate |
| 185 | INDENT and DEDENT tokens, using a stack, as follows. |
| 186 | |
| 187 | Before the first line of the file is read, a single zero is pushed on |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 188 | the stack; this will never be popped off again. The numbers pushed on |
| 189 | the stack will always be strictly increasing from bottom to top. At |
| 190 | the beginning of each logical line, the line's indentation level is |
| 191 | compared to the top of the stack. If it is equal, nothing happens. |
| 192 | If it larger, it is pushed on the stack, and one INDENT token is |
| 193 | generated. If it is smaller, it {\em must} be one of the numbers |
| 194 | occurring on the stack; all numbers on the stack that are larger are |
| 195 | popped off, and for each number popped off a DEDENT token is |
| 196 | generated. At the end of the file, a DEDENT token is generated for |
| 197 | each number remaining on the stack that is larger than zero. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 198 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 199 | Here is an example of a correctly (though confusingly) indented piece |
| 200 | of Python code: |
| 201 | |
| 202 | \begin{verbatim} |
| 203 | def perm(l): |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 204 | # Compute the list of all permutations of l |
| 205 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 206 | if len(l) <= 1: |
| 207 | return [l] |
| 208 | r = [] |
| 209 | for i in range(len(l)): |
| 210 | s = l[:i] + l[i+1:] |
| 211 | p = perm(s) |
| 212 | for x in p: |
| 213 | r.append(l[i:i+1] + x) |
| 214 | return r |
| 215 | \end{verbatim} |
| 216 | |
| 217 | The following example shows various indentation errors: |
| 218 | |
| 219 | \begin{verbatim} |
| 220 | def perm(l): # error: first line indented |
| 221 | for i in range(len(l)): # error: not indented |
| 222 | s = l[:i] + l[i+1:] |
| 223 | p = perm(l[:i] + l[i+1:]) # error: unexpected indent |
| 224 | for x in p: |
| 225 | r.append(l[i:i+1] + x) |
| 226 | return r # error: inconsistent indent |
| 227 | \end{verbatim} |
| 228 | |
| 229 | (Actually, the first three errors are detected by the parser; only the |
| 230 | last error is found by the lexical analyzer -- the indentation of |
| 231 | \verb\return r\ does not match a level popped off the stack.) |
| 232 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 233 | \section{Other tokens} |
| 234 | |
| 235 | Besides NEWLINE, INDENT and DEDENT, the following categories of tokens |
| 236 | exist: identifiers, keywords, literals, operators, and delimiters. |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 237 | Spaces and tabs are not tokens, but serve to delimit tokens. Where |
| 238 | ambiguity exists, a token comprises the longest possible string that |
| 239 | forms a legal token, when read from left to right. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 240 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 241 | \section{Identifiers} |
| 242 | |
| 243 | Identifiers are described by the following regular expressions: |
| 244 | |
| 245 | \begin{verbatim} |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 246 | identifier: (letter|"_") (letter|digit|"_")* |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 247 | letter: lowercase | uppercase |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 248 | lowercase: "a"..."z" |
| 249 | uppercase: "A"..."Z" |
| 250 | digit: "0"..."9" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 251 | \end{verbatim} |
| 252 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 253 | Identifiers are unlimited in length. Case is significant. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 254 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 255 | \subsection{Keywords} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 256 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 257 | The following identifiers are used as reserved words, or {\em |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 258 | keywords} of the language, and cannot be used as ordinary |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 259 | identifiers. They must be spelled exactly as written here: |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 260 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 261 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 262 | and del for in print |
| 263 | break elif from is raise |
| 264 | class else global not return |
| 265 | continue except if or try |
| 266 | def finally import pass while |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 267 | \end{verbatim} |
| 268 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 269 | % # This Python program sorts and formats the above table |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 270 | % import string |
| 271 | % l = [] |
| 272 | % try: |
| 273 | % while 1: |
| 274 | % l = l + string.split(raw_input()) |
| 275 | % except EOFError: |
| 276 | % pass |
| 277 | % l.sort() |
| 278 | % for i in range((len(l)+4)/5): |
| 279 | % for j in range(i, len(l), 5): |
| 280 | % print string.ljust(l[j], 10), |
| 281 | % print |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 282 | |
| 283 | \section{Literals} |
| 284 | |
| 285 | \subsection{String literals} |
| 286 | |
| 287 | String literals are described by the following regular expressions: |
| 288 | |
| 289 | \begin{verbatim} |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 290 | stringliteral: "'" stringitem* "'" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 291 | stringitem: stringchar | escapeseq |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 292 | stringchar: <any ASCII character except newline or "\" or "'"> |
| 293 | escapeseq: "'" <any ASCII character except newline> |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 294 | \end{verbatim} |
| 295 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 296 | String literals cannot span physical line boundaries. Escape |
| 297 | sequences in strings are actually interpreted according to rules |
| 298 | simular to those used by Standard C. The recognized escape sequences |
| 299 | are: |
| 300 | |
| 301 | \begin{center} |
| 302 | \begin{tabular}{|l|l|} |
| 303 | \hline |
| 304 | \verb/\\/ & Backslash (\verb/\/) \\ |
| 305 | \verb/\'/ & Single quote (\verb/'/) \\ |
| 306 | \verb/\a/ & ASCII Bell (BEL) \\ |
| 307 | \verb/\b/ & ASCII Backspace (BS) \\ |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 308 | %\verb/\E/ & ASCII Escape (ESC) \\ |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 309 | \verb/\f/ & ASCII Formfeed (FF) \\ |
| 310 | \verb/\n/ & ASCII Linefeed (LF) \\ |
| 311 | \verb/\r/ & ASCII Carriage Return (CR) \\ |
| 312 | \verb/\t/ & ASCII Horizontal Tab (TAB) \\ |
| 313 | \verb/\v/ & ASCII Vertical Tab (VT) \\ |
| 314 | \verb/\/{\em ooo} & ASCII character with octal value {\em ooo} \\ |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 315 | \verb/\x/{em xx...} & ASCII character with hex value {\em xx...} \\ |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 316 | \hline |
| 317 | \end{tabular} |
| 318 | \end{center} |
| 319 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 320 | In strict compatibility with in Standard C, up to three octal digits are |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 321 | accepted, but an unlimited number of hex digits is taken to be part of |
| 322 | the hex escape (and then the lower 8 bits of the resulting hex number |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 323 | are used in all current implementations...). |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 324 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 325 | All unrecognized escape sequences are left in the string unchanged, |
| 326 | i.e., {\em the backslash is left in the string.} (This rule is |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 327 | useful when debugging: if an escape sequence is mistyped, the |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 328 | resulting output is more easily recognized as broken. It also helps a |
| 329 | great deal for string literals used as regular expressions or |
| 330 | otherwise passed to other modules that do their own escape handling -- |
| 331 | but you may end up quadrupling backslashes that must appear literally.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 332 | |
| 333 | \subsection{Numeric literals} |
| 334 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 335 | There are three types of numeric literals: plain integers, long |
| 336 | integers, and floating point numbers. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 337 | |
| 338 | Integers and long integers are described by the following regular expressions: |
| 339 | |
| 340 | \begin{verbatim} |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 341 | longinteger: integer ("l"|"L") |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 342 | integer: decimalinteger | octinteger | hexinteger |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 343 | decimalinteger: nonzerodigit digit* | "0" |
| 344 | octinteger: "0" octdigit+ |
| 345 | hexinteger: "0" ("x"|"X") hexdigit+ |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 346 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 347 | nonzerodigit: "1"..."9" |
| 348 | octdigit: "0"..."7" |
| 349 | hexdigit: digit|"a"..."f"|"A"..."F" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 350 | \end{verbatim} |
| 351 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 352 | Although both lower case `l'and upper case `L' are allowed as suffix |
| 353 | for long integers, it is strongly recommended to always use `L', since |
| 354 | the letter `l' looks too much like the digit `1'. |
| 355 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 356 | Plain integer decimal literals must be at most $2^{31} - 1$ (i.e., the |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 357 | largest positive integer, assuming 32-bit arithmetic); octal and |
| 358 | hexadecimal literals may be as large as $2^{32} - 1$. There is no limit |
| 359 | for long integer literals. |
| 360 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 361 | Some examples of plain and long integer literals: |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 362 | |
| 363 | \begin{verbatim} |
| 364 | 7 2147483647 0177 0x80000000 |
| 365 | 3L 79228162514264337593543950336L 0377L 0100000000L |
| 366 | \end{verbatim} |
| 367 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 368 | Floating point numbers are described by the following regular expressions: |
| 369 | |
| 370 | \begin{verbatim} |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 371 | floatnumber: pointfloat | exponentfloat |
| 372 | pointfloat: [intpart] fraction | intpart "." |
| 373 | exponentfloat: (intpart | pointfloat) exponent |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 374 | intpart: digit+ |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 375 | fraction: "." digit+ |
| 376 | exponent: ("e"|"E") ["+"|"-"] digit+ |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 377 | \end{verbatim} |
| 378 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 379 | The allowed range of floating point literals is |
| 380 | implementation-dependent. |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 381 | |
| 382 | Some examples of floating point literals: |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 383 | |
| 384 | \begin{verbatim} |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 385 | 3.14 10. .001 1e100 3.14e-10 |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 386 | \end{verbatim} |
| 387 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 388 | Note that numeric literals do not include a sign; a phrase like |
| 389 | \verb\-1\ is actually an expression composed of the operator |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 390 | \verb\-\ and the literal \verb\1\. |
| 391 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 392 | \section{Operators} |
| 393 | |
| 394 | The following tokens are operators: |
| 395 | |
| 396 | \begin{verbatim} |
| 397 | + - * / % |
| 398 | << >> & | ^ ~ |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 399 | < == > <= <> != >= |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 400 | \end{verbatim} |
| 401 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 402 | The comparison operators \verb\<>\ and \verb\!=\ are alternate |
| 403 | spellings of the same operator. |
| 404 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 405 | \section{Delimiters} |
| 406 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 407 | The following tokens serve as delimiters or otherwise have a special |
| 408 | meaning: |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 409 | |
| 410 | \begin{verbatim} |
| 411 | ( ) [ ] { } |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 412 | ; , : . ` = |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 413 | \end{verbatim} |
| 414 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 415 | The following printing ASCII characters are not used in Python (except |
| 416 | in string literals and in comments). Their occurrence is an |
| 417 | unconditional error: |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 418 | |
| 419 | \begin{verbatim} |
| 420 | ! @ $ " ? |
| 421 | \end{verbatim} |
| 422 | |
Guido van Rossum | 7b632a6 | 1992-01-16 17:49:21 +0000 | [diff] [blame] | 423 | They may be used by future versions of the language though! |
| 424 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 425 | \chapter{Execution model} |
| 426 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 427 | \section{Objects, values and types} |
| 428 | |
| 429 | I won't try to define rigorously here what an object is, but I'll give |
| 430 | some properties of objects that are important to know about. |
| 431 | |
| 432 | Every object has an identity, a type and a value. An object's {\em |
| 433 | identity} never changes once it has been created; think of it as the |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 434 | object's address in memory. An object's {\em type} determines the |
| 435 | operations that an object supports (e.g., ``does it have a length?'') |
| 436 | and also defines the ``meaning'' of the object's value. The type also |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 437 | never changes. The {\em value} of some objects can change; whether |
| 438 | this is possible is a property of its type. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 439 | |
| 440 | Objects are never explicitly destroyed; however, when they become |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 441 | unreachable they may be garbage-collected. An implementation is |
| 442 | allowed to delay garbage collection or omit it altogether -- it is a |
| 443 | matter of implementation quality how garbage collection is |
| 444 | implemented, as long as no objects are collected that are still |
| 445 | reachable. (Implementation note: the current implementation uses a |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 446 | reference-counting scheme which collects most objects as soon as they |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 447 | become unreachable, but never collects garbage containing circular |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 448 | references.) |
| 449 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 450 | Note that the use of the implementation's tracing or debugging |
| 451 | facilities may keep objects alive that would normally be collectable. |
| 452 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 453 | Some objects contain references to ``external'' resources such as open |
| 454 | files or windows. It is understood that these resources are freed |
| 455 | when the object is garbage-collected, but since garbage collection is |
| 456 | not guaranteed to happen, such objects also provide an explicit way to |
| 457 | release the external resource, usually a \verb\close\ method. |
| 458 | Programs are strongly recommended to always explicitly close such |
| 459 | objects. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 460 | |
| 461 | Some objects contain references to other objects. These references |
| 462 | are part of the object's value; in most cases, when such a |
| 463 | ``container'' object is compared to another (of the same type), the |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 464 | comparison applies to the {\em values} of the referenced objects (not |
| 465 | their identities). |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 466 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 467 | Types affect almost all aspects of an object's life. Even the meaning |
| 468 | of object identity is affected in some sense: for immutable types, |
| 469 | operations that compute new values may actually return a reference to |
| 470 | any existing object with the same type and value, while for mutable |
| 471 | objects this is not allowed. E.g., after |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 472 | |
| 473 | \begin{verbatim} |
| 474 | a = 1; b = 1; c = []; d = [] |
| 475 | \end{verbatim} |
| 476 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 477 | \verb\a\ and \verb\b\ may or may not refer to the same object with the |
| 478 | value one, depending on the implementation, but \verb\c\ and \verb\d\ |
| 479 | are guaranteed to refer to two different, unique, newly created empty |
| 480 | lists. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 481 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 482 | \section{Code blocks, execution frames, and name spaces} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 483 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 484 | A ``code block'' is a piece of Python program text that can be |
| 485 | executed as a unit, such as a module, a class definition or a function |
| 486 | body. Some code blocks (like modules) are executed only once, others |
| 487 | (like function bodies) may be executed many times. Code block may |
| 488 | textually contain other code blocks. Code blocks may invoke other |
| 489 | code blocks (that aren't textually contained) as part of their |
| 490 | execution. |
| 491 | |
| 492 | Each command typed interactively is a separate code block; a script |
| 493 | file is a code block; the string argument passed to the built-in |
| 494 | functions \verb\eval\ and \verb\exec\ are code blocks; the expression |
| 495 | read and evaluated by the built-in function \verb\input\ is a code |
| 496 | block. |
| 497 | |
| 498 | A code block is executed in an ``execution frame''. An execution |
| 499 | frame contains some administrative information (used for debugging), |
| 500 | determines where and how execution continues after the code block's |
| 501 | execution has completed, and (perhaps most importantly) defines two |
| 502 | ``name spaces'' that affect execution of the code block. |
| 503 | |
| 504 | A name space is a mapping from names (identifiers) to objects. A |
| 505 | particular name space may be referenced by more than one execution |
| 506 | frame, and from other places as well. Adding a name to a name space |
| 507 | is called ``binding'' a name (to an object); changing the mapping of a |
| 508 | name is called ``rebinding''; removing a name from the name space is |
| 509 | called ``unbinding''. Name spaces are functionally equivalent to |
| 510 | dictionaries (described below). |
| 511 | |
| 512 | The ``local name space'' of an execution frame determines the default |
| 513 | place where names are defined and searched. The ``global name |
| 514 | space'' determines the place where names listed in \verb\global\ |
| 515 | statements are defined and searched, and where names that are not |
| 516 | explicitly bound in the current code block are searched. |
| 517 | |
| 518 | Whether a name is local or global in a code block is determined by |
| 519 | static inspection of the source text for the code block: in the |
| 520 | absence of \verb\global\ statements, a name that is bound anywhere in |
| 521 | the code block is local in the entire code block; all other names are |
| 522 | considered global. The \verb\global\ statement forces global |
| 523 | interpretation of selected names throughout the code block. The |
| 524 | following constructs bind names: formal parameters, \verb\import\ |
| 525 | statements, class and function definitions (these bind the class or |
| 526 | function name), and targets that are identifiers if occurring in an |
| 527 | assignment, \verb\for\ loop header, or \verb\except\ clause header. |
| 528 | (A target occurring in a \verb\del\ statement does not bind a name.) |
| 529 | |
| 530 | When a global name is not found in the global name space, it is |
| 531 | searched in the list of ``built-in'' names (this is actually the |
| 532 | global name space of the module \verb\builtin\). When a name is not |
| 533 | found at all, the \verb\NameError\ exception is raised. |
| 534 | |
| 535 | The following table lists the meaning of the local and global name |
| 536 | space for various types of code blocks. The name space for a |
| 537 | particular module is automatically created when the module is first |
| 538 | referenced. |
| 539 | |
| 540 | \begin{center} |
| 541 | \begin{tabular}{|l|l|l|l|} |
| 542 | \hline |
| 543 | Code block type & Global name space & Local name space & Notes \\ |
| 544 | \hline |
| 545 | Module & n.s. for this module & same as global & \\ |
| 546 | Script & n.s. for \verb\__main__\ & same as global & \\ |
| 547 | Interactive command & n.s. for \verb\__main__\ & same as global & \\ |
| 548 | Class definition & global n.s. of containing block & new n.s. & \\ |
| 549 | Function body & global n.s. of containing block & new n.s. & \\ |
| 550 | String passed to \verb\exec\ or \verb\eval\ |
| 551 | & global n.s. of caller & local n.s. of caller & (1) \\ |
| 552 | File read by \verb\execfile\ |
| 553 | & global n.s. of caller & local n.s. of caller & (1) \\ |
| 554 | Expression read by \verb\input\ |
| 555 | & global n.s. of caller & local n.s. of caller & \\ |
| 556 | \hline |
| 557 | \end{tabular} |
| 558 | \end{center} |
| 559 | |
| 560 | Notes: |
| 561 | \begin{description} |
| 562 | \item[(1)] The global and local name space for these functions can be |
| 563 | overridden with optional extra arguments. |
| 564 | \end{description} |
| 565 | |
| 566 | \section{Exceptions} |
| 567 | |
| 568 | Exceptions are a means of breaking out of the normal flow of control |
| 569 | of a code block in order to handle errors (or other exceptional |
| 570 | conditions). An exception is ``raised'' at the point where the error |
| 571 | is detected; it may be ``handled'' by the surrounding code block or by any |
| 572 | code block that directly or indirectly invoked the code block where |
| 573 | the error occurred. |
| 574 | |
| 575 | The Python interpreter raises an exception when it detects an run-time |
| 576 | error (such as division by zero). A Python program can also |
| 577 | explicitly raise an exception with the \verb\raise\ statement. |
| 578 | Exception handlers are specified with the \verb\try...except\ statement. |
| 579 | |
| 580 | Python uses the ``termination'' model of error handling: a handler can |
| 581 | find out what happened and continue execution at an outer level, but |
| 582 | it cannot repair the cause of the error and retry the failing |
| 583 | operation (except by re-entering the the offending piece of code from |
| 584 | the top). |
| 585 | |
| 586 | When an exception is not handled at all, the interpreter terminates |
| 587 | execution of the program, or returns to its interactive main loop. |
| 588 | |
| 589 | Exceptions are identified by string objects. Two different string |
| 590 | objects with the same value identify different exceptions. |
| 591 | |
| 592 | When an exception is raised, an object (maybe \verb\None\) is passed |
| 593 | as the exception's ``parameter''; this object does not affect the |
| 594 | selection of an exception handler, but is passed to the selected |
| 595 | exception handler as additional information. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 596 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 597 | \chapter{The standard type hierarchy} |
| 598 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 599 | Below is a list of the types that are built into Python. Extension |
| 600 | modules written in C can define additional types. Future versions of |
| 601 | Python may add types to the type hierarchy (e.g., rational or complex |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 602 | numbers, lists of efficiently stored integers, etc.). |
| 603 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 604 | Some type descriptions contain a paragraph listing `special |
| 605 | attributes'. These are attributes that provide access to the |
| 606 | implementation and are not intended for general use. Their definition |
| 607 | may change in the future. There are also some `generic' special |
| 608 | attributes, not listed with the individual objects: \verb\__methods__\ |
| 609 | is a list of the method names of a built-in object, if it has any; |
| 610 | \verb\__members__\ is a list of the data attribute names of a built-in |
| 611 | object, if it has any. |
| 612 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 613 | \begin{description} |
| 614 | |
| 615 | \item[None] |
| 616 | This type has a single value. There is a single object with this value. |
| 617 | This object is accessed through the built-in name \verb\None\. |
| 618 | It is returned from functions that don't explicitly return an object. |
| 619 | |
| 620 | \item[Numbers] |
| 621 | These are created by numeric literals and returned as results |
| 622 | by arithmetic operators and arithmetic built-in functions. |
| 623 | Numeric objects are immutable; once created their value never changes. |
| 624 | Python numbers are of course strongly related to mathematical numbers, |
| 625 | but subject to the limitations of numerical representation in computers. |
| 626 | |
| 627 | Python distinguishes between integers and floating point numbers: |
| 628 | |
| 629 | \begin{description} |
| 630 | \item[Integers] |
| 631 | These represent elements from the mathematical set of whole numbers. |
| 632 | |
| 633 | There are two types of integers: |
| 634 | |
| 635 | \begin{description} |
| 636 | |
| 637 | \item[Plain integers] |
| 638 | These represent numbers in the range $-2^{31}$ through $2^{31}-1$. |
| 639 | (The range may be larger on machines with a larger natural word |
| 640 | size, but not smaller.) |
| 641 | When the result of an operation falls outside this range, the |
| 642 | exception \verb\OverflowError\ is raised. |
| 643 | For the purpose of shift and mask operations, integers are assumed to |
| 644 | have a binary, 2's complement notation using 32 or more bits, and |
| 645 | hiding no bits from the user (i.e., all $2^{32}$ different bit |
| 646 | patterns correspond to different values). |
| 647 | |
| 648 | \item[Long integers] |
| 649 | These represent numbers in an unlimited range, subject to avaiable |
| 650 | (virtual) memory only. For the purpose of shift and mask operations, |
| 651 | a binary representation is assumed, and negative numbers are |
| 652 | represented in a variant of 2's complement which gives the illusion of |
| 653 | an infinite string of sign bits extending to the left. |
| 654 | |
| 655 | \end{description} % Integers |
| 656 | |
| 657 | The rules for integer representation are intended to give the most |
| 658 | meaningful interpretation of shift and mask operations involving |
| 659 | negative integers and the least surprises when switching between the |
| 660 | plain and long integer domains. For any operation except left shift, |
| 661 | if it yields a result in the plain integer domain without causing |
| 662 | overflow, it will yield the same result in the long integer domain or |
| 663 | when using mixed operands. |
| 664 | |
| 665 | \item[Floating point numbers] |
| 666 | These represent machine-level double precision floating point numbers. |
| 667 | You are at the mercy of the underlying machine architecture and |
| 668 | C implementation for the accepted range and handling of overflow. |
| 669 | |
| 670 | \end{description} % Numbers |
| 671 | |
| 672 | \item[Sequences] |
| 673 | These represent finite ordered sets indexed by natural numbers. |
| 674 | The built-in function \verb\len()\ returns the number of elements |
| 675 | of a sequence. When this number is $n$, the index set contains |
| 676 | the numbers $0, 1, \ldots, n-1$. Element \verb\i\ of sequence |
| 677 | \verb\a\ is selected by \verb\a[i]\. |
| 678 | |
| 679 | Sequences also support slicing: \verb\a[i:j]\ selects all elements |
| 680 | with index $k$ such that $i < k < j$. When used as an expression, |
| 681 | a slice is a sequence of the same type -- this implies that the |
| 682 | index set is renumbered so that it starts at 0 again. |
| 683 | |
| 684 | Sequences are distinguished according to their mutability: |
| 685 | |
| 686 | \begin{description} |
| 687 | % |
| 688 | \item[Immutable sequences] |
| 689 | An object of an immutable sequence type cannot change once it is |
| 690 | created. (If the object contains references to other objects, |
| 691 | these other objects may be mutable and may be changed; however |
| 692 | the collection of objects directly referenced by an immutable object |
| 693 | cannot change.) |
| 694 | |
| 695 | The following types are immutable sequences: |
| 696 | |
| 697 | \begin{description} |
| 698 | |
| 699 | \item[Strings] |
| 700 | The elements of a string are characters. There is no separate |
| 701 | character type; a character is represented by a string of one element. |
| 702 | Characters represent (at least) 8-bit bytes. The built-in |
| 703 | functions \verb\chr()\ and \verb\ord()\ convert between characters |
| 704 | and nonnegative integers representing the byte values. |
| 705 | Bytes with the values 0-127 represent the corresponding ASCII values. |
| 706 | |
| 707 | (On systems whose native character set is not ASCII, strings may use |
| 708 | EBCDIC in their internal representation, provided the functions |
| 709 | \verb\chr()\ and \verb\ord()\ implement a mapping between ASCII and |
| 710 | EBCDIC, and string comparisons preserve the ASCII order. |
| 711 | Or perhaps someone can propose a better rule?) |
| 712 | |
| 713 | \item[Tuples] |
| 714 | The elements of a tuple are arbitrary Python objects. |
| 715 | Tuples of two or more elements are formed by comma-separated lists |
| 716 | of expressions. A tuple of one element can be formed by affixing |
| 717 | a comma to an expression (an expression by itself of course does |
| 718 | not create a tuple). An empty tuple can be formed by enclosing |
| 719 | `nothing' in parentheses. |
| 720 | |
| 721 | \end{description} % Immutable sequences |
| 722 | |
| 723 | \item[Mutable sequences] |
| 724 | Mutable sequences can be changed after they are created. |
| 725 | The subscript and slice notations can be used as the target |
| 726 | of assignment and \verb\del\ (delete) statements. |
| 727 | |
| 728 | There is currently a single mutable sequence type: |
| 729 | |
| 730 | \begin{description} |
| 731 | |
| 732 | \item[Lists] |
| 733 | The elements of a list are arbitrary Python objects. |
| 734 | Lists are formed by placing a comma-separated list of expressions |
| 735 | in square brackets. (Note that there are no special cases for lists |
| 736 | of length 0 or 1.) |
| 737 | |
| 738 | \end{description} % Mutable sequences |
| 739 | |
| 740 | \end{description} % Sequences |
| 741 | |
| 742 | \item[Mapping types] |
| 743 | These represent finite sets of objects indexed by arbitrary index sets. |
| 744 | The subscript notation \verb\a[k]\ selects the element indexed |
| 745 | by \verb\k\ from the mapping \verb\a\; this can be used in |
| 746 | expressions and as the target of assignments or \verb\del\ statements. |
| 747 | The built-in function \verb\len()\ returns the number of elements |
| 748 | in a mapping. |
| 749 | |
| 750 | There is currently a single mapping type: |
| 751 | |
| 752 | \begin{description} |
| 753 | |
| 754 | \item[Dictionaries] |
| 755 | These represent finite sets of objects indexed by strings. |
| 756 | Dictionaries are created by the \verb\{...}\ notation (see section |
| 757 | \ref{dict}). (Implementation note: the strings used for indexing must |
| 758 | not contain null bytes.) |
| 759 | |
| 760 | \end{description} % Mapping types |
| 761 | |
| 762 | \item[Callable types] |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 763 | These are the types to which the function call operation (written as |
| 764 | \verb\function(argument, argument, ...)\) can be applied: |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 765 | |
| 766 | \begin{description} |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 767 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 768 | \item[User-defined functions] |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 769 | A user-defined function is created by a function definition (see |
| 770 | section \ref{function}). It should be called with an argument list |
| 771 | containing the same number of items as the function's formal parameter |
| 772 | list. |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 773 | |
| 774 | Special read-only attributes: \verb\func_code\ is the code object |
| 775 | representing the compiled function body, and \verb\func_globals\ is (a |
| 776 | reference to) the dictionary that holds the function's global |
| 777 | variables -- it implements the global name space of the module in |
| 778 | which the function was defined. |
| 779 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 780 | \item[User-defined methods] |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 781 | A user-defined method (a.k.a. {\tt object closure}) is a pair of a |
| 782 | class instance object and a user-defined function. It should be |
| 783 | called with an argument list containing one item less than the number |
| 784 | of items in the function's formal parameter list. When called, the |
| 785 | class instance becomes the first argument, and the call arguments are |
| 786 | shifted one to the right. |
| 787 | |
| 788 | Special read-only attributes: \verb\im_self\ is the class instance |
| 789 | object, \verb\im_func\ is the function object. |
| 790 | |
| 791 | \item[Built-in functions] |
| 792 | A built-in function object is a wrapper around a C function. Examples |
| 793 | of built-in functions are \verb\len\ and \verb\math.sin\. There |
| 794 | are no special attributes. The number and type of the arguments are |
| 795 | determined by the C function. |
| 796 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 797 | \item[Built-in methods] |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 798 | This is really a different disguise of a built-in function, this time |
| 799 | containing an object passed to the C function as an implicit extra |
| 800 | argument. An example of a built-in method is \verb\list.append\ if |
| 801 | \verb\list\ is a list object. |
| 802 | |
| 803 | \item[Classes] |
| 804 | Class objects are described below. When a class object is called as a |
| 805 | parameterless function, a new class instance (also described below) is |
| 806 | created and returned. The class's initialization function is not |
| 807 | called -- this is the responsibility of the caller. It is illegal to |
| 808 | call a class object with one or more arguments. |
| 809 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 810 | \end{description} |
| 811 | |
| 812 | \item[Modules] |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 813 | Modules are imported by the \verb\import\ statement (see section |
| 814 | \ref{import}). A module object is a container for a module's name |
| 815 | space, which is a dictionary (the same dictionary as referenced by the |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 816 | \verb\func_globals\ attribute of functions defined in the module). |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 817 | Module attribute references are translated to lookups in this |
| 818 | dictionary. A module object does not contain the code object used to |
| 819 | initialize the module (since it isn't needed once the initialization |
| 820 | is done). |
| 821 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 822 | Attribute assignment update the module's name space dictionary. |
| 823 | |
| 824 | Special read-only attributes: \verb\__dict__\ yields the module's name |
| 825 | space as a dictionary object; \verb\__name__\ yields the module's name. |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 826 | |
| 827 | \item[Classes] |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 828 | Class objects are created by class definitions (see section |
| 829 | \ref{class}). A class is a container for a dictionary containing the |
| 830 | class's name space. Class attribute references are translated to |
| 831 | lookups in this dictionary. When an attribute name is not found |
| 832 | there, the attribute search continues in the base classes. The search |
| 833 | is depth-first, left-to-right in the order of their occurrence in the |
| 834 | base class list. |
| 835 | |
| 836 | Attribute assignments update the class's dictionary, never the |
| 837 | dictionary of a base class. |
| 838 | |
| 839 | A class can be called as a parameterless function to yield a class |
| 840 | instance (see above). |
| 841 | |
| 842 | Special read-only attributes: \verb\__dict__\ yields te dictionary |
| 843 | containing the class's name space; \verb\__bases__\ yields a tuple |
| 844 | (possibly empty or a singleton) containing the base classes, in the |
| 845 | order of their occurrence in the base class list. |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 846 | |
| 847 | \item[Class instances] |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 848 | A class instance is created by calling a class object as a |
| 849 | parameterless function. A class instance has a dictionary in which |
| 850 | attribute references are searched. When an attribute is not found |
| 851 | there, and the instance's class has an attribute by that name, and |
| 852 | that class attribute is a user-defined function (and in no other |
| 853 | cases), the instance attribute reference yields a user-defined method |
| 854 | object (see above) constructed from the instance and the function. |
| 855 | |
| 856 | Attribute assignments update the instance's dictionary. |
| 857 | |
| 858 | Special read-only attributes: \verb\__dict__\ yields the attribute |
| 859 | dictionary; \verb\__class__\ yields the instance's class. |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 860 | |
| 861 | \item[Files] |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 862 | A file object represents an open file. (It is a wrapper around a C |
| 863 | {\tt stdio} file pointer.) File objects are created by the |
| 864 | \verb\open()\ built-in function, and also by \verb\posix.popen()\ and |
| 865 | the \verb\makefile\ method of socket objects. \verb\sys.stdin\, |
| 866 | \verb\sys.stdout\ and \verb\sys.stderr\ are file objects corresponding |
| 867 | the the interpreter's standard input, output and error streams. |
| 868 | See the Python Library Reference for methods of file objects and other |
| 869 | details. |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 870 | |
| 871 | \item[Internal types] |
| 872 | A few types used internally by the interpreter are exposed to the user. |
| 873 | Their definition may change with future versions of the interpreter, |
| 874 | but they are mentioned here for completeness. |
| 875 | |
| 876 | \begin{description} |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 877 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 878 | \item[Code objects] |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 879 | Code objects represent executable code. The difference between a code |
| 880 | object and a function object is that the function object contains an |
| 881 | explicit reference to the function's context (the module in which it |
| 882 | was defined) which a code object contains no context. There is no way |
| 883 | to execute a bare code object. |
| 884 | |
| 885 | Special read-only attributes: \verb\co_code\ is a string representing |
| 886 | the sequence of instructions; \verb\co_consts\ is a list of literals |
| 887 | used by the code; \verb\co_names\ is a list of names (strings) used by |
| 888 | the code; \verb\co_filename\ is the filename from which the code was |
| 889 | compiled. (To find out the line numbers, you would have to decode the |
| 890 | instructions; the standard library module \verb\dis\ contains an |
| 891 | example of how to do this.) |
| 892 | |
| 893 | \item[Frame objects] |
| 894 | Frame objects represent execution frames. They may occur in traceback |
| 895 | objects (see below). |
| 896 | |
| 897 | Special read-only attributes: \verb\f_back\ is to the previous |
| 898 | stack frame (towards the caller), or \verb\None\ if this is the bottom |
| 899 | stack frame; \verb\f_code\ is the code object being executed in this |
| 900 | frame; \verb\f_globals\ is the dictionary used to look up global |
| 901 | variables; \verb\f_locals\ is used for local variables; |
| 902 | \verb\f_lineno\ gives the line number and \verb\f_lasti\ gives the |
| 903 | precise instruction (this is an index into the instruction string of |
| 904 | the code object). |
| 905 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 906 | \item[Traceback objects] |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 907 | Traceback objects represent a stack trace of an exception. A |
| 908 | traceback object is created when an exception occurs. When the search |
| 909 | for an exception handler unwinds the execution stack, at each unwound |
| 910 | level a traceback object is inserted in front of the current |
| 911 | traceback. When an exception handler is entered, the stack trace is |
| 912 | made available to the program as \verb\sys.exc_traceback\. When the |
| 913 | program contains no suitable handler, the stack trace is written |
| 914 | (nicely formatted) to the standard error stream; if the interpreter is |
| 915 | interactive, it is made available to the user as |
| 916 | \verb\sys.last_traceback\. |
| 917 | |
| 918 | Special read-only attributes: \verb\tb_next\ is the next level in the |
| 919 | stack trace (towards the frame where the exception occurred), or |
| 920 | \verb\None\ if there is no next level; \verb\tb_frame\ points to the |
| 921 | execution frame of the current level; \verb\tb_lineno\ gives the line |
| 922 | number where the exception occurred; \verb\tb_lasti\ indicates the |
| 923 | precise instruction. The line number and last instruction in the |
| 924 | traceback may differ from the line number of its frame object if the |
| 925 | exception occurred in a \verb\try\ statement with no matching |
| 926 | \verb\except\ clause or with a \verb\finally\ clause. |
| 927 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 928 | \end{description} % Internal types |
| 929 | |
| 930 | \end{description} % Types |
| 931 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 932 | \chapter{Expressions and conditions} |
| 933 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 934 | From now on, extended BNF notation will be used to describe syntax, |
| 935 | not lexical analysis. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 936 | |
| 937 | This chapter explains the meaning of the elements of expressions and |
| 938 | conditions. Conditions are a superset of expressions, and a condition |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 939 | may be used wherever an expression is required by enclosing it in |
| 940 | parentheses. The only places where expressions are used in the syntax |
| 941 | instead of conditions is in expression statements and on the |
| 942 | right-hand side of assignments; this catches some nasty bugs like |
| 943 | accedentally writing \verb\x == 1\ instead of \verb\x = 1\. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 944 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 945 | The comma has several roles in Python's syntax. It is usually an |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 946 | operator with a lower precedence than all others, but occasionally |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 947 | serves other purposes as well; e.g., it separates function arguments, |
| 948 | is used in list and dictionary constructors, and has special semantics |
| 949 | in \verb\print\ statements. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 950 | |
| 951 | When (one alternative of) a syntax rule has the form |
| 952 | |
| 953 | \begin{verbatim} |
| 954 | name: othername |
| 955 | \end{verbatim} |
| 956 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 957 | and no semantics are given, the semantics of this form of \verb\name\ |
| 958 | are the same as for \verb\othername\. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 959 | |
| 960 | \section{Arithmetic conversions} |
| 961 | |
| 962 | When a description of an arithmetic operator below uses the phrase |
| 963 | ``the numeric arguments are converted to a common type'', |
| 964 | this both means that if either argument is not a number, a |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 965 | \verb\TypeError\ exception is raised, and that otherwise |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 966 | the following conversions are applied: |
| 967 | |
| 968 | \begin{itemize} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 969 | \item first, if either argument is a floating point number, |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 970 | the other is converted to floating point; |
| 971 | \item else, if either argument is a long integer, |
| 972 | the other is converted to long integer; |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 973 | \item otherwise, both must be plain integers and no conversion |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 974 | is necessary. |
| 975 | \end{itemize} |
| 976 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 977 | \section{Atoms} |
| 978 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 979 | Atoms are the most basic elements of expressions. Forms enclosed in |
| 980 | reverse quotes or in parentheses, brackets or braces are also |
| 981 | categorized syntactically as atoms. The syntax for atoms is: |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 982 | |
| 983 | \begin{verbatim} |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 984 | atom: identifier | literal | enclosure |
| 985 | enclosure: parenth_form | list_display | dict_display | string_conversion |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 986 | \end{verbatim} |
| 987 | |
| 988 | \subsection{Identifiers (Names)} |
| 989 | |
| 990 | An identifier occurring as an atom is a reference to a local, global |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 991 | or built-in name binding. If a name can be assigned to anywhere in a |
| 992 | code block, and is not mentioned in a \verb\global\ statement in that |
| 993 | code block, it refers to a local name throughout that code block. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 994 | Otherwise, it refers to a global name if one exists, else to a |
| 995 | built-in name. |
| 996 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 997 | When the name is bound to an object, evaluation of the atom yields |
| 998 | that object. When a name is not bound, an attempt to evaluate it |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 999 | raises a \verb\NameError\ exception. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1000 | |
| 1001 | \subsection{Literals} |
| 1002 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1003 | Python knows string and numeric literals: |
| 1004 | |
| 1005 | \begin{verbatim} |
| 1006 | literal: stringliteral | integer | longinteger | floatnumber |
| 1007 | \end{verbatim} |
| 1008 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1009 | Evaluation of a literal yields an object of the given type |
| 1010 | (string, integer, long integer, floating point number) |
| 1011 | with the given value. |
| 1012 | The value may be approximated in the case of floating point literals. |
| 1013 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1014 | All literals correspond to immutable data types, and hence the |
| 1015 | object's identity is less important than its value. Multiple |
| 1016 | evaluations of literals with the same value (either the same |
| 1017 | occurrence in the program text or a different occurrence) may obtain |
| 1018 | the same object or a different object with the same value. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1019 | |
| 1020 | (In the original implementation, all literals in the same code block |
| 1021 | with the same type and value yield the same object.) |
| 1022 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1023 | \subsection{Parenthesized forms} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1024 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1025 | A parenthesized form is an optional condition list enclosed in |
| 1026 | parentheses: |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1027 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1028 | \begin{verbatim} |
| 1029 | parenth_form: "(" [condition_list] ")" |
| 1030 | \end{verbatim} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1031 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1032 | A parenthesized condition list yields whatever that condition list |
| 1033 | yields. |
| 1034 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1035 | An empty pair of parentheses yields an empty tuple object. Since |
| 1036 | tuples are immutable, the rules for literals apply here. |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1037 | |
| 1038 | (Note that tuples are not formed by the parentheses, but rather by use |
| 1039 | of the comma operator. The exception is the empty tuple, for which |
| 1040 | parentheses {\em are} required -- allowing unparenthesized ``nothing'' |
| 1041 | in expressions would causes ambiguities and allow common typos to |
| 1042 | pass uncaught.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1043 | |
| 1044 | \subsection{List displays} |
| 1045 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1046 | A list display is a possibly empty series of conditions enclosed in |
| 1047 | square brackets: |
| 1048 | |
| 1049 | \begin{verbatim} |
| 1050 | list_display: "[" [condition_list] "]" |
| 1051 | \end{verbatim} |
| 1052 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1053 | A list display yields a new list object. |
| 1054 | |
| 1055 | If it has no condition list, the list object has no items. |
| 1056 | Otherwise, the elements of the condition list are evaluated |
| 1057 | from left to right and inserted in the list object in that order. |
| 1058 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1059 | \subsection{Dictionary displays} \label{dict} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1060 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1061 | A dictionary display is a possibly empty series of key/datum pairs |
| 1062 | enclosed in curly braces: |
| 1063 | |
| 1064 | \begin{verbatim} |
| 1065 | dict_display: "{" [key_datum_list] "}" |
| 1066 | key_datum_list: [key_datum ("," key_datum)* [","] |
| 1067 | key_datum: condition ":" condition |
| 1068 | \end{verbatim} |
| 1069 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1070 | A dictionary display yields a new dictionary object. |
| 1071 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1072 | The key/datum pairs are evaluated from left to right to define the |
| 1073 | entries of the dictionary: each key object is used as a key into the |
| 1074 | dictionary to store the corresponding datum. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1075 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1076 | Keys must be strings, otherwise a \verb\TypeError\ exception is raised. |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1077 | Clashes between duplicate keys are not detected; the last datum |
| 1078 | (textually rightmost in the display) stored for a given key value |
| 1079 | prevails. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1080 | |
| 1081 | \subsection{String conversions} |
| 1082 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1083 | A string conversion is a condition list enclosed in reverse (or |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1084 | backward) quotes: |
| 1085 | |
| 1086 | \begin{verbatim} |
| 1087 | string_conversion: "`" condition_list "`" |
| 1088 | \end{verbatim} |
| 1089 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1090 | A string conversion evaluates the contained condition list and converts the |
| 1091 | resulting object into a string according to rules specific to its type. |
| 1092 | |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 1093 | If the object is a string, a number, \verb\None\, or a tuple, list or |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1094 | dictionary containing only objects whose type is one of these, the |
| 1095 | resulting string is a valid Python expression which can be passed to |
| 1096 | the built-in function \verb\eval()\ to yield an expression with the |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1097 | same value (or an approximation, if floating point numbers are |
| 1098 | involved). |
| 1099 | |
| 1100 | (In particular, converting a string adds quotes around it and converts |
| 1101 | ``funny'' characters to escape sequences that are safe to print.) |
| 1102 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1103 | It is illegal to attempt to convert recursive objects (e.g., lists or |
| 1104 | dictionaries that contain a reference to themselves, directly or |
| 1105 | indirectly.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1106 | |
| 1107 | \section{Primaries} |
| 1108 | |
| 1109 | Primaries represent the most tightly bound operations of the language. |
| 1110 | Their syntax is: |
| 1111 | |
| 1112 | \begin{verbatim} |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1113 | primary: atom | attributeref | subscription | slicing | call |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1114 | \end{verbatim} |
| 1115 | |
| 1116 | \subsection{Attribute references} |
| 1117 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1118 | An attribute reference is a primary followed by a period and a name: |
| 1119 | |
| 1120 | \begin{verbatim} |
| 1121 | attributeref: primary "." identifier |
| 1122 | \end{verbatim} |
| 1123 | |
| 1124 | The primary must evaluate to an object of a type that supports |
| 1125 | attribute references, e.g., a module or a list. This object is then |
| 1126 | asked to produce the attribute whose name is the identifier. If this |
| 1127 | attribute is not available, the exception \verb\AttributeError\ is |
| 1128 | raised. Otherwise, the type and value of the object produced is |
| 1129 | determined by the object. Multiple evaluations of the same attribute |
| 1130 | reference may yield different objects. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1131 | |
| 1132 | \subsection{Subscriptions} |
| 1133 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1134 | A subscription selects an item of a sequence or mapping object: |
| 1135 | |
| 1136 | \begin{verbatim} |
| 1137 | subscription: primary "[" condition "]" |
| 1138 | \end{verbatim} |
| 1139 | |
| 1140 | The primary must evaluate to an object of a sequence or mapping type. |
| 1141 | |
| 1142 | If it is a mapping, the condition must evaluate to an object whose |
| 1143 | value is one of the keys of the mapping, and the subscription selects |
| 1144 | the value in the mapping that corresponds to that key. |
| 1145 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1146 | If it is a sequence, the condition must evaluate to a plain integer. |
| 1147 | If this value is negative, the length of the sequence is added to it |
| 1148 | (so that, e.g., \verb\x[-1]\ selects the last item of \verb\x\.) |
| 1149 | The resulting value must be a nonnegative integer smaller than the |
| 1150 | number of items in the sequence, and the subscription selects the item |
| 1151 | whose index is that value (counting from zero). |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1152 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1153 | A string's items are characters. A character is not a separate data |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1154 | type but a string of exactly one character. |
| 1155 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1156 | \subsection{Slicings} |
| 1157 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1158 | A slicing selects a range of items in a sequence object: |
| 1159 | |
| 1160 | \begin{verbatim} |
| 1161 | slicing: primary "[" [condition] ":" [condition] "]" |
| 1162 | \end{verbatim} |
| 1163 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1164 | The primary must evaluate to a sequence object. The lower and upper |
| 1165 | bound expressions, if present, must evaluate to plain integers; |
| 1166 | defaults are zero and the sequence's length, respectively. If either |
| 1167 | bound is negative, the sequence's length is added to it. The slicing |
| 1168 | now selects all items with index $k$ such that $i <= k < j$ where $i$ |
| 1169 | and $j$ are the specified lower and upper bounds. This may be an |
| 1170 | empty sequence. It is not an error if $i$ or $j$ lie outside the |
| 1171 | range of valid indexes (such items don't exist so they aren't |
| 1172 | selected). |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1173 | |
| 1174 | \subsection{Calls} |
| 1175 | |
| 1176 | A call calls a function with a possibly empty series of arguments: |
| 1177 | |
| 1178 | \begin{verbatim} |
| 1179 | call: primary "(" [condition_list] ")" |
| 1180 | \end{verbatim} |
| 1181 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1182 | The primary must evaluate to a callable object (user-defined |
| 1183 | functions, built-in functions, methods of built-in objects, class |
| 1184 | objects, and methods of class instances are callable). If it is a |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 1185 | class, the argument list must be empty; otherwise, the arguments are |
| 1186 | evaluated. |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1187 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 1188 | A call always returns some value, possibly \verb\None\, unless it |
| 1189 | raises an exception. How this value is computed depends on the type |
| 1190 | of the callable object. If it is: |
| 1191 | |
| 1192 | \begin{description} |
| 1193 | |
| 1194 | \item[a user-defined function:] the code block for the function is |
| 1195 | executed, passing it the argument list. The first thing the code |
| 1196 | block will do is bind the formal parameters to the arguments. When |
| 1197 | the code block executes a \verb\return\ statement, this specifies the |
| 1198 | return value of the function call. |
| 1199 | |
| 1200 | \item[a built-in function or method:] the result is up to the |
| 1201 | interpreter; see the library reference manual for the descriptions of |
| 1202 | built-in functions and methods. |
| 1203 | |
| 1204 | \item[a class object:] a new instance of that class is returned. |
| 1205 | |
| 1206 | \item[a class instance method:] the corresponding user-defined |
| 1207 | function is called, with an argument list that is one longer than the |
| 1208 | argument list of the call: the instance becomes the first argument. |
| 1209 | |
| 1210 | \end{description} |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1211 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1212 | \section{Factors} |
| 1213 | |
| 1214 | Factors represent the unary numeric operators. |
| 1215 | Their syntax is: |
| 1216 | |
| 1217 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1218 | factor: primary | "-" factor | "+" factor | "~" factor |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1219 | \end{verbatim} |
| 1220 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1221 | The unary \verb\"-"\ operator yields the negative of its |
| 1222 | numeric argument. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1223 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1224 | The unary \verb\"+"\ operator yields its numeric argument unchanged. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1225 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1226 | The unary \verb\"~"\ operator yields the bit-wise negation of its |
| 1227 | plain or long integer argument. The bit-wise negation negation of |
| 1228 | \verb\x\ is defined as \verb\-(x+1)\. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1229 | |
| 1230 | In all three cases, if the argument does not have the proper type, |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1231 | a \verb\TypeError\ exception is raised. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1232 | |
| 1233 | \section{Terms} |
| 1234 | |
| 1235 | Terms represent the most tightly binding binary operators: |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1236 | % |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1237 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1238 | term: factor | term "*" factor | term "/" factor | term "%" factor |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1239 | \end{verbatim} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1240 | % |
| 1241 | The \verb\"*"\ (multiplication) operator yields the product of its |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1242 | arguments. The arguments must either both be numbers, or one argument |
| 1243 | must be a plain integer and the other must be a sequence. In the |
| 1244 | former case, the numbers are converted to a common type and then |
| 1245 | multiplied together. In the latter case, sequence repetition is |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1246 | performed; a negative repetition factor yields an empty sequence. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1247 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1248 | The \verb\"/"\ (division) operator yields the quotient of its |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1249 | arguments. The numeric arguments are first converted to a common |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1250 | type. Plain or long integer division yields an integer of the same |
| 1251 | type; the result is that of mathematical division with the `floor' |
| 1252 | function applied to the result. Division by zero raises the |
| 1253 | \verb\ZeroDivisionError\ exception. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1254 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1255 | The \verb\"%"\ (modulo) operator yields the remainder from the |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1256 | division of the first argument by the second. The numeric arguments |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1257 | are first converted to a common type. A zero right argument raises the |
| 1258 | \verb\ZeroDivisionError\ exception. The arguments may be floating point |
| 1259 | numbers, e.g., \verb\3.14 % 0.7\ equals \verb\0.34\. The modulo operator |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1260 | always yields a result with the same sign as its second operand (or |
| 1261 | zero); the absolute value of the result is strictly smaller than the |
| 1262 | second operand. |
| 1263 | |
| 1264 | The integer division and modulo operators are connected by the |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1265 | following identity: \verb\x == (x/y)*y + (x%y)\. |
| 1266 | Integer division and modulo are also connected with the built-in |
| 1267 | function \verb\divmod()\: \verb\divmod(x, y) == (x/y, x%y)\. |
| 1268 | These identities don't hold for floating point numbers; there a |
| 1269 | similar identity holds where \verb\x/y\ is replaced by |
| 1270 | \verb\floor(x/y)\). |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1271 | |
| 1272 | \section{Arithmetic expressions} |
| 1273 | |
| 1274 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1275 | arith_expr: term | arith_expr "+" term | arith_expr "-" term |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1276 | \end{verbatim} |
| 1277 | |
Guido van Rossum | 670e5a0 | 1992-01-17 14:03:20 +0000 | [diff] [blame] | 1278 | The \verb|"+"| operator yields the sum of its arguments. The |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1279 | arguments must either both be numbers, or both sequences of the same |
| 1280 | type. In the former case, the numbers are converted to a common type |
| 1281 | and then added together. In the latter case, the sequences are |
| 1282 | concatenated. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1283 | |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1284 | The \verb|"-"| operator yields the difference of its arguments. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1285 | The numeric arguments are first converted to a common type. |
| 1286 | |
| 1287 | \section{Shift expressions} |
| 1288 | |
| 1289 | \begin{verbatim} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1290 | shift_expr: arith_expr | shift_expr ( "<<" | ">>" ) arith_expr |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1291 | \end{verbatim} |
| 1292 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1293 | These operators accept plain or long integers as arguments. The |
| 1294 | arguments are converted to a common type. They shift the first |
| 1295 | argument to the left or right by the number of bits given by the |
| 1296 | second argument. |
| 1297 | |
| 1298 | A right shift by $n$ bits is defined as division by $2^n$. A left |
| 1299 | shift by $n$ bits is defined as multiplication with $2^n$ without |
| 1300 | overflow check; for plain integers this drops bits if the result is |
| 1301 | not less than $2^{31} - 1$ in absolute value. |
| 1302 | |
| 1303 | Negative shift counts raise a \verb\ValueError\ exception. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1304 | |
| 1305 | \section{Bitwise AND expressions} |
| 1306 | |
| 1307 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1308 | and_expr: shift_expr | and_expr "&" shift_expr |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1309 | \end{verbatim} |
| 1310 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1311 | This operator yields the bitwise AND of its arguments, which must be |
| 1312 | plain or long integers. The arguments are converted to a common type. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1313 | |
| 1314 | \section{Bitwise XOR expressions} |
| 1315 | |
| 1316 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1317 | xor_expr: and_expr | xor_expr "^" and_expr |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1318 | \end{verbatim} |
| 1319 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1320 | This operator yields the bitwise exclusive OR of its arguments, which |
| 1321 | must be plain or long integers. The arguments are converted to a |
| 1322 | common type. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1323 | |
| 1324 | \section{Bitwise OR expressions} |
| 1325 | |
| 1326 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1327 | or_expr: xor_expr | or_expr "|" xor_expr |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1328 | \end{verbatim} |
| 1329 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1330 | This operator yields the bitwise OR of its arguments, which must be |
| 1331 | plain or long integers. The arguments are converted to a common type. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1332 | |
| 1333 | \section{Comparisons} |
| 1334 | |
| 1335 | \begin{verbatim} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1336 | comparison: or_expr (comp_operator or_expr)* |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1337 | comp_operator: "<"|">"|"=="|">="|"<="|"<>"|"!="|"is" ["not"]|["not"] "in" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1338 | \end{verbatim} |
| 1339 | |
| 1340 | Comparisons yield integer value: 1 for true, 0 for false. |
| 1341 | |
| 1342 | Comparisons can be chained arbitrarily, |
| 1343 | e.g., $x < y <= z$ is equivalent to |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1344 | $x < y$ \verb\and\ $y <= z$, except that $y$ is evaluated only once |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1345 | (but in both cases $z$ is not evaluated at all when $x < y$ is |
| 1346 | found to be false). |
| 1347 | |
| 1348 | Formally, $e_0 op_1 e_1 op_2 e_2 ...e_{n-1} op_n e_n$ is equivalent to |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1349 | $e_0 op_1 e_1$ \verb\and\ $e_1 op_2 e_2$ \verb\and\ ... \verb\and\ |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1350 | $e_{n-1} op_n e_n$, except that each expression is evaluated at most once. |
| 1351 | |
| 1352 | Note that $e_0 op_1 e_1 op_2 e_2$ does not imply any kind of comparison |
| 1353 | between $e_0$ and $e_2$, e.g., $x < y > z$ is perfectly legal. |
| 1354 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1355 | The forms \verb\<>\ and \verb\!=\ are equivalent; for consistency with |
| 1356 | C, \verb\!=\ is preferred; where \verb\!=\ is mentioned below |
| 1357 | \verb\<>\ is also implied. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1358 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1359 | The operators {\tt "<", ">", "==", ">=", "<="}, and {\tt "!="} compare |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1360 | the values of two objects. The objects needn't have the same type. |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1361 | If both are numbers, they are coverted to a common type. Otherwise, |
| 1362 | objects of different types {\em always} compare unequal, and are |
| 1363 | ordered consistently but arbitrarily. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1364 | |
| 1365 | (This unusual |
| 1366 | definition of comparison is done to simplify the definition of |
Guido van Rossum | 4fc43bc | 1991-11-25 17:26:57 +0000 | [diff] [blame] | 1367 | operations like sorting and the \verb\in\ and \verb\not in\ operators.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1368 | |
| 1369 | Comparison of objects of the same type depends on the type: |
| 1370 | |
| 1371 | \begin{itemize} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1372 | |
| 1373 | \item |
| 1374 | Numbers are compared arithmetically. |
| 1375 | |
| 1376 | \item |
| 1377 | Strings are compared lexicographically using the numeric equivalents |
| 1378 | (the result of the built-in function \verb\ord\) of their characters. |
| 1379 | |
| 1380 | \item |
| 1381 | Tuples and lists are compared lexicographically using comparison of |
| 1382 | corresponding items. |
| 1383 | |
| 1384 | \item |
| 1385 | Mappings (dictionaries) are compared through lexicographic |
| 1386 | comparison of their sorted (key, value) lists.% |
| 1387 | \footnote{This is expensive since it requires sorting the keys first, |
| 1388 | but about the only sensible definition. It was tried to compare |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1389 | dictionaries using the rule below for most other types, but this gave |
| 1390 | surprises in cases like \verb|if d == {}: ...|.} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1391 | |
| 1392 | \item |
| 1393 | Most other types compare unequal unless they are the same object; |
| 1394 | the choice whether one object is considered smaller or larger than |
| 1395 | another one is made arbitrarily but consistently within one |
| 1396 | execution of a program. |
| 1397 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1398 | \end{itemize} |
| 1399 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1400 | The operators \verb\in\ and \verb\not in\ test for sequence |
| 1401 | membership: if $y$ is a sequence, $x ~\verb\in\~ y$ is true if and |
| 1402 | only if there exists an index $i$ such that $x = y[i]$. |
| 1403 | $x ~\verb\not in\~ y$ yields the inverse truth value. The exception |
| 1404 | \verb\TypeError\ is raised when $y$ is not a sequence, or when $y$ is |
| 1405 | a string and $x$ is not a string of length one.% |
| 1406 | \footnote{The latter restriction is sometimes a nuisance.} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1407 | |
| 1408 | The operators \verb\is\ and \verb\is not\ compare object identity: |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1409 | $x ~\verb\is\~ y$ is true if and only if $x$ and $y$ are the same |
| 1410 | object. $x ~\verb\is not\~ y$ yields the inverse truth value. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1411 | |
| 1412 | \section{Boolean operators} |
| 1413 | |
| 1414 | \begin{verbatim} |
| 1415 | condition: or_test |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1416 | or_test: and_test | or_test "or" and_test |
| 1417 | and_test: not_test | and_test "and" not_test |
| 1418 | not_test: comparison | "not" not_test |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1419 | \end{verbatim} |
| 1420 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1421 | In the context of Boolean operators, and also when conditions are used |
| 1422 | by control flow statements, the following values are interpreted as |
| 1423 | false: \verb\None\, numeric zero of all types, empty sequences |
| 1424 | (strings, tuples and lists), and empty mappings (dictionaries). All |
| 1425 | other values are interpreted as true. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1426 | |
| 1427 | The operator \verb\not\ yields 1 if its argument is false, 0 otherwise. |
| 1428 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1429 | The condition $x ~\verb\and\~ y$ first evaluates $x$; if $x$ is false, |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1430 | $x$ is returned; otherwise, $y$ is evaluated and returned. |
| 1431 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1432 | The condition $x ~\verb\or\~ y$ first evaluates $x$; if $x$ is true, |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1433 | $x$ is returned; otherwise, $y$ is evaluated and returned. |
| 1434 | |
| 1435 | (Note that \verb\and\ and \verb\or\ do not restrict the value and type |
| 1436 | they return to 0 and 1, but rather return the last evaluated argument. |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1437 | This is sometimes useful, e.g., if \verb\s\ is a string, which should be |
| 1438 | replaced by a default value if it is empty, \verb\s or 'foo'\ |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1439 | returns the desired value. Because \verb\not\ has to invent a value |
| 1440 | anyway, it does not bother to return a value of the same type as its |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1441 | argument, so \verb\not 'foo'\ yields \verb\0\, not \verb\''\.) |
| 1442 | |
| 1443 | \section{Expression lists and condition lists} |
| 1444 | |
| 1445 | \begin{verbatim} |
| 1446 | expr_list: or_expr ("," or_expr)* [","] |
| 1447 | cond_list: condition ("," condition)* [","] |
| 1448 | \end{verbatim} |
| 1449 | |
| 1450 | The only difference between expression lists and condition lists is |
| 1451 | the lowest priority of operators that can be used in them without |
| 1452 | being enclosed in parentheses; condition lists allow all operators, |
| 1453 | while expression lists don't allow comparisons and Boolean operators |
| 1454 | (they do allow bitwise and shift operators though). |
| 1455 | |
| 1456 | Expression lists are used in expression statements and assignments; |
| 1457 | condition lists are used everywhere else. |
| 1458 | |
| 1459 | An expression (condition) list containing at least one comma yields a |
| 1460 | tuple. The length of the tuple is the number of expressions |
| 1461 | (conditions) in the list. The expressions (conditions) are evaluated |
| 1462 | from left to right. |
| 1463 | |
| 1464 | The trailing comma is required only to create a single tuple (a.k.a. a |
| 1465 | {\em singleton}); it is optional in all other cases. A single |
| 1466 | expression (condition) without a trailing comma doesn't create a |
| 1467 | tuple, but rather yields the value of that expression (condition). |
| 1468 | |
| 1469 | To create an empty tuple, use an empty pair of parentheses: \verb\()\. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1470 | |
| 1471 | \chapter{Simple statements} |
| 1472 | |
| 1473 | Simple statements are comprised within a single logical line. |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1474 | Several simple statements may occur on a single line separated |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1475 | by semicolons. The syntax for simple statements is: |
| 1476 | |
| 1477 | \begin{verbatim} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1478 | simple_stmt: expression_stmt |
| 1479 | | assignment |
| 1480 | | pass_stmt |
| 1481 | | del_stmt |
| 1482 | | print_stmt |
| 1483 | | return_stmt |
| 1484 | | raise_stmt |
| 1485 | | break_stmt |
| 1486 | | continue_stmt |
| 1487 | | import_stmt |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1488 | | global_stmt |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1489 | \end{verbatim} |
| 1490 | |
| 1491 | \section{Expression statements} |
| 1492 | |
| 1493 | \begin{verbatim} |
| 1494 | expression_stmt: expression_list |
| 1495 | \end{verbatim} |
| 1496 | |
| 1497 | An expression statement evaluates the expression list (which may |
| 1498 | be a single expression). |
| 1499 | If the value is not \verb\None\, it is converted to a string |
| 1500 | using the rules for string conversions, and the resulting string |
| 1501 | is written to standard output on a line by itself. |
| 1502 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1503 | (The exception for \verb\None\ is made so that procedure calls, which |
| 1504 | are syntactically equivalent to expressions, do not cause any output. |
| 1505 | A tuple with only \verb\None\ items is written normally.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1506 | |
| 1507 | \section{Assignments} |
| 1508 | |
| 1509 | \begin{verbatim} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1510 | assignment: (target_list "=")+ expression_list |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1511 | target_list: target ("," target)* [","] |
| 1512 | target: identifier | "(" target_list ")" | "[" target_list "]" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1513 | | attributeref | subscription | slicing |
| 1514 | \end{verbatim} |
| 1515 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1516 | (See the section on primaries for the syntax definition of the last |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1517 | three symbols.) |
| 1518 | |
| 1519 | An assignment evaluates the expression list (remember that this can |
| 1520 | be a single expression or a comma-separated list, |
| 1521 | the latter yielding a tuple) |
| 1522 | and assigns the single resulting object to each of the target lists, |
| 1523 | from left to right. |
| 1524 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1525 | Assignment is defined recursively depending on the form of the target. |
| 1526 | When a target is part of a mutable object (an attribute reference, |
| 1527 | subscription or slicing), the mutable object must ultimately perform |
| 1528 | the assignment and decide about its validity, and may raise an |
| 1529 | exception if the assignment is unacceptable. The rules observed by |
| 1530 | various types and the exceptions raised are given with the definition |
| 1531 | of the object types (some of which are defined in the library |
| 1532 | reference). |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1533 | |
| 1534 | Assignment of an object to a target list is recursively |
| 1535 | defined as follows. |
| 1536 | |
| 1537 | \begin{itemize} |
| 1538 | \item |
| 1539 | If the target list contains no commas (except in nested constructs): |
| 1540 | the object is assigned to the single target contained in the list. |
| 1541 | |
| 1542 | \item |
| 1543 | If the target list contains commas (that are not in nested constructs): |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1544 | the object must be a tuple with the same number of items |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1545 | as the list contains targets, and the items are assigned, from left |
| 1546 | to right, to the corresponding targets. |
| 1547 | |
| 1548 | \end{itemize} |
| 1549 | |
| 1550 | Assignment of an object to a (non-list) |
| 1551 | target is recursively defined as follows. |
| 1552 | |
| 1553 | \begin{itemize} |
| 1554 | |
| 1555 | \item |
| 1556 | If the target is an identifier (name): |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1557 | \begin{itemize} |
| 1558 | \item |
| 1559 | If the name does not occur in a \verb\global\ statement in the current |
| 1560 | code block: the object is bound to that name in the current local |
| 1561 | name space. |
| 1562 | \item |
| 1563 | Otherwise: the object is bound to that name in the current global name |
| 1564 | space. |
| 1565 | \end{itemize} |
| 1566 | A previous binding of the same name in the same name space is undone. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1567 | |
| 1568 | \item |
| 1569 | If the target is a target list enclosed in parentheses: |
| 1570 | the object is assigned to that target list. |
| 1571 | |
| 1572 | \item |
| 1573 | If the target is a target list enclosed in square brackets: |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1574 | the object must be a list with the same number of items |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1575 | as the target list contains targets, |
| 1576 | and the list's items are assigned, from left to right, |
| 1577 | to the corresponding targets. |
| 1578 | |
| 1579 | \item |
| 1580 | If the target is an attribute reference: |
| 1581 | The primary expression in the reference is evaluated. |
| 1582 | It should yield an object with assignable attributes; |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1583 | if this is not the case, \verb\TypeError\ is raised. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1584 | That object is then asked to assign the assigned object |
| 1585 | to the given attribute; if it cannot perform the assignment, |
| 1586 | it raises an exception. |
| 1587 | |
| 1588 | \item |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1589 | If the target is a subscription: The primary expression in the |
| 1590 | reference is evaluated. It should yield either a mutable sequence |
| 1591 | (list) object or a mapping (dictionary) object. Next, the subscript |
| 1592 | expression is evaluated. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1593 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1594 | If the primary is a sequence object, the subscript must yield a plain |
| 1595 | integer. If it is negative, the sequence's length is added to it. |
| 1596 | The resulting value must be a nonnegative integer less than the |
| 1597 | sequence's length, and the sequence is asked to assign the assigned |
| 1598 | object to its item with that index. If the index is out of range, |
| 1599 | \verb\IndexError\ is raised (assignment to a subscripted sequence |
| 1600 | cannot add new items to a list). |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1601 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1602 | If the primary is a mapping object, the subscript must have a type |
| 1603 | compatible with the mapping's key type, and the mapping is then asked |
| 1604 | to to create a key/datum pair which maps the subscript to the assigned |
| 1605 | object. This can either replace an existing key/value pair with the |
| 1606 | same key value, or insert a new key/value pair (if no key with the |
| 1607 | same value existed). |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1608 | |
| 1609 | \item |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1610 | If the target is a slicing: The primary expression in the reference is |
| 1611 | evaluated. It should yield a mutable sequence (list) object. The |
| 1612 | assigned object should be a sequence object of the same type. Next, |
| 1613 | the lower and upper bound expressions are evaluated, insofar they are |
| 1614 | present; defaults are zero and the sequence's length. The bounds |
| 1615 | should evaluate to (small) integers. If either bound is negative, the |
| 1616 | sequence's length is added to it. The resulting bounds are clipped to |
| 1617 | lie between zero and the sequence's length, inclusive. Finally, the |
| 1618 | sequence object is asked to replace the items indicated by the slice |
| 1619 | with the items of the assigned sequence. This may change the |
| 1620 | sequence's length, if it allows it. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1621 | |
| 1622 | \end{itemize} |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1623 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1624 | (In the original implementation, the syntax for targets is taken |
| 1625 | to be the same as for expressions, and invalid syntax is rejected |
| 1626 | during the code generation phase, causing less detailed error |
| 1627 | messages.) |
| 1628 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1629 | \section{The {\tt pass} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1630 | |
| 1631 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1632 | pass_stmt: "pass" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1633 | \end{verbatim} |
| 1634 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1635 | \verb\pass\ is a null operation -- when it is executed, nothing |
| 1636 | happens. It is useful as a placeholder when a statement is |
| 1637 | required syntactically, but no code needs to be executed, for example: |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1638 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1639 | \begin{verbatim} |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 1640 | def f(arg): pass # a function that does nothing (yet) |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1641 | |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 1642 | class C: pass # an class with no methods (yet) |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1643 | \end{verbatim} |
| 1644 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1645 | \section{The {\tt del} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1646 | |
| 1647 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1648 | del_stmt: "del" target_list |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1649 | \end{verbatim} |
| 1650 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1651 | Deletion is recursively defined very similar to the way assignment is |
| 1652 | defined. Rather that spelling it out in full details, here are some |
| 1653 | hints. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1654 | |
| 1655 | Deletion of a target list recursively deletes each target, |
| 1656 | from left to right. |
| 1657 | |
| 1658 | Deletion of a name removes the binding of that name (which must exist) |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1659 | from the local or global name space, depending on whether the name |
| 1660 | occurs in a \verb\global\ statement in the same code block. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1661 | |
| 1662 | Deletion of attribute references, subscriptions and slicings |
| 1663 | is passed to the primary object involved; deletion of a slicing |
| 1664 | is in general equivalent to assignment of an empty slice of the |
| 1665 | right type (but even this is determined by the sliced object). |
| 1666 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1667 | \section{The {\tt print} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1668 | |
| 1669 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1670 | print_stmt: "print" [ condition ("," condition)* [","] ] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1671 | \end{verbatim} |
| 1672 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1673 | \verb\print\ evaluates each condition in turn and writes the resulting |
| 1674 | object to standard output (see below). If an object is not a string, |
| 1675 | it is first converted to a string using the rules for string |
| 1676 | conversions. The (resulting or original) string is then written. A |
| 1677 | space is written before each object is (converted and) written, unless |
| 1678 | the output system believes it is positioned at the beginning of a |
| 1679 | line. This is the case: (1) when no characters have yet been written |
| 1680 | to standard output; or (2) when the last character written to standard |
| 1681 | output is \verb/\n/; or (3) when the last write operation on standard |
| 1682 | output was not a \verb\print\ statement. (In some cases it may be |
| 1683 | functional to write an empty string to standard output for this |
| 1684 | reason.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1685 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1686 | A \verb/"\n"/ character is written at the end, unless the \verb\print\ |
| 1687 | statement ends with a comma. This is the only action if the statement |
| 1688 | contains just the keyword \verb\print\. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1689 | |
| 1690 | Standard output is defined as the file object named \verb\stdout\ |
| 1691 | in the built-in module \verb\sys\. If no such object exists, |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1692 | or if it is not a writable file, a \verb\RuntimeError\ exception is raised. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1693 | (The original implementation attempts to write to the system's original |
| 1694 | standard output instead, but this is not safe, and should be fixed.) |
| 1695 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1696 | \section{The {\tt return} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1697 | |
| 1698 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1699 | return_stmt: "return" [condition_list] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1700 | \end{verbatim} |
| 1701 | |
| 1702 | \verb\return\ may only occur syntactically nested in a function |
| 1703 | definition, not within a nested class definition. |
| 1704 | |
| 1705 | If a condition list is present, it is evaluated, else \verb\None\ |
| 1706 | is substituted. |
| 1707 | |
| 1708 | \verb\return\ leaves the current function call with the condition |
| 1709 | list (or \verb\None\) as return value. |
| 1710 | |
| 1711 | When \verb\return\ passes control out of a \verb\try\ statement |
| 1712 | with a \verb\finally\ clause, that finally clause is executed |
| 1713 | before really leaving the function. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1714 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1715 | \section{The {\tt raise} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1716 | |
| 1717 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1718 | raise_stmt: "raise" condition ["," condition] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1719 | \end{verbatim} |
| 1720 | |
| 1721 | \verb\raise\ evaluates its first condition, which must yield |
| 1722 | a string object. If there is a second condition, this is evaluated, |
| 1723 | else \verb\None\ is substituted. |
| 1724 | |
| 1725 | It then raises the exception identified by the first object, |
| 1726 | with the second one (or \verb\None\) as its parameter. |
| 1727 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1728 | \section{The {\tt break} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1729 | |
| 1730 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1731 | break_stmt: "break" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1732 | \end{verbatim} |
| 1733 | |
| 1734 | \verb\break\ may only occur syntactically nested in a \verb\for\ |
| 1735 | or \verb\while\ loop, not nested in a function or class definition. |
| 1736 | |
| 1737 | It terminates the neares enclosing loop, skipping the optional |
| 1738 | \verb\else\ clause if the loop has one. |
| 1739 | |
| 1740 | If a \verb\for\ loop is terminated by \verb\break\, the loop control |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1741 | target keeps its current value. |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1742 | |
| 1743 | When \verb\break\ passes control out of a \verb\try\ statement |
| 1744 | with a \verb\finally\ clause, that finally clause is executed |
| 1745 | before really leaving the loop. |
| 1746 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1747 | \section{The {\tt continue} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1748 | |
| 1749 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1750 | continue_stmt: "continue" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1751 | \end{verbatim} |
| 1752 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1753 | \verb\continue\ may only occur syntactically nested in a \verb\for\ or |
| 1754 | \verb\while\ loop, not nested in a function or class definition, and |
| 1755 | not nested in the \verb\try\ clause of a \verb\try\ statement with a |
| 1756 | \verb\finally\ clause (it may occur nested in a \verb\except\ or |
| 1757 | \verb\finally\ clause of a \verb\try\ statement though). |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1758 | |
| 1759 | It continues with the next cycle of the nearest enclosing loop. |
| 1760 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 1761 | \section{The {\tt import} statement} \label{import} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1762 | |
| 1763 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1764 | import_stmt: "import" identifier ("," identifier)* |
| 1765 | | "from" identifier "import" identifier ("," identifier)* |
| 1766 | | "from" identifier "import" "*" |
| 1767 | \end{verbatim} |
| 1768 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1769 | Import statements are executed in two steps: (1) find a module, and |
| 1770 | initialize it if necessary; (2) define a name or names in the local |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1771 | name space (of the scope where the \verb\import\ statement occurs). |
| 1772 | The first form (without \verb\from\) repeats these steps for each |
| 1773 | identifier in the list, the \verb\from\ form performs them once, with |
| 1774 | the first identifier specifying the module name. |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1775 | |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1776 | The system maintains a table of modules that have been initialized, |
| 1777 | indexed by module name. (The current implementation makes this table |
| 1778 | accessible as \verb\sys.modules\.) When a module name is found in |
| 1779 | this table, step (1) is finished. If not, a search for a module |
| 1780 | definition is started. This first looks for a built-in module |
| 1781 | definition, and if no built-in module if the given name is found, it |
| 1782 | searches a user-specified list of directories for a file whose name is |
| 1783 | the module name with extension \verb\".py"\. (The current |
| 1784 | implementation uses the list of strings \verb\sys.path\ as the search |
| 1785 | path; it is initialized from the shell environment variable |
| 1786 | \verb\$PYTHONPATH\, with an installation-dependent default.) |
| 1787 | |
| 1788 | If a built-in module is found, its built-in initialization code is |
| 1789 | executed and step (1) is finished. If no matching file is found, |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1790 | \verb\ImportError\ is raised. If a file is found, it is parsed, |
| 1791 | yielding an executable code block. If a syntax error occurs, |
| 1792 | \verb\SyntaxError\ is raised. Otherwise, an empty module of the given |
| 1793 | name is created and inserted in the module table, and then the code |
| 1794 | block is executed in the context of this module. Exceptions during |
| 1795 | this execution terminate step (1). |
| 1796 | |
| 1797 | When step (1) finishes without raising an exception, step (2) can |
| 1798 | begin. |
| 1799 | |
| 1800 | The first form of \verb\import\ statement binds the module name in the |
| 1801 | local name space to the module object, and then goes on to import the |
| 1802 | next identifier, if any. The \verb\from\ from does not bind the |
| 1803 | module name: it goes through the list of identifiers, looks each one |
| 1804 | of them up in the module found in step (1), and binds the name in the |
| 1805 | local name space to the object thus found. If a name is not found, |
| 1806 | \verb\ImportError\ is raised. If the list of identifiers is replaced |
| 1807 | by a star (\verb\*\), all names defined in the module are bound, |
| 1808 | except those beginning with an underscore(\verb\_\). |
| 1809 | |
| 1810 | Names bound by import statements may not occur in \verb\global\ |
| 1811 | statements in the same scope. |
| 1812 | |
| 1813 | The \verb\from\ form with \verb\*\ may only occur in a module scope. |
| 1814 | |
| 1815 | (The current implementation does not enforce the latter two |
| 1816 | restrictions, but programs should not abuse this freedom, as future |
| 1817 | implementations may enforce them or silently change the meaning of the |
| 1818 | program.) |
Guido van Rossum | 0f1f9da | 1992-01-20 17:10:21 +0000 | [diff] [blame] | 1819 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 1820 | \section{The {\tt global} statement} \label{global} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1821 | |
| 1822 | \begin{verbatim} |
| 1823 | global_stmt: "global" identifier ("," identifier)* |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1824 | \end{verbatim} |
| 1825 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1826 | The \verb\global\ statement is a declaration which holds for the |
| 1827 | entire current scope. It means that the listed identifiers are to be |
| 1828 | interpreted as globals. While {\em using} global names is automatic |
| 1829 | if they are not defined in the local scope, {\em assigning} to global |
| 1830 | names would be impossible without \verb\global\. |
| 1831 | |
| 1832 | Names listed in a \verb\global\ statement must not be used in the same |
| 1833 | scope before that \verb\global\ statement is executed. |
| 1834 | |
| 1835 | Name listed in a \verb\global\ statement must not be defined as formal |
| 1836 | parameters or in a \verb\for\ loop control target, \verb\class\ |
| 1837 | definition, function definition, or \verb\import\ statement. |
| 1838 | |
| 1839 | (The current implementation does not enforce the latter two |
| 1840 | restrictions, but programs should not abuse this freedom, as future |
| 1841 | implementations may enforce them or silently change the meaning of the |
| 1842 | program.) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1843 | |
| 1844 | \chapter{Compound statements} |
| 1845 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1846 | Compound statements contain (groups of) other statements; they affect |
| 1847 | or control the execution of those other statements in some way. |
| 1848 | |
| 1849 | The \verb\if\, \verb\while\ and \verb\for\ statements implement |
| 1850 | traditional control flow constructs. \verb\try\ specifies exception |
| 1851 | handlers and/or cleanup code for a group of statements. Function and |
| 1852 | class definitions are also syntactically compound statements. |
| 1853 | |
| 1854 | Compound statements consist of one or more `clauses'. A clause |
| 1855 | consists of a header and a `suite'. The clause headers of a |
| 1856 | particular compound statement are all at the same indentation level; |
| 1857 | all clauses begin with a uniquely identifying keyword and end with a |
| 1858 | colon. A suite is a group of statements controlled by a clause. A |
| 1859 | suite can be a bunch of semicolon-separated simple statements on the |
| 1860 | same line as the header, following the colon, or it can be a list of |
| 1861 | indented statements. Only the latter form of suite can contain nested |
| 1862 | compound statements; the following is illegal (mostly because it |
| 1863 | wouldn't be clear what to do with \verb\else\): |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1864 | |
| 1865 | \begin{verbatim} |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1866 | if test1: if test2: print x |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1867 | \end{verbatim} |
| 1868 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1869 | Also note that the semicolon binds tighter that the colon in this |
| 1870 | context (so to speak), so that in the following example, either all or |
| 1871 | none of the \verb\print\ statements are executed: |
| 1872 | |
| 1873 | \begin{verbatim} |
| 1874 | if some_test: print x; print y; print z |
| 1875 | \end{verbatim} |
| 1876 | |
| 1877 | Summarizing: |
| 1878 | |
| 1879 | \begin{verbatim} |
| 1880 | compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | funcdef | classdef |
| 1881 | suite: stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT |
| 1882 | statement: stmt_list NEWLINE | compound_stmt |
| 1883 | stmt_list: simple_stmt (";" simple_stmt)* [";"] |
| 1884 | \end{verbatim} |
| 1885 | |
| 1886 | Note that statements always ends in a \verb\NEWLINE\ possibly followed |
| 1887 | by a \verb\DEDENT\. |
| 1888 | |
| 1889 | Also note that optional continuation clauses always begin with a |
| 1890 | keyword that cannot start a statement, thus there are no ambiguities |
| 1891 | (the `dangling \verb\else\' problem is solved in Python by requiring |
| 1892 | nested \verb\if\ statements to be indented). |
| 1893 | |
| 1894 | The formatting of the grammar rules in the following section places |
| 1895 | each clause on a separate line for clarity. |
| 1896 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1897 | \section{The {\tt if} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1898 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1899 | The \verb\if\ statement is used for conditional execution: |
| 1900 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1901 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1902 | if_stmt: "if" condition ":" suite |
| 1903 | ("elif" condition ":" suite)* |
| 1904 | ["else" ":" suite] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1905 | \end{verbatim} |
| 1906 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1907 | It selects exactly one of the suites, by testing the conditions one by |
| 1908 | one until one is true; then that suite is executed. If all conditions |
| 1909 | are false, the suite of the \verb\else\ clause is executed, if present. |
| 1910 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1911 | \section{The {\tt while} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1912 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1913 | The \verb\while\ statement is used for repeated execution as long as a |
| 1914 | condition is true: |
| 1915 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1916 | \begin{verbatim} |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1917 | while_stmt: "while" condition ":" suite |
| 1918 | ["else" ":" suite] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1919 | \end{verbatim} |
| 1920 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1921 | This repeatedly tests the condition and, if it is true, executes the |
| 1922 | first suite; if the condition is false (which may be the first time it |
| 1923 | is tested) the suite of the \verb\else\ clause is executed, if |
| 1924 | present, and the loop terminates. |
| 1925 | |
| 1926 | A \verb\break\ statement executed in the first suite terminates the |
| 1927 | loop without executing the \verb\else\ clause's suite. A |
| 1928 | \verb\continue\ statement executed in the first suited skips the rest |
| 1929 | of the suite and goes back to testing the condition. |
| 1930 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1931 | \section{The {\tt for} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1932 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1933 | The \verb\for\ statement is used to iterate over the elements of a |
| 1934 | sequence (string, tuple or list): |
| 1935 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1936 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1937 | for_stmt: "for" target_list "in" condition_list ":" suite |
| 1938 | ["else" ":" suite] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1939 | \end{verbatim} |
| 1940 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1941 | The suite is executed once for each item in the condition list, in the |
| 1942 | order of ascending indices. Each item in turn is assigned to the |
| 1943 | target list using the standard rules for assignments, and then the |
| 1944 | suite is executed. When the list is exhausted (which is immediately |
| 1945 | when the sequence is empty), the suite in the \verb\else\ clause is |
| 1946 | executed, if present. |
| 1947 | |
| 1948 | A \verb\break\ statement executed in the first suite terminates the |
| 1949 | loop without executing the \verb\else\ clause's suite. A |
| 1950 | \verb\continue\ statement executed in the first suited skips the rest |
| 1951 | of the suite and continues with the next item or with the \verb\else\ |
| 1952 | clause. |
| 1953 | |
| 1954 | The suite may assign to the variable(s) in the target list; this does |
| 1955 | not affect the next item assigned to it. |
| 1956 | |
| 1957 | The target list are not deleted when the loop is finished (but if the |
| 1958 | loop has executed 0 times it will not have been assigned to at all by |
| 1959 | the loop). |
| 1960 | |
| 1961 | The built-in function \verb\range()\ returns a sequence of integers |
| 1962 | suitable to emulate the effect of Pascal's \verb\for i := 1 to n do\. |
| 1963 | |
| 1964 | {\bf Warning:} There is a subtlety when the sequence is being modified |
| 1965 | by the loop (this can only occur for lists). An internal counter is |
| 1966 | used to keep track of which item is used next, and this is incremented |
| 1967 | on each iteration. When this counter has reached the end of the |
| 1968 | sequence the loop terminates. This means that if the suite deletes |
| 1969 | the current (or a previous) item from the sequence, the next item will |
| 1970 | be skipped (since it gets the index of the current item and this has |
| 1971 | already been treated). Likewise, if the suite inserts an item in the |
| 1972 | sequence before the current item, the current item will be treated |
| 1973 | again the next time through the loop. This can lead to nasty bugs |
| 1974 | that can be avoided by making a temporary copy using the \ |
| 1975 | |
Guido van Rossum | 68c172e | 1992-01-21 11:34:56 +0000 | [diff] [blame] | 1976 | \section{The {\tt try} statement} |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1977 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1978 | The \verb\try\ statement specifies exception handlers and/or cleanup |
| 1979 | code for a group of statements: |
| 1980 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1981 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1982 | try_stmt: "try" ":" suite |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 1983 | ("except" condition ["," target] ":" suite)* |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1984 | ["except" ":" suite] |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 1985 | ["finally" ":" suite] |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 1986 | \end{verbatim} |
| 1987 | |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 1988 | There are really two forms: \verb\try...except\ and |
| 1989 | \verb\try...finally\. A \verb\try\ statement with both types of |
| 1990 | clauses is equivalent to a \verb\try...finally\ statement with a |
| 1991 | \verb\try...except\ statement in its \verb\try\ clause. A \verb\try\ |
| 1992 | statement with neither a \verb\except\ clause nor a \verb\finally\ |
| 1993 | clause just executes the suite of statements in its \verb\try\ clause. |
| 1994 | |
| 1995 | The \verb\try...except\ form specifies one or more exception handlers. |
| 1996 | When no exception occurs in the \verb\try\ clause, no exception |
| 1997 | handler is executed. When an exception occurs in the \verb\try\ |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 1998 | suite, a search for an exception handler is started. This inspects |
| 1999 | the except clauses (exception handlers) in turn until one is found |
| 2000 | that matches the exception. A condition-less except clause (which |
| 2001 | must be last) matches any exception. For except clause with a |
| 2002 | condition, that condition is evaluated, and the clause matches the |
| 2003 | exception if the resulting object is ``compatible'' with the |
| 2004 | exception. An object is compatible with an exception if it is either |
| 2005 | the object that identifies the exception or it is a tuple containing |
| 2006 | an item that is compatible with the exception. |
| 2007 | |
| 2008 | If no except clause matches the exception, the search for an exception |
| 2009 | handler continues in the surrounding code and on the invocation stack. |
| 2010 | |
| 2011 | If the evaluation of a condition in the header of an except clause |
| 2012 | raises an exception, the original search for a handler is cancelled |
| 2013 | and a search starts for the new exception in the surrounding code and |
| 2014 | on the call stack. |
| 2015 | |
| 2016 | When a matching except clause is found in a try statement, the |
| 2017 | exception's parameter is assigned to the target specified in the |
| 2018 | except clause (if present), and the except clause's suite is executed. |
| 2019 | When the end of this suite is reached, execution continues normally |
| 2020 | at the point following the entire try statement. (This means that if |
| 2021 | two nested handlers exist for the same exception, and the exception |
| 2022 | occurs in the try clause of the inner handler, the outer handler will |
| 2023 | not notice the exception.) |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 2024 | |
| 2025 | The \verb\try...finally\ form specifies a `cleanup' handler. The |
| 2026 | \verb\try\ clause is executed. When no exception occurs, the |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 2027 | \verb\finally\ clause is executed. When an exception occurs in the |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 2028 | \verb\try\ clause, the exception is temporarily saved, the |
| 2029 | \verb\finally\ clause is executed, and then the saved exception is |
| 2030 | re-raised. If the \verb\finally\ clause raises another exception or |
| 2031 | executes a \verb\return\, \verb\break\ or \verb\continue\ statement, |
| 2032 | the saved exception is lost. |
| 2033 | |
| 2034 | When a \verb\return\ or \verb\break\ statement is executed in the |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 2035 | \verb\try\ suite of a \verb\try...finally\ statement, the |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 2036 | \verb\finally\ clause is also executed `on the way out'. A |
| 2037 | \verb\continue\ statement is illegal in the \verb\try\ clause (the |
| 2038 | reason is a problem with the current implementation -- this |
| 2039 | restriction may be lifted in the future). |
| 2040 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 2041 | \section{Function definitions} \label{function} |
Guido van Rossum | 255ad6e | 1992-01-28 18:10:46 +0000 | [diff] [blame] | 2042 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 2043 | XXX |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2044 | |
| 2045 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 2046 | funcdef: "def" identifier "(" [parameter_list] ")" ":" suite |
| 2047 | parameter_list: parameter ("," parameter)* |
| 2048 | parameter: identifier | "(" parameter_list ")" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2049 | \end{verbatim} |
| 2050 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 2051 | XXX |
| 2052 | |
| 2053 | \section{Class definitions} \label{class} |
| 2054 | |
| 2055 | XXX |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2056 | |
| 2057 | \begin{verbatim} |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 2058 | classdef: "class" identifier [inheritance] ":" suite |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 2059 | inheritance: "(" condition_list ")" |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2060 | \end{verbatim} |
| 2061 | |
Guido van Rossum | 862c6f1 | 1992-01-29 14:47:05 +0000 | [diff] [blame] | 2062 | XXX |
| 2063 | |
| 2064 | \section{P.M.} |
| 2065 | |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2066 | XXX Syntax for scripts, modules |
Guido van Rossum | cf8148b | 1992-03-02 16:13:50 +0000 | [diff] [blame^] | 2067 | XXX Syntax for interactive input, eval, exec, execfile, input |
Guido van Rossum | 743d1e7 | 1992-01-07 16:43:53 +0000 | [diff] [blame] | 2068 | XXX New definition of expressions (as conditions) |
Guido van Rossum | f2612d1 | 1991-11-21 13:53:03 +0000 | [diff] [blame] | 2069 | |
| 2070 | \end{document} |