# Python code coverage for Lib/pydoc_data/topics.py

# | count | content |
---|---|---|

1 | n/a | # -*- coding: utf-8 -*- |

2 | n/a | # Autogenerated by Sphinx on Mon Sep 12 10:47:11 2016 |

3 | n/a | topics = {'assert': '\n' |

4 | n/a | 'The "assert" statement\n' |

5 | n/a | '**********************\n' |

6 | n/a | '\n' |

7 | n/a | 'Assert statements are a convenient way to insert debugging ' |

8 | n/a | 'assertions\n' |

9 | n/a | 'into a program:\n' |

10 | n/a | '\n' |

11 | n/a | ' assert_stmt ::= "assert" expression ["," expression]\n' |

12 | n/a | '\n' |

13 | n/a | 'The simple form, "assert expression", is equivalent to\n' |

14 | n/a | '\n' |

15 | n/a | ' if __debug__:\n' |

16 | n/a | ' if not expression: raise AssertionError\n' |

17 | n/a | '\n' |

18 | n/a | 'The extended form, "assert expression1, expression2", is ' |

19 | n/a | 'equivalent to\n' |

20 | n/a | '\n' |

21 | n/a | ' if __debug__:\n' |

22 | n/a | ' if not expression1: raise AssertionError(expression2)\n' |

23 | n/a | '\n' |

24 | n/a | 'These equivalences assume that "__debug__" and "AssertionError" ' |

25 | n/a | 'refer\n' |

26 | n/a | 'to the built-in variables with those names. In the current\n' |

27 | n/a | 'implementation, the built-in variable "__debug__" is "True" under\n' |

28 | n/a | 'normal circumstances, "False" when optimization is requested ' |

29 | n/a | '(command\n' |

30 | n/a | 'line option -O). The current code generator emits no code for an\n' |

31 | n/a | 'assert statement when optimization is requested at compile time. ' |

32 | n/a | 'Note\n' |

33 | n/a | 'that it is unnecessary to include the source code for the ' |

34 | n/a | 'expression\n' |

35 | n/a | 'that failed in the error message; it will be displayed as part of ' |

36 | n/a | 'the\n' |

37 | n/a | 'stack trace.\n' |

38 | n/a | '\n' |

39 | n/a | 'Assignments to "__debug__" are illegal. The value for the ' |

40 | n/a | 'built-in\n' |

41 | n/a | 'variable is determined when the interpreter starts.\n', |

42 | n/a | 'assignment': '\n' |

43 | n/a | 'Assignment statements\n' |

44 | n/a | '*********************\n' |

45 | n/a | '\n' |

46 | n/a | 'Assignment statements are used to (re)bind names to values and ' |

47 | n/a | 'to\n' |

48 | n/a | 'modify attributes or items of mutable objects:\n' |

49 | n/a | '\n' |

50 | n/a | ' assignment_stmt ::= (target_list "=")+ (starred_expression ' |

51 | n/a | '| yield_expression)\n' |

52 | n/a | ' target_list ::= target ("," target)* [","]\n' |

53 | n/a | ' target ::= identifier\n' |

54 | n/a | ' | "(" [target_list] ")"\n' |

55 | n/a | ' | "[" [target_list] "]"\n' |

56 | n/a | ' | attributeref\n' |

57 | n/a | ' | subscription\n' |

58 | n/a | ' | slicing\n' |

59 | n/a | ' | "*" target\n' |

60 | n/a | '\n' |

61 | n/a | '(See section Primaries for the syntax definitions for ' |

62 | n/a | '*attributeref*,\n' |

63 | n/a | '*subscription*, and *slicing*.)\n' |

64 | n/a | '\n' |

65 | n/a | 'An assignment statement evaluates the expression list ' |

66 | n/a | '(remember that\n' |

67 | n/a | 'this can be a single expression or a comma-separated list, the ' |

68 | n/a | 'latter\n' |

69 | n/a | 'yielding a tuple) and assigns the single resulting object to ' |

70 | n/a | 'each of\n' |

71 | n/a | 'the target lists, from left to right.\n' |

72 | n/a | '\n' |

73 | n/a | 'Assignment is defined recursively depending on the form of the ' |

74 | n/a | 'target\n' |

75 | n/a | '(list). When a target is part of a mutable object (an ' |

76 | n/a | 'attribute\n' |

77 | n/a | 'reference, subscription or slicing), the mutable object must\n' |

78 | n/a | 'ultimately perform the assignment and decide about its ' |

79 | n/a | 'validity, and\n' |

80 | n/a | 'may raise an exception if the assignment is unacceptable. The ' |

81 | n/a | 'rules\n' |

82 | n/a | 'observed by various types and the exceptions raised are given ' |

83 | n/a | 'with the\n' |

84 | n/a | 'definition of the object types (see section The standard type\n' |

85 | n/a | 'hierarchy).\n' |

86 | n/a | '\n' |

87 | n/a | 'Assignment of an object to a target list, optionally enclosed ' |

88 | n/a | 'in\n' |

89 | n/a | 'parentheses or square brackets, is recursively defined as ' |

90 | n/a | 'follows.\n' |

91 | n/a | '\n' |

92 | n/a | '* If the target list is empty: The object must also be an ' |

93 | n/a | 'empty\n' |

94 | n/a | ' iterable.\n' |

95 | n/a | '\n' |

96 | n/a | '* If the target list is a single target in parentheses: The ' |

97 | n/a | 'object\n' |

98 | n/a | ' is assigned to that target.\n' |

99 | n/a | '\n' |

100 | n/a | '* If the target list is a comma-separated list of targets, or ' |

101 | n/a | 'a\n' |

102 | n/a | ' single target in square brackets: The object must be an ' |

103 | n/a | 'iterable\n' |

104 | n/a | ' with the same number of items as there are targets in the ' |

105 | n/a | 'target\n' |

106 | n/a | ' list, and the items are assigned, from left to right, to ' |

107 | n/a | 'the\n' |

108 | n/a | ' corresponding targets.\n' |

109 | n/a | '\n' |

110 | n/a | ' * If the target list contains one target prefixed with an\n' |

111 | n/a | ' asterisk, called a "starred" target: The object must be ' |

112 | n/a | 'an\n' |

113 | n/a | ' iterable with at least as many items as there are targets ' |

114 | n/a | 'in the\n' |

115 | n/a | ' target list, minus one. The first items of the iterable ' |

116 | n/a | 'are\n' |

117 | n/a | ' assigned, from left to right, to the targets before the ' |

118 | n/a | 'starred\n' |

119 | n/a | ' target. The final items of the iterable are assigned to ' |

120 | n/a | 'the\n' |

121 | n/a | ' targets after the starred target. A list of the remaining ' |

122 | n/a | 'items\n' |

123 | n/a | ' in the iterable is then assigned to the starred target ' |

124 | n/a | '(the list\n' |

125 | n/a | ' can be empty).\n' |

126 | n/a | '\n' |

127 | n/a | ' * Else: The object must be an iterable with the same number ' |

128 | n/a | 'of\n' |

129 | n/a | ' items as there are targets in the target list, and the ' |

130 | n/a | 'items are\n' |

131 | n/a | ' assigned, from left to right, to the corresponding ' |

132 | n/a | 'targets.\n' |

133 | n/a | '\n' |

134 | n/a | 'Assignment of an object to a single target is recursively ' |

135 | n/a | 'defined as\n' |

136 | n/a | 'follows.\n' |

137 | n/a | '\n' |

138 | n/a | '* If the target is an identifier (name):\n' |

139 | n/a | '\n' |

140 | n/a | ' * If the name does not occur in a "global" or "nonlocal" ' |

141 | n/a | 'statement\n' |

142 | n/a | ' in the current code block: the name is bound to the object ' |

143 | n/a | 'in the\n' |

144 | n/a | ' current local namespace.\n' |

145 | n/a | '\n' |

146 | n/a | ' * Otherwise: the name is bound to the object in the global\n' |

147 | n/a | ' namespace or the outer namespace determined by ' |

148 | n/a | '"nonlocal",\n' |

149 | n/a | ' respectively.\n' |

150 | n/a | '\n' |

151 | n/a | ' The name is rebound if it was already bound. This may cause ' |

152 | n/a | 'the\n' |

153 | n/a | ' reference count for the object previously bound to the name ' |

154 | n/a | 'to reach\n' |

155 | n/a | ' zero, causing the object to be deallocated and its ' |

156 | n/a | 'destructor (if it\n' |

157 | n/a | ' has one) to be called.\n' |

158 | n/a | '\n' |

159 | n/a | '* If the target is an attribute reference: The primary ' |

160 | n/a | 'expression in\n' |

161 | n/a | ' the reference is evaluated. It should yield an object with\n' |

162 | n/a | ' assignable attributes; if this is not the case, "TypeError" ' |

163 | n/a | 'is\n' |

164 | n/a | ' raised. That object is then asked to assign the assigned ' |

165 | n/a | 'object to\n' |

166 | n/a | ' the given attribute; if it cannot perform the assignment, it ' |

167 | n/a | 'raises\n' |

168 | n/a | ' an exception (usually but not necessarily ' |

169 | n/a | '"AttributeError").\n' |

170 | n/a | '\n' |

171 | n/a | ' Note: If the object is a class instance and the attribute ' |

172 | n/a | 'reference\n' |

173 | n/a | ' occurs on both sides of the assignment operator, the RHS ' |

174 | n/a | 'expression,\n' |

175 | n/a | ' "a.x" can access either an instance attribute or (if no ' |

176 | n/a | 'instance\n' |

177 | n/a | ' attribute exists) a class attribute. The LHS target "a.x" ' |

178 | n/a | 'is always\n' |

179 | n/a | ' set as an instance attribute, creating it if necessary. ' |

180 | n/a | 'Thus, the\n' |

181 | n/a | ' two occurrences of "a.x" do not necessarily refer to the ' |

182 | n/a | 'same\n' |

183 | n/a | ' attribute: if the RHS expression refers to a class ' |

184 | n/a | 'attribute, the\n' |

185 | n/a | ' LHS creates a new instance attribute as the target of the\n' |

186 | n/a | ' assignment:\n' |

187 | n/a | '\n' |

188 | n/a | ' class Cls:\n' |

189 | n/a | ' x = 3 # class variable\n' |

190 | n/a | ' inst = Cls()\n' |

191 | n/a | ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x ' |

192 | n/a | 'as 3\n' |

193 | n/a | '\n' |

194 | n/a | ' This description does not necessarily apply to descriptor\n' |

195 | n/a | ' attributes, such as properties created with "property()".\n' |

196 | n/a | '\n' |

197 | n/a | '* If the target is a subscription: The primary expression in ' |

198 | n/a | 'the\n' |

199 | n/a | ' reference is evaluated. It should yield either a mutable ' |

200 | n/a | 'sequence\n' |

201 | n/a | ' object (such as a list) or a mapping object (such as a ' |

202 | n/a | 'dictionary).\n' |

203 | n/a | ' Next, the subscript expression is evaluated.\n' |

204 | n/a | '\n' |

205 | n/a | ' If the primary is a mutable sequence object (such as a ' |

206 | n/a | 'list), the\n' |

207 | n/a | ' subscript must yield an integer. If it is negative, the ' |

208 | n/a | "sequence's\n" |

209 | n/a | ' length is added to it. The resulting value must be a ' |

210 | n/a | 'nonnegative\n' |

211 | n/a | " integer less than the sequence's length, and the sequence is " |

212 | n/a | 'asked\n' |

213 | n/a | ' to assign the assigned object to its item with that index. ' |

214 | n/a | 'If the\n' |

215 | n/a | ' index is out of range, "IndexError" is raised (assignment to ' |

216 | n/a | 'a\n' |

217 | n/a | ' subscripted sequence cannot add new items to a list).\n' |

218 | n/a | '\n' |

219 | n/a | ' If the primary is a mapping object (such as a dictionary), ' |

220 | n/a | 'the\n' |

221 | n/a | " subscript must have a type compatible with the mapping's key " |

222 | n/a | 'type,\n' |

223 | n/a | ' and the mapping is then asked to create a key/datum pair ' |

224 | n/a | 'which maps\n' |

225 | n/a | ' the subscript to the assigned object. This can either ' |

226 | n/a | 'replace an\n' |

227 | n/a | ' existing key/value pair with the same key value, or insert a ' |

228 | n/a | 'new\n' |

229 | n/a | ' key/value pair (if no key with the same value existed).\n' |

230 | n/a | '\n' |

231 | n/a | ' For user-defined objects, the "__setitem__()" method is ' |

232 | n/a | 'called with\n' |

233 | n/a | ' appropriate arguments.\n' |

234 | n/a | '\n' |

235 | n/a | '* If the target is a slicing: The primary expression in the\n' |

236 | n/a | ' reference is evaluated. It should yield a mutable sequence ' |

237 | n/a | 'object\n' |

238 | n/a | ' (such as a list). The assigned object should be a sequence ' |

239 | n/a | 'object\n' |

240 | n/a | ' of the same type. Next, the lower and upper bound ' |

241 | n/a | 'expressions are\n' |

242 | n/a | ' evaluated, insofar they are present; defaults are zero and ' |

243 | n/a | 'the\n' |

244 | n/a | " sequence's length. The bounds should evaluate to integers. " |

245 | n/a | 'If\n' |

246 | n/a | " either bound is negative, the sequence's length is added to " |

247 | n/a | 'it. The\n' |

248 | n/a | ' resulting bounds are clipped to lie between zero and the ' |

249 | n/a | "sequence's\n" |

250 | n/a | ' length, inclusive. Finally, the sequence object is asked to ' |

251 | n/a | 'replace\n' |

252 | n/a | ' the slice with the items of the assigned sequence. The ' |

253 | n/a | 'length of\n' |

254 | n/a | ' the slice may be different from the length of the assigned ' |

255 | n/a | 'sequence,\n' |

256 | n/a | ' thus changing the length of the target sequence, if the ' |

257 | n/a | 'target\n' |

258 | n/a | ' sequence allows it.\n' |

259 | n/a | '\n' |

260 | n/a | '**CPython implementation detail:** In the current ' |

261 | n/a | 'implementation, the\n' |

262 | n/a | 'syntax for targets is taken to be the same as for expressions, ' |

263 | n/a | 'and\n' |

264 | n/a | 'invalid syntax is rejected during the code generation phase, ' |

265 | n/a | 'causing\n' |

266 | n/a | 'less detailed error messages.\n' |

267 | n/a | '\n' |

268 | n/a | 'Although the definition of assignment implies that overlaps ' |

269 | n/a | 'between\n' |

270 | n/a | "the left-hand side and the right-hand side are 'simultaneous' " |

271 | n/a | '(for\n' |

272 | n/a | 'example "a, b = b, a" swaps two variables), overlaps *within* ' |

273 | n/a | 'the\n' |

274 | n/a | 'collection of assigned-to variables occur left-to-right, ' |

275 | n/a | 'sometimes\n' |

276 | n/a | 'resulting in confusion. For instance, the following program ' |

277 | n/a | 'prints\n' |

278 | n/a | '"[0, 2]":\n' |

279 | n/a | '\n' |

280 | n/a | ' x = [0, 1]\n' |

281 | n/a | ' i = 0\n' |

282 | n/a | ' i, x[i] = 1, 2 # i is updated, then x[i] is ' |

283 | n/a | 'updated\n' |

284 | n/a | ' print(x)\n' |

285 | n/a | '\n' |

286 | n/a | 'See also:\n' |

287 | n/a | '\n' |

288 | n/a | ' **PEP 3132** - Extended Iterable Unpacking\n' |

289 | n/a | ' The specification for the "*target" feature.\n' |

290 | n/a | '\n' |

291 | n/a | '\n' |

292 | n/a | 'Augmented assignment statements\n' |

293 | n/a | '===============================\n' |

294 | n/a | '\n' |

295 | n/a | 'Augmented assignment is the combination, in a single ' |

296 | n/a | 'statement, of a\n' |

297 | n/a | 'binary operation and an assignment statement:\n' |

298 | n/a | '\n' |

299 | n/a | ' augmented_assignment_stmt ::= augtarget augop ' |

300 | n/a | '(expression_list | yield_expression)\n' |

301 | n/a | ' augtarget ::= identifier | attributeref | ' |

302 | n/a | 'subscription | slicing\n' |

303 | n/a | ' augop ::= "+=" | "-=" | "*=" | "@=" | ' |

304 | n/a | '"/=" | "//=" | "%=" | "**="\n' |

305 | n/a | ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' |

306 | n/a | '\n' |

307 | n/a | '(See section Primaries for the syntax definitions of the last ' |

308 | n/a | 'three\n' |

309 | n/a | 'symbols.)\n' |

310 | n/a | '\n' |

311 | n/a | 'An augmented assignment evaluates the target (which, unlike ' |

312 | n/a | 'normal\n' |

313 | n/a | 'assignment statements, cannot be an unpacking) and the ' |

314 | n/a | 'expression\n' |

315 | n/a | 'list, performs the binary operation specific to the type of ' |

316 | n/a | 'assignment\n' |

317 | n/a | 'on the two operands, and assigns the result to the original ' |

318 | n/a | 'target.\n' |

319 | n/a | 'The target is only evaluated once.\n' |

320 | n/a | '\n' |

321 | n/a | 'An augmented assignment expression like "x += 1" can be ' |

322 | n/a | 'rewritten as\n' |

323 | n/a | '"x = x + 1" to achieve a similar, but not exactly equal ' |

324 | n/a | 'effect. In the\n' |

325 | n/a | 'augmented version, "x" is only evaluated once. Also, when ' |

326 | n/a | 'possible,\n' |

327 | n/a | 'the actual operation is performed *in-place*, meaning that ' |

328 | n/a | 'rather than\n' |

329 | n/a | 'creating a new object and assigning that to the target, the ' |

330 | n/a | 'old object\n' |

331 | n/a | 'is modified instead.\n' |

332 | n/a | '\n' |

333 | n/a | 'Unlike normal assignments, augmented assignments evaluate the ' |

334 | n/a | 'left-\n' |

335 | n/a | 'hand side *before* evaluating the right-hand side. For ' |

336 | n/a | 'example, "a[i]\n' |

337 | n/a | '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' |

338 | n/a | 'performs\n' |

339 | n/a | 'the addition, and lastly, it writes the result back to ' |

340 | n/a | '"a[i]".\n' |

341 | n/a | '\n' |

342 | n/a | 'With the exception of assigning to tuples and multiple targets ' |

343 | n/a | 'in a\n' |

344 | n/a | 'single statement, the assignment done by augmented assignment\n' |

345 | n/a | 'statements is handled the same way as normal assignments. ' |

346 | n/a | 'Similarly,\n' |

347 | n/a | 'with the exception of the possible *in-place* behavior, the ' |

348 | n/a | 'binary\n' |

349 | n/a | 'operation performed by augmented assignment is the same as the ' |

350 | n/a | 'normal\n' |

351 | n/a | 'binary operations.\n' |

352 | n/a | '\n' |

353 | n/a | 'For targets which are attribute references, the same caveat ' |

354 | n/a | 'about\n' |

355 | n/a | 'class and instance attributes applies as for regular ' |

356 | n/a | 'assignments.\n' |

357 | n/a | '\n' |

358 | n/a | '\n' |

359 | n/a | 'Annotated assignment statements\n' |

360 | n/a | '===============================\n' |

361 | n/a | '\n' |

362 | n/a | 'Annotation assignment is the combination, in a single ' |

363 | n/a | 'statement, of a\n' |

364 | n/a | 'variable or attribute annotation and an optional assignment ' |

365 | n/a | 'statement:\n' |

366 | n/a | '\n' |

367 | n/a | ' annotated_assignment_stmt ::= augtarget ":" expression ["=" ' |

368 | n/a | 'expression]\n' |

369 | n/a | '\n' |

370 | n/a | 'The difference from normal Assignment statements is that only ' |

371 | n/a | 'single\n' |

372 | n/a | 'target and only single right hand side value is allowed.\n' |

373 | n/a | '\n' |

374 | n/a | 'For simple names as assignment targets, if in class or module ' |

375 | n/a | 'scope,\n' |

376 | n/a | 'the annotations are evaluated and stored in a special class or ' |

377 | n/a | 'module\n' |

378 | n/a | 'attribute "__annotations__" that is a dictionary mapping from ' |

379 | n/a | 'variable\n' |

380 | n/a | 'names (mangled if private) to evaluated annotations. This ' |

381 | n/a | 'attribute is\n' |

382 | n/a | 'writable and is automatically created at the start of class or ' |

383 | n/a | 'module\n' |

384 | n/a | 'body execution, if annotations are found statically.\n' |

385 | n/a | '\n' |

386 | n/a | 'For expressions as assignment targets, the annotations are ' |

387 | n/a | 'evaluated\n' |

388 | n/a | 'if in class or module scope, but not stored.\n' |

389 | n/a | '\n' |

390 | n/a | 'If a name is annotated in a function scope, then this name is ' |

391 | n/a | 'local\n' |

392 | n/a | 'for that scope. Annotations are never evaluated and stored in ' |

393 | n/a | 'function\n' |

394 | n/a | 'scopes.\n' |

395 | n/a | '\n' |

396 | n/a | 'If the right hand side is present, an annotated assignment ' |

397 | n/a | 'performs\n' |

398 | n/a | 'the actual assignment before evaluating annotations (where\n' |

399 | n/a | 'applicable). If the right hand side is not present for an ' |

400 | n/a | 'expression\n' |

401 | n/a | 'target, then the interpreter evaluates the target except for ' |

402 | n/a | 'the last\n' |

403 | n/a | '"__setitem__()" or "__setattr__()" call.\n' |

404 | n/a | '\n' |

405 | n/a | 'See also: **PEP 526** - Variable and attribute annotation ' |

406 | n/a | 'syntax\n' |

407 | n/a | ' **PEP 484** - Type hints\n', |

408 | n/a | 'atom-identifiers': '\n' |

409 | n/a | 'Identifiers (Names)\n' |

410 | n/a | '*******************\n' |

411 | n/a | '\n' |

412 | n/a | 'An identifier occurring as an atom is a name. See ' |

413 | n/a | 'section Identifiers\n' |

414 | n/a | 'and keywords for lexical definition and section Naming ' |

415 | n/a | 'and binding for\n' |

416 | n/a | 'documentation of naming and binding.\n' |

417 | n/a | '\n' |

418 | n/a | 'When the name is bound to an object, evaluation of the ' |

419 | n/a | 'atom yields\n' |

420 | n/a | 'that object. When a name is not bound, an attempt to ' |

421 | n/a | 'evaluate it\n' |

422 | n/a | 'raises a "NameError" exception.\n' |

423 | n/a | '\n' |

424 | n/a | '**Private name mangling:** When an identifier that ' |

425 | n/a | 'textually occurs in\n' |

426 | n/a | 'a class definition begins with two or more underscore ' |

427 | n/a | 'characters and\n' |

428 | n/a | 'does not end in two or more underscores, it is ' |

429 | n/a | 'considered a *private\n' |

430 | n/a | 'name* of that class. Private names are transformed to a ' |

431 | n/a | 'longer form\n' |

432 | n/a | 'before code is generated for them. The transformation ' |

433 | n/a | 'inserts the\n' |

434 | n/a | 'class name, with leading underscores removed and a ' |

435 | n/a | 'single underscore\n' |

436 | n/a | 'inserted, in front of the name. For example, the ' |

437 | n/a | 'identifier "__spam"\n' |

438 | n/a | 'occurring in a class named "Ham" will be transformed to ' |

439 | n/a | '"_Ham__spam".\n' |

440 | n/a | 'This transformation is independent of the syntactical ' |

441 | n/a | 'context in which\n' |

442 | n/a | 'the identifier is used. If the transformed name is ' |

443 | n/a | 'extremely long\n' |

444 | n/a | '(longer than 255 characters), implementation defined ' |

445 | n/a | 'truncation may\n' |

446 | n/a | 'happen. If the class name consists only of underscores, ' |

447 | n/a | 'no\n' |

448 | n/a | 'transformation is done.\n', |

449 | n/a | 'atom-literals': '\n' |

450 | n/a | 'Literals\n' |

451 | n/a | '********\n' |

452 | n/a | '\n' |

453 | n/a | 'Python supports string and bytes literals and various ' |

454 | n/a | 'numeric\n' |

455 | n/a | 'literals:\n' |

456 | n/a | '\n' |

457 | n/a | ' literal ::= stringliteral | bytesliteral\n' |

458 | n/a | ' | integer | floatnumber | imagnumber\n' |

459 | n/a | '\n' |

460 | n/a | 'Evaluation of a literal yields an object of the given type ' |

461 | n/a | '(string,\n' |

462 | n/a | 'bytes, integer, floating point number, complex number) with ' |

463 | n/a | 'the given\n' |

464 | n/a | 'value. The value may be approximated in the case of ' |

465 | n/a | 'floating point\n' |

466 | n/a | 'and imaginary (complex) literals. See section Literals for ' |

467 | n/a | 'details.\n' |

468 | n/a | '\n' |

469 | n/a | 'All literals correspond to immutable data types, and hence ' |

470 | n/a | 'the\n' |

471 | n/a | "object's identity is less important than its value. " |

472 | n/a | 'Multiple\n' |

473 | n/a | 'evaluations of literals with the same value (either the ' |

474 | n/a | 'same\n' |

475 | n/a | 'occurrence in the program text or a different occurrence) ' |

476 | n/a | 'may obtain\n' |

477 | n/a | 'the same object or a different object with the same ' |

478 | n/a | 'value.\n', |

479 | n/a | 'attribute-access': '\n' |

480 | n/a | 'Customizing attribute access\n' |

481 | n/a | '****************************\n' |

482 | n/a | '\n' |

483 | n/a | 'The following methods can be defined to customize the ' |

484 | n/a | 'meaning of\n' |

485 | n/a | 'attribute access (use of, assignment to, or deletion of ' |

486 | n/a | '"x.name") for\n' |

487 | n/a | 'class instances.\n' |

488 | n/a | '\n' |

489 | n/a | 'object.__getattr__(self, name)\n' |

490 | n/a | '\n' |

491 | n/a | ' Called when an attribute lookup has not found the ' |

492 | n/a | 'attribute in the\n' |

493 | n/a | ' usual places (i.e. it is not an instance attribute ' |

494 | n/a | 'nor is it found\n' |

495 | n/a | ' in the class tree for "self"). "name" is the ' |

496 | n/a | 'attribute name. This\n' |

497 | n/a | ' method should return the (computed) attribute value ' |

498 | n/a | 'or raise an\n' |

499 | n/a | ' "AttributeError" exception.\n' |

500 | n/a | '\n' |

501 | n/a | ' Note that if the attribute is found through the ' |

502 | n/a | 'normal mechanism,\n' |

503 | n/a | ' "__getattr__()" is not called. (This is an ' |

504 | n/a | 'intentional asymmetry\n' |

505 | n/a | ' between "__getattr__()" and "__setattr__()".) This is ' |

506 | n/a | 'done both for\n' |

507 | n/a | ' efficiency reasons and because otherwise ' |

508 | n/a | '"__getattr__()" would have\n' |

509 | n/a | ' no way to access other attributes of the instance. ' |

510 | n/a | 'Note that at\n' |

511 | n/a | ' least for instance variables, you can fake total ' |

512 | n/a | 'control by not\n' |

513 | n/a | ' inserting any values in the instance attribute ' |

514 | n/a | 'dictionary (but\n' |

515 | n/a | ' instead inserting them in another object). See the\n' |

516 | n/a | ' "__getattribute__()" method below for a way to ' |

517 | n/a | 'actually get total\n' |

518 | n/a | ' control over attribute access.\n' |

519 | n/a | '\n' |

520 | n/a | 'object.__getattribute__(self, name)\n' |

521 | n/a | '\n' |

522 | n/a | ' Called unconditionally to implement attribute ' |

523 | n/a | 'accesses for\n' |

524 | n/a | ' instances of the class. If the class also defines ' |

525 | n/a | '"__getattr__()",\n' |

526 | n/a | ' the latter will not be called unless ' |

527 | n/a | '"__getattribute__()" either\n' |

528 | n/a | ' calls it explicitly or raises an "AttributeError". ' |

529 | n/a | 'This method\n' |

530 | n/a | ' should return the (computed) attribute value or raise ' |

531 | n/a | 'an\n' |

532 | n/a | ' "AttributeError" exception. In order to avoid ' |

533 | n/a | 'infinite recursion in\n' |

534 | n/a | ' this method, its implementation should always call ' |

535 | n/a | 'the base class\n' |

536 | n/a | ' method with the same name to access any attributes it ' |

537 | n/a | 'needs, for\n' |

538 | n/a | ' example, "object.__getattribute__(self, name)".\n' |

539 | n/a | '\n' |

540 | n/a | ' Note: This method may still be bypassed when looking ' |

541 | n/a | 'up special\n' |

542 | n/a | ' methods as the result of implicit invocation via ' |

543 | n/a | 'language syntax\n' |

544 | n/a | ' or built-in functions. See Special method lookup.\n' |

545 | n/a | '\n' |

546 | n/a | 'object.__setattr__(self, name, value)\n' |

547 | n/a | '\n' |

548 | n/a | ' Called when an attribute assignment is attempted. ' |

549 | n/a | 'This is called\n' |

550 | n/a | ' instead of the normal mechanism (i.e. store the value ' |

551 | n/a | 'in the\n' |

552 | n/a | ' instance dictionary). *name* is the attribute name, ' |

553 | n/a | '*value* is the\n' |

554 | n/a | ' value to be assigned to it.\n' |

555 | n/a | '\n' |

556 | n/a | ' If "__setattr__()" wants to assign to an instance ' |

557 | n/a | 'attribute, it\n' |

558 | n/a | ' should call the base class method with the same name, ' |

559 | n/a | 'for example,\n' |

560 | n/a | ' "object.__setattr__(self, name, value)".\n' |

561 | n/a | '\n' |

562 | n/a | 'object.__delattr__(self, name)\n' |

563 | n/a | '\n' |

564 | n/a | ' Like "__setattr__()" but for attribute deletion ' |

565 | n/a | 'instead of\n' |

566 | n/a | ' assignment. This should only be implemented if "del ' |

567 | n/a | 'obj.name" is\n' |

568 | n/a | ' meaningful for the object.\n' |

569 | n/a | '\n' |

570 | n/a | 'object.__dir__(self)\n' |

571 | n/a | '\n' |

572 | n/a | ' Called when "dir()" is called on the object. A ' |

573 | n/a | 'sequence must be\n' |

574 | n/a | ' returned. "dir()" converts the returned sequence to a ' |

575 | n/a | 'list and\n' |

576 | n/a | ' sorts it.\n' |

577 | n/a | '\n' |

578 | n/a | '\n' |

579 | n/a | 'Implementing Descriptors\n' |

580 | n/a | '========================\n' |

581 | n/a | '\n' |

582 | n/a | 'The following methods only apply when an instance of the ' |

583 | n/a | 'class\n' |

584 | n/a | 'containing the method (a so-called *descriptor* class) ' |

585 | n/a | 'appears in an\n' |

586 | n/a | '*owner* class (the descriptor must be in either the ' |

587 | n/a | "owner's class\n" |

588 | n/a | 'dictionary or in the class dictionary for one of its ' |

589 | n/a | 'parents). In the\n' |

590 | n/a | 'examples below, "the attribute" refers to the attribute ' |

591 | n/a | 'whose name is\n' |

592 | n/a | "the key of the property in the owner class' " |

593 | n/a | '"__dict__".\n' |

594 | n/a | '\n' |

595 | n/a | 'object.__get__(self, instance, owner)\n' |

596 | n/a | '\n' |

597 | n/a | ' Called to get the attribute of the owner class (class ' |

598 | n/a | 'attribute\n' |

599 | n/a | ' access) or of an instance of that class (instance ' |

600 | n/a | 'attribute\n' |

601 | n/a | ' access). *owner* is always the owner class, while ' |

602 | n/a | '*instance* is the\n' |

603 | n/a | ' instance that the attribute was accessed through, or ' |

604 | n/a | '"None" when\n' |

605 | n/a | ' the attribute is accessed through the *owner*. This ' |

606 | n/a | 'method should\n' |

607 | n/a | ' return the (computed) attribute value or raise an ' |

608 | n/a | '"AttributeError"\n' |

609 | n/a | ' exception.\n' |

610 | n/a | '\n' |

611 | n/a | 'object.__set__(self, instance, value)\n' |

612 | n/a | '\n' |

613 | n/a | ' Called to set the attribute on an instance *instance* ' |

614 | n/a | 'of the owner\n' |

615 | n/a | ' class to a new value, *value*.\n' |

616 | n/a | '\n' |

617 | n/a | 'object.__delete__(self, instance)\n' |

618 | n/a | '\n' |

619 | n/a | ' Called to delete the attribute on an instance ' |

620 | n/a | '*instance* of the\n' |

621 | n/a | ' owner class.\n' |

622 | n/a | '\n' |

623 | n/a | 'object.__set_name__(self, owner, name)\n' |

624 | n/a | '\n' |

625 | n/a | ' Called at the time the owning class *owner* is ' |

626 | n/a | 'created. The\n' |

627 | n/a | ' descriptor has been assigned to *name*.\n' |

628 | n/a | '\n' |

629 | n/a | ' New in version 3.6.\n' |

630 | n/a | '\n' |

631 | n/a | 'The attribute "__objclass__" is interpreted by the ' |

632 | n/a | '"inspect" module as\n' |

633 | n/a | 'specifying the class where this object was defined ' |

634 | n/a | '(setting this\n' |

635 | n/a | 'appropriately can assist in runtime introspection of ' |

636 | n/a | 'dynamic class\n' |

637 | n/a | 'attributes). For callables, it may indicate that an ' |

638 | n/a | 'instance of the\n' |

639 | n/a | 'given type (or a subclass) is expected or required as ' |

640 | n/a | 'the first\n' |

641 | n/a | 'positional argument (for example, CPython sets this ' |

642 | n/a | 'attribute for\n' |

643 | n/a | 'unbound methods that are implemented in C).\n' |

644 | n/a | '\n' |

645 | n/a | '\n' |

646 | n/a | 'Invoking Descriptors\n' |

647 | n/a | '====================\n' |

648 | n/a | '\n' |

649 | n/a | 'In general, a descriptor is an object attribute with ' |

650 | n/a | '"binding\n' |

651 | n/a | 'behavior", one whose attribute access has been ' |

652 | n/a | 'overridden by methods\n' |

653 | n/a | 'in the descriptor protocol: "__get__()", "__set__()", ' |

654 | n/a | 'and\n' |

655 | n/a | '"__delete__()". If any of those methods are defined for ' |

656 | n/a | 'an object, it\n' |

657 | n/a | 'is said to be a descriptor.\n' |

658 | n/a | '\n' |

659 | n/a | 'The default behavior for attribute access is to get, ' |

660 | n/a | 'set, or delete\n' |

661 | n/a | "the attribute from an object's dictionary. For instance, " |

662 | n/a | '"a.x" has a\n' |

663 | n/a | 'lookup chain starting with "a.__dict__[\'x\']", then\n' |

664 | n/a | '"type(a).__dict__[\'x\']", and continuing through the ' |

665 | n/a | 'base classes of\n' |

666 | n/a | '"type(a)" excluding metaclasses.\n' |

667 | n/a | '\n' |

668 | n/a | 'However, if the looked-up value is an object defining ' |

669 | n/a | 'one of the\n' |

670 | n/a | 'descriptor methods, then Python may override the default ' |

671 | n/a | 'behavior and\n' |

672 | n/a | 'invoke the descriptor method instead. Where this occurs ' |

673 | n/a | 'in the\n' |

674 | n/a | 'precedence chain depends on which descriptor methods ' |

675 | n/a | 'were defined and\n' |

676 | n/a | 'how they were called.\n' |

677 | n/a | '\n' |

678 | n/a | 'The starting point for descriptor invocation is a ' |

679 | n/a | 'binding, "a.x". How\n' |

680 | n/a | 'the arguments are assembled depends on "a":\n' |

681 | n/a | '\n' |

682 | n/a | 'Direct Call\n' |

683 | n/a | ' The simplest and least common call is when user code ' |

684 | n/a | 'directly\n' |

685 | n/a | ' invokes a descriptor method: "x.__get__(a)".\n' |

686 | n/a | '\n' |

687 | n/a | 'Instance Binding\n' |

688 | n/a | ' If binding to an object instance, "a.x" is ' |

689 | n/a | 'transformed into the\n' |

690 | n/a | ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' |

691 | n/a | '\n' |

692 | n/a | 'Class Binding\n' |

693 | n/a | ' If binding to a class, "A.x" is transformed into the ' |

694 | n/a | 'call:\n' |

695 | n/a | ' "A.__dict__[\'x\'].__get__(None, A)".\n' |

696 | n/a | '\n' |

697 | n/a | 'Super Binding\n' |

698 | n/a | ' If "a" is an instance of "super", then the binding ' |

699 | n/a | '"super(B,\n' |

700 | n/a | ' obj).m()" searches "obj.__class__.__mro__" for the ' |

701 | n/a | 'base class "A"\n' |

702 | n/a | ' immediately preceding "B" and then invokes the ' |

703 | n/a | 'descriptor with the\n' |

704 | n/a | ' call: "A.__dict__[\'m\'].__get__(obj, ' |

705 | n/a | 'obj.__class__)".\n' |

706 | n/a | '\n' |

707 | n/a | 'For instance bindings, the precedence of descriptor ' |

708 | n/a | 'invocation depends\n' |

709 | n/a | 'on the which descriptor methods are defined. A ' |

710 | n/a | 'descriptor can define\n' |

711 | n/a | 'any combination of "__get__()", "__set__()" and ' |

712 | n/a | '"__delete__()". If it\n' |

713 | n/a | 'does not define "__get__()", then accessing the ' |

714 | n/a | 'attribute will return\n' |

715 | n/a | 'the descriptor object itself unless there is a value in ' |

716 | n/a | "the object's\n" |

717 | n/a | 'instance dictionary. If the descriptor defines ' |

718 | n/a | '"__set__()" and/or\n' |

719 | n/a | '"__delete__()", it is a data descriptor; if it defines ' |

720 | n/a | 'neither, it is\n' |

721 | n/a | 'a non-data descriptor. Normally, data descriptors ' |

722 | n/a | 'define both\n' |

723 | n/a | '"__get__()" and "__set__()", while non-data descriptors ' |

724 | n/a | 'have just the\n' |

725 | n/a | '"__get__()" method. Data descriptors with "__set__()" ' |

726 | n/a | 'and "__get__()"\n' |

727 | n/a | 'defined always override a redefinition in an instance ' |

728 | n/a | 'dictionary. In\n' |

729 | n/a | 'contrast, non-data descriptors can be overridden by ' |

730 | n/a | 'instances.\n' |

731 | n/a | '\n' |

732 | n/a | 'Python methods (including "staticmethod()" and ' |

733 | n/a | '"classmethod()") are\n' |

734 | n/a | 'implemented as non-data descriptors. Accordingly, ' |

735 | n/a | 'instances can\n' |

736 | n/a | 'redefine and override methods. This allows individual ' |

737 | n/a | 'instances to\n' |

738 | n/a | 'acquire behaviors that differ from other instances of ' |

739 | n/a | 'the same class.\n' |

740 | n/a | '\n' |

741 | n/a | 'The "property()" function is implemented as a data ' |

742 | n/a | 'descriptor.\n' |

743 | n/a | 'Accordingly, instances cannot override the behavior of a ' |

744 | n/a | 'property.\n' |

745 | n/a | '\n' |

746 | n/a | '\n' |

747 | n/a | '__slots__\n' |

748 | n/a | '=========\n' |

749 | n/a | '\n' |

750 | n/a | 'By default, instances of classes have a dictionary for ' |

751 | n/a | 'attribute\n' |

752 | n/a | 'storage. This wastes space for objects having very few ' |

753 | n/a | 'instance\n' |

754 | n/a | 'variables. The space consumption can become acute when ' |

755 | n/a | 'creating large\n' |

756 | n/a | 'numbers of instances.\n' |

757 | n/a | '\n' |

758 | n/a | 'The default can be overridden by defining *__slots__* in ' |

759 | n/a | 'a class\n' |

760 | n/a | 'definition. The *__slots__* declaration takes a sequence ' |

761 | n/a | 'of instance\n' |

762 | n/a | 'variables and reserves just enough space in each ' |

763 | n/a | 'instance to hold a\n' |

764 | n/a | 'value for each variable. Space is saved because ' |

765 | n/a | '*__dict__* is not\n' |

766 | n/a | 'created for each instance.\n' |

767 | n/a | '\n' |

768 | n/a | 'object.__slots__\n' |

769 | n/a | '\n' |

770 | n/a | ' This class variable can be assigned a string, ' |

771 | n/a | 'iterable, or sequence\n' |

772 | n/a | ' of strings with variable names used by instances. ' |

773 | n/a | '*__slots__*\n' |

774 | n/a | ' reserves space for the declared variables and ' |

775 | n/a | 'prevents the\n' |

776 | n/a | ' automatic creation of *__dict__* and *__weakref__* ' |

777 | n/a | 'for each\n' |

778 | n/a | ' instance.\n' |

779 | n/a | '\n' |

780 | n/a | '\n' |

781 | n/a | 'Notes on using *__slots__*\n' |

782 | n/a | '--------------------------\n' |

783 | n/a | '\n' |

784 | n/a | '* When inheriting from a class without *__slots__*, the ' |

785 | n/a | '*__dict__*\n' |

786 | n/a | ' attribute of that class will always be accessible, so ' |

787 | n/a | 'a *__slots__*\n' |

788 | n/a | ' definition in the subclass is meaningless.\n' |

789 | n/a | '\n' |

790 | n/a | '* Without a *__dict__* variable, instances cannot be ' |

791 | n/a | 'assigned new\n' |

792 | n/a | ' variables not listed in the *__slots__* definition. ' |

793 | n/a | 'Attempts to\n' |

794 | n/a | ' assign to an unlisted variable name raises ' |

795 | n/a | '"AttributeError". If\n' |

796 | n/a | ' dynamic assignment of new variables is desired, then ' |

797 | n/a | 'add\n' |

798 | n/a | ' "\'__dict__\'" to the sequence of strings in the ' |

799 | n/a | '*__slots__*\n' |

800 | n/a | ' declaration.\n' |

801 | n/a | '\n' |

802 | n/a | '* Without a *__weakref__* variable for each instance, ' |

803 | n/a | 'classes\n' |

804 | n/a | ' defining *__slots__* do not support weak references to ' |

805 | n/a | 'its\n' |

806 | n/a | ' instances. If weak reference support is needed, then ' |

807 | n/a | 'add\n' |

808 | n/a | ' "\'__weakref__\'" to the sequence of strings in the ' |

809 | n/a | '*__slots__*\n' |

810 | n/a | ' declaration.\n' |

811 | n/a | '\n' |

812 | n/a | '* *__slots__* are implemented at the class level by ' |

813 | n/a | 'creating\n' |

814 | n/a | ' descriptors (Implementing Descriptors) for each ' |

815 | n/a | 'variable name. As a\n' |

816 | n/a | ' result, class attributes cannot be used to set default ' |

817 | n/a | 'values for\n' |

818 | n/a | ' instance variables defined by *__slots__*; otherwise, ' |

819 | n/a | 'the class\n' |

820 | n/a | ' attribute would overwrite the descriptor assignment.\n' |

821 | n/a | '\n' |

822 | n/a | '* The action of a *__slots__* declaration is limited to ' |

823 | n/a | 'the class\n' |

824 | n/a | ' where it is defined. As a result, subclasses will ' |

825 | n/a | 'have a *__dict__*\n' |

826 | n/a | ' unless they also define *__slots__* (which must only ' |

827 | n/a | 'contain names\n' |

828 | n/a | ' of any *additional* slots).\n' |

829 | n/a | '\n' |

830 | n/a | '* If a class defines a slot also defined in a base ' |

831 | n/a | 'class, the\n' |

832 | n/a | ' instance variable defined by the base class slot is ' |

833 | n/a | 'inaccessible\n' |

834 | n/a | ' (except by retrieving its descriptor directly from the ' |

835 | n/a | 'base class).\n' |

836 | n/a | ' This renders the meaning of the program undefined. In ' |

837 | n/a | 'the future, a\n' |

838 | n/a | ' check may be added to prevent this.\n' |

839 | n/a | '\n' |

840 | n/a | '* Nonempty *__slots__* does not work for classes derived ' |

841 | n/a | 'from\n' |

842 | n/a | ' "variable-length" built-in types such as "int", ' |

843 | n/a | '"bytes" and "tuple".\n' |

844 | n/a | '\n' |

845 | n/a | '* Any non-string iterable may be assigned to ' |

846 | n/a | '*__slots__*. Mappings\n' |

847 | n/a | ' may also be used; however, in the future, special ' |

848 | n/a | 'meaning may be\n' |

849 | n/a | ' assigned to the values corresponding to each key.\n' |

850 | n/a | '\n' |

851 | n/a | '* *__class__* assignment works only if both classes have ' |

852 | n/a | 'the same\n' |

853 | n/a | ' *__slots__*.\n', |

854 | n/a | 'attribute-references': '\n' |

855 | n/a | 'Attribute references\n' |

856 | n/a | '********************\n' |

857 | n/a | '\n' |

858 | n/a | 'An attribute reference is a primary followed by a ' |

859 | n/a | 'period and a name:\n' |

860 | n/a | '\n' |

861 | n/a | ' attributeref ::= primary "." identifier\n' |

862 | n/a | '\n' |

863 | n/a | 'The primary must evaluate to an object of a type ' |

864 | n/a | 'that supports\n' |

865 | n/a | 'attribute references, which most objects do. This ' |

866 | n/a | 'object is then\n' |

867 | n/a | 'asked to produce the attribute whose name is the ' |

868 | n/a | 'identifier. This\n' |

869 | n/a | 'production can be customized by overriding the ' |

870 | n/a | '"__getattr__()" method.\n' |

871 | n/a | 'If this attribute is not available, the exception ' |

872 | n/a | '"AttributeError" is\n' |

873 | n/a | 'raised. Otherwise, the type and value of the object ' |

874 | n/a | 'produced is\n' |

875 | n/a | 'determined by the object. Multiple evaluations of ' |

876 | n/a | 'the same attribute\n' |

877 | n/a | 'reference may yield different objects.\n', |

878 | n/a | 'augassign': '\n' |

879 | n/a | 'Augmented assignment statements\n' |

880 | n/a | '*******************************\n' |

881 | n/a | '\n' |

882 | n/a | 'Augmented assignment is the combination, in a single statement, ' |

883 | n/a | 'of a\n' |

884 | n/a | 'binary operation and an assignment statement:\n' |

885 | n/a | '\n' |

886 | n/a | ' augmented_assignment_stmt ::= augtarget augop ' |

887 | n/a | '(expression_list | yield_expression)\n' |

888 | n/a | ' augtarget ::= identifier | attributeref | ' |

889 | n/a | 'subscription | slicing\n' |

890 | n/a | ' augop ::= "+=" | "-=" | "*=" | "@=" | ' |

891 | n/a | '"/=" | "//=" | "%=" | "**="\n' |

892 | n/a | ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' |

893 | n/a | '\n' |

894 | n/a | '(See section Primaries for the syntax definitions of the last ' |

895 | n/a | 'three\n' |

896 | n/a | 'symbols.)\n' |

897 | n/a | '\n' |

898 | n/a | 'An augmented assignment evaluates the target (which, unlike ' |

899 | n/a | 'normal\n' |

900 | n/a | 'assignment statements, cannot be an unpacking) and the ' |

901 | n/a | 'expression\n' |

902 | n/a | 'list, performs the binary operation specific to the type of ' |

903 | n/a | 'assignment\n' |

904 | n/a | 'on the two operands, and assigns the result to the original ' |

905 | n/a | 'target.\n' |

906 | n/a | 'The target is only evaluated once.\n' |

907 | n/a | '\n' |

908 | n/a | 'An augmented assignment expression like "x += 1" can be ' |

909 | n/a | 'rewritten as\n' |

910 | n/a | '"x = x + 1" to achieve a similar, but not exactly equal effect. ' |

911 | n/a | 'In the\n' |

912 | n/a | 'augmented version, "x" is only evaluated once. Also, when ' |

913 | n/a | 'possible,\n' |

914 | n/a | 'the actual operation is performed *in-place*, meaning that ' |

915 | n/a | 'rather than\n' |

916 | n/a | 'creating a new object and assigning that to the target, the old ' |

917 | n/a | 'object\n' |

918 | n/a | 'is modified instead.\n' |

919 | n/a | '\n' |

920 | n/a | 'Unlike normal assignments, augmented assignments evaluate the ' |

921 | n/a | 'left-\n' |

922 | n/a | 'hand side *before* evaluating the right-hand side. For ' |

923 | n/a | 'example, "a[i]\n' |

924 | n/a | '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' |

925 | n/a | 'performs\n' |

926 | n/a | 'the addition, and lastly, it writes the result back to "a[i]".\n' |

927 | n/a | '\n' |

928 | n/a | 'With the exception of assigning to tuples and multiple targets ' |

929 | n/a | 'in a\n' |

930 | n/a | 'single statement, the assignment done by augmented assignment\n' |

931 | n/a | 'statements is handled the same way as normal assignments. ' |

932 | n/a | 'Similarly,\n' |

933 | n/a | 'with the exception of the possible *in-place* behavior, the ' |

934 | n/a | 'binary\n' |

935 | n/a | 'operation performed by augmented assignment is the same as the ' |

936 | n/a | 'normal\n' |

937 | n/a | 'binary operations.\n' |

938 | n/a | '\n' |

939 | n/a | 'For targets which are attribute references, the same caveat ' |

940 | n/a | 'about\n' |

941 | n/a | 'class and instance attributes applies as for regular ' |

942 | n/a | 'assignments.\n', |

943 | n/a | 'binary': '\n' |

944 | n/a | 'Binary arithmetic operations\n' |

945 | n/a | '****************************\n' |

946 | n/a | '\n' |

947 | n/a | 'The binary arithmetic operations have the conventional priority\n' |

948 | n/a | 'levels. Note that some of these operations also apply to certain ' |

949 | n/a | 'non-\n' |

950 | n/a | 'numeric types. Apart from the power operator, there are only two\n' |

951 | n/a | 'levels, one for multiplicative operators and one for additive\n' |

952 | n/a | 'operators:\n' |

953 | n/a | '\n' |

954 | n/a | ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n' |

955 | n/a | ' m_expr "//" u_expr| m_expr "/" u_expr |\n' |

956 | n/a | ' m_expr "%" u_expr\n' |

957 | n/a | ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' |

958 | n/a | '\n' |

959 | n/a | 'The "*" (multiplication) operator yields the product of its ' |

960 | n/a | 'arguments.\n' |

961 | n/a | 'The arguments must either both be numbers, or one argument must be ' |

962 | n/a | 'an\n' |

963 | n/a | 'integer and the other must be a sequence. In the former case, the\n' |

964 | n/a | 'numbers are converted to a common type and then multiplied ' |

965 | n/a | 'together.\n' |

966 | n/a | 'In the latter case, sequence repetition is performed; a negative\n' |

967 | n/a | 'repetition factor yields an empty sequence.\n' |

968 | n/a | '\n' |

969 | n/a | 'The "@" (at) operator is intended to be used for matrix\n' |

970 | n/a | 'multiplication. No builtin Python types implement this operator.\n' |

971 | n/a | '\n' |

972 | n/a | 'New in version 3.5.\n' |

973 | n/a | '\n' |

974 | n/a | 'The "/" (division) and "//" (floor division) operators yield the\n' |

975 | n/a | 'quotient of their arguments. The numeric arguments are first\n' |

976 | n/a | 'converted to a common type. Division of integers yields a float, ' |

977 | n/a | 'while\n' |

978 | n/a | 'floor division of integers results in an integer; the result is ' |

979 | n/a | 'that\n' |

980 | n/a | "of mathematical division with the 'floor' function applied to the\n" |

981 | n/a | 'result. Division by zero raises the "ZeroDivisionError" ' |

982 | n/a | 'exception.\n' |

983 | n/a | '\n' |

984 | n/a | 'The "%" (modulo) operator yields the remainder from the division ' |

985 | n/a | 'of\n' |

986 | n/a | 'the first argument by the second. The numeric arguments are ' |

987 | n/a | 'first\n' |

988 | n/a | 'converted to a common type. A zero right argument raises the\n' |

989 | n/a | '"ZeroDivisionError" exception. The arguments may be floating ' |

990 | n/a | 'point\n' |

991 | n/a | 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' |

992 | n/a | '"4*0.7 +\n' |

993 | n/a | '0.34".) The modulo operator always yields a result with the same ' |

994 | n/a | 'sign\n' |

995 | n/a | 'as its second operand (or zero); the absolute value of the result ' |

996 | n/a | 'is\n' |

997 | n/a | 'strictly smaller than the absolute value of the second operand ' |

998 | n/a | '[1].\n' |

999 | n/a | '\n' |

1000 | n/a | 'The floor division and modulo operators are connected by the ' |

1001 | n/a | 'following\n' |

1002 | n/a | 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are ' |

1003 | n/a | 'also\n' |

1004 | n/a | 'connected with the built-in function "divmod()": "divmod(x, y) ==\n' |

1005 | n/a | '(x//y, x%y)". [2].\n' |

1006 | n/a | '\n' |

1007 | n/a | 'In addition to performing the modulo operation on numbers, the ' |

1008 | n/a | '"%"\n' |

1009 | n/a | 'operator is also overloaded by string objects to perform ' |

1010 | n/a | 'old-style\n' |

1011 | n/a | 'string formatting (also known as interpolation). The syntax for\n' |

1012 | n/a | 'string formatting is described in the Python Library Reference,\n' |

1013 | n/a | 'section printf-style String Formatting.\n' |

1014 | n/a | '\n' |

1015 | n/a | 'The floor division operator, the modulo operator, and the ' |

1016 | n/a | '"divmod()"\n' |

1017 | n/a | 'function are not defined for complex numbers. Instead, convert to ' |

1018 | n/a | 'a\n' |

1019 | n/a | 'floating point number using the "abs()" function if appropriate.\n' |

1020 | n/a | '\n' |

1021 | n/a | 'The "+" (addition) operator yields the sum of its arguments. The\n' |

1022 | n/a | 'arguments must either both be numbers or both be sequences of the ' |

1023 | n/a | 'same\n' |

1024 | n/a | 'type. In the former case, the numbers are converted to a common ' |

1025 | n/a | 'type\n' |

1026 | n/a | 'and then added together. In the latter case, the sequences are\n' |

1027 | n/a | 'concatenated.\n' |

1028 | n/a | '\n' |

1029 | n/a | 'The "-" (subtraction) operator yields the difference of its ' |

1030 | n/a | 'arguments.\n' |

1031 | n/a | 'The numeric arguments are first converted to a common type.\n', |

1032 | n/a | 'bitwise': '\n' |

1033 | n/a | 'Binary bitwise operations\n' |

1034 | n/a | '*************************\n' |

1035 | n/a | '\n' |

1036 | n/a | 'Each of the three bitwise operations has a different priority ' |

1037 | n/a | 'level:\n' |

1038 | n/a | '\n' |

1039 | n/a | ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' |

1040 | n/a | ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' |

1041 | n/a | ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' |

1042 | n/a | '\n' |

1043 | n/a | 'The "&" operator yields the bitwise AND of its arguments, which ' |

1044 | n/a | 'must\n' |

1045 | n/a | 'be integers.\n' |

1046 | n/a | '\n' |

1047 | n/a | 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' |

1048 | n/a | 'arguments, which must be integers.\n' |

1049 | n/a | '\n' |

1050 | n/a | 'The "|" operator yields the bitwise (inclusive) OR of its ' |

1051 | n/a | 'arguments,\n' |

1052 | n/a | 'which must be integers.\n', |

1053 | n/a | 'bltin-code-objects': '\n' |

1054 | n/a | 'Code Objects\n' |

1055 | n/a | '************\n' |

1056 | n/a | '\n' |

1057 | n/a | 'Code objects are used by the implementation to ' |

1058 | n/a | 'represent "pseudo-\n' |

1059 | n/a | 'compiled" executable Python code such as a function ' |

1060 | n/a | 'body. They differ\n' |

1061 | n/a | "from function objects because they don't contain a " |

1062 | n/a | 'reference to their\n' |

1063 | n/a | 'global execution environment. Code objects are ' |

1064 | n/a | 'returned by the built-\n' |

1065 | n/a | 'in "compile()" function and can be extracted from ' |

1066 | n/a | 'function objects\n' |

1067 | n/a | 'through their "__code__" attribute. See also the ' |

1068 | n/a | '"code" module.\n' |

1069 | n/a | '\n' |

1070 | n/a | 'A code object can be executed or evaluated by passing ' |

1071 | n/a | 'it (instead of a\n' |

1072 | n/a | 'source string) to the "exec()" or "eval()" built-in ' |

1073 | n/a | 'functions.\n' |

1074 | n/a | '\n' |

1075 | n/a | 'See The standard type hierarchy for more ' |

1076 | n/a | 'information.\n', |

1077 | n/a | 'bltin-ellipsis-object': '\n' |

1078 | n/a | 'The Ellipsis Object\n' |

1079 | n/a | '*******************\n' |

1080 | n/a | '\n' |

1081 | n/a | 'This object is commonly used by slicing (see ' |

1082 | n/a | 'Slicings). It supports\n' |

1083 | n/a | 'no special operations. There is exactly one ' |

1084 | n/a | 'ellipsis object, named\n' |

1085 | n/a | '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' |

1086 | n/a | 'produces the\n' |

1087 | n/a | '"Ellipsis" singleton.\n' |

1088 | n/a | '\n' |

1089 | n/a | 'It is written as "Ellipsis" or "...".\n', |

1090 | n/a | 'bltin-null-object': '\n' |

1091 | n/a | 'The Null Object\n' |

1092 | n/a | '***************\n' |

1093 | n/a | '\n' |

1094 | n/a | "This object is returned by functions that don't " |

1095 | n/a | 'explicitly return a\n' |

1096 | n/a | 'value. It supports no special operations. There is ' |

1097 | n/a | 'exactly one null\n' |

1098 | n/a | 'object, named "None" (a built-in name). "type(None)()" ' |

1099 | n/a | 'produces the\n' |

1100 | n/a | 'same singleton.\n' |

1101 | n/a | '\n' |

1102 | n/a | 'It is written as "None".\n', |

1103 | n/a | 'bltin-type-objects': '\n' |

1104 | n/a | 'Type Objects\n' |

1105 | n/a | '************\n' |

1106 | n/a | '\n' |

1107 | n/a | 'Type objects represent the various object types. An ' |

1108 | n/a | "object's type is\n" |

1109 | n/a | 'accessed by the built-in function "type()". There are ' |

1110 | n/a | 'no special\n' |

1111 | n/a | 'operations on types. The standard module "types" ' |

1112 | n/a | 'defines names for\n' |

1113 | n/a | 'all standard built-in types.\n' |

1114 | n/a | '\n' |

1115 | n/a | 'Types are written like this: "<class \'int\'>".\n', |

1116 | n/a | 'booleans': '\n' |

1117 | n/a | 'Boolean operations\n' |

1118 | n/a | '******************\n' |

1119 | n/a | '\n' |

1120 | n/a | ' or_test ::= and_test | or_test "or" and_test\n' |

1121 | n/a | ' and_test ::= not_test | and_test "and" not_test\n' |

1122 | n/a | ' not_test ::= comparison | "not" not_test\n' |

1123 | n/a | '\n' |

1124 | n/a | 'In the context of Boolean operations, and also when expressions ' |

1125 | n/a | 'are\n' |

1126 | n/a | 'used by control flow statements, the following values are ' |

1127 | n/a | 'interpreted\n' |

1128 | n/a | 'as false: "False", "None", numeric zero of all types, and empty\n' |

1129 | n/a | 'strings and containers (including strings, tuples, lists,\n' |

1130 | n/a | 'dictionaries, sets and frozensets). All other values are ' |

1131 | n/a | 'interpreted\n' |

1132 | n/a | 'as true. User-defined objects can customize their truth value ' |

1133 | n/a | 'by\n' |

1134 | n/a | 'providing a "__bool__()" method.\n' |

1135 | n/a | '\n' |

1136 | n/a | 'The operator "not" yields "True" if its argument is false, ' |

1137 | n/a | '"False"\n' |

1138 | n/a | 'otherwise.\n' |

1139 | n/a | '\n' |

1140 | n/a | 'The expression "x and y" first evaluates *x*; if *x* is false, ' |

1141 | n/a | 'its\n' |

1142 | n/a | 'value is returned; otherwise, *y* is evaluated and the resulting ' |

1143 | n/a | 'value\n' |

1144 | n/a | 'is returned.\n' |

1145 | n/a | '\n' |

1146 | n/a | 'The expression "x or y" first evaluates *x*; if *x* is true, its ' |

1147 | n/a | 'value\n' |

1148 | n/a | 'is returned; otherwise, *y* is evaluated and the resulting value ' |

1149 | n/a | 'is\n' |

1150 | n/a | 'returned.\n' |

1151 | n/a | '\n' |

1152 | n/a | '(Note that neither "and" nor "or" restrict the value and type ' |

1153 | n/a | 'they\n' |

1154 | n/a | 'return to "False" and "True", but rather return the last ' |

1155 | n/a | 'evaluated\n' |

1156 | n/a | 'argument. This is sometimes useful, e.g., if "s" is a string ' |

1157 | n/a | 'that\n' |

1158 | n/a | 'should be replaced by a default value if it is empty, the ' |

1159 | n/a | 'expression\n' |

1160 | n/a | '"s or \'foo\'" yields the desired value. Because "not" has to ' |

1161 | n/a | 'create a\n' |

1162 | n/a | 'new value, it returns a boolean value regardless of the type of ' |

1163 | n/a | 'its\n' |

1164 | n/a | 'argument (for example, "not \'foo\'" produces "False" rather ' |

1165 | n/a | 'than "\'\'".)\n', |

1166 | n/a | 'break': '\n' |

1167 | n/a | 'The "break" statement\n' |

1168 | n/a | '*********************\n' |

1169 | n/a | '\n' |

1170 | n/a | ' break_stmt ::= "break"\n' |

1171 | n/a | '\n' |

1172 | n/a | '"break" may only occur syntactically nested in a "for" or "while"\n' |

1173 | n/a | 'loop, but not nested in a function or class definition within that\n' |

1174 | n/a | 'loop.\n' |

1175 | n/a | '\n' |

1176 | n/a | 'It terminates the nearest enclosing loop, skipping the optional ' |

1177 | n/a | '"else"\n' |

1178 | n/a | 'clause if the loop has one.\n' |

1179 | n/a | '\n' |

1180 | n/a | 'If a "for" loop is terminated by "break", the loop control target\n' |

1181 | n/a | 'keeps its current value.\n' |

1182 | n/a | '\n' |

1183 | n/a | 'When "break" passes control out of a "try" statement with a ' |

1184 | n/a | '"finally"\n' |

1185 | n/a | 'clause, that "finally" clause is executed before really leaving ' |

1186 | n/a | 'the\n' |

1187 | n/a | 'loop.\n', |

1188 | n/a | 'callable-types': '\n' |

1189 | n/a | 'Emulating callable objects\n' |

1190 | n/a | '**************************\n' |

1191 | n/a | '\n' |

1192 | n/a | 'object.__call__(self[, args...])\n' |

1193 | n/a | '\n' |

1194 | n/a | ' Called when the instance is "called" as a function; if ' |

1195 | n/a | 'this method\n' |

1196 | n/a | ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' |

1197 | n/a | ' "x.__call__(arg1, arg2, ...)".\n', |

1198 | n/a | 'calls': '\n' |

1199 | n/a | 'Calls\n' |

1200 | n/a | '*****\n' |

1201 | n/a | '\n' |

1202 | n/a | 'A call calls a callable object (e.g., a *function*) with a ' |

1203 | n/a | 'possibly\n' |

1204 | n/a | 'empty series of *arguments*:\n' |

1205 | n/a | '\n' |

1206 | n/a | ' call ::= primary "(" [argument_list [","] | ' |

1207 | n/a | 'comprehension] ")"\n' |

1208 | n/a | ' argument_list ::= positional_arguments ["," ' |

1209 | n/a | 'starred_and_keywords]\n' |

1210 | n/a | ' ["," keywords_arguments]\n' |

1211 | n/a | ' | starred_and_keywords ["," ' |

1212 | n/a | 'keywords_arguments]\n' |

1213 | n/a | ' | keywords_arguments\n' |

1214 | n/a | ' positional_arguments ::= ["*"] expression ("," ["*"] ' |

1215 | n/a | 'expression)*\n' |

1216 | n/a | ' starred_and_keywords ::= ("*" expression | keyword_item)\n' |

1217 | n/a | ' ("," "*" expression | "," ' |

1218 | n/a | 'keyword_item)*\n' |

1219 | n/a | ' keywords_arguments ::= (keyword_item | "**" expression)\n' |

1220 | n/a | ' ("," keyword_item | "**" expression)*\n' |

1221 | n/a | ' keyword_item ::= identifier "=" expression\n' |

1222 | n/a | '\n' |

1223 | n/a | 'An optional trailing comma may be present after the positional and\n' |

1224 | n/a | 'keyword arguments but does not affect the semantics.\n' |

1225 | n/a | '\n' |

1226 | n/a | 'The primary must evaluate to a callable object (user-defined\n' |

1227 | n/a | 'functions, built-in functions, methods of built-in objects, class\n' |

1228 | n/a | 'objects, methods of class instances, and all objects having a\n' |

1229 | n/a | '"__call__()" method are callable). All argument expressions are\n' |

1230 | n/a | 'evaluated before the call is attempted. Please refer to section\n' |

1231 | n/a | 'Function definitions for the syntax of formal *parameter* lists.\n' |

1232 | n/a | '\n' |

1233 | n/a | 'If keyword arguments are present, they are first converted to\n' |

1234 | n/a | 'positional arguments, as follows. First, a list of unfilled slots ' |

1235 | n/a | 'is\n' |

1236 | n/a | 'created for the formal parameters. If there are N positional\n' |

1237 | n/a | 'arguments, they are placed in the first N slots. Next, for each\n' |

1238 | n/a | 'keyword argument, the identifier is used to determine the\n' |

1239 | n/a | 'corresponding slot (if the identifier is the same as the first ' |

1240 | n/a | 'formal\n' |

1241 | n/a | 'parameter name, the first slot is used, and so on). If the slot ' |

1242 | n/a | 'is\n' |

1243 | n/a | 'already filled, a "TypeError" exception is raised. Otherwise, the\n' |

1244 | n/a | 'value of the argument is placed in the slot, filling it (even if ' |

1245 | n/a | 'the\n' |

1246 | n/a | 'expression is "None", it fills the slot). When all arguments have\n' |

1247 | n/a | 'been processed, the slots that are still unfilled are filled with ' |

1248 | n/a | 'the\n' |

1249 | n/a | 'corresponding default value from the function definition. ' |

1250 | n/a | '(Default\n' |

1251 | n/a | 'values are calculated, once, when the function is defined; thus, a\n' |

1252 | n/a | 'mutable object such as a list or dictionary used as default value ' |

1253 | n/a | 'will\n' |

1254 | n/a | "be shared by all calls that don't specify an argument value for " |

1255 | n/a | 'the\n' |

1256 | n/a | 'corresponding slot; this should usually be avoided.) If there are ' |

1257 | n/a | 'any\n' |

1258 | n/a | 'unfilled slots for which no default value is specified, a ' |

1259 | n/a | '"TypeError"\n' |

1260 | n/a | 'exception is raised. Otherwise, the list of filled slots is used ' |

1261 | n/a | 'as\n' |

1262 | n/a | 'the argument list for the call.\n' |

1263 | n/a | '\n' |

1264 | n/a | '**CPython implementation detail:** An implementation may provide\n' |

1265 | n/a | 'built-in functions whose positional parameters do not have names, ' |

1266 | n/a | 'even\n' |

1267 | n/a | "if they are 'named' for the purpose of documentation, and which\n" |

1268 | n/a | 'therefore cannot be supplied by keyword. In CPython, this is the ' |

1269 | n/a | 'case\n' |

1270 | n/a | 'for functions implemented in C that use "PyArg_ParseTuple()" to ' |

1271 | n/a | 'parse\n' |

1272 | n/a | 'their arguments.\n' |

1273 | n/a | '\n' |

1274 | n/a | 'If there are more positional arguments than there are formal ' |

1275 | n/a | 'parameter\n' |

1276 | n/a | 'slots, a "TypeError" exception is raised, unless a formal ' |

1277 | n/a | 'parameter\n' |

1278 | n/a | 'using the syntax "*identifier" is present; in this case, that ' |

1279 | n/a | 'formal\n' |

1280 | n/a | 'parameter receives a tuple containing the excess positional ' |

1281 | n/a | 'arguments\n' |

1282 | n/a | '(or an empty tuple if there were no excess positional arguments).\n' |

1283 | n/a | '\n' |

1284 | n/a | 'If any keyword argument does not correspond to a formal parameter\n' |

1285 | n/a | 'name, a "TypeError" exception is raised, unless a formal parameter\n' |

1286 | n/a | 'using the syntax "**identifier" is present; in this case, that ' |

1287 | n/a | 'formal\n' |

1288 | n/a | 'parameter receives a dictionary containing the excess keyword\n' |

1289 | n/a | 'arguments (using the keywords as keys and the argument values as\n' |

1290 | n/a | 'corresponding values), or a (new) empty dictionary if there were ' |

1291 | n/a | 'no\n' |

1292 | n/a | 'excess keyword arguments.\n' |

1293 | n/a | '\n' |

1294 | n/a | 'If the syntax "*expression" appears in the function call, ' |

1295 | n/a | '"expression"\n' |

1296 | n/a | 'must evaluate to an *iterable*. Elements from these iterables are\n' |

1297 | n/a | 'treated as if they were additional positional arguments. For the ' |

1298 | n/a | 'call\n' |

1299 | n/a | '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, ...,\n' |

1300 | n/a | '*yM*, this is equivalent to a call with M+4 positional arguments ' |

1301 | n/a | '*x1*,\n' |

1302 | n/a | '*x2*, *y1*, ..., *yM*, *x3*, *x4*.\n' |

1303 | n/a | '\n' |

1304 | n/a | 'A consequence of this is that although the "*expression" syntax ' |

1305 | n/a | 'may\n' |

1306 | n/a | 'appear *after* explicit keyword arguments, it is processed ' |

1307 | n/a | '*before*\n' |

1308 | n/a | 'the keyword arguments (and any "**expression" arguments -- see ' |

1309 | n/a | 'below).\n' |

1310 | n/a | 'So:\n' |

1311 | n/a | '\n' |

1312 | n/a | ' >>> def f(a, b):\n' |

1313 | n/a | ' ... print(a, b)\n' |

1314 | n/a | ' ...\n' |

1315 | n/a | ' >>> f(b=1, *(2,))\n' |

1316 | n/a | ' 2 1\n' |

1317 | n/a | ' >>> f(a=1, *(2,))\n' |

1318 | n/a | ' Traceback (most recent call last):\n' |

1319 | n/a | ' File "<stdin>", line 1, in ?\n' |

1320 | n/a | " TypeError: f() got multiple values for keyword argument 'a'\n" |

1321 | n/a | ' >>> f(1, *(2,))\n' |

1322 | n/a | ' 1 2\n' |

1323 | n/a | '\n' |

1324 | n/a | 'It is unusual for both keyword arguments and the "*expression" ' |

1325 | n/a | 'syntax\n' |

1326 | n/a | 'to be used in the same call, so in practice this confusion does ' |

1327 | n/a | 'not\n' |

1328 | n/a | 'arise.\n' |

1329 | n/a | '\n' |

1330 | n/a | 'If the syntax "**expression" appears in the function call,\n' |

1331 | n/a | '"expression" must evaluate to a *mapping*, the contents of which ' |

1332 | n/a | 'are\n' |

1333 | n/a | 'treated as additional keyword arguments. If a keyword is already\n' |

1334 | n/a | 'present (as an explicit keyword argument, or from another ' |

1335 | n/a | 'unpacking),\n' |

1336 | n/a | 'a "TypeError" exception is raised.\n' |

1337 | n/a | '\n' |

1338 | n/a | 'Formal parameters using the syntax "*identifier" or "**identifier"\n' |

1339 | n/a | 'cannot be used as positional argument slots or as keyword argument\n' |

1340 | n/a | 'names.\n' |

1341 | n/a | '\n' |

1342 | n/a | 'Changed in version 3.5: Function calls accept any number of "*" ' |

1343 | n/a | 'and\n' |

1344 | n/a | '"**" unpackings, positional arguments may follow iterable ' |

1345 | n/a | 'unpackings\n' |

1346 | n/a | '("*"), and keyword arguments may follow dictionary unpackings ' |

1347 | n/a | '("**").\n' |

1348 | n/a | 'Originally proposed by **PEP 448**.\n' |

1349 | n/a | '\n' |

1350 | n/a | 'A call always returns some value, possibly "None", unless it raises ' |

1351 | n/a | 'an\n' |

1352 | n/a | 'exception. How this value is computed depends on the type of the\n' |

1353 | n/a | 'callable object.\n' |

1354 | n/a | '\n' |

1355 | n/a | 'If it is---\n' |

1356 | n/a | '\n' |

1357 | n/a | 'a user-defined function:\n' |

1358 | n/a | ' The code block for the function is executed, passing it the\n' |

1359 | n/a | ' argument list. The first thing the code block will do is bind ' |

1360 | n/a | 'the\n' |

1361 | n/a | ' formal parameters to the arguments; this is described in ' |

1362 | n/a | 'section\n' |

1363 | n/a | ' Function definitions. When the code block executes a "return"\n' |

1364 | n/a | ' statement, this specifies the return value of the function ' |

1365 | n/a | 'call.\n' |

1366 | n/a | '\n' |

1367 | n/a | 'a built-in function or method:\n' |

1368 | n/a | ' The result is up to the interpreter; see Built-in Functions for ' |

1369 | n/a | 'the\n' |

1370 | n/a | ' descriptions of built-in functions and methods.\n' |

1371 | n/a | '\n' |

1372 | n/a | 'a class object:\n' |

1373 | n/a | ' A new instance of that class is returned.\n' |

1374 | n/a | '\n' |

1375 | n/a | 'a class instance method:\n' |

1376 | n/a | ' The corresponding user-defined function is called, with an ' |

1377 | n/a | 'argument\n' |

1378 | n/a | ' list that is one longer than the argument list of the call: the\n' |

1379 | n/a | ' instance becomes the first argument.\n' |

1380 | n/a | '\n' |

1381 | n/a | 'a class instance:\n' |

1382 | n/a | ' The class must define a "__call__()" method; the effect is then ' |

1383 | n/a | 'the\n' |

1384 | n/a | ' same as if that method was called.\n', |

1385 | n/a | 'class': '\n' |

1386 | n/a | 'Class definitions\n' |

1387 | n/a | '*****************\n' |

1388 | n/a | '\n' |

1389 | n/a | 'A class definition defines a class object (see section The ' |

1390 | n/a | 'standard\n' |

1391 | n/a | 'type hierarchy):\n' |

1392 | n/a | '\n' |

1393 | n/a | ' classdef ::= [decorators] "class" classname [inheritance] ":" ' |

1394 | n/a | 'suite\n' |

1395 | n/a | ' inheritance ::= "(" [argument_list] ")"\n' |

1396 | n/a | ' classname ::= identifier\n' |

1397 | n/a | '\n' |

1398 | n/a | 'A class definition is an executable statement. The inheritance ' |

1399 | n/a | 'list\n' |

1400 | n/a | 'usually gives a list of base classes (see Metaclasses for more\n' |

1401 | n/a | 'advanced uses), so each item in the list should evaluate to a ' |

1402 | n/a | 'class\n' |

1403 | n/a | 'object which allows subclassing. Classes without an inheritance ' |

1404 | n/a | 'list\n' |

1405 | n/a | 'inherit, by default, from the base class "object"; hence,\n' |

1406 | n/a | '\n' |

1407 | n/a | ' class Foo:\n' |

1408 | n/a | ' pass\n' |

1409 | n/a | '\n' |

1410 | n/a | 'is equivalent to\n' |

1411 | n/a | '\n' |

1412 | n/a | ' class Foo(object):\n' |

1413 | n/a | ' pass\n' |

1414 | n/a | '\n' |

1415 | n/a | "The class's suite is then executed in a new execution frame (see\n" |

1416 | n/a | 'Naming and binding), using a newly created local namespace and the\n' |

1417 | n/a | 'original global namespace. (Usually, the suite contains mostly\n' |

1418 | n/a | "function definitions.) When the class's suite finishes execution, " |

1419 | n/a | 'its\n' |

1420 | n/a | 'execution frame is discarded but its local namespace is saved. [4] ' |

1421 | n/a | 'A\n' |

1422 | n/a | 'class object is then created using the inheritance list for the ' |

1423 | n/a | 'base\n' |

1424 | n/a | 'classes and the saved local namespace for the attribute ' |

1425 | n/a | 'dictionary.\n' |

1426 | n/a | 'The class name is bound to this class object in the original local\n' |

1427 | n/a | 'namespace.\n' |

1428 | n/a | '\n' |

1429 | n/a | 'The order in which attributes are defined in the class body is\n' |

1430 | n/a | 'preserved in the new class\'s "__dict__". Note that this is ' |

1431 | n/a | 'reliable\n' |

1432 | n/a | 'only right after the class is created and only for classes that ' |

1433 | n/a | 'were\n' |

1434 | n/a | 'defined using the definition syntax.\n' |

1435 | n/a | '\n' |

1436 | n/a | 'Class creation can be customized heavily using metaclasses.\n' |

1437 | n/a | '\n' |

1438 | n/a | 'Classes can also be decorated: just like when decorating ' |

1439 | n/a | 'functions,\n' |

1440 | n/a | '\n' |

1441 | n/a | ' @f1(arg)\n' |

1442 | n/a | ' @f2\n' |

1443 | n/a | ' class Foo: pass\n' |

1444 | n/a | '\n' |

1445 | n/a | 'is roughly equivalent to\n' |

1446 | n/a | '\n' |

1447 | n/a | ' class Foo: pass\n' |

1448 | n/a | ' Foo = f1(arg)(f2(Foo))\n' |

1449 | n/a | '\n' |

1450 | n/a | 'The evaluation rules for the decorator expressions are the same as ' |

1451 | n/a | 'for\n' |

1452 | n/a | 'function decorators. The result is then bound to the class name.\n' |

1453 | n/a | '\n' |

1454 | n/a | "**Programmer's note:** Variables defined in the class definition " |

1455 | n/a | 'are\n' |

1456 | n/a | 'class attributes; they are shared by instances. Instance ' |

1457 | n/a | 'attributes\n' |

1458 | n/a | 'can be set in a method with "self.name = value". Both class and\n' |

1459 | n/a | 'instance attributes are accessible through the notation ' |

1460 | n/a | '""self.name"",\n' |

1461 | n/a | 'and an instance attribute hides a class attribute with the same ' |

1462 | n/a | 'name\n' |

1463 | n/a | 'when accessed in this way. Class attributes can be used as ' |

1464 | n/a | 'defaults\n' |

1465 | n/a | 'for instance attributes, but using mutable values there can lead ' |

1466 | n/a | 'to\n' |

1467 | n/a | 'unexpected results. Descriptors can be used to create instance\n' |

1468 | n/a | 'variables with different implementation details.\n' |

1469 | n/a | '\n' |

1470 | n/a | 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n' |

1471 | n/a | ' Class Decorators\n', |

1472 | n/a | 'comparisons': '\n' |

1473 | n/a | 'Comparisons\n' |

1474 | n/a | '***********\n' |

1475 | n/a | '\n' |

1476 | n/a | 'Unlike C, all comparison operations in Python have the same ' |

1477 | n/a | 'priority,\n' |

1478 | n/a | 'which is lower than that of any arithmetic, shifting or ' |

1479 | n/a | 'bitwise\n' |

1480 | n/a | 'operation. Also unlike C, expressions like "a < b < c" have ' |

1481 | n/a | 'the\n' |

1482 | n/a | 'interpretation that is conventional in mathematics:\n' |

1483 | n/a | '\n' |

1484 | n/a | ' comparison ::= or_expr ( comp_operator or_expr )*\n' |

1485 | n/a | ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' |

1486 | n/a | ' | "is" ["not"] | ["not"] "in"\n' |

1487 | n/a | '\n' |

1488 | n/a | 'Comparisons yield boolean values: "True" or "False".\n' |

1489 | n/a | '\n' |

1490 | n/a | 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' |

1491 | n/a | 'is\n' |

1492 | n/a | 'equivalent to "x < y and y <= z", except that "y" is ' |

1493 | n/a | 'evaluated only\n' |

1494 | n/a | 'once (but in both cases "z" is not evaluated at all when "x < ' |

1495 | n/a | 'y" is\n' |

1496 | n/a | 'found to be false).\n' |

1497 | n/a | '\n' |

1498 | n/a | 'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and ' |

1499 | n/a | '*op1*,\n' |

1500 | n/a | '*op2*, ..., *opN* are comparison operators, then "a op1 b op2 ' |

1501 | n/a | 'c ... y\n' |

1502 | n/a | 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' |

1503 | n/a | 'z", except\n' |

1504 | n/a | 'that each expression is evaluated at most once.\n' |

1505 | n/a | '\n' |

1506 | n/a | 'Note that "a op1 b op2 c" doesn\'t imply any kind of ' |

1507 | n/a | 'comparison between\n' |

1508 | n/a | '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' |

1509 | n/a | '(though\n' |

1510 | n/a | 'perhaps not pretty).\n' |

1511 | n/a | '\n' |

1512 | n/a | '\n' |

1513 | n/a | 'Value comparisons\n' |

1514 | n/a | '=================\n' |

1515 | n/a | '\n' |

1516 | n/a | 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' |

1517 | n/a | 'the values\n' |

1518 | n/a | 'of two objects. The objects do not need to have the same ' |

1519 | n/a | 'type.\n' |

1520 | n/a | '\n' |

1521 | n/a | 'Chapter Objects, values and types states that objects have a ' |

1522 | n/a | 'value (in\n' |

1523 | n/a | 'addition to type and identity). The value of an object is a ' |

1524 | n/a | 'rather\n' |

1525 | n/a | 'abstract notion in Python: For example, there is no canonical ' |

1526 | n/a | 'access\n' |

1527 | n/a | "method for an object's value. Also, there is no requirement " |

1528 | n/a | 'that the\n' |

1529 | n/a | 'value of an object should be constructed in a particular way, ' |

1530 | n/a | 'e.g.\n' |

1531 | n/a | 'comprised of all its data attributes. Comparison operators ' |

1532 | n/a | 'implement a\n' |

1533 | n/a | 'particular notion of what the value of an object is. One can ' |

1534 | n/a | 'think of\n' |

1535 | n/a | 'them as defining the value of an object indirectly, by means ' |

1536 | n/a | 'of their\n' |

1537 | n/a | 'comparison implementation.\n' |

1538 | n/a | '\n' |

1539 | n/a | 'Because all types are (direct or indirect) subtypes of ' |

1540 | n/a | '"object", they\n' |

1541 | n/a | 'inherit the default comparison behavior from "object". Types ' |

1542 | n/a | 'can\n' |

1543 | n/a | 'customize their comparison behavior by implementing *rich ' |

1544 | n/a | 'comparison\n' |

1545 | n/a | 'methods* like "__lt__()", described in Basic customization.\n' |

1546 | n/a | '\n' |

1547 | n/a | 'The default behavior for equality comparison ("==" and "!=") ' |

1548 | n/a | 'is based\n' |

1549 | n/a | 'on the identity of the objects. Hence, equality comparison ' |

1550 | n/a | 'of\n' |

1551 | n/a | 'instances with the same identity results in equality, and ' |

1552 | n/a | 'equality\n' |

1553 | n/a | 'comparison of instances with different identities results in\n' |

1554 | n/a | 'inequality. A motivation for this default behavior is the ' |

1555 | n/a | 'desire that\n' |

1556 | n/a | 'all objects should be reflexive (i.e. "x is y" implies "x == ' |

1557 | n/a | 'y").\n' |

1558 | n/a | '\n' |

1559 | n/a | 'A default order comparison ("<", ">", "<=", and ">=") is not ' |

1560 | n/a | 'provided;\n' |

1561 | n/a | 'an attempt raises "TypeError". A motivation for this default ' |

1562 | n/a | 'behavior\n' |

1563 | n/a | 'is the lack of a similar invariant as for equality.\n' |

1564 | n/a | '\n' |

1565 | n/a | 'The behavior of the default equality comparison, that ' |

1566 | n/a | 'instances with\n' |

1567 | n/a | 'different identities are always unequal, may be in contrast ' |

1568 | n/a | 'to what\n' |

1569 | n/a | 'types will need that have a sensible definition of object ' |

1570 | n/a | 'value and\n' |

1571 | n/a | 'value-based equality. Such types will need to customize ' |

1572 | n/a | 'their\n' |

1573 | n/a | 'comparison behavior, and in fact, a number of built-in types ' |

1574 | n/a | 'have done\n' |

1575 | n/a | 'that.\n' |

1576 | n/a | '\n' |

1577 | n/a | 'The following list describes the comparison behavior of the ' |

1578 | n/a | 'most\n' |

1579 | n/a | 'important built-in types.\n' |

1580 | n/a | '\n' |

1581 | n/a | '* Numbers of built-in numeric types (Numeric Types --- int, ' |

1582 | n/a | 'float,\n' |

1583 | n/a | ' complex) and of the standard library types ' |

1584 | n/a | '"fractions.Fraction" and\n' |

1585 | n/a | ' "decimal.Decimal" can be compared within and across their ' |

1586 | n/a | 'types,\n' |

1587 | n/a | ' with the restriction that complex numbers do not support ' |

1588 | n/a | 'order\n' |

1589 | n/a | ' comparison. Within the limits of the types involved, they ' |

1590 | n/a | 'compare\n' |

1591 | n/a | ' mathematically (algorithmically) correct without loss of ' |

1592 | n/a | 'precision.\n' |

1593 | n/a | '\n' |

1594 | n/a | ' The not-a-number values "float(\'NaN\')" and ' |

1595 | n/a | '"Decimal(\'NaN\')" are\n' |

1596 | n/a | ' special. They are identical to themselves ("x is x" is ' |

1597 | n/a | 'true) but\n' |

1598 | n/a | ' are not equal to themselves ("x == x" is false). ' |

1599 | n/a | 'Additionally,\n' |

1600 | n/a | ' comparing any number to a not-a-number value will return ' |

1601 | n/a | '"False".\n' |

1602 | n/a | ' For example, both "3 < float(\'NaN\')" and "float(\'NaN\') ' |

1603 | n/a | '< 3" will\n' |

1604 | n/a | ' return "False".\n' |

1605 | n/a | '\n' |

1606 | n/a | '* Binary sequences (instances of "bytes" or "bytearray") can ' |

1607 | n/a | 'be\n' |

1608 | n/a | ' compared within and across their types. They compare\n' |

1609 | n/a | ' lexicographically using the numeric values of their ' |

1610 | n/a | 'elements.\n' |

1611 | n/a | '\n' |

1612 | n/a | '* Strings (instances of "str") compare lexicographically ' |

1613 | n/a | 'using the\n' |

1614 | n/a | ' numerical Unicode code points (the result of the built-in ' |

1615 | n/a | 'function\n' |

1616 | n/a | ' "ord()") of their characters. [3]\n' |

1617 | n/a | '\n' |

1618 | n/a | ' Strings and binary sequences cannot be directly compared.\n' |

1619 | n/a | '\n' |

1620 | n/a | '* Sequences (instances of "tuple", "list", or "range") can ' |

1621 | n/a | 'be\n' |

1622 | n/a | ' compared only within each of their types, with the ' |

1623 | n/a | 'restriction that\n' |

1624 | n/a | ' ranges do not support order comparison. Equality ' |

1625 | n/a | 'comparison across\n' |

1626 | n/a | ' these types results in unequality, and ordering comparison ' |

1627 | n/a | 'across\n' |

1628 | n/a | ' these types raises "TypeError".\n' |

1629 | n/a | '\n' |

1630 | n/a | ' Sequences compare lexicographically using comparison of\n' |

1631 | n/a | ' corresponding elements, whereby reflexivity of the elements ' |

1632 | n/a | 'is\n' |

1633 | n/a | ' enforced.\n' |

1634 | n/a | '\n' |

1635 | n/a | ' In enforcing reflexivity of elements, the comparison of ' |

1636 | n/a | 'collections\n' |

1637 | n/a | ' assumes that for a collection element "x", "x == x" is ' |

1638 | n/a | 'always true.\n' |

1639 | n/a | ' Based on that assumption, element identity is compared ' |

1640 | n/a | 'first, and\n' |

1641 | n/a | ' element comparison is performed only for distinct ' |

1642 | n/a | 'elements. This\n' |

1643 | n/a | ' approach yields the same result as a strict element ' |

1644 | n/a | 'comparison\n' |

1645 | n/a | ' would, if the compared elements are reflexive. For ' |

1646 | n/a | 'non-reflexive\n' |

1647 | n/a | ' elements, the result is different than for strict element\n' |

1648 | n/a | ' comparison, and may be surprising: The non-reflexive ' |

1649 | n/a | 'not-a-number\n' |

1650 | n/a | ' values for example result in the following comparison ' |

1651 | n/a | 'behavior when\n' |

1652 | n/a | ' used in a list:\n' |

1653 | n/a | '\n' |

1654 | n/a | " >>> nan = float('NaN')\n" |

1655 | n/a | ' >>> nan is nan\n' |

1656 | n/a | ' True\n' |

1657 | n/a | ' >>> nan == nan\n' |

1658 | n/a | ' False <-- the defined non-reflexive ' |

1659 | n/a | 'behavior of NaN\n' |

1660 | n/a | ' >>> [nan] == [nan]\n' |

1661 | n/a | ' True <-- list enforces reflexivity and ' |

1662 | n/a | 'tests identity first\n' |

1663 | n/a | '\n' |

1664 | n/a | ' Lexicographical comparison between built-in collections ' |

1665 | n/a | 'works as\n' |

1666 | n/a | ' follows:\n' |

1667 | n/a | '\n' |

1668 | n/a | ' * For two collections to compare equal, they must be of the ' |

1669 | n/a | 'same\n' |

1670 | n/a | ' type, have the same length, and each pair of ' |

1671 | n/a | 'corresponding\n' |

1672 | n/a | ' elements must compare equal (for example, "[1,2] == ' |

1673 | n/a | '(1,2)" is\n' |

1674 | n/a | ' false because the type is not the same).\n' |

1675 | n/a | '\n' |

1676 | n/a | ' * Collections that support order comparison are ordered the ' |

1677 | n/a | 'same\n' |

1678 | n/a | ' as their first unequal elements (for example, "[1,2,x] <= ' |

1679 | n/a | '[1,2,y]"\n' |

1680 | n/a | ' has the same value as "x <= y"). If a corresponding ' |

1681 | n/a | 'element does\n' |

1682 | n/a | ' not exist, the shorter collection is ordered first (for ' |

1683 | n/a | 'example,\n' |

1684 | n/a | ' "[1,2] < [1,2,3]" is true).\n' |

1685 | n/a | '\n' |

1686 | n/a | '* Mappings (instances of "dict") compare equal if and only if ' |

1687 | n/a | 'they\n' |

1688 | n/a | ' have equal *(key, value)* pairs. Equality comparison of the ' |

1689 | n/a | 'keys and\n' |

1690 | n/a | ' elements enforces reflexivity.\n' |

1691 | n/a | '\n' |

1692 | n/a | ' Order comparisons ("<", ">", "<=", and ">=") raise ' |

1693 | n/a | '"TypeError".\n' |

1694 | n/a | '\n' |

1695 | n/a | '* Sets (instances of "set" or "frozenset") can be compared ' |

1696 | n/a | 'within\n' |

1697 | n/a | ' and across their types.\n' |

1698 | n/a | '\n' |

1699 | n/a | ' They define order comparison operators to mean subset and ' |

1700 | n/a | 'superset\n' |

1701 | n/a | ' tests. Those relations do not define total orderings (for ' |

1702 | n/a | 'example,\n' |

1703 | n/a | ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets ' |

1704 | n/a | 'of one\n' |

1705 | n/a | ' another, nor supersets of one another). Accordingly, sets ' |

1706 | n/a | 'are not\n' |

1707 | n/a | ' appropriate arguments for functions which depend on total ' |

1708 | n/a | 'ordering\n' |

1709 | n/a | ' (for example, "min()", "max()", and "sorted()" produce ' |

1710 | n/a | 'undefined\n' |

1711 | n/a | ' results given a list of sets as inputs).\n' |

1712 | n/a | '\n' |

1713 | n/a | ' Comparison of sets enforces reflexivity of its elements.\n' |

1714 | n/a | '\n' |

1715 | n/a | '* Most other built-in types have no comparison methods ' |

1716 | n/a | 'implemented,\n' |

1717 | n/a | ' so they inherit the default comparison behavior.\n' |

1718 | n/a | '\n' |

1719 | n/a | 'User-defined classes that customize their comparison behavior ' |

1720 | n/a | 'should\n' |

1721 | n/a | 'follow some consistency rules, if possible:\n' |

1722 | n/a | '\n' |

1723 | n/a | '* Equality comparison should be reflexive. In other words, ' |

1724 | n/a | 'identical\n' |

1725 | n/a | ' objects should compare equal:\n' |

1726 | n/a | '\n' |

1727 | n/a | ' "x is y" implies "x == y"\n' |

1728 | n/a | '\n' |

1729 | n/a | '* Comparison should be symmetric. In other words, the ' |

1730 | n/a | 'following\n' |

1731 | n/a | ' expressions should have the same result:\n' |

1732 | n/a | '\n' |

1733 | n/a | ' "x == y" and "y == x"\n' |

1734 | n/a | '\n' |

1735 | n/a | ' "x != y" and "y != x"\n' |

1736 | n/a | '\n' |

1737 | n/a | ' "x < y" and "y > x"\n' |

1738 | n/a | '\n' |

1739 | n/a | ' "x <= y" and "y >= x"\n' |

1740 | n/a | '\n' |

1741 | n/a | '* Comparison should be transitive. The following ' |

1742 | n/a | '(non-exhaustive)\n' |

1743 | n/a | ' examples illustrate that:\n' |

1744 | n/a | '\n' |

1745 | n/a | ' "x > y and y > z" implies "x > z"\n' |

1746 | n/a | '\n' |

1747 | n/a | ' "x < y and y <= z" implies "x < z"\n' |

1748 | n/a | '\n' |

1749 | n/a | '* Inverse comparison should result in the boolean negation. ' |

1750 | n/a | 'In other\n' |

1751 | n/a | ' words, the following expressions should have the same ' |

1752 | n/a | 'result:\n' |

1753 | n/a | '\n' |

1754 | n/a | ' "x == y" and "not x != y"\n' |

1755 | n/a | '\n' |

1756 | n/a | ' "x < y" and "not x >= y" (for total ordering)\n' |

1757 | n/a | '\n' |

1758 | n/a | ' "x > y" and "not x <= y" (for total ordering)\n' |

1759 | n/a | '\n' |

1760 | n/a | ' The last two expressions apply to totally ordered ' |

1761 | n/a | 'collections (e.g.\n' |

1762 | n/a | ' to sequences, but not to sets or mappings). See also the\n' |

1763 | n/a | ' "total_ordering()" decorator.\n' |

1764 | n/a | '\n' |

1765 | n/a | 'Python does not enforce these consistency rules. In fact, ' |

1766 | n/a | 'the\n' |

1767 | n/a | 'not-a-number values are an example for not following these ' |

1768 | n/a | 'rules.\n' |

1769 | n/a | '\n' |

1770 | n/a | '\n' |

1771 | n/a | 'Membership test operations\n' |

1772 | n/a | '==========================\n' |

1773 | n/a | '\n' |

1774 | n/a | 'The operators "in" and "not in" test for membership. "x in ' |

1775 | n/a | 's"\n' |

1776 | n/a | 'evaluates to true if *x* is a member of *s*, and false ' |

1777 | n/a | 'otherwise. "x\n' |

1778 | n/a | 'not in s" returns the negation of "x in s". All built-in ' |

1779 | n/a | 'sequences\n' |

1780 | n/a | 'and set types support this as well as dictionary, for which ' |

1781 | n/a | '"in" tests\n' |

1782 | n/a | 'whether the dictionary has a given key. For container types ' |

1783 | n/a | 'such as\n' |

1784 | n/a | 'list, tuple, set, frozenset, dict, or collections.deque, the\n' |

1785 | n/a | 'expression "x in y" is equivalent to "any(x is e or x == e ' |

1786 | n/a | 'for e in\n' |

1787 | n/a | 'y)".\n' |

1788 | n/a | '\n' |

1789 | n/a | 'For the string and bytes types, "x in y" is true if and only ' |

1790 | n/a | 'if *x* is\n' |

1791 | n/a | 'a substring of *y*. An equivalent test is "y.find(x) != ' |

1792 | n/a | '-1". Empty\n' |

1793 | n/a | 'strings are always considered to be a substring of any other ' |

1794 | n/a | 'string,\n' |

1795 | n/a | 'so """ in "abc"" will return "True".\n' |

1796 | n/a | '\n' |

1797 | n/a | 'For user-defined classes which define the "__contains__()" ' |

1798 | n/a | 'method, "x\n' |

1799 | n/a | 'in y" is true if and only if "y.__contains__(x)" is true.\n' |

1800 | n/a | '\n' |

1801 | n/a | 'For user-defined classes which do not define "__contains__()" ' |

1802 | n/a | 'but do\n' |

1803 | n/a | 'define "__iter__()", "x in y" is true if some value "z" with ' |

1804 | n/a | '"x == z"\n' |

1805 | n/a | 'is produced while iterating over "y". If an exception is ' |

1806 | n/a | 'raised\n' |

1807 | n/a | 'during the iteration, it is as if "in" raised that ' |

1808 | n/a | 'exception.\n' |

1809 | n/a | '\n' |

1810 | n/a | 'Lastly, the old-style iteration protocol is tried: if a class ' |

1811 | n/a | 'defines\n' |

1812 | n/a | '"__getitem__()", "x in y" is true if and only if there is a ' |

1813 | n/a | 'non-\n' |

1814 | n/a | 'negative integer index *i* such that "x == y[i]", and all ' |

1815 | n/a | 'lower\n' |

1816 | n/a | 'integer indices do not raise "IndexError" exception. (If any ' |

1817 | n/a | 'other\n' |

1818 | n/a | 'exception is raised, it is as if "in" raised that ' |

1819 | n/a | 'exception).\n' |

1820 | n/a | '\n' |

1821 | n/a | 'The operator "not in" is defined to have the inverse true ' |

1822 | n/a | 'value of\n' |

1823 | n/a | '"in".\n' |

1824 | n/a | '\n' |

1825 | n/a | '\n' |

1826 | n/a | 'Identity comparisons\n' |

1827 | n/a | '====================\n' |

1828 | n/a | '\n' |

1829 | n/a | 'The operators "is" and "is not" test for object identity: "x ' |

1830 | n/a | 'is y" is\n' |

1831 | n/a | 'true if and only if *x* and *y* are the same object. Object ' |

1832 | n/a | 'identity\n' |

1833 | n/a | 'is determined using the "id()" function. "x is not y" yields ' |

1834 | n/a | 'the\n' |

1835 | n/a | 'inverse truth value. [4]\n', |

1836 | n/a | 'compound': '\n' |

1837 | n/a | 'Compound statements\n' |

1838 | n/a | '*******************\n' |

1839 | n/a | '\n' |

1840 | n/a | 'Compound statements contain (groups of) other statements; they ' |

1841 | n/a | 'affect\n' |

1842 | n/a | 'or control the execution of those other statements in some way. ' |

1843 | n/a | 'In\n' |

1844 | n/a | 'general, compound statements span multiple lines, although in ' |

1845 | n/a | 'simple\n' |

1846 | n/a | 'incarnations a whole compound statement may be contained in one ' |

1847 | n/a | 'line.\n' |

1848 | n/a | '\n' |

1849 | n/a | 'The "if", "while" and "for" statements implement traditional ' |

1850 | n/a | 'control\n' |

1851 | n/a | 'flow constructs. "try" specifies exception handlers and/or ' |

1852 | n/a | 'cleanup\n' |

1853 | n/a | 'code for a group of statements, while the "with" statement ' |

1854 | n/a | 'allows the\n' |

1855 | n/a | 'execution of initialization and finalization code around a block ' |

1856 | n/a | 'of\n' |

1857 | n/a | 'code. Function and class definitions are also syntactically ' |

1858 | n/a | 'compound\n' |

1859 | n/a | 'statements.\n' |

1860 | n/a | '\n' |

1861 | n/a | "A compound statement consists of one or more 'clauses.' A " |

1862 | n/a | 'clause\n' |

1863 | n/a | "consists of a header and a 'suite.' The clause headers of a\n" |

1864 | n/a | 'particular compound statement are all at the same indentation ' |

1865 | n/a | 'level.\n' |

1866 | n/a | 'Each clause header begins with a uniquely identifying keyword ' |

1867 | n/a | 'and ends\n' |

1868 | n/a | 'with a colon. A suite is a group of statements controlled by a\n' |

1869 | n/a | 'clause. A suite can be one or more semicolon-separated simple\n' |

1870 | n/a | 'statements on the same line as the header, following the ' |

1871 | n/a | "header's\n" |

1872 | n/a | 'colon, or it can be one or more indented statements on ' |

1873 | n/a | 'subsequent\n' |

1874 | n/a | 'lines. Only the latter form of a suite can contain nested ' |

1875 | n/a | 'compound\n' |

1876 | n/a | "statements; the following is illegal, mostly because it wouldn't " |

1877 | n/a | 'be\n' |

1878 | n/a | 'clear to which "if" clause a following "else" clause would ' |

1879 | n/a | 'belong:\n' |

1880 | n/a | '\n' |

1881 | n/a | ' if test1: if test2: print(x)\n' |

1882 | n/a | '\n' |

1883 | n/a | 'Also note that the semicolon binds tighter than the colon in ' |

1884 | n/a | 'this\n' |

1885 | n/a | 'context, so that in the following example, either all or none of ' |

1886 | n/a | 'the\n' |

1887 | n/a | '"print()" calls are executed:\n' |

1888 | n/a | '\n' |

1889 | n/a | ' if x < y < z: print(x); print(y); print(z)\n' |

1890 | n/a | '\n' |

1891 | n/a | 'Summarizing:\n' |

1892 | n/a | '\n' |

1893 | n/a | ' compound_stmt ::= if_stmt\n' |

1894 | n/a | ' | while_stmt\n' |

1895 | n/a | ' | for_stmt\n' |

1896 | n/a | ' | try_stmt\n' |

1897 | n/a | ' | with_stmt\n' |

1898 | n/a | ' | funcdef\n' |

1899 | n/a | ' | classdef\n' |

1900 | n/a | ' | async_with_stmt\n' |

1901 | n/a | ' | async_for_stmt\n' |

1902 | n/a | ' | async_funcdef\n' |

1903 | n/a | ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' |

1904 | n/a | 'statement+ DEDENT\n' |

1905 | n/a | ' statement ::= stmt_list NEWLINE | compound_stmt\n' |

1906 | n/a | ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' |

1907 | n/a | '\n' |

1908 | n/a | 'Note that statements always end in a "NEWLINE" possibly followed ' |

1909 | n/a | 'by a\n' |

1910 | n/a | '"DEDENT". Also note that optional continuation clauses always ' |

1911 | n/a | 'begin\n' |

1912 | n/a | 'with a keyword that cannot start a statement, thus there are no\n' |

1913 | n/a | 'ambiguities (the \'dangling "else"\' problem is solved in Python ' |

1914 | n/a | 'by\n' |

1915 | n/a | 'requiring nested "if" statements to be indented).\n' |

1916 | n/a | '\n' |

1917 | n/a | 'The formatting of the grammar rules in the following sections ' |

1918 | n/a | 'places\n' |

1919 | n/a | 'each clause on a separate line for clarity.\n' |

1920 | n/a | '\n' |

1921 | n/a | '\n' |

1922 | n/a | 'The "if" statement\n' |

1923 | n/a | '==================\n' |

1924 | n/a | '\n' |

1925 | n/a | 'The "if" statement is used for conditional execution:\n' |

1926 | n/a | '\n' |

1927 | n/a | ' if_stmt ::= "if" expression ":" suite\n' |

1928 | n/a | ' ( "elif" expression ":" suite )*\n' |

1929 | n/a | ' ["else" ":" suite]\n' |

1930 | n/a | '\n' |

1931 | n/a | 'It selects exactly one of the suites by evaluating the ' |

1932 | n/a | 'expressions one\n' |

1933 | n/a | 'by one until one is found to be true (see section Boolean ' |

1934 | n/a | 'operations\n' |

1935 | n/a | 'for the definition of true and false); then that suite is ' |

1936 | n/a | 'executed\n' |

1937 | n/a | '(and no other part of the "if" statement is executed or ' |

1938 | n/a | 'evaluated).\n' |

1939 | n/a | 'If all expressions are false, the suite of the "else" clause, ' |

1940 | n/a | 'if\n' |

1941 | n/a | 'present, is executed.\n' |

1942 | n/a | '\n' |

1943 | n/a | '\n' |

1944 | n/a | 'The "while" statement\n' |

1945 | n/a | '=====================\n' |

1946 | n/a | '\n' |

1947 | n/a | 'The "while" statement is used for repeated execution as long as ' |

1948 | n/a | 'an\n' |

1949 | n/a | 'expression is true:\n' |

1950 | n/a | '\n' |

1951 | n/a | ' while_stmt ::= "while" expression ":" suite\n' |

1952 | n/a | ' ["else" ":" suite]\n' |

1953 | n/a | '\n' |

1954 | n/a | 'This repeatedly tests the expression and, if it is true, ' |

1955 | n/a | 'executes the\n' |

1956 | n/a | 'first suite; if the expression is false (which may be the first ' |

1957 | n/a | 'time\n' |

1958 | n/a | 'it is tested) the suite of the "else" clause, if present, is ' |

1959 | n/a | 'executed\n' |

1960 | n/a | 'and the loop terminates.\n' |

1961 | n/a | '\n' |

1962 | n/a | 'A "break" statement executed in the first suite terminates the ' |

1963 | n/a | 'loop\n' |

1964 | n/a | 'without executing the "else" clause\'s suite. A "continue" ' |

1965 | n/a | 'statement\n' |

1966 | n/a | 'executed in the first suite skips the rest of the suite and goes ' |

1967 | n/a | 'back\n' |

1968 | n/a | 'to testing the expression.\n' |

1969 | n/a | '\n' |

1970 | n/a | '\n' |

1971 | n/a | 'The "for" statement\n' |

1972 | n/a | '===================\n' |

1973 | n/a | '\n' |

1974 | n/a | 'The "for" statement is used to iterate over the elements of a ' |

1975 | n/a | 'sequence\n' |

1976 | n/a | '(such as a string, tuple or list) or other iterable object:\n' |

1977 | n/a | '\n' |

1978 | n/a | ' for_stmt ::= "for" target_list "in" expression_list ":" ' |

1979 | n/a | 'suite\n' |

1980 | n/a | ' ["else" ":" suite]\n' |

1981 | n/a | '\n' |

1982 | n/a | 'The expression list is evaluated once; it should yield an ' |

1983 | n/a | 'iterable\n' |

1984 | n/a | 'object. An iterator is created for the result of the\n' |

1985 | n/a | '"expression_list". The suite is then executed once for each ' |

1986 | n/a | 'item\n' |

1987 | n/a | 'provided by the iterator, in the order returned by the ' |

1988 | n/a | 'iterator. Each\n' |

1989 | n/a | 'item in turn is assigned to the target list using the standard ' |

1990 | n/a | 'rules\n' |

1991 | n/a | 'for assignments (see Assignment statements), and then the suite ' |

1992 | n/a | 'is\n' |

1993 | n/a | 'executed. When the items are exhausted (which is immediately ' |

1994 | n/a | 'when the\n' |

1995 | n/a | 'sequence is empty or an iterator raises a "StopIteration" ' |

1996 | n/a | 'exception),\n' |

1997 | n/a | 'the suite in the "else" clause, if present, is executed, and the ' |

1998 | n/a | 'loop\n' |

1999 | n/a | 'terminates.\n' |

2000 | n/a | '\n' |

2001 | n/a | 'A "break" statement executed in the first suite terminates the ' |

2002 | n/a | 'loop\n' |

2003 | n/a | 'without executing the "else" clause\'s suite. A "continue" ' |

2004 | n/a | 'statement\n' |

2005 | n/a | 'executed in the first suite skips the rest of the suite and ' |

2006 | n/a | 'continues\n' |

2007 | n/a | 'with the next item, or with the "else" clause if there is no ' |

2008 | n/a | 'next\n' |

2009 | n/a | 'item.\n' |

2010 | n/a | '\n' |

2011 | n/a | 'The for-loop makes assignments to the variables(s) in the target ' |

2012 | n/a | 'list.\n' |

2013 | n/a | 'This overwrites all previous assignments to those variables ' |

2014 | n/a | 'including\n' |

2015 | n/a | 'those made in the suite of the for-loop:\n' |

2016 | n/a | '\n' |

2017 | n/a | ' for i in range(10):\n' |

2018 | n/a | ' print(i)\n' |

2019 | n/a | ' i = 5 # this will not affect the for-loop\n' |

2020 | n/a | ' # because i will be overwritten with ' |

2021 | n/a | 'the next\n' |

2022 | n/a | ' # index in the range\n' |

2023 | n/a | '\n' |

2024 | n/a | 'Names in the target list are not deleted when the loop is ' |

2025 | n/a | 'finished,\n' |

2026 | n/a | 'but if the sequence is empty, they will not have been assigned ' |

2027 | n/a | 'to at\n' |

2028 | n/a | 'all by the loop. Hint: the built-in function "range()" returns ' |

2029 | n/a | 'an\n' |

2030 | n/a | "iterator of integers suitable to emulate the effect of Pascal's " |

2031 | n/a | '"for i\n' |

2032 | n/a | ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' |

2033 | n/a | '2]".\n' |

2034 | n/a | '\n' |

2035 | n/a | 'Note: There is a subtlety when the sequence is being modified by ' |

2036 | n/a | 'the\n' |

2037 | n/a | ' loop (this can only occur for mutable sequences, i.e. lists). ' |

2038 | n/a | 'An\n' |

2039 | n/a | ' internal counter is used to keep track of which item is used ' |

2040 | n/a | 'next,\n' |

2041 | n/a | ' and this is incremented on each iteration. When this counter ' |

2042 | n/a | 'has\n' |

2043 | n/a | ' reached the length of the sequence the loop terminates. This ' |

2044 | n/a | 'means\n' |

2045 | n/a | ' that if the suite deletes the current (or a previous) item ' |

2046 | n/a | 'from the\n' |

2047 | n/a | ' sequence, the next item will be skipped (since it gets the ' |

2048 | n/a | 'index of\n' |

2049 | n/a | ' the current item which has already been treated). Likewise, ' |

2050 | n/a | 'if the\n' |

2051 | n/a | ' suite inserts an item in the sequence before the current item, ' |

2052 | n/a | 'the\n' |

2053 | n/a | ' current item will be treated again the next time through the ' |

2054 | n/a | 'loop.\n' |

2055 | n/a | ' This can lead to nasty bugs that can be avoided by making a\n' |

2056 | n/a | ' temporary copy using a slice of the whole sequence, e.g.,\n' |

2057 | n/a | '\n' |

2058 | n/a | ' for x in a[:]:\n' |

2059 | n/a | ' if x < 0: a.remove(x)\n' |

2060 | n/a | '\n' |

2061 | n/a | '\n' |

2062 | n/a | 'The "try" statement\n' |

2063 | n/a | '===================\n' |

2064 | n/a | '\n' |

2065 | n/a | 'The "try" statement specifies exception handlers and/or cleanup ' |

2066 | n/a | 'code\n' |

2067 | n/a | 'for a group of statements:\n' |

2068 | n/a | '\n' |

2069 | n/a | ' try_stmt ::= try1_stmt | try2_stmt\n' |

2070 | n/a | ' try1_stmt ::= "try" ":" suite\n' |

2071 | n/a | ' ("except" [expression ["as" identifier]] ":" ' |

2072 | n/a | 'suite)+\n' |

2073 | n/a | ' ["else" ":" suite]\n' |

2074 | n/a | ' ["finally" ":" suite]\n' |

2075 | n/a | ' try2_stmt ::= "try" ":" suite\n' |

2076 | n/a | ' "finally" ":" suite\n' |

2077 | n/a | '\n' |

2078 | n/a | 'The "except" clause(s) specify one or more exception handlers. ' |

2079 | n/a | 'When no\n' |

2080 | n/a | 'exception occurs in the "try" clause, no exception handler is\n' |

2081 | n/a | 'executed. When an exception occurs in the "try" suite, a search ' |

2082 | n/a | 'for an\n' |

2083 | n/a | 'exception handler is started. This search inspects the except ' |

2084 | n/a | 'clauses\n' |

2085 | n/a | 'in turn until one is found that matches the exception. An ' |

2086 | n/a | 'expression-\n' |

2087 | n/a | 'less except clause, if present, must be last; it matches any\n' |

2088 | n/a | 'exception. For an except clause with an expression, that ' |

2089 | n/a | 'expression\n' |

2090 | n/a | 'is evaluated, and the clause matches the exception if the ' |

2091 | n/a | 'resulting\n' |

2092 | n/a | 'object is "compatible" with the exception. An object is ' |

2093 | n/a | 'compatible\n' |

2094 | n/a | 'with an exception if it is the class or a base class of the ' |

2095 | n/a | 'exception\n' |

2096 | n/a | 'object or a tuple containing an item compatible with the ' |

2097 | n/a | 'exception.\n' |

2098 | n/a | '\n' |

2099 | n/a | 'If no except clause matches the exception, the search for an ' |

2100 | n/a | 'exception\n' |

2101 | n/a | 'handler continues in the surrounding code and on the invocation ' |

2102 | n/a | 'stack.\n' |

2103 | n/a | '[1]\n' |

2104 | n/a | '\n' |

2105 | n/a | 'If the evaluation of an expression in the header of an except ' |

2106 | n/a | 'clause\n' |

2107 | n/a | 'raises an exception, the original search for a handler is ' |

2108 | n/a | 'canceled and\n' |

2109 | n/a | 'a search starts for the new exception in the surrounding code ' |

2110 | n/a | 'and on\n' |

2111 | n/a | 'the call stack (it is treated as if the entire "try" statement ' |

2112 | n/a | 'raised\n' |

2113 | n/a | 'the exception).\n' |

2114 | n/a | '\n' |

2115 | n/a | 'When a matching except clause is found, the exception is ' |

2116 | n/a | 'assigned to\n' |

2117 | n/a | 'the target specified after the "as" keyword in that except ' |

2118 | n/a | 'clause, if\n' |

2119 | n/a | "present, and the except clause's suite is executed. All except\n" |

2120 | n/a | 'clauses must have an executable block. When the end of this ' |

2121 | n/a | 'block is\n' |

2122 | n/a | 'reached, execution continues normally after the entire try ' |

2123 | n/a | 'statement.\n' |

2124 | n/a | '(This means that if two nested handlers exist for the same ' |

2125 | n/a | 'exception,\n' |

2126 | n/a | 'and the exception occurs in the try clause of the inner handler, ' |

2127 | n/a | 'the\n' |

2128 | n/a | 'outer handler will not handle the exception.)\n' |

2129 | n/a | '\n' |

2130 | n/a | 'When an exception has been assigned using "as target", it is ' |

2131 | n/a | 'cleared\n' |

2132 | n/a | 'at the end of the except clause. This is as if\n' |

2133 | n/a | '\n' |

2134 | n/a | ' except E as N:\n' |

2135 | n/a | ' foo\n' |

2136 | n/a | '\n' |

2137 | n/a | 'was translated to\n' |

2138 | n/a | '\n' |

2139 | n/a | ' except E as N:\n' |

2140 | n/a | ' try:\n' |

2141 | n/a | ' foo\n' |

2142 | n/a | ' finally:\n' |

2143 | n/a | ' del N\n' |

2144 | n/a | '\n' |

2145 | n/a | 'This means the exception must be assigned to a different name to ' |

2146 | n/a | 'be\n' |

2147 | n/a | 'able to refer to it after the except clause. Exceptions are ' |

2148 | n/a | 'cleared\n' |

2149 | n/a | 'because with the traceback attached to them, they form a ' |

2150 | n/a | 'reference\n' |

2151 | n/a | 'cycle with the stack frame, keeping all locals in that frame ' |

2152 | n/a | 'alive\n' |

2153 | n/a | 'until the next garbage collection occurs.\n' |

2154 | n/a | '\n' |

2155 | n/a | "Before an except clause's suite is executed, details about the\n" |

2156 | n/a | 'exception are stored in the "sys" module and can be accessed ' |

2157 | n/a | 'via\n' |

2158 | n/a | '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' |

2159 | n/a | 'of the\n' |

2160 | n/a | 'exception class, the exception instance and a traceback object ' |

2161 | n/a | '(see\n' |

2162 | n/a | 'section The standard type hierarchy) identifying the point in ' |

2163 | n/a | 'the\n' |

2164 | n/a | 'program where the exception occurred. "sys.exc_info()" values ' |

2165 | n/a | 'are\n' |

2166 | n/a | 'restored to their previous values (before the call) when ' |

2167 | n/a | 'returning\n' |

2168 | n/a | 'from a function that handled an exception.\n' |

2169 | n/a | '\n' |

2170 | n/a | 'The optional "else" clause is executed if and when control flows ' |

2171 | n/a | 'off\n' |

2172 | n/a | 'the end of the "try" clause. [2] Exceptions in the "else" clause ' |

2173 | n/a | 'are\n' |

2174 | n/a | 'not handled by the preceding "except" clauses.\n' |

2175 | n/a | '\n' |

2176 | n/a | 'If "finally" is present, it specifies a \'cleanup\' handler. ' |

2177 | n/a | 'The "try"\n' |

2178 | n/a | 'clause is executed, including any "except" and "else" clauses. ' |

2179 | n/a | 'If an\n' |

2180 | n/a | 'exception occurs in any of the clauses and is not handled, the\n' |

2181 | n/a | 'exception is temporarily saved. The "finally" clause is ' |

2182 | n/a | 'executed. If\n' |

2183 | n/a | 'there is a saved exception it is re-raised at the end of the ' |

2184 | n/a | '"finally"\n' |

2185 | n/a | 'clause. If the "finally" clause raises another exception, the ' |

2186 | n/a | 'saved\n' |

2187 | n/a | 'exception is set as the context of the new exception. If the ' |

2188 | n/a | '"finally"\n' |

2189 | n/a | 'clause executes a "return" or "break" statement, the saved ' |

2190 | n/a | 'exception\n' |

2191 | n/a | 'is discarded:\n' |

2192 | n/a | '\n' |

2193 | n/a | ' >>> def f():\n' |

2194 | n/a | ' ... try:\n' |

2195 | n/a | ' ... 1/0\n' |

2196 | n/a | ' ... finally:\n' |

2197 | n/a | ' ... return 42\n' |

2198 | n/a | ' ...\n' |

2199 | n/a | ' >>> f()\n' |

2200 | n/a | ' 42\n' |

2201 | n/a | '\n' |

2202 | n/a | 'The exception information is not available to the program ' |

2203 | n/a | 'during\n' |

2204 | n/a | 'execution of the "finally" clause.\n' |

2205 | n/a | '\n' |

2206 | n/a | 'When a "return", "break" or "continue" statement is executed in ' |

2207 | n/a | 'the\n' |

2208 | n/a | '"try" suite of a "try"..."finally" statement, the "finally" ' |

2209 | n/a | 'clause is\n' |

2210 | n/a | 'also executed \'on the way out.\' A "continue" statement is ' |

2211 | n/a | 'illegal in\n' |

2212 | n/a | 'the "finally" clause. (The reason is a problem with the current\n' |

2213 | n/a | 'implementation --- this restriction may be lifted in the ' |

2214 | n/a | 'future).\n' |

2215 | n/a | '\n' |

2216 | n/a | 'The return value of a function is determined by the last ' |

2217 | n/a | '"return"\n' |

2218 | n/a | 'statement executed. Since the "finally" clause always executes, ' |

2219 | n/a | 'a\n' |

2220 | n/a | '"return" statement executed in the "finally" clause will always ' |

2221 | n/a | 'be the\n' |

2222 | n/a | 'last one executed:\n' |

2223 | n/a | '\n' |

2224 | n/a | ' >>> def foo():\n' |

2225 | n/a | ' ... try:\n' |

2226 | n/a | " ... return 'try'\n" |

2227 | n/a | ' ... finally:\n' |

2228 | n/a | " ... return 'finally'\n" |

2229 | n/a | ' ...\n' |

2230 | n/a | ' >>> foo()\n' |

2231 | n/a | " 'finally'\n" |

2232 | n/a | '\n' |

2233 | n/a | 'Additional information on exceptions can be found in section\n' |

2234 | n/a | 'Exceptions, and information on using the "raise" statement to ' |

2235 | n/a | 'generate\n' |

2236 | n/a | 'exceptions may be found in section The raise statement.\n' |

2237 | n/a | '\n' |

2238 | n/a | '\n' |

2239 | n/a | 'The "with" statement\n' |

2240 | n/a | '====================\n' |

2241 | n/a | '\n' |

2242 | n/a | 'The "with" statement is used to wrap the execution of a block ' |

2243 | n/a | 'with\n' |

2244 | n/a | 'methods defined by a context manager (see section With ' |

2245 | n/a | 'Statement\n' |

2246 | n/a | 'Context Managers). This allows common ' |

2247 | n/a | '"try"..."except"..."finally"\n' |

2248 | n/a | 'usage patterns to be encapsulated for convenient reuse.\n' |

2249 | n/a | '\n' |

2250 | n/a | ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' |

2251 | n/a | ' with_item ::= expression ["as" target]\n' |

2252 | n/a | '\n' |

2253 | n/a | 'The execution of the "with" statement with one "item" proceeds ' |

2254 | n/a | 'as\n' |

2255 | n/a | 'follows:\n' |

2256 | n/a | '\n' |

2257 | n/a | '1. The context expression (the expression given in the ' |

2258 | n/a | '"with_item")\n' |

2259 | n/a | ' is evaluated to obtain a context manager.\n' |

2260 | n/a | '\n' |

2261 | n/a | '2. The context manager\'s "__exit__()" is loaded for later use.\n' |

2262 | n/a | '\n' |

2263 | n/a | '3. The context manager\'s "__enter__()" method is invoked.\n' |

2264 | n/a | '\n' |

2265 | n/a | '4. If a target was included in the "with" statement, the return\n' |

2266 | n/a | ' value from "__enter__()" is assigned to it.\n' |

2267 | n/a | '\n' |

2268 | n/a | ' Note: The "with" statement guarantees that if the ' |

2269 | n/a | '"__enter__()"\n' |

2270 | n/a | ' method returns without an error, then "__exit__()" will ' |

2271 | n/a | 'always be\n' |

2272 | n/a | ' called. Thus, if an error occurs during the assignment to ' |

2273 | n/a | 'the\n' |

2274 | n/a | ' target list, it will be treated the same as an error ' |

2275 | n/a | 'occurring\n' |

2276 | n/a | ' within the suite would be. See step 6 below.\n' |

2277 | n/a | '\n' |

2278 | n/a | '5. The suite is executed.\n' |

2279 | n/a | '\n' |

2280 | n/a | '6. The context manager\'s "__exit__()" method is invoked. If ' |

2281 | n/a | 'an\n' |

2282 | n/a | ' exception caused the suite to be exited, its type, value, ' |

2283 | n/a | 'and\n' |

2284 | n/a | ' traceback are passed as arguments to "__exit__()". Otherwise, ' |

2285 | n/a | 'three\n' |

2286 | n/a | ' "None" arguments are supplied.\n' |

2287 | n/a | '\n' |

2288 | n/a | ' If the suite was exited due to an exception, and the return ' |

2289 | n/a | 'value\n' |

2290 | n/a | ' from the "__exit__()" method was false, the exception is ' |

2291 | n/a | 'reraised.\n' |

2292 | n/a | ' If the return value was true, the exception is suppressed, ' |

2293 | n/a | 'and\n' |

2294 | n/a | ' execution continues with the statement following the "with"\n' |

2295 | n/a | ' statement.\n' |

2296 | n/a | '\n' |

2297 | n/a | ' If the suite was exited for any reason other than an ' |

2298 | n/a | 'exception, the\n' |

2299 | n/a | ' return value from "__exit__()" is ignored, and execution ' |

2300 | n/a | 'proceeds\n' |

2301 | n/a | ' at the normal location for the kind of exit that was taken.\n' |

2302 | n/a | '\n' |

2303 | n/a | 'With more than one item, the context managers are processed as ' |

2304 | n/a | 'if\n' |

2305 | n/a | 'multiple "with" statements were nested:\n' |

2306 | n/a | '\n' |

2307 | n/a | ' with A() as a, B() as b:\n' |

2308 | n/a | ' suite\n' |

2309 | n/a | '\n' |

2310 | n/a | 'is equivalent to\n' |

2311 | n/a | '\n' |

2312 | n/a | ' with A() as a:\n' |

2313 | n/a | ' with B() as b:\n' |

2314 | n/a | ' suite\n' |

2315 | n/a | '\n' |

2316 | n/a | 'Changed in version 3.1: Support for multiple context ' |

2317 | n/a | 'expressions.\n' |

2318 | n/a | '\n' |

2319 | n/a | 'See also:\n' |

2320 | n/a | '\n' |

2321 | n/a | ' **PEP 343** - The "with" statement\n' |

2322 | n/a | ' The specification, background, and examples for the Python ' |

2323 | n/a | '"with"\n' |

2324 | n/a | ' statement.\n' |

2325 | n/a | '\n' |

2326 | n/a | '\n' |

2327 | n/a | 'Function definitions\n' |

2328 | n/a | '====================\n' |

2329 | n/a | '\n' |

2330 | n/a | 'A function definition defines a user-defined function object ' |

2331 | n/a | '(see\n' |

2332 | n/a | 'section The standard type hierarchy):\n' |

2333 | n/a | '\n' |

2334 | n/a | ' funcdef ::= [decorators] "def" funcname "(" ' |

2335 | n/a | '[parameter_list] ")" ["->" expression] ":" suite\n' |

2336 | n/a | ' decorators ::= decorator+\n' |

2337 | n/a | ' decorator ::= "@" dotted_name ["(" ' |

2338 | n/a | '[argument_list [","]] ")"] NEWLINE\n' |

2339 | n/a | ' dotted_name ::= identifier ("." identifier)*\n' |

2340 | n/a | ' parameter_list ::= defparameter ("," defparameter)* ' |

2341 | n/a | '["," [parameter_list_starargs]]\n' |

2342 | n/a | ' | parameter_list_starargs\n' |

2343 | n/a | ' parameter_list_starargs ::= "*" [parameter] ("," ' |

2344 | n/a | 'defparameter)* ["," ["**" parameter [","]]]\n' |

2345 | n/a | ' | "**" parameter [","]\n' |

2346 | n/a | ' parameter ::= identifier [":" expression]\n' |

2347 | n/a | ' defparameter ::= parameter ["=" expression]\n' |

2348 | n/a | ' funcname ::= identifier\n' |

2349 | n/a | '\n' |

2350 | n/a | 'A function definition is an executable statement. Its execution ' |

2351 | n/a | 'binds\n' |

2352 | n/a | 'the function name in the current local namespace to a function ' |

2353 | n/a | 'object\n' |

2354 | n/a | '(a wrapper around the executable code for the function). This\n' |

2355 | n/a | 'function object contains a reference to the current global ' |

2356 | n/a | 'namespace\n' |

2357 | n/a | 'as the global namespace to be used when the function is called.\n' |

2358 | n/a | '\n' |

2359 | n/a | 'The function definition does not execute the function body; this ' |

2360 | n/a | 'gets\n' |

2361 | n/a | 'executed only when the function is called. [3]\n' |

2362 | n/a | '\n' |

2363 | n/a | 'A function definition may be wrapped by one or more *decorator*\n' |

2364 | n/a | 'expressions. Decorator expressions are evaluated when the ' |

2365 | n/a | 'function is\n' |

2366 | n/a | 'defined, in the scope that contains the function definition. ' |

2367 | n/a | 'The\n' |

2368 | n/a | 'result must be a callable, which is invoked with the function ' |

2369 | n/a | 'object\n' |

2370 | n/a | 'as the only argument. The returned value is bound to the ' |

2371 | n/a | 'function name\n' |

2372 | n/a | 'instead of the function object. Multiple decorators are applied ' |

2373 | n/a | 'in\n' |

2374 | n/a | 'nested fashion. For example, the following code\n' |

2375 | n/a | '\n' |

2376 | n/a | ' @f1(arg)\n' |

2377 | n/a | ' @f2\n' |

2378 | n/a | ' def func(): pass\n' |

2379 | n/a | '\n' |

2380 | n/a | 'is roughly equivalent to\n' |

2381 | n/a | '\n' |

2382 | n/a | ' def func(): pass\n' |

2383 | n/a | ' func = f1(arg)(f2(func))\n' |

2384 | n/a | '\n' |

2385 | n/a | 'except that the original function is not temporarily bound to ' |

2386 | n/a | 'the name\n' |

2387 | n/a | '"func".\n' |

2388 | n/a | '\n' |

2389 | n/a | 'When one or more *parameters* have the form *parameter* "="\n' |

2390 | n/a | '*expression*, the function is said to have "default parameter ' |

2391 | n/a | 'values."\n' |

2392 | n/a | 'For a parameter with a default value, the corresponding ' |

2393 | n/a | '*argument* may\n' |

2394 | n/a | "be omitted from a call, in which case the parameter's default " |

2395 | n/a | 'value is\n' |

2396 | n/a | 'substituted. If a parameter has a default value, all following\n' |

2397 | n/a | 'parameters up until the ""*"" must also have a default value --- ' |

2398 | n/a | 'this\n' |

2399 | n/a | 'is a syntactic restriction that is not expressed by the ' |

2400 | n/a | 'grammar.\n' |

2401 | n/a | '\n' |

2402 | n/a | '**Default parameter values are evaluated from left to right when ' |

2403 | n/a | 'the\n' |

2404 | n/a | 'function definition is executed.** This means that the ' |

2405 | n/a | 'expression is\n' |

2406 | n/a | 'evaluated once, when the function is defined, and that the same ' |

2407 | n/a | '"pre-\n' |

2408 | n/a | 'computed" value is used for each call. This is especially ' |

2409 | n/a | 'important\n' |

2410 | n/a | 'to understand when a default parameter is a mutable object, such ' |

2411 | n/a | 'as a\n' |

2412 | n/a | 'list or a dictionary: if the function modifies the object (e.g. ' |

2413 | n/a | 'by\n' |

2414 | n/a | 'appending an item to a list), the default value is in effect ' |

2415 | n/a | 'modified.\n' |

2416 | n/a | 'This is generally not what was intended. A way around this is ' |

2417 | n/a | 'to use\n' |

2418 | n/a | '"None" as the default, and explicitly test for it in the body of ' |

2419 | n/a | 'the\n' |

2420 | n/a | 'function, e.g.:\n' |

2421 | n/a | '\n' |

2422 | n/a | ' def whats_on_the_telly(penguin=None):\n' |

2423 | n/a | ' if penguin is None:\n' |

2424 | n/a | ' penguin = []\n' |

2425 | n/a | ' penguin.append("property of the zoo")\n' |

2426 | n/a | ' return penguin\n' |

2427 | n/a | '\n' |

2428 | n/a | 'Function call semantics are described in more detail in section ' |

2429 | n/a | 'Calls.\n' |

2430 | n/a | 'A function call always assigns values to all parameters ' |

2431 | n/a | 'mentioned in\n' |

2432 | n/a | 'the parameter list, either from position arguments, from ' |

2433 | n/a | 'keyword\n' |

2434 | n/a | 'arguments, or from default values. If the form ""*identifier"" ' |

2435 | n/a | 'is\n' |

2436 | n/a | 'present, it is initialized to a tuple receiving any excess ' |

2437 | n/a | 'positional\n' |

2438 | n/a | 'parameters, defaulting to the empty tuple. If the form\n' |

2439 | n/a | '""**identifier"" is present, it is initialized to a new ordered\n' |

2440 | n/a | 'mapping receiving any excess keyword arguments, defaulting to a ' |

2441 | n/a | 'new\n' |

2442 | n/a | 'empty mapping of the same type. Parameters after ""*"" or\n' |

2443 | n/a | '""*identifier"" are keyword-only parameters and may only be ' |

2444 | n/a | 'passed\n' |

2445 | n/a | 'used keyword arguments.\n' |

2446 | n/a | '\n' |

2447 | n/a | 'Parameters may have annotations of the form "": expression"" ' |

2448 | n/a | 'following\n' |

2449 | n/a | 'the parameter name. Any parameter may have an annotation even ' |

2450 | n/a | 'those\n' |

2451 | n/a | 'of the form "*identifier" or "**identifier". Functions may ' |

2452 | n/a | 'have\n' |

2453 | n/a | '"return" annotation of the form ""-> expression"" after the ' |

2454 | n/a | 'parameter\n' |

2455 | n/a | 'list. These annotations can be any valid Python expression and ' |

2456 | n/a | 'are\n' |

2457 | n/a | 'evaluated when the function definition is executed. Annotations ' |

2458 | n/a | 'may\n' |

2459 | n/a | 'be evaluated in a different order than they appear in the source ' |

2460 | n/a | 'code.\n' |

2461 | n/a | 'The presence of annotations does not change the semantics of a\n' |

2462 | n/a | 'function. The annotation values are available as values of a\n' |

2463 | n/a | "dictionary keyed by the parameters' names in the " |

2464 | n/a | '"__annotations__"\n' |

2465 | n/a | 'attribute of the function object.\n' |

2466 | n/a | '\n' |

2467 | n/a | 'It is also possible to create anonymous functions (functions not ' |

2468 | n/a | 'bound\n' |

2469 | n/a | 'to a name), for immediate use in expressions. This uses lambda\n' |

2470 | n/a | 'expressions, described in section Lambdas. Note that the ' |

2471 | n/a | 'lambda\n' |

2472 | n/a | 'expression is merely a shorthand for a simplified function ' |

2473 | n/a | 'definition;\n' |

2474 | n/a | 'a function defined in a ""def"" statement can be passed around ' |

2475 | n/a | 'or\n' |

2476 | n/a | 'assigned to another name just like a function defined by a ' |

2477 | n/a | 'lambda\n' |

2478 | n/a | 'expression. The ""def"" form is actually more powerful since ' |

2479 | n/a | 'it\n' |

2480 | n/a | 'allows the execution of multiple statements and annotations.\n' |

2481 | n/a | '\n' |

2482 | n/a | "**Programmer's note:** Functions are first-class objects. A " |

2483 | n/a | '""def""\n' |

2484 | n/a | 'statement executed inside a function definition defines a local\n' |

2485 | n/a | 'function that can be returned or passed around. Free variables ' |

2486 | n/a | 'used\n' |

2487 | n/a | 'in the nested function can access the local variables of the ' |

2488 | n/a | 'function\n' |

2489 | n/a | 'containing the def. See section Naming and binding for ' |

2490 | n/a | 'details.\n' |

2491 | n/a | '\n' |

2492 | n/a | 'See also:\n' |

2493 | n/a | '\n' |

2494 | n/a | ' **PEP 3107** - Function Annotations\n' |

2495 | n/a | ' The original specification for function annotations.\n' |

2496 | n/a | '\n' |

2497 | n/a | '\n' |

2498 | n/a | 'Class definitions\n' |

2499 | n/a | '=================\n' |

2500 | n/a | '\n' |

2501 | n/a | 'A class definition defines a class object (see section The ' |

2502 | n/a | 'standard\n' |

2503 | n/a | 'type hierarchy):\n' |

2504 | n/a | '\n' |

2505 | n/a | ' classdef ::= [decorators] "class" classname [inheritance] ' |

2506 | n/a | '":" suite\n' |

2507 | n/a | ' inheritance ::= "(" [argument_list] ")"\n' |

2508 | n/a | ' classname ::= identifier\n' |

2509 | n/a | '\n' |

2510 | n/a | 'A class definition is an executable statement. The inheritance ' |

2511 | n/a | 'list\n' |

2512 | n/a | 'usually gives a list of base classes (see Metaclasses for more\n' |

2513 | n/a | 'advanced uses), so each item in the list should evaluate to a ' |

2514 | n/a | 'class\n' |

2515 | n/a | 'object which allows subclassing. Classes without an inheritance ' |

2516 | n/a | 'list\n' |

2517 | n/a | 'inherit, by default, from the base class "object"; hence,\n' |

2518 | n/a | '\n' |

2519 | n/a | ' class Foo:\n' |

2520 | n/a | ' pass\n' |

2521 | n/a | '\n' |

2522 | n/a | 'is equivalent to\n' |

2523 | n/a | '\n' |

2524 | n/a | ' class Foo(object):\n' |

2525 | n/a | ' pass\n' |

2526 | n/a | '\n' |

2527 | n/a | "The class's suite is then executed in a new execution frame " |

2528 | n/a | '(see\n' |

2529 | n/a | 'Naming and binding), using a newly created local namespace and ' |

2530 | n/a | 'the\n' |

2531 | n/a | 'original global namespace. (Usually, the suite contains mostly\n' |

2532 | n/a | "function definitions.) When the class's suite finishes " |

2533 | n/a | 'execution, its\n' |

2534 | n/a | 'execution frame is discarded but its local namespace is saved. ' |

2535 | n/a | '[4] A\n' |

2536 | n/a | 'class object is then created using the inheritance list for the ' |

2537 | n/a | 'base\n' |

2538 | n/a | 'classes and the saved local namespace for the attribute ' |

2539 | n/a | 'dictionary.\n' |

2540 | n/a | 'The class name is bound to this class object in the original ' |

2541 | n/a | 'local\n' |

2542 | n/a | 'namespace.\n' |

2543 | n/a | '\n' |

2544 | n/a | 'The order in which attributes are defined in the class body is\n' |

2545 | n/a | 'preserved in the new class\'s "__dict__". Note that this is ' |

2546 | n/a | 'reliable\n' |

2547 | n/a | 'only right after the class is created and only for classes that ' |

2548 | n/a | 'were\n' |

2549 | n/a | 'defined using the definition syntax.\n' |

2550 | n/a | '\n' |

2551 | n/a | 'Class creation can be customized heavily using metaclasses.\n' |

2552 | n/a | '\n' |

2553 | n/a | 'Classes can also be decorated: just like when decorating ' |

2554 | n/a | 'functions,\n' |

2555 | n/a | '\n' |

2556 | n/a | ' @f1(arg)\n' |

2557 | n/a | ' @f2\n' |

2558 | n/a | ' class Foo: pass\n' |

2559 | n/a | '\n' |

2560 | n/a | 'is roughly equivalent to\n' |

2561 | n/a | '\n' |

2562 | n/a | ' class Foo: pass\n' |

2563 | n/a | ' Foo = f1(arg)(f2(Foo))\n' |

2564 | n/a | '\n' |

2565 | n/a | 'The evaluation rules for the decorator expressions are the same ' |

2566 | n/a | 'as for\n' |

2567 | n/a | 'function decorators. The result is then bound to the class ' |

2568 | n/a | 'name.\n' |

2569 | n/a | '\n' |

2570 | n/a | "**Programmer's note:** Variables defined in the class definition " |

2571 | n/a | 'are\n' |

2572 | n/a | 'class attributes; they are shared by instances. Instance ' |

2573 | n/a | 'attributes\n' |

2574 | n/a | 'can be set in a method with "self.name = value". Both class ' |

2575 | n/a | 'and\n' |

2576 | n/a | 'instance attributes are accessible through the notation ' |

2577 | n/a | '""self.name"",\n' |

2578 | n/a | 'and an instance attribute hides a class attribute with the same ' |

2579 | n/a | 'name\n' |

2580 | n/a | 'when accessed in this way. Class attributes can be used as ' |

2581 | n/a | 'defaults\n' |

2582 | n/a | 'for instance attributes, but using mutable values there can lead ' |

2583 | n/a | 'to\n' |

2584 | n/a | 'unexpected results. Descriptors can be used to create instance\n' |

2585 | n/a | 'variables with different implementation details.\n' |

2586 | n/a | '\n' |

2587 | n/a | 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n' |

2588 | n/a | ' Class Decorators\n' |

2589 | n/a | '\n' |

2590 | n/a | '\n' |

2591 | n/a | 'Coroutines\n' |

2592 | n/a | '==========\n' |

2593 | n/a | '\n' |

2594 | n/a | 'New in version 3.5.\n' |

2595 | n/a | '\n' |

2596 | n/a | '\n' |

2597 | n/a | 'Coroutine function definition\n' |

2598 | n/a | '-----------------------------\n' |

2599 | n/a | '\n' |

2600 | n/a | ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' |

2601 | n/a | '[parameter_list] ")" ["->" expression] ":" suite\n' |

2602 | n/a | '\n' |

2603 | n/a | 'Execution of Python coroutines can be suspended and resumed at ' |

2604 | n/a | 'many\n' |

2605 | n/a | 'points (see *coroutine*). In the body of a coroutine, any ' |

2606 | n/a | '"await" and\n' |

2607 | n/a | '"async" identifiers become reserved keywords; "await" ' |

2608 | n/a | 'expressions,\n' |

2609 | n/a | '"async for" and "async with" can only be used in coroutine ' |

2610 | n/a | 'bodies.\n' |

2611 | n/a | '\n' |

2612 | n/a | 'Functions defined with "async def" syntax are always coroutine\n' |

2613 | n/a | 'functions, even if they do not contain "await" or "async" ' |

2614 | n/a | 'keywords.\n' |

2615 | n/a | '\n' |

2616 | n/a | 'It is a "SyntaxError" to use "yield" expressions in "async def"\n' |

2617 | n/a | 'coroutines.\n' |

2618 | n/a | '\n' |

2619 | n/a | 'An example of a coroutine function:\n' |

2620 | n/a | '\n' |

2621 | n/a | ' async def func(param1, param2):\n' |

2622 | n/a | ' do_stuff()\n' |

2623 | n/a | ' await some_coroutine()\n' |

2624 | n/a | '\n' |

2625 | n/a | '\n' |

2626 | n/a | 'The "async for" statement\n' |

2627 | n/a | '-------------------------\n' |

2628 | n/a | '\n' |

2629 | n/a | ' async_for_stmt ::= "async" for_stmt\n' |

2630 | n/a | '\n' |

2631 | n/a | 'An *asynchronous iterable* is able to call asynchronous code in ' |

2632 | n/a | 'its\n' |

2633 | n/a | '*iter* implementation, and *asynchronous iterator* can call\n' |

2634 | n/a | 'asynchronous code in its *next* method.\n' |

2635 | n/a | '\n' |

2636 | n/a | 'The "async for" statement allows convenient iteration over\n' |

2637 | n/a | 'asynchronous iterators.\n' |

2638 | n/a | '\n' |

2639 | n/a | 'The following code:\n' |

2640 | n/a | '\n' |

2641 | n/a | ' async for TARGET in ITER:\n' |

2642 | n/a | ' BLOCK\n' |

2643 | n/a | ' else:\n' |

2644 | n/a | ' BLOCK2\n' |

2645 | n/a | '\n' |

2646 | n/a | 'Is semantically equivalent to:\n' |

2647 | n/a | '\n' |

2648 | n/a | ' iter = (ITER)\n' |

2649 | n/a | ' iter = type(iter).__aiter__(iter)\n' |

2650 | n/a | ' running = True\n' |

2651 | n/a | ' while running:\n' |

2652 | n/a | ' try:\n' |

2653 | n/a | ' TARGET = await type(iter).__anext__(iter)\n' |

2654 | n/a | ' except StopAsyncIteration:\n' |

2655 | n/a | ' running = False\n' |

2656 | n/a | ' else:\n' |

2657 | n/a | ' BLOCK\n' |

2658 | n/a | ' else:\n' |

2659 | n/a | ' BLOCK2\n' |

2660 | n/a | '\n' |

2661 | n/a | 'See also "__aiter__()" and "__anext__()" for details.\n' |

2662 | n/a | '\n' |

2663 | n/a | 'It is a "SyntaxError" to use "async for" statement outside of ' |

2664 | n/a | 'an\n' |

2665 | n/a | '"async def" function.\n' |

2666 | n/a | '\n' |

2667 | n/a | '\n' |

2668 | n/a | 'The "async with" statement\n' |

2669 | n/a | '--------------------------\n' |

2670 | n/a | '\n' |

2671 | n/a | ' async_with_stmt ::= "async" with_stmt\n' |

2672 | n/a | '\n' |

2673 | n/a | 'An *asynchronous context manager* is a *context manager* that is ' |

2674 | n/a | 'able\n' |

2675 | n/a | 'to suspend execution in its *enter* and *exit* methods.\n' |

2676 | n/a | '\n' |

2677 | n/a | 'The following code:\n' |

2678 | n/a | '\n' |

2679 | n/a | ' async with EXPR as VAR:\n' |

2680 | n/a | ' BLOCK\n' |

2681 | n/a | '\n' |

2682 | n/a | 'Is semantically equivalent to:\n' |

2683 | n/a | '\n' |

2684 | n/a | ' mgr = (EXPR)\n' |

2685 | n/a | ' aexit = type(mgr).__aexit__\n' |

2686 | n/a | ' aenter = type(mgr).__aenter__(mgr)\n' |

2687 | n/a | ' exc = True\n' |

2688 | n/a | '\n' |

2689 | n/a | ' VAR = await aenter\n' |

2690 | n/a | ' try:\n' |

2691 | n/a | ' BLOCK\n' |

2692 | n/a | ' except:\n' |

2693 | n/a | ' if not await aexit(mgr, *sys.exc_info()):\n' |

2694 | n/a | ' raise\n' |

2695 | n/a | ' else:\n' |

2696 | n/a | ' await aexit(mgr, None, None, None)\n' |

2697 | n/a | '\n' |

2698 | n/a | 'See also "__aenter__()" and "__aexit__()" for details.\n' |

2699 | n/a | '\n' |

2700 | n/a | 'It is a "SyntaxError" to use "async with" statement outside of ' |

2701 | n/a | 'an\n' |

2702 | n/a | '"async def" function.\n' |

2703 | n/a | '\n' |

2704 | n/a | 'See also: **PEP 492** - Coroutines with async and await syntax\n' |

2705 | n/a | '\n' |

2706 | n/a | '-[ Footnotes ]-\n' |

2707 | n/a | '\n' |

2708 | n/a | '[1] The exception is propagated to the invocation stack unless\n' |

2709 | n/a | ' there is a "finally" clause which happens to raise another\n' |

2710 | n/a | ' exception. That new exception causes the old one to be ' |

2711 | n/a | 'lost.\n' |

2712 | n/a | '\n' |

2713 | n/a | '[2] Currently, control "flows off the end" except in the case ' |

2714 | n/a | 'of\n' |

2715 | n/a | ' an exception or the execution of a "return", "continue", or\n' |

2716 | n/a | ' "break" statement.\n' |

2717 | n/a | '\n' |

2718 | n/a | '[3] A string literal appearing as the first statement in the\n' |

2719 | n/a | ' function body is transformed into the function\'s "__doc__"\n' |

2720 | n/a | " attribute and therefore the function's *docstring*.\n" |

2721 | n/a | '\n' |

2722 | n/a | '[4] A string literal appearing as the first statement in the ' |

2723 | n/a | 'class\n' |

2724 | n/a | ' body is transformed into the namespace\'s "__doc__" item ' |

2725 | n/a | 'and\n' |

2726 | n/a | " therefore the class's *docstring*.\n", |

2727 | n/a | 'context-managers': '\n' |

2728 | n/a | 'With Statement Context Managers\n' |

2729 | n/a | '*******************************\n' |

2730 | n/a | '\n' |

2731 | n/a | 'A *context manager* is an object that defines the ' |

2732 | n/a | 'runtime context to\n' |

2733 | n/a | 'be established when executing a "with" statement. The ' |

2734 | n/a | 'context manager\n' |

2735 | n/a | 'handles the entry into, and the exit from, the desired ' |

2736 | n/a | 'runtime context\n' |

2737 | n/a | 'for the execution of the block of code. Context ' |

2738 | n/a | 'managers are normally\n' |

2739 | n/a | 'invoked using the "with" statement (described in section ' |

2740 | n/a | 'The with\n' |

2741 | n/a | 'statement), but can also be used by directly invoking ' |

2742 | n/a | 'their methods.\n' |

2743 | n/a | '\n' |

2744 | n/a | 'Typical uses of context managers include saving and ' |

2745 | n/a | 'restoring various\n' |

2746 | n/a | 'kinds of global state, locking and unlocking resources, ' |

2747 | n/a | 'closing opened\n' |

2748 | n/a | 'files, etc.\n' |

2749 | n/a | '\n' |

2750 | n/a | 'For more information on context managers, see Context ' |

2751 | n/a | 'Manager Types.\n' |

2752 | n/a | '\n' |

2753 | n/a | 'object.__enter__(self)\n' |

2754 | n/a | '\n' |

2755 | n/a | ' Enter the runtime context related to this object. The ' |

2756 | n/a | '"with"\n' |

2757 | n/a | " statement will bind this method's return value to the " |

2758 | n/a | 'target(s)\n' |

2759 | n/a | ' specified in the "as" clause of the statement, if ' |

2760 | n/a | 'any.\n' |

2761 | n/a | '\n' |

2762 | n/a | 'object.__exit__(self, exc_type, exc_value, traceback)\n' |

2763 | n/a | '\n' |

2764 | n/a | ' Exit the runtime context related to this object. The ' |

2765 | n/a | 'parameters\n' |

2766 | n/a | ' describe the exception that caused the context to be ' |

2767 | n/a | 'exited. If the\n' |

2768 | n/a | ' context was exited without an exception, all three ' |

2769 | n/a | 'arguments will\n' |

2770 | n/a | ' be "None".\n' |

2771 | n/a | '\n' |

2772 | n/a | ' If an exception is supplied, and the method wishes to ' |

2773 | n/a | 'suppress the\n' |

2774 | n/a | ' exception (i.e., prevent it from being propagated), ' |

2775 | n/a | 'it should\n' |

2776 | n/a | ' return a true value. Otherwise, the exception will be ' |

2777 | n/a | 'processed\n' |

2778 | n/a | ' normally upon exit from this method.\n' |

2779 | n/a | '\n' |

2780 | n/a | ' Note that "__exit__()" methods should not reraise the ' |

2781 | n/a | 'passed-in\n' |

2782 | n/a | " exception; this is the caller's responsibility.\n" |

2783 | n/a | '\n' |

2784 | n/a | 'See also:\n' |

2785 | n/a | '\n' |

2786 | n/a | ' **PEP 343** - The "with" statement\n' |

2787 | n/a | ' The specification, background, and examples for the ' |

2788 | n/a | 'Python "with"\n' |

2789 | n/a | ' statement.\n', |

2790 | n/a | 'continue': '\n' |

2791 | n/a | 'The "continue" statement\n' |

2792 | n/a | '************************\n' |

2793 | n/a | '\n' |

2794 | n/a | ' continue_stmt ::= "continue"\n' |

2795 | n/a | '\n' |

2796 | n/a | '"continue" may only occur syntactically nested in a "for" or ' |

2797 | n/a | '"while"\n' |

2798 | n/a | 'loop, but not nested in a function or class definition or ' |

2799 | n/a | '"finally"\n' |

2800 | n/a | 'clause within that loop. It continues with the next cycle of ' |

2801 | n/a | 'the\n' |

2802 | n/a | 'nearest enclosing loop.\n' |

2803 | n/a | '\n' |

2804 | n/a | 'When "continue" passes control out of a "try" statement with a\n' |

2805 | n/a | '"finally" clause, that "finally" clause is executed before ' |

2806 | n/a | 'really\n' |

2807 | n/a | 'starting the next loop cycle.\n', |

2808 | n/a | 'conversions': '\n' |

2809 | n/a | 'Arithmetic conversions\n' |

2810 | n/a | '**********************\n' |

2811 | n/a | '\n' |

2812 | n/a | 'When a description of an arithmetic operator below uses the ' |

2813 | n/a | 'phrase\n' |

2814 | n/a | '"the numeric arguments are converted to a common type," this ' |

2815 | n/a | 'means\n' |

2816 | n/a | 'that the operator implementation for built-in types works as ' |

2817 | n/a | 'follows:\n' |

2818 | n/a | '\n' |

2819 | n/a | '* If either argument is a complex number, the other is ' |

2820 | n/a | 'converted to\n' |

2821 | n/a | ' complex;\n' |

2822 | n/a | '\n' |

2823 | n/a | '* otherwise, if either argument is a floating point number, ' |

2824 | n/a | 'the\n' |

2825 | n/a | ' other is converted to floating point;\n' |

2826 | n/a | '\n' |

2827 | n/a | '* otherwise, both must be integers and no conversion is ' |

2828 | n/a | 'necessary.\n' |

2829 | n/a | '\n' |

2830 | n/a | 'Some additional rules apply for certain operators (e.g., a ' |

2831 | n/a | 'string as a\n' |

2832 | n/a | "left argument to the '%' operator). Extensions must define " |

2833 | n/a | 'their own\n' |

2834 | n/a | 'conversion behavior.\n', |

2835 | n/a | 'customization': '\n' |

2836 | n/a | 'Basic customization\n' |

2837 | n/a | '*******************\n' |

2838 | n/a | '\n' |

2839 | n/a | 'object.__new__(cls[, ...])\n' |

2840 | n/a | '\n' |

2841 | n/a | ' Called to create a new instance of class *cls*. ' |

2842 | n/a | '"__new__()" is a\n' |

2843 | n/a | ' static method (special-cased so you need not declare it ' |

2844 | n/a | 'as such)\n' |

2845 | n/a | ' that takes the class of which an instance was requested ' |

2846 | n/a | 'as its\n' |

2847 | n/a | ' first argument. The remaining arguments are those ' |

2848 | n/a | 'passed to the\n' |

2849 | n/a | ' object constructor expression (the call to the class). ' |

2850 | n/a | 'The return\n' |

2851 | n/a | ' value of "__new__()" should be the new object instance ' |

2852 | n/a | '(usually an\n' |

2853 | n/a | ' instance of *cls*).\n' |

2854 | n/a | '\n' |

2855 | n/a | ' Typical implementations create a new instance of the ' |

2856 | n/a | 'class by\n' |

2857 | n/a | ' invoking the superclass\'s "__new__()" method using\n' |

2858 | n/a | ' "super(currentclass, cls).__new__(cls[, ...])" with ' |

2859 | n/a | 'appropriate\n' |

2860 | n/a | ' arguments and then modifying the newly-created instance ' |

2861 | n/a | 'as\n' |

2862 | n/a | ' necessary before returning it.\n' |

2863 | n/a | '\n' |

2864 | n/a | ' If "__new__()" returns an instance of *cls*, then the ' |

2865 | n/a | 'new\n' |

2866 | n/a | ' instance\'s "__init__()" method will be invoked like\n' |

2867 | n/a | ' "__init__(self[, ...])", where *self* is the new ' |

2868 | n/a | 'instance and the\n' |

2869 | n/a | ' remaining arguments are the same as were passed to ' |

2870 | n/a | '"__new__()".\n' |

2871 | n/a | '\n' |

2872 | n/a | ' If "__new__()" does not return an instance of *cls*, ' |

2873 | n/a | 'then the new\n' |

2874 | n/a | ' instance\'s "__init__()" method will not be invoked.\n' |

2875 | n/a | '\n' |

2876 | n/a | ' "__new__()" is intended mainly to allow subclasses of ' |

2877 | n/a | 'immutable\n' |

2878 | n/a | ' types (like int, str, or tuple) to customize instance ' |

2879 | n/a | 'creation. It\n' |

2880 | n/a | ' is also commonly overridden in custom metaclasses in ' |

2881 | n/a | 'order to\n' |

2882 | n/a | ' customize class creation.\n' |

2883 | n/a | '\n' |

2884 | n/a | 'object.__init__(self[, ...])\n' |

2885 | n/a | '\n' |

2886 | n/a | ' Called after the instance has been created (by ' |

2887 | n/a | '"__new__()"), but\n' |

2888 | n/a | ' before it is returned to the caller. The arguments are ' |

2889 | n/a | 'those\n' |

2890 | n/a | ' passed to the class constructor expression. If a base ' |

2891 | n/a | 'class has an\n' |

2892 | n/a | ' "__init__()" method, the derived class\'s "__init__()" ' |

2893 | n/a | 'method, if\n' |

2894 | n/a | ' any, must explicitly call it to ensure proper ' |

2895 | n/a | 'initialization of the\n' |

2896 | n/a | ' base class part of the instance; for example:\n' |

2897 | n/a | ' "BaseClass.__init__(self, [args...])".\n' |

2898 | n/a | '\n' |

2899 | n/a | ' Because "__new__()" and "__init__()" work together in ' |

2900 | n/a | 'constructing\n' |

2901 | n/a | ' objects ("__new__()" to create it, and "__init__()" to ' |

2902 | n/a | 'customize\n' |

2903 | n/a | ' it), no non-"None" value may be returned by ' |

2904 | n/a | '"__init__()"; doing so\n' |

2905 | n/a | ' will cause a "TypeError" to be raised at runtime.\n' |

2906 | n/a | '\n' |

2907 | n/a | 'object.__del__(self)\n' |

2908 | n/a | '\n' |

2909 | n/a | ' Called when the instance is about to be destroyed. This ' |

2910 | n/a | 'is also\n' |

2911 | n/a | ' called a destructor. If a base class has a "__del__()" ' |

2912 | n/a | 'method, the\n' |

2913 | n/a | ' derived class\'s "__del__()" method, if any, must ' |

2914 | n/a | 'explicitly call it\n' |

2915 | n/a | ' to ensure proper deletion of the base class part of the ' |

2916 | n/a | 'instance.\n' |

2917 | n/a | ' Note that it is possible (though not recommended!) for ' |

2918 | n/a | 'the\n' |

2919 | n/a | ' "__del__()" method to postpone destruction of the ' |

2920 | n/a | 'instance by\n' |

2921 | n/a | ' creating a new reference to it. It may then be called ' |

2922 | n/a | 'at a later\n' |

2923 | n/a | ' time when this new reference is deleted. It is not ' |

2924 | n/a | 'guaranteed that\n' |

2925 | n/a | ' "__del__()" methods are called for objects that still ' |

2926 | n/a | 'exist when\n' |

2927 | n/a | ' the interpreter exits.\n' |

2928 | n/a | '\n' |

2929 | n/a | ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' |

2930 | n/a | 'the former\n' |

2931 | n/a | ' decrements the reference count for "x" by one, and the ' |

2932 | n/a | 'latter is\n' |

2933 | n/a | ' only called when "x"\'s reference count reaches zero. ' |

2934 | n/a | 'Some common\n' |

2935 | n/a | ' situations that may prevent the reference count of an ' |

2936 | n/a | 'object from\n' |

2937 | n/a | ' going to zero include: circular references between ' |

2938 | n/a | 'objects (e.g.,\n' |

2939 | n/a | ' a doubly-linked list or a tree data structure with ' |

2940 | n/a | 'parent and\n' |

2941 | n/a | ' child pointers); a reference to the object on the ' |

2942 | n/a | 'stack frame of\n' |

2943 | n/a | ' a function that caught an exception (the traceback ' |

2944 | n/a | 'stored in\n' |

2945 | n/a | ' "sys.exc_info()[2]" keeps the stack frame alive); or a ' |

2946 | n/a | 'reference\n' |

2947 | n/a | ' to the object on the stack frame that raised an ' |

2948 | n/a | 'unhandled\n' |

2949 | n/a | ' exception in interactive mode (the traceback stored ' |

2950 | n/a | 'in\n' |

2951 | n/a | ' "sys.last_traceback" keeps the stack frame alive). ' |

2952 | n/a | 'The first\n' |

2953 | n/a | ' situation can only be remedied by explicitly breaking ' |

2954 | n/a | 'the cycles;\n' |

2955 | n/a | ' the second can be resolved by freeing the reference to ' |

2956 | n/a | 'the\n' |

2957 | n/a | ' traceback object when it is no longer useful, and the ' |

2958 | n/a | 'third can\n' |

2959 | n/a | ' be resolved by storing "None" in "sys.last_traceback". ' |

2960 | n/a | 'Circular\n' |

2961 | n/a | ' references which are garbage are detected and cleaned ' |

2962 | n/a | 'up when the\n' |

2963 | n/a | " cyclic garbage collector is enabled (it's on by " |

2964 | n/a | 'default). Refer\n' |

2965 | n/a | ' to the documentation for the "gc" module for more ' |

2966 | n/a | 'information\n' |

2967 | n/a | ' about this topic.\n' |

2968 | n/a | '\n' |

2969 | n/a | ' Warning: Due to the precarious circumstances under ' |

2970 | n/a | 'which\n' |

2971 | n/a | ' "__del__()" methods are invoked, exceptions that occur ' |

2972 | n/a | 'during\n' |

2973 | n/a | ' their execution are ignored, and a warning is printed ' |

2974 | n/a | 'to\n' |

2975 | n/a | ' "sys.stderr" instead. Also, when "__del__()" is ' |

2976 | n/a | 'invoked in\n' |

2977 | n/a | ' response to a module being deleted (e.g., when ' |

2978 | n/a | 'execution of the\n' |

2979 | n/a | ' program is done), other globals referenced by the ' |

2980 | n/a | '"__del__()"\n' |

2981 | n/a | ' method may already have been deleted or in the process ' |

2982 | n/a | 'of being\n' |

2983 | n/a | ' torn down (e.g. the import machinery shutting down). ' |

2984 | n/a | 'For this\n' |

2985 | n/a | ' reason, "__del__()" methods should do the absolute ' |

2986 | n/a | 'minimum needed\n' |

2987 | n/a | ' to maintain external invariants. Starting with ' |

2988 | n/a | 'version 1.5,\n' |

2989 | n/a | ' Python guarantees that globals whose name begins with ' |

2990 | n/a | 'a single\n' |

2991 | n/a | ' underscore are deleted from their module before other ' |

2992 | n/a | 'globals are\n' |

2993 | n/a | ' deleted; if no other references to such globals exist, ' |

2994 | n/a | 'this may\n' |

2995 | n/a | ' help in assuring that imported modules are still ' |

2996 | n/a | 'available at the\n' |

2997 | n/a | ' time when the "__del__()" method is called.\n' |

2998 | n/a | '\n' |

2999 | n/a | 'object.__repr__(self)\n' |

3000 | n/a | '\n' |

3001 | n/a | ' Called by the "repr()" built-in function to compute the ' |

3002 | n/a | '"official"\n' |

3003 | n/a | ' string representation of an object. If at all possible, ' |

3004 | n/a | 'this\n' |

3005 | n/a | ' should look like a valid Python expression that could be ' |

3006 | n/a | 'used to\n' |

3007 | n/a | ' recreate an object with the same value (given an ' |

3008 | n/a | 'appropriate\n' |

3009 | n/a | ' environment). If this is not possible, a string of the ' |

3010 | n/a | 'form\n' |

3011 | n/a | ' "<...some useful description...>" should be returned. ' |

3012 | n/a | 'The return\n' |

3013 | n/a | ' value must be a string object. If a class defines ' |

3014 | n/a | '"__repr__()" but\n' |

3015 | n/a | ' not "__str__()", then "__repr__()" is also used when an ' |

3016 | n/a | '"informal"\n' |

3017 | n/a | ' string representation of instances of that class is ' |

3018 | n/a | 'required.\n' |

3019 | n/a | '\n' |

3020 | n/a | ' This is typically used for debugging, so it is important ' |

3021 | n/a | 'that the\n' |

3022 | n/a | ' representation is information-rich and unambiguous.\n' |

3023 | n/a | '\n' |

3024 | n/a | 'object.__str__(self)\n' |

3025 | n/a | '\n' |

3026 | n/a | ' Called by "str(object)" and the built-in functions ' |

3027 | n/a | '"format()" and\n' |

3028 | n/a | ' "print()" to compute the "informal" or nicely printable ' |

3029 | n/a | 'string\n' |

3030 | n/a | ' representation of an object. The return value must be a ' |

3031 | n/a | 'string\n' |

3032 | n/a | ' object.\n' |

3033 | n/a | '\n' |

3034 | n/a | ' This method differs from "object.__repr__()" in that ' |

3035 | n/a | 'there is no\n' |

3036 | n/a | ' expectation that "__str__()" return a valid Python ' |

3037 | n/a | 'expression: a\n' |

3038 | n/a | ' more convenient or concise representation can be used.\n' |

3039 | n/a | '\n' |

3040 | n/a | ' The default implementation defined by the built-in type ' |

3041 | n/a | '"object"\n' |

3042 | n/a | ' calls "object.__repr__()".\n' |

3043 | n/a | '\n' |

3044 | n/a | 'object.__bytes__(self)\n' |

3045 | n/a | '\n' |

3046 | n/a | ' Called by "bytes()" to compute a byte-string ' |

3047 | n/a | 'representation of an\n' |

3048 | n/a | ' object. This should return a "bytes" object.\n' |

3049 | n/a | '\n' |

3050 | n/a | 'object.__format__(self, format_spec)\n' |

3051 | n/a | '\n' |

3052 | n/a | ' Called by the "format()" built-in function, and by ' |

3053 | n/a | 'extension,\n' |

3054 | n/a | ' evaluation of formatted string literals and the ' |

3055 | n/a | '"str.format()"\n' |

3056 | n/a | ' method, to produce a "formatted" string representation ' |

3057 | n/a | 'of an\n' |

3058 | n/a | ' object. The "format_spec" argument is a string that ' |

3059 | n/a | 'contains a\n' |

3060 | n/a | ' description of the formatting options desired. The ' |

3061 | n/a | 'interpretation\n' |

3062 | n/a | ' of the "format_spec" argument is up to the type ' |

3063 | n/a | 'implementing\n' |

3064 | n/a | ' "__format__()", however most classes will either ' |

3065 | n/a | 'delegate\n' |

3066 | n/a | ' formatting to one of the built-in types, or use a ' |

3067 | n/a | 'similar\n' |

3068 | n/a | ' formatting option syntax.\n' |

3069 | n/a | '\n' |

3070 | n/a | ' See Format Specification Mini-Language for a description ' |

3071 | n/a | 'of the\n' |

3072 | n/a | ' standard formatting syntax.\n' |

3073 | n/a | '\n' |

3074 | n/a | ' The return value must be a string object.\n' |

3075 | n/a | '\n' |

3076 | n/a | ' Changed in version 3.4: The __format__ method of ' |

3077 | n/a | '"object" itself\n' |

3078 | n/a | ' raises a "TypeError" if passed any non-empty string.\n' |

3079 | n/a | '\n' |

3080 | n/a | 'object.__lt__(self, other)\n' |

3081 | n/a | 'object.__le__(self, other)\n' |

3082 | n/a | 'object.__eq__(self, other)\n' |

3083 | n/a | 'object.__ne__(self, other)\n' |

3084 | n/a | 'object.__gt__(self, other)\n' |

3085 | n/a | 'object.__ge__(self, other)\n' |

3086 | n/a | '\n' |

3087 | n/a | ' These are the so-called "rich comparison" methods. The\n' |

3088 | n/a | ' correspondence between operator symbols and method names ' |

3089 | n/a | 'is as\n' |

3090 | n/a | ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' |

3091 | n/a | '"x.__le__(y)",\n' |

3092 | n/a | ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' |

3093 | n/a | '"x>y" calls\n' |

3094 | n/a | ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' |

3095 | n/a | '\n' |

3096 | n/a | ' A rich comparison method may return the singleton ' |

3097 | n/a | '"NotImplemented"\n' |

3098 | n/a | ' if it does not implement the operation for a given pair ' |

3099 | n/a | 'of\n' |

3100 | n/a | ' arguments. By convention, "False" and "True" are ' |

3101 | n/a | 'returned for a\n' |

3102 | n/a | ' successful comparison. However, these methods can return ' |

3103 | n/a | 'any value,\n' |

3104 | n/a | ' so if the comparison operator is used in a Boolean ' |

3105 | n/a | 'context (e.g.,\n' |

3106 | n/a | ' in the condition of an "if" statement), Python will call ' |

3107 | n/a | '"bool()"\n' |

3108 | n/a | ' on the value to determine if the result is true or ' |

3109 | n/a | 'false.\n' |

3110 | n/a | '\n' |

3111 | n/a | ' By default, "__ne__()" delegates to "__eq__()" and ' |

3112 | n/a | 'inverts the\n' |

3113 | n/a | ' result unless it is "NotImplemented". There are no ' |

3114 | n/a | 'other implied\n' |

3115 | n/a | ' relationships among the comparison operators, for ' |

3116 | n/a | 'example, the\n' |

3117 | n/a | ' truth of "(x<y or x==y)" does not imply "x<=y". To ' |

3118 | n/a | 'automatically\n' |

3119 | n/a | ' generate ordering operations from a single root ' |

3120 | n/a | 'operation, see\n' |

3121 | n/a | ' "functools.total_ordering()".\n' |

3122 | n/a | '\n' |

3123 | n/a | ' See the paragraph on "__hash__()" for some important ' |

3124 | n/a | 'notes on\n' |

3125 | n/a | ' creating *hashable* objects which support custom ' |

3126 | n/a | 'comparison\n' |

3127 | n/a | ' operations and are usable as dictionary keys.\n' |

3128 | n/a | '\n' |

3129 | n/a | ' There are no swapped-argument versions of these methods ' |

3130 | n/a | '(to be used\n' |

3131 | n/a | ' when the left argument does not support the operation ' |

3132 | n/a | 'but the right\n' |

3133 | n/a | ' argument does); rather, "__lt__()" and "__gt__()" are ' |

3134 | n/a | "each other's\n" |

3135 | n/a | ' reflection, "__le__()" and "__ge__()" are each other\'s ' |

3136 | n/a | 'reflection,\n' |

3137 | n/a | ' and "__eq__()" and "__ne__()" are their own reflection. ' |

3138 | n/a | 'If the\n' |

3139 | n/a | " operands are of different types, and right operand's " |

3140 | n/a | 'type is a\n' |

3141 | n/a | " direct or indirect subclass of the left operand's type, " |

3142 | n/a | 'the\n' |

3143 | n/a | ' reflected method of the right operand has priority, ' |

3144 | n/a | 'otherwise the\n' |

3145 | n/a | " left operand's method has priority. Virtual subclassing " |

3146 | n/a | 'is not\n' |

3147 | n/a | ' considered.\n' |

3148 | n/a | '\n' |

3149 | n/a | 'object.__hash__(self)\n' |

3150 | n/a | '\n' |

3151 | n/a | ' Called by built-in function "hash()" and for operations ' |

3152 | n/a | 'on members\n' |

3153 | n/a | ' of hashed collections including "set", "frozenset", and ' |

3154 | n/a | '"dict".\n' |

3155 | n/a | ' "__hash__()" should return an integer. The only ' |

3156 | n/a | 'required property\n' |

3157 | n/a | ' is that objects which compare equal have the same hash ' |

3158 | n/a | 'value; it is\n' |

3159 | n/a | ' advised to somehow mix together (e.g. using exclusive ' |

3160 | n/a | 'or) the hash\n' |

3161 | n/a | ' values for the components of the object that also play a ' |

3162 | n/a | 'part in\n' |

3163 | n/a | ' comparison of objects.\n' |

3164 | n/a | '\n' |

3165 | n/a | ' Note: "hash()" truncates the value returned from an ' |

3166 | n/a | "object's\n" |

3167 | n/a | ' custom "__hash__()" method to the size of a ' |

3168 | n/a | '"Py_ssize_t". This\n' |

3169 | n/a | ' is typically 8 bytes on 64-bit builds and 4 bytes on ' |

3170 | n/a | '32-bit\n' |

3171 | n/a | ' builds. If an object\'s "__hash__()" must ' |

3172 | n/a | 'interoperate on builds\n' |

3173 | n/a | ' of different bit sizes, be sure to check the width on ' |

3174 | n/a | 'all\n' |

3175 | n/a | ' supported builds. An easy way to do this is with ' |

3176 | n/a | '"python -c\n' |

3177 | n/a | ' "import sys; print(sys.hash_info.width)"".\n' |

3178 | n/a | '\n' |

3179 | n/a | ' If a class does not define an "__eq__()" method it ' |

3180 | n/a | 'should not\n' |

3181 | n/a | ' define a "__hash__()" operation either; if it defines ' |

3182 | n/a | '"__eq__()"\n' |

3183 | n/a | ' but not "__hash__()", its instances will not be usable ' |

3184 | n/a | 'as items in\n' |

3185 | n/a | ' hashable collections. If a class defines mutable ' |

3186 | n/a | 'objects and\n' |

3187 | n/a | ' implements an "__eq__()" method, it should not ' |

3188 | n/a | 'implement\n' |

3189 | n/a | ' "__hash__()", since the implementation of hashable ' |

3190 | n/a | 'collections\n' |

3191 | n/a | " requires that a key's hash value is immutable (if the " |

3192 | n/a | "object's hash\n" |

3193 | n/a | ' value changes, it will be in the wrong hash bucket).\n' |

3194 | n/a | '\n' |

3195 | n/a | ' User-defined classes have "__eq__()" and "__hash__()" ' |

3196 | n/a | 'methods by\n' |

3197 | n/a | ' default; with them, all objects compare unequal (except ' |

3198 | n/a | 'with\n' |

3199 | n/a | ' themselves) and "x.__hash__()" returns an appropriate ' |

3200 | n/a | 'value such\n' |

3201 | n/a | ' that "x == y" implies both that "x is y" and "hash(x) == ' |

3202 | n/a | 'hash(y)".\n' |

3203 | n/a | '\n' |

3204 | n/a | ' A class that overrides "__eq__()" and does not define ' |

3205 | n/a | '"__hash__()"\n' |

3206 | n/a | ' will have its "__hash__()" implicitly set to "None". ' |

3207 | n/a | 'When the\n' |

3208 | n/a | ' "__hash__()" method of a class is "None", instances of ' |

3209 | n/a | 'the class\n' |

3210 | n/a | ' will raise an appropriate "TypeError" when a program ' |

3211 | n/a | 'attempts to\n' |

3212 | n/a | ' retrieve their hash value, and will also be correctly ' |

3213 | n/a | 'identified as\n' |

3214 | n/a | ' unhashable when checking "isinstance(obj, ' |

3215 | n/a | 'collections.Hashable)".\n' |

3216 | n/a | '\n' |

3217 | n/a | ' If a class that overrides "__eq__()" needs to retain ' |

3218 | n/a | 'the\n' |

3219 | n/a | ' implementation of "__hash__()" from a parent class, the ' |

3220 | n/a | 'interpreter\n' |

3221 | n/a | ' must be told this explicitly by setting "__hash__ =\n' |

3222 | n/a | ' <ParentClass>.__hash__".\n' |

3223 | n/a | '\n' |

3224 | n/a | ' If a class that does not override "__eq__()" wishes to ' |

3225 | n/a | 'suppress\n' |

3226 | n/a | ' hash support, it should include "__hash__ = None" in the ' |

3227 | n/a | 'class\n' |

3228 | n/a | ' definition. A class which defines its own "__hash__()" ' |

3229 | n/a | 'that\n' |

3230 | n/a | ' explicitly raises a "TypeError" would be incorrectly ' |

3231 | n/a | 'identified as\n' |

3232 | n/a | ' hashable by an "isinstance(obj, collections.Hashable)" ' |

3233 | n/a | 'call.\n' |

3234 | n/a | '\n' |

3235 | n/a | ' Note: By default, the "__hash__()" values of str, bytes ' |

3236 | n/a | 'and\n' |

3237 | n/a | ' datetime objects are "salted" with an unpredictable ' |

3238 | n/a | 'random value.\n' |

3239 | n/a | ' Although they remain constant within an individual ' |

3240 | n/a | 'Python\n' |

3241 | n/a | ' process, they are not predictable between repeated ' |

3242 | n/a | 'invocations of\n' |

3243 | n/a | ' Python.This is intended to provide protection against ' |

3244 | n/a | 'a denial-\n' |

3245 | n/a | ' of-service caused by carefully-chosen inputs that ' |

3246 | n/a | 'exploit the\n' |

3247 | n/a | ' worst case performance of a dict insertion, O(n^2) ' |

3248 | n/a | 'complexity.\n' |

3249 | n/a | ' See ' |

3250 | n/a | 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' |

3251 | n/a | ' details.Changing hash values affects the iteration ' |

3252 | n/a | 'order of\n' |

3253 | n/a | ' dicts, sets and other mappings. Python has never made ' |

3254 | n/a | 'guarantees\n' |

3255 | n/a | ' about this ordering (and it typically varies between ' |

3256 | n/a | '32-bit and\n' |

3257 | n/a | ' 64-bit builds).See also "PYTHONHASHSEED".\n' |

3258 | n/a | '\n' |

3259 | n/a | ' Changed in version 3.3: Hash randomization is enabled by ' |

3260 | n/a | 'default.\n' |

3261 | n/a | '\n' |

3262 | n/a | 'object.__bool__(self)\n' |

3263 | n/a | '\n' |

3264 | n/a | ' Called to implement truth value testing and the built-in ' |

3265 | n/a | 'operation\n' |

3266 | n/a | ' "bool()"; should return "False" or "True". When this ' |

3267 | n/a | 'method is not\n' |

3268 | n/a | ' defined, "__len__()" is called, if it is defined, and ' |

3269 | n/a | 'the object is\n' |

3270 | n/a | ' considered true if its result is nonzero. If a class ' |

3271 | n/a | 'defines\n' |

3272 | n/a | ' neither "__len__()" nor "__bool__()", all its instances ' |

3273 | n/a | 'are\n' |

3274 | n/a | ' considered true.\n', |

3275 | n/a | 'debugger': '\n' |

3276 | n/a | '"pdb" --- The Python Debugger\n' |

3277 | n/a | '*****************************\n' |

3278 | n/a | '\n' |

3279 | n/a | '**Source code:** Lib/pdb.py\n' |

3280 | n/a | '\n' |

3281 | n/a | '======================================================================\n' |

3282 | n/a | '\n' |

3283 | n/a | 'The module "pdb" defines an interactive source code debugger ' |

3284 | n/a | 'for\n' |

3285 | n/a | 'Python programs. It supports setting (conditional) breakpoints ' |

3286 | n/a | 'and\n' |

3287 | n/a | 'single stepping at the source line level, inspection of stack ' |

3288 | n/a | 'frames,\n' |

3289 | n/a | 'source code listing, and evaluation of arbitrary Python code in ' |

3290 | n/a | 'the\n' |

3291 | n/a | 'context of any stack frame. It also supports post-mortem ' |

3292 | n/a | 'debugging\n' |

3293 | n/a | 'and can be called under program control.\n' |

3294 | n/a | '\n' |

3295 | n/a | 'The debugger is extensible -- it is actually defined as the ' |

3296 | n/a | 'class\n' |

3297 | n/a | '"Pdb". This is currently undocumented but easily understood by ' |

3298 | n/a | 'reading\n' |

3299 | n/a | 'the source. The extension interface uses the modules "bdb" and ' |

3300 | n/a | '"cmd".\n' |

3301 | n/a | '\n' |

3302 | n/a | 'The debugger\'s prompt is "(Pdb)". Typical usage to run a ' |

3303 | n/a | 'program under\n' |

3304 | n/a | 'control of the debugger is:\n' |

3305 | n/a | '\n' |

3306 | n/a | ' >>> import pdb\n' |

3307 | n/a | ' >>> import mymodule\n' |

3308 | n/a | " >>> pdb.run('mymodule.test()')\n" |

3309 | n/a | ' > <string>(0)?()\n' |

3310 | n/a | ' (Pdb) continue\n' |

3311 | n/a | ' > <string>(1)?()\n' |

3312 | n/a | ' (Pdb) continue\n' |

3313 | n/a | " NameError: 'spam'\n" |

3314 | n/a | ' > <string>(1)?()\n' |

3315 | n/a | ' (Pdb)\n' |

3316 | n/a | '\n' |

3317 | n/a | 'Changed in version 3.3: Tab-completion via the "readline" module ' |

3318 | n/a | 'is\n' |

3319 | n/a | 'available for commands and command arguments, e.g. the current ' |

3320 | n/a | 'global\n' |

3321 | n/a | 'and local names are offered as arguments of the "p" command.\n' |

3322 | n/a | '\n' |

3323 | n/a | '"pdb.py" can also be invoked as a script to debug other ' |

3324 | n/a | 'scripts. For\n' |

3325 | n/a | 'example:\n' |

3326 | n/a | '\n' |

3327 | n/a | ' python3 -m pdb myscript.py\n' |

3328 | n/a | '\n' |

3329 | n/a | 'When invoked as a script, pdb will automatically enter ' |

3330 | n/a | 'post-mortem\n' |

3331 | n/a | 'debugging if the program being debugged exits abnormally. After ' |

3332 | n/a | 'post-\n' |

3333 | n/a | 'mortem debugging (or after normal exit of the program), pdb ' |

3334 | n/a | 'will\n' |

3335 | n/a | "restart the program. Automatic restarting preserves pdb's state " |

3336 | n/a | '(such\n' |

3337 | n/a | 'as breakpoints) and in most cases is more useful than quitting ' |

3338 | n/a | 'the\n' |

3339 | n/a | "debugger upon program's exit.\n" |

3340 | n/a | '\n' |

3341 | n/a | 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' |

3342 | n/a | 'executes\n' |

3343 | n/a | 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n' |

3344 | n/a | '\n' |

3345 | n/a | 'The typical usage to break into the debugger from a running ' |

3346 | n/a | 'program is\n' |

3347 | n/a | 'to insert\n' |

3348 | n/a | '\n' |

3349 | n/a | ' import pdb; pdb.set_trace()\n' |

3350 | n/a | '\n' |

3351 | n/a | 'at the location you want to break into the debugger. You can ' |

3352 | n/a | 'then\n' |

3353 | n/a | 'step through the code following this statement, and continue ' |

3354 | n/a | 'running\n' |

3355 | n/a | 'without the debugger using the "continue" command.\n' |

3356 | n/a | '\n' |

3357 | n/a | 'The typical usage to inspect a crashed program is:\n' |

3358 | n/a | '\n' |

3359 | n/a | ' >>> import pdb\n' |

3360 | n/a | ' >>> import mymodule\n' |

3361 | n/a | ' >>> mymodule.test()\n' |

3362 | n/a | ' Traceback (most recent call last):\n' |

3363 | n/a | ' File "<stdin>", line 1, in ?\n' |

3364 | n/a | ' File "./mymodule.py", line 4, in test\n' |

3365 | n/a | ' test2()\n' |

3366 | n/a | ' File "./mymodule.py", line 3, in test2\n' |

3367 | n/a | ' print(spam)\n' |

3368 | n/a | ' NameError: spam\n' |

3369 | n/a | ' >>> pdb.pm()\n' |

3370 | n/a | ' > ./mymodule.py(3)test2()\n' |

3371 | n/a | ' -> print(spam)\n' |

3372 | n/a | ' (Pdb)\n' |

3373 | n/a | '\n' |

3374 | n/a | 'The module defines the following functions; each enters the ' |

3375 | n/a | 'debugger\n' |

3376 | n/a | 'in a slightly different way:\n' |

3377 | n/a | '\n' |

3378 | n/a | 'pdb.run(statement, globals=None, locals=None)\n' |

3379 | n/a | '\n' |

3380 | n/a | ' Execute the *statement* (given as a string or a code object) ' |

3381 | n/a | 'under\n' |

3382 | n/a | ' debugger control. The debugger prompt appears before any ' |

3383 | n/a | 'code is\n' |

3384 | n/a | ' executed; you can set breakpoints and type "continue", or you ' |

3385 | n/a | 'can\n' |

3386 | n/a | ' step through the statement using "step" or "next" (all these\n' |

3387 | n/a | ' commands are explained below). The optional *globals* and ' |

3388 | n/a | '*locals*\n' |

3389 | n/a | ' arguments specify the environment in which the code is ' |

3390 | n/a | 'executed; by\n' |

3391 | n/a | ' default the dictionary of the module "__main__" is used. ' |

3392 | n/a | '(See the\n' |

3393 | n/a | ' explanation of the built-in "exec()" or "eval()" functions.)\n' |

3394 | n/a | '\n' |

3395 | n/a | 'pdb.runeval(expression, globals=None, locals=None)\n' |

3396 | n/a | '\n' |

3397 | n/a | ' Evaluate the *expression* (given as a string or a code ' |

3398 | n/a | 'object)\n' |

3399 | n/a | ' under debugger control. When "runeval()" returns, it returns ' |

3400 | n/a | 'the\n' |

3401 | n/a | ' value of the expression. Otherwise this function is similar ' |

3402 | n/a | 'to\n' |

3403 | n/a | ' "run()".\n' |

3404 | n/a | '\n' |

3405 | n/a | 'pdb.runcall(function, *args, **kwds)\n' |

3406 | n/a | '\n' |

3407 | n/a | ' Call the *function* (a function or method object, not a ' |

3408 | n/a | 'string)\n' |

3409 | n/a | ' with the given arguments. When "runcall()" returns, it ' |

3410 | n/a | 'returns\n' |

3411 | n/a | ' whatever the function call returned. The debugger prompt ' |

3412 | n/a | 'appears\n' |

3413 | n/a | ' as soon as the function is entered.\n' |

3414 | n/a | '\n' |

3415 | n/a | 'pdb.set_trace()\n' |

3416 | n/a | '\n' |

3417 | n/a | ' Enter the debugger at the calling stack frame. This is ' |

3418 | n/a | 'useful to\n' |

3419 | n/a | ' hard-code a breakpoint at a given point in a program, even if ' |

3420 | n/a | 'the\n' |

3421 | n/a | ' code is not otherwise being debugged (e.g. when an assertion\n' |

3422 | n/a | ' fails).\n' |

3423 | n/a | '\n' |

3424 | n/a | 'pdb.post_mortem(traceback=None)\n' |

3425 | n/a | '\n' |

3426 | n/a | ' Enter post-mortem debugging of the given *traceback* object. ' |

3427 | n/a | 'If no\n' |

3428 | n/a | ' *traceback* is given, it uses the one of the exception that ' |

3429 | n/a | 'is\n' |

3430 | n/a | ' currently being handled (an exception must be being handled ' |

3431 | n/a | 'if the\n' |

3432 | n/a | ' default is to be used).\n' |

3433 | n/a | '\n' |

3434 | n/a | 'pdb.pm()\n' |

3435 | n/a | '\n' |

3436 | n/a | ' Enter post-mortem debugging of the traceback found in\n' |

3437 | n/a | ' "sys.last_traceback".\n' |

3438 | n/a | '\n' |

3439 | n/a | 'The "run*" functions and "set_trace()" are aliases for ' |

3440 | n/a | 'instantiating\n' |

3441 | n/a | 'the "Pdb" class and calling the method of the same name. If you ' |

3442 | n/a | 'want\n' |

3443 | n/a | 'to access further features, you have to do this yourself:\n' |

3444 | n/a | '\n' |

3445 | n/a | "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, " |

3446 | n/a | 'skip=None, nosigint=False, readrc=True)\n' |

3447 | n/a | '\n' |

3448 | n/a | ' "Pdb" is the debugger class.\n' |

3449 | n/a | '\n' |

3450 | n/a | ' The *completekey*, *stdin* and *stdout* arguments are passed ' |

3451 | n/a | 'to the\n' |

3452 | n/a | ' underlying "cmd.Cmd" class; see the description there.\n' |

3453 | n/a | '\n' |

3454 | n/a | ' The *skip* argument, if given, must be an iterable of ' |

3455 | n/a | 'glob-style\n' |

3456 | n/a | ' module name patterns. The debugger will not step into frames ' |

3457 | n/a | 'that\n' |

3458 | n/a | ' originate in a module that matches one of these patterns. ' |

3459 | n/a | '[1]\n' |

3460 | n/a | '\n' |

3461 | n/a | ' By default, Pdb sets a handler for the SIGINT signal (which ' |

3462 | n/a | 'is sent\n' |

3463 | n/a | ' when the user presses "Ctrl-C" on the console) when you give ' |

3464 | n/a | 'a\n' |

3465 | n/a | ' "continue" command. This allows you to break into the ' |

3466 | n/a | 'debugger\n' |

3467 | n/a | ' again by pressing "Ctrl-C". If you want Pdb not to touch ' |

3468 | n/a | 'the\n' |

3469 | n/a | ' SIGINT handler, set *nosigint* to true.\n' |

3470 | n/a | '\n' |

3471 | n/a | ' The *readrc* argument defaults to true and controls whether ' |

3472 | n/a | 'Pdb\n' |

3473 | n/a | ' will load .pdbrc files from the filesystem.\n' |

3474 | n/a | '\n' |

3475 | n/a | ' Example call to enable tracing with *skip*:\n' |

3476 | n/a | '\n' |

3477 | n/a | " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" |

3478 | n/a | '\n' |

3479 | n/a | ' New in version 3.1: The *skip* argument.\n' |

3480 | n/a | '\n' |

3481 | n/a | ' New in version 3.2: The *nosigint* argument. Previously, a ' |

3482 | n/a | 'SIGINT\n' |

3483 | n/a | ' handler was never set by Pdb.\n' |

3484 | n/a | '\n' |

3485 | n/a | ' Changed in version 3.6: The *readrc* argument.\n' |

3486 | n/a | '\n' |

3487 | n/a | ' run(statement, globals=None, locals=None)\n' |

3488 | n/a | ' runeval(expression, globals=None, locals=None)\n' |

3489 | n/a | ' runcall(function, *args, **kwds)\n' |

3490 | n/a | ' set_trace()\n' |

3491 | n/a | '\n' |

3492 | n/a | ' See the documentation for the functions explained above.\n' |

3493 | n/a | '\n' |

3494 | n/a | '\n' |

3495 | n/a | 'Debugger Commands\n' |

3496 | n/a | '=================\n' |

3497 | n/a | '\n' |

3498 | n/a | 'The commands recognized by the debugger are listed below. Most\n' |

3499 | n/a | 'commands can be abbreviated to one or two letters as indicated; ' |

3500 | n/a | 'e.g.\n' |

3501 | n/a | '"h(elp)" means that either "h" or "help" can be used to enter ' |

3502 | n/a | 'the help\n' |

3503 | n/a | 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' |

3504 | n/a | 'Arguments to commands must be separated by whitespace (spaces ' |

3505 | n/a | 'or\n' |

3506 | n/a | 'tabs). Optional arguments are enclosed in square brackets ' |

3507 | n/a | '("[]") in\n' |

3508 | n/a | 'the command syntax; the square brackets must not be typed.\n' |

3509 | n/a | 'Alternatives in the command syntax are separated by a vertical ' |

3510 | n/a | 'bar\n' |

3511 | n/a | '("|").\n' |

3512 | n/a | '\n' |

3513 | n/a | 'Entering a blank line repeats the last command entered. ' |

3514 | n/a | 'Exception: if\n' |

3515 | n/a | 'the last command was a "list" command, the next 11 lines are ' |

3516 | n/a | 'listed.\n' |

3517 | n/a | '\n' |

3518 | n/a | "Commands that the debugger doesn't recognize are assumed to be " |

3519 | n/a | 'Python\n' |

3520 | n/a | 'statements and are executed in the context of the program being\n' |

3521 | n/a | 'debugged. Python statements can also be prefixed with an ' |

3522 | n/a | 'exclamation\n' |

3523 | n/a | 'point ("!"). This is a powerful way to inspect the program ' |

3524 | n/a | 'being\n' |

3525 | n/a | 'debugged; it is even possible to change a variable or call a ' |

3526 | n/a | 'function.\n' |

3527 | n/a | 'When an exception occurs in such a statement, the exception name ' |

3528 | n/a | 'is\n' |

3529 | n/a | "printed but the debugger's state is not changed.\n" |

3530 | n/a | '\n' |

3531 | n/a | 'The debugger supports aliases. Aliases can have parameters ' |

3532 | n/a | 'which\n' |

3533 | n/a | 'allows one a certain level of adaptability to the context under\n' |

3534 | n/a | 'examination.\n' |

3535 | n/a | '\n' |

3536 | n/a | 'Multiple commands may be entered on a single line, separated by ' |

3537 | n/a | '";;".\n' |

3538 | n/a | '(A single ";" is not used as it is the separator for multiple ' |

3539 | n/a | 'commands\n' |

3540 | n/a | 'in a line that is passed to the Python parser.) No intelligence ' |

3541 | n/a | 'is\n' |

3542 | n/a | 'applied to separating the commands; the input is split at the ' |

3543 | n/a | 'first\n' |

3544 | n/a | '";;" pair, even if it is in the middle of a quoted string.\n' |

3545 | n/a | '\n' |

3546 | n/a | 'If a file ".pdbrc" exists in the user\'s home directory or in ' |

3547 | n/a | 'the\n' |

3548 | n/a | 'current directory, it is read in and executed as if it had been ' |

3549 | n/a | 'typed\n' |

3550 | n/a | 'at the debugger prompt. This is particularly useful for ' |

3551 | n/a | 'aliases. If\n' |

3552 | n/a | 'both files exist, the one in the home directory is read first ' |

3553 | n/a | 'and\n' |

3554 | n/a | 'aliases defined there can be overridden by the local file.\n' |

3555 | n/a | '\n' |

3556 | n/a | 'Changed in version 3.2: ".pdbrc" can now contain commands that\n' |

3557 | n/a | 'continue debugging, such as "continue" or "next". Previously, ' |

3558 | n/a | 'these\n' |

3559 | n/a | 'commands had no effect.\n' |

3560 | n/a | '\n' |

3561 | n/a | 'h(elp) [command]\n' |

3562 | n/a | '\n' |

3563 | n/a | ' Without argument, print the list of available commands. With ' |

3564 | n/a | 'a\n' |

3565 | n/a | ' *command* as argument, print help about that command. "help ' |

3566 | n/a | 'pdb"\n' |

3567 | n/a | ' displays the full documentation (the docstring of the "pdb"\n' |

3568 | n/a | ' module). Since the *command* argument must be an identifier, ' |

3569 | n/a | '"help\n' |

3570 | n/a | ' exec" must be entered to get help on the "!" command.\n' |

3571 | n/a | '\n' |

3572 | n/a | 'w(here)\n' |

3573 | n/a | '\n' |

3574 | n/a | ' Print a stack trace, with the most recent frame at the ' |

3575 | n/a | 'bottom. An\n' |

3576 | n/a | ' arrow indicates the current frame, which determines the ' |

3577 | n/a | 'context of\n' |

3578 | n/a | ' most commands.\n' |

3579 | n/a | '\n' |

3580 | n/a | 'd(own) [count]\n' |

3581 | n/a | '\n' |

3582 | n/a | ' Move the current frame *count* (default one) levels down in ' |

3583 | n/a | 'the\n' |

3584 | n/a | ' stack trace (to a newer frame).\n' |

3585 | n/a | '\n' |

3586 | n/a | 'u(p) [count]\n' |

3587 | n/a | '\n' |

3588 | n/a | ' Move the current frame *count* (default one) levels up in the ' |

3589 | n/a | 'stack\n' |

3590 | n/a | ' trace (to an older frame).\n' |

3591 | n/a | '\n' |

3592 | n/a | 'b(reak) [([filename:]lineno | function) [, condition]]\n' |

3593 | n/a | '\n' |

3594 | n/a | ' With a *lineno* argument, set a break there in the current ' |

3595 | n/a | 'file.\n' |

3596 | n/a | ' With a *function* argument, set a break at the first ' |

3597 | n/a | 'executable\n' |

3598 | n/a | ' statement within that function. The line number may be ' |

3599 | n/a | 'prefixed\n' |

3600 | n/a | ' with a filename and a colon, to specify a breakpoint in ' |

3601 | n/a | 'another\n' |

3602 | n/a | " file (probably one that hasn't been loaded yet). The file " |

3603 | n/a | 'is\n' |

3604 | n/a | ' searched on "sys.path". Note that each breakpoint is ' |

3605 | n/a | 'assigned a\n' |

3606 | n/a | ' number to which all the other breakpoint commands refer.\n' |

3607 | n/a | '\n' |

3608 | n/a | ' If a second argument is present, it is an expression which ' |

3609 | n/a | 'must\n' |

3610 | n/a | ' evaluate to true before the breakpoint is honored.\n' |

3611 | n/a | '\n' |

3612 | n/a | ' Without argument, list all breaks, including for each ' |

3613 | n/a | 'breakpoint,\n' |

3614 | n/a | ' the number of times that breakpoint has been hit, the ' |

3615 | n/a | 'current\n' |

3616 | n/a | ' ignore count, and the associated condition if any.\n' |

3617 | n/a | '\n' |

3618 | n/a | 'tbreak [([filename:]lineno | function) [, condition]]\n' |

3619 | n/a | '\n' |

3620 | n/a | ' Temporary breakpoint, which is removed automatically when it ' |

3621 | n/a | 'is\n' |

3622 | n/a | ' first hit. The arguments are the same as for "break".\n' |

3623 | n/a | '\n' |

3624 | n/a | 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' |

3625 | n/a | '\n' |

3626 | n/a | ' With a *filename:lineno* argument, clear all the breakpoints ' |

3627 | n/a | 'at\n' |

3628 | n/a | ' this line. With a space separated list of breakpoint numbers, ' |

3629 | n/a | 'clear\n' |

3630 | n/a | ' those breakpoints. Without argument, clear all breaks (but ' |

3631 | n/a | 'first\n' |

3632 | n/a | ' ask confirmation).\n' |

3633 | n/a | '\n' |

3634 | n/a | 'disable [bpnumber [bpnumber ...]]\n' |

3635 | n/a | '\n' |

3636 | n/a | ' Disable the breakpoints given as a space separated list of\n' |

3637 | n/a | ' breakpoint numbers. Disabling a breakpoint means it cannot ' |

3638 | n/a | 'cause\n' |

3639 | n/a | ' the program to stop execution, but unlike clearing a ' |

3640 | n/a | 'breakpoint, it\n' |

3641 | n/a | ' remains in the list of breakpoints and can be (re-)enabled.\n' |

3642 | n/a | '\n' |

3643 | n/a | 'enable [bpnumber [bpnumber ...]]\n' |

3644 | n/a | '\n' |

3645 | n/a | ' Enable the breakpoints specified.\n' |

3646 | n/a | '\n' |

3647 | n/a | 'ignore bpnumber [count]\n' |

3648 | n/a | '\n' |

3649 | n/a | ' Set the ignore count for the given breakpoint number. If ' |

3650 | n/a | 'count is\n' |

3651 | n/a | ' omitted, the ignore count is set to 0. A breakpoint becomes ' |

3652 | n/a | 'active\n' |

3653 | n/a | ' when the ignore count is zero. When non-zero, the count is\n' |

3654 | n/a | ' decremented each time the breakpoint is reached and the ' |

3655 | n/a | 'breakpoint\n' |

3656 | n/a | ' is not disabled and any associated condition evaluates to ' |

3657 | n/a | 'true.\n' |

3658 | n/a | '\n' |

3659 | n/a | 'condition bpnumber [condition]\n' |

3660 | n/a | '\n' |

3661 | n/a | ' Set a new *condition* for the breakpoint, an expression which ' |

3662 | n/a | 'must\n' |

3663 | n/a | ' evaluate to true before the breakpoint is honored. If ' |

3664 | n/a | '*condition*\n' |

3665 | n/a | ' is absent, any existing condition is removed; i.e., the ' |

3666 | n/a | 'breakpoint\n' |

3667 | n/a | ' is made unconditional.\n' |

3668 | n/a | '\n' |

3669 | n/a | 'commands [bpnumber]\n' |

3670 | n/a | '\n' |

3671 | n/a | ' Specify a list of commands for breakpoint number *bpnumber*. ' |

3672 | n/a | 'The\n' |

3673 | n/a | ' commands themselves appear on the following lines. Type a ' |

3674 | n/a | 'line\n' |

3675 | n/a | ' containing just "end" to terminate the commands. An example:\n' |

3676 | n/a | '\n' |

3677 | n/a | ' (Pdb) commands 1\n' |

3678 | n/a | ' (com) p some_variable\n' |

3679 | n/a | ' (com) end\n' |

3680 | n/a | ' (Pdb)\n' |

3681 | n/a | '\n' |

3682 | n/a | ' To remove all commands from a breakpoint, type commands and ' |

3683 | n/a | 'follow\n' |

3684 | n/a | ' it immediately with "end"; that is, give no commands.\n' |

3685 | n/a | '\n' |

3686 | n/a | ' With no *bpnumber* argument, commands refers to the last ' |

3687 | n/a | 'breakpoint\n' |

3688 | n/a | ' set.\n' |

3689 | n/a | '\n' |

3690 | n/a | ' You can use breakpoint commands to start your program up ' |

3691 | n/a | 'again.\n' |

3692 | n/a | ' Simply use the continue command, or step, or any other ' |

3693 | n/a | 'command that\n' |

3694 | n/a | ' resumes execution.\n' |

3695 | n/a | '\n' |

3696 | n/a | ' Specifying any command resuming execution (currently ' |

3697 | n/a | 'continue,\n' |

3698 | n/a | ' step, next, return, jump, quit and their abbreviations) ' |

3699 | n/a | 'terminates\n' |

3700 | n/a | ' the command list (as if that command was immediately followed ' |

3701 | n/a | 'by\n' |

3702 | n/a | ' end). This is because any time you resume execution (even ' |

3703 | n/a | 'with a\n' |

3704 | n/a | ' simple next or step), you may encounter another ' |

3705 | n/a | 'breakpoint--which\n' |

3706 | n/a | ' could have its own command list, leading to ambiguities about ' |

3707 | n/a | 'which\n' |

3708 | n/a | ' list to execute.\n' |

3709 | n/a | '\n' |

3710 | n/a | " If you use the 'silent' command in the command list, the " |

3711 | n/a | 'usual\n' |

3712 | n/a | ' message about stopping at a breakpoint is not printed. This ' |

3713 | n/a | 'may be\n' |

3714 | n/a | ' desirable for breakpoints that are to print a specific ' |

3715 | n/a | 'message and\n' |

3716 | n/a | ' then continue. If none of the other commands print anything, ' |

3717 | n/a | 'you\n' |

3718 | n/a | ' see no sign that the breakpoint was reached.\n' |

3719 | n/a | '\n' |

3720 | n/a | 's(tep)\n' |

3721 | n/a | '\n' |

3722 | n/a | ' Execute the current line, stop at the first possible ' |

3723 | n/a | 'occasion\n' |

3724 | n/a | ' (either in a function that is called or on the next line in ' |

3725 | n/a | 'the\n' |

3726 | n/a | ' current function).\n' |

3727 | n/a | '\n' |

3728 | n/a | 'n(ext)\n' |

3729 | n/a | '\n' |

3730 | n/a | ' Continue execution until the next line in the current ' |

3731 | n/a | 'function is\n' |

3732 | n/a | ' reached or it returns. (The difference between "next" and ' |

3733 | n/a | '"step"\n' |

3734 | n/a | ' is that "step" stops inside a called function, while "next"\n' |

3735 | n/a | ' executes called functions at (nearly) full speed, only ' |

3736 | n/a | 'stopping at\n' |

3737 | n/a | ' the next line in the current function.)\n' |

3738 | n/a | '\n' |

3739 | n/a | 'unt(il) [lineno]\n' |

3740 | n/a | '\n' |

3741 | n/a | ' Without argument, continue execution until the line with a ' |

3742 | n/a | 'number\n' |

3743 | n/a | ' greater than the current one is reached.\n' |

3744 | n/a | '\n' |

3745 | n/a | ' With a line number, continue execution until a line with a ' |

3746 | n/a | 'number\n' |

3747 | n/a | ' greater or equal to that is reached. In both cases, also ' |

3748 | n/a | 'stop when\n' |

3749 | n/a | ' the current frame returns.\n' |

3750 | n/a | '\n' |

3751 | n/a | ' Changed in version 3.2: Allow giving an explicit line ' |

3752 | n/a | 'number.\n' |

3753 | n/a | '\n' |

3754 | n/a | 'r(eturn)\n' |

3755 | n/a | '\n' |

3756 | n/a | ' Continue execution until the current function returns.\n' |

3757 | n/a | '\n' |

3758 | n/a | 'c(ont(inue))\n' |

3759 | n/a | '\n' |

3760 | n/a | ' Continue execution, only stop when a breakpoint is ' |

3761 | n/a | 'encountered.\n' |

3762 | n/a | '\n' |

3763 | n/a | 'j(ump) lineno\n' |

3764 | n/a | '\n' |

3765 | n/a | ' Set the next line that will be executed. Only available in ' |

3766 | n/a | 'the\n' |

3767 | n/a | ' bottom-most frame. This lets you jump back and execute code ' |

3768 | n/a | 'again,\n' |

3769 | n/a | " or jump forward to skip code that you don't want to run.\n" |

3770 | n/a | '\n' |

3771 | n/a | ' It should be noted that not all jumps are allowed -- for ' |

3772 | n/a | 'instance\n' |

3773 | n/a | ' it is not possible to jump into the middle of a "for" loop or ' |

3774 | n/a | 'out\n' |

3775 | n/a | ' of a "finally" clause.\n' |

3776 | n/a | '\n' |

3777 | n/a | 'l(ist) [first[, last]]\n' |

3778 | n/a | '\n' |

3779 | n/a | ' List source code for the current file. Without arguments, ' |

3780 | n/a | 'list 11\n' |

3781 | n/a | ' lines around the current line or continue the previous ' |

3782 | n/a | 'listing.\n' |

3783 | n/a | ' With "." as argument, list 11 lines around the current line. ' |

3784 | n/a | 'With\n' |

3785 | n/a | ' one argument, list 11 lines around at that line. With two\n' |

3786 | n/a | ' arguments, list the given range; if the second argument is ' |

3787 | n/a | 'less\n' |

3788 | n/a | ' than the first, it is interpreted as a count.\n' |

3789 | n/a | '\n' |

3790 | n/a | ' The current line in the current frame is indicated by "->". ' |

3791 | n/a | 'If an\n' |

3792 | n/a | ' exception is being debugged, the line where the exception ' |

3793 | n/a | 'was\n' |

3794 | n/a | ' originally raised or propagated is indicated by ">>", if it ' |

3795 | n/a | 'differs\n' |

3796 | n/a | ' from the current line.\n' |

3797 | n/a | '\n' |

3798 | n/a | ' New in version 3.2: The ">>" marker.\n' |

3799 | n/a | '\n' |

3800 | n/a | 'll | longlist\n' |

3801 | n/a | '\n' |

3802 | n/a | ' List all source code for the current function or frame.\n' |

3803 | n/a | ' Interesting lines are marked as for "list".\n' |

3804 | n/a | '\n' |

3805 | n/a | ' New in version 3.2.\n' |

3806 | n/a | '\n' |

3807 | n/a | 'a(rgs)\n' |

3808 | n/a | '\n' |

3809 | n/a | ' Print the argument list of the current function.\n' |

3810 | n/a | '\n' |

3811 | n/a | 'p expression\n' |

3812 | n/a | '\n' |

3813 | n/a | ' Evaluate the *expression* in the current context and print ' |

3814 | n/a | 'its\n' |

3815 | n/a | ' value.\n' |

3816 | n/a | '\n' |

3817 | n/a | ' Note: "print()" can also be used, but is not a debugger ' |

3818 | n/a | 'command\n' |

3819 | n/a | ' --- this executes the Python "print()" function.\n' |

3820 | n/a | '\n' |

3821 | n/a | 'pp expression\n' |

3822 | n/a | '\n' |

3823 | n/a | ' Like the "p" command, except the value of the expression is ' |

3824 | n/a | 'pretty-\n' |

3825 | n/a | ' printed using the "pprint" module.\n' |

3826 | n/a | '\n' |

3827 | n/a | 'whatis expression\n' |

3828 | n/a | '\n' |

3829 | n/a | ' Print the type of the *expression*.\n' |

3830 | n/a | '\n' |

3831 | n/a | 'source expression\n' |

3832 | n/a | '\n' |

3833 | n/a | ' Try to get source code for the given object and display it.\n' |

3834 | n/a | '\n' |

3835 | n/a | ' New in version 3.2.\n' |

3836 | n/a | '\n' |

3837 | n/a | 'display [expression]\n' |

3838 | n/a | '\n' |

3839 | n/a | ' Display the value of the expression if it changed, each time\n' |

3840 | n/a | ' execution stops in the current frame.\n' |

3841 | n/a | '\n' |

3842 | n/a | ' Without expression, list all display expressions for the ' |

3843 | n/a | 'current\n' |

3844 | n/a | ' frame.\n' |

3845 | n/a | '\n' |

3846 | n/a | ' New in version 3.2.\n' |

3847 | n/a | '\n' |

3848 | n/a | 'undisplay [expression]\n' |

3849 | n/a | '\n' |

3850 | n/a | ' Do not display the expression any more in the current frame.\n' |

3851 | n/a | ' Without expression, clear all display expressions for the ' |

3852 | n/a | 'current\n' |

3853 | n/a | ' frame.\n' |

3854 | n/a | '\n' |

3855 | n/a | ' New in version 3.2.\n' |

3856 | n/a | '\n' |

3857 | n/a | 'interact\n' |

3858 | n/a | '\n' |

3859 | n/a | ' Start an interactive interpreter (using the "code" module) ' |

3860 | n/a | 'whose\n' |

3861 | n/a | ' global namespace contains all the (global and local) names ' |

3862 | n/a | 'found in\n' |

3863 | n/a | ' the current scope.\n' |

3864 | n/a | '\n' |

3865 | n/a | ' New in version 3.2.\n' |

3866 | n/a | '\n' |

3867 | n/a | 'alias [name [command]]\n' |

3868 | n/a | '\n' |

3869 | n/a | ' Create an alias called *name* that executes *command*. The ' |

3870 | n/a | 'command\n' |

3871 | n/a | ' must *not* be enclosed in quotes. Replaceable parameters can ' |

3872 | n/a | 'be\n' |

3873 | n/a | ' indicated by "%1", "%2", and so on, while "%*" is replaced by ' |

3874 | n/a | 'all\n' |

3875 | n/a | ' the parameters. If no command is given, the current alias ' |

3876 | n/a | 'for\n' |

3877 | n/a | ' *name* is shown. If no arguments are given, all aliases are ' |

3878 | n/a | 'listed.\n' |

3879 | n/a | '\n' |

3880 | n/a | ' Aliases may be nested and can contain anything that can be ' |

3881 | n/a | 'legally\n' |

3882 | n/a | ' typed at the pdb prompt. Note that internal pdb commands ' |

3883 | n/a | '*can* be\n' |

3884 | n/a | ' overridden by aliases. Such a command is then hidden until ' |

3885 | n/a | 'the\n' |

3886 | n/a | ' alias is removed. Aliasing is recursively applied to the ' |

3887 | n/a | 'first\n' |

3888 | n/a | ' word of the command line; all other words in the line are ' |

3889 | n/a | 'left\n' |

3890 | n/a | ' alone.\n' |

3891 | n/a | '\n' |

3892 | n/a | ' As an example, here are two useful aliases (especially when ' |

3893 | n/a | 'placed\n' |

3894 | n/a | ' in the ".pdbrc" file):\n' |

3895 | n/a | '\n' |

3896 | n/a | ' # Print instance variables (usage "pi classInst")\n' |

3897 | n/a | ' alias pi for k in %1.__dict__.keys(): ' |

3898 | n/a | 'print("%1.",k,"=",%1.__dict__[k])\n' |

3899 | n/a | ' # Print instance variables in self\n' |

3900 | n/a | ' alias ps pi self\n' |

3901 | n/a | '\n' |

3902 | n/a | 'unalias name\n' |

3903 | n/a | '\n' |

3904 | n/a | ' Delete the specified alias.\n' |

3905 | n/a | '\n' |

3906 | n/a | '! statement\n' |

3907 | n/a | '\n' |

3908 | n/a | ' Execute the (one-line) *statement* in the context of the ' |

3909 | n/a | 'current\n' |

3910 | n/a | ' stack frame. The exclamation point can be omitted unless the ' |

3911 | n/a | 'first\n' |

3912 | n/a | ' word of the statement resembles a debugger command. To set ' |

3913 | n/a | 'a\n' |

3914 | n/a | ' global variable, you can prefix the assignment command with ' |

3915 | n/a | 'a\n' |

3916 | n/a | ' "global" statement on the same line, e.g.:\n' |

3917 | n/a | '\n' |

3918 | n/a | " (Pdb) global list_options; list_options = ['-l']\n" |

3919 | n/a | ' (Pdb)\n' |

3920 | n/a | '\n' |

3921 | n/a | 'run [args ...]\n' |

3922 | n/a | 'restart [args ...]\n' |

3923 | n/a | '\n' |

3924 | n/a | ' Restart the debugged Python program. If an argument is ' |

3925 | n/a | 'supplied,\n' |

3926 | n/a | ' it is split with "shlex" and the result is used as the new\n' |

3927 | n/a | ' "sys.argv". History, breakpoints, actions and debugger ' |

3928 | n/a | 'options are\n' |

3929 | n/a | ' preserved. "restart" is an alias for "run".\n' |

3930 | n/a | '\n' |

3931 | n/a | 'q(uit)\n' |

3932 | n/a | '\n' |

3933 | n/a | ' Quit from the debugger. The program being executed is ' |

3934 | n/a | 'aborted.\n' |

3935 | n/a | '\n' |

3936 | n/a | '-[ Footnotes ]-\n' |

3937 | n/a | '\n' |

3938 | n/a | '[1] Whether a frame is considered to originate in a certain ' |

3939 | n/a | 'module\n' |

3940 | n/a | ' is determined by the "__name__" in the frame globals.\n', |

3941 | n/a | 'del': '\n' |

3942 | n/a | 'The "del" statement\n' |

3943 | n/a | '*******************\n' |

3944 | n/a | '\n' |

3945 | n/a | ' del_stmt ::= "del" target_list\n' |

3946 | n/a | '\n' |

3947 | n/a | 'Deletion is recursively defined very similar to the way assignment ' |

3948 | n/a | 'is\n' |

3949 | n/a | 'defined. Rather than spelling it out in full details, here are some\n' |

3950 | n/a | 'hints.\n' |

3951 | n/a | '\n' |

3952 | n/a | 'Deletion of a target list recursively deletes each target, from left\n' |

3953 | n/a | 'to right.\n' |

3954 | n/a | '\n' |

3955 | n/a | 'Deletion of a name removes the binding of that name from the local ' |

3956 | n/a | 'or\n' |

3957 | n/a | 'global namespace, depending on whether the name occurs in a "global"\n' |

3958 | n/a | 'statement in the same code block. If the name is unbound, a\n' |

3959 | n/a | '"NameError" exception will be raised.\n' |

3960 | n/a | '\n' |

3961 | n/a | 'Deletion of attribute references, subscriptions and slicings is ' |

3962 | n/a | 'passed\n' |

3963 | n/a | 'to the primary object involved; deletion of a slicing is in general\n' |

3964 | n/a | 'equivalent to assignment of an empty slice of the right type (but ' |

3965 | n/a | 'even\n' |

3966 | n/a | 'this is determined by the sliced object).\n' |

3967 | n/a | '\n' |

3968 | n/a | 'Changed in version 3.2: Previously it was illegal to delete a name\n' |

3969 | n/a | 'from the local namespace if it occurs as a free variable in a nested\n' |

3970 | n/a | 'block.\n', |

3971 | n/a | 'dict': '\n' |

3972 | n/a | 'Dictionary displays\n' |

3973 | n/a | '*******************\n' |

3974 | n/a | '\n' |

3975 | n/a | 'A dictionary display is a possibly empty series of key/datum pairs\n' |

3976 | n/a | 'enclosed in curly braces:\n' |

3977 | n/a | '\n' |

3978 | n/a | ' dict_display ::= "{" [key_datum_list | dict_comprehension] ' |

3979 | n/a | '"}"\n' |

3980 | n/a | ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' |

3981 | n/a | ' key_datum ::= expression ":" expression | "**" or_expr\n' |

3982 | n/a | ' dict_comprehension ::= expression ":" expression comp_for\n' |

3983 | n/a | '\n' |

3984 | n/a | 'A dictionary display yields a new dictionary object.\n' |

3985 | n/a | '\n' |

3986 | n/a | 'If a comma-separated sequence of key/datum pairs is given, they are\n' |

3987 | n/a | 'evaluated from left to right to define the entries of the ' |

3988 | n/a | 'dictionary:\n' |

3989 | n/a | 'each key object is used as a key into the dictionary to store the\n' |

3990 | n/a | 'corresponding datum. This means that you can specify the same key\n' |

3991 | n/a | "multiple times in the key/datum list, and the final dictionary's " |

3992 | n/a | 'value\n' |

3993 | n/a | 'for that key will be the last one given.\n' |

3994 | n/a | '\n' |

3995 | n/a | 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n' |

3996 | n/a | 'must be a *mapping*. Each mapping item is added to the new\n' |

3997 | n/a | 'dictionary. Later values replace values already set by earlier\n' |

3998 | n/a | 'key/datum pairs and earlier dictionary unpackings.\n' |

3999 | n/a | '\n' |

4000 | n/a | 'New in version 3.5: Unpacking into dictionary displays, originally\n' |

4001 | n/a | 'proposed by **PEP 448**.\n' |

4002 | n/a | '\n' |

4003 | n/a | 'A dict comprehension, in contrast to list and set comprehensions,\n' |

4004 | n/a | 'needs two expressions separated with a colon followed by the usual\n' |

4005 | n/a | '"for" and "if" clauses. When the comprehension is run, the ' |

4006 | n/a | 'resulting\n' |

4007 | n/a | 'key and value elements are inserted in the new dictionary in the ' |

4008 | n/a | 'order\n' |

4009 | n/a | 'they are produced.\n' |

4010 | n/a | '\n' |

4011 | n/a | 'Restrictions on the types of the key values are listed earlier in\n' |

4012 | n/a | 'section The standard type hierarchy. (To summarize, the key type\n' |

4013 | n/a | 'should be *hashable*, which excludes all mutable objects.) Clashes\n' |

4014 | n/a | 'between duplicate keys are not detected; the last datum (textually\n' |

4015 | n/a | 'rightmost in the display) stored for a given key value prevails.\n', |

4016 | n/a | 'dynamic-features': '\n' |

4017 | n/a | 'Interaction with dynamic features\n' |

4018 | n/a | '*********************************\n' |

4019 | n/a | '\n' |

4020 | n/a | 'Name resolution of free variables occurs at runtime, not ' |

4021 | n/a | 'at compile\n' |

4022 | n/a | 'time. This means that the following code will print 42:\n' |

4023 | n/a | '\n' |

4024 | n/a | ' i = 10\n' |

4025 | n/a | ' def f():\n' |

4026 | n/a | ' print(i)\n' |

4027 | n/a | ' i = 42\n' |

4028 | n/a | ' f()\n' |

4029 | n/a | '\n' |

4030 | n/a | 'There are several cases where Python statements are ' |

4031 | n/a | 'illegal when used\n' |

4032 | n/a | 'in conjunction with nested scopes that contain free ' |

4033 | n/a | 'variables.\n' |

4034 | n/a | '\n' |

4035 | n/a | 'If a variable is referenced in an enclosing scope, it is ' |

4036 | n/a | 'illegal to\n' |

4037 | n/a | 'delete the name. An error will be reported at compile ' |

4038 | n/a | 'time.\n' |

4039 | n/a | '\n' |

4040 | n/a | 'The "eval()" and "exec()" functions do not have access ' |

4041 | n/a | 'to the full\n' |

4042 | n/a | 'environment for resolving names. Names may be resolved ' |

4043 | n/a | 'in the local\n' |

4044 | n/a | 'and global namespaces of the caller. Free variables are ' |

4045 | n/a | 'not resolved\n' |

4046 | n/a | 'in the nearest enclosing namespace, but in the global ' |

4047 | n/a | 'namespace. [1]\n' |

4048 | n/a | 'The "exec()" and "eval()" functions have optional ' |

4049 | n/a | 'arguments to\n' |

4050 | n/a | 'override the global and local namespace. If only one ' |

4051 | n/a | 'namespace is\n' |

4052 | n/a | 'specified, it is used for both.\n', |

4053 | n/a | 'else': '\n' |

4054 | n/a | 'The "if" statement\n' |

4055 | n/a | '******************\n' |

4056 | n/a | '\n' |

4057 | n/a | 'The "if" statement is used for conditional execution:\n' |

4058 | n/a | '\n' |

4059 | n/a | ' if_stmt ::= "if" expression ":" suite\n' |

4060 | n/a | ' ( "elif" expression ":" suite )*\n' |

4061 | n/a | ' ["else" ":" suite]\n' |

4062 | n/a | '\n' |

4063 | n/a | 'It selects exactly one of the suites by evaluating the expressions ' |

4064 | n/a | 'one\n' |

4065 | n/a | 'by one until one is found to be true (see section Boolean ' |

4066 | n/a | 'operations\n' |

4067 | n/a | 'for the definition of true and false); then that suite is executed\n' |

4068 | n/a | '(and no other part of the "if" statement is executed or evaluated).\n' |

4069 | n/a | 'If all expressions are false, the suite of the "else" clause, if\n' |

4070 | n/a | 'present, is executed.\n', |

4071 | n/a | 'exceptions': '\n' |

4072 | n/a | 'Exceptions\n' |

4073 | n/a | '**********\n' |

4074 | n/a | '\n' |

4075 | n/a | 'Exceptions are a means of breaking out of the normal flow of ' |

4076 | n/a | 'control\n' |

4077 | n/a | 'of a code block in order to handle errors or other ' |

4078 | n/a | 'exceptional\n' |

4079 | n/a | 'conditions. An exception is *raised* at the point where the ' |

4080 | n/a | 'error is\n' |

4081 | n/a | 'detected; it may be *handled* by the surrounding code block or ' |

4082 | n/a | 'by any\n' |

4083 | n/a | 'code block that directly or indirectly invoked the code block ' |

4084 | n/a | 'where\n' |

4085 | n/a | 'the error occurred.\n' |

4086 | n/a | '\n' |

4087 | n/a | 'The Python interpreter raises an exception when it detects a ' |

4088 | n/a | 'run-time\n' |

4089 | n/a | 'error (such as division by zero). A Python program can also\n' |

4090 | n/a | 'explicitly raise an exception with the "raise" statement. ' |

4091 | n/a | 'Exception\n' |

4092 | n/a | 'handlers are specified with the "try" ... "except" statement. ' |

4093 | n/a | 'The\n' |

4094 | n/a | '"finally" clause of such a statement can be used to specify ' |

4095 | n/a | 'cleanup\n' |

4096 | n/a | 'code which does not handle the exception, but is executed ' |

4097 | n/a | 'whether an\n' |

4098 | n/a | 'exception occurred or not in the preceding code.\n' |

4099 | n/a | '\n' |

4100 | n/a | 'Python uses the "termination" model of error handling: an ' |

4101 | n/a | 'exception\n' |

4102 | n/a | 'handler can find out what happened and continue execution at ' |

4103 | n/a | 'an outer\n' |

4104 | n/a | 'level, but it cannot repair the cause of the error and retry ' |

4105 | n/a | 'the\n' |

4106 | n/a | 'failing operation (except by re-entering the offending piece ' |

4107 | n/a | 'of code\n' |

4108 | n/a | 'from the top).\n' |

4109 | n/a | '\n' |

4110 | n/a | 'When an exception is not handled at all, the interpreter ' |

4111 | n/a | 'terminates\n' |

4112 | n/a | 'execution of the program, or returns to its interactive main ' |

4113 | n/a | 'loop. In\n' |

4114 | n/a | 'either case, it prints a stack backtrace, except when the ' |

4115 | n/a | 'exception is\n' |

4116 | n/a | '"SystemExit".\n' |

4117 | n/a | '\n' |

4118 | n/a | 'Exceptions are identified by class instances. The "except" ' |

4119 | n/a | 'clause is\n' |

4120 | n/a | 'selected depending on the class of the instance: it must ' |

4121 | n/a | 'reference the\n' |

4122 | n/a | 'class of the instance or a base class thereof. The instance ' |

4123 | n/a | 'can be\n' |

4124 | n/a | 'received by the handler and can carry additional information ' |

4125 | n/a | 'about the\n' |

4126 | n/a | 'exceptional condition.\n' |

4127 | n/a | '\n' |

4128 | n/a | 'Note: Exception messages are not part of the Python API. ' |

4129 | n/a | 'Their\n' |

4130 | n/a | ' contents may change from one version of Python to the next ' |

4131 | n/a | 'without\n' |

4132 | n/a | ' warning and should not be relied on by code which will run ' |

4133 | n/a | 'under\n' |

4134 | n/a | ' multiple versions of the interpreter.\n' |

4135 | n/a | '\n' |

4136 | n/a | 'See also the description of the "try" statement in section The ' |

4137 | n/a | 'try\n' |

4138 | n/a | 'statement and "raise" statement in section The raise ' |

4139 | n/a | 'statement.\n' |

4140 | n/a | '\n' |

4141 | n/a | '-[ Footnotes ]-\n' |

4142 | n/a | '\n' |

4143 | n/a | '[1] This limitation occurs because the code that is executed ' |

4144 | n/a | 'by\n' |

4145 | n/a | ' these operations is not available at the time the module ' |

4146 | n/a | 'is\n' |

4147 | n/a | ' compiled.\n', |

4148 | n/a | 'execmodel': '\n' |

4149 | n/a | 'Execution model\n' |

4150 | n/a | '***************\n' |

4151 | n/a | '\n' |

4152 | n/a | '\n' |

4153 | n/a | 'Structure of a program\n' |

4154 | n/a | '======================\n' |

4155 | n/a | '\n' |

4156 | n/a | 'A Python program is constructed from code blocks. A *block* is ' |

4157 | n/a | 'a piece\n' |

4158 | n/a | 'of Python program text that is executed as a unit. The ' |

4159 | n/a | 'following are\n' |

4160 | n/a | 'blocks: a module, a function body, and a class definition. ' |

4161 | n/a | 'Each\n' |

4162 | n/a | 'command typed interactively is a block. A script file (a file ' |

4163 | n/a | 'given\n' |

4164 | n/a | 'as standard input to the interpreter or specified as a command ' |

4165 | n/a | 'line\n' |

4166 | n/a | 'argument to the interpreter) is a code block. A script command ' |

4167 | n/a | '(a\n' |

4168 | n/a | 'command specified on the interpreter command line with the ' |

4169 | n/a | "'**-c**'\n" |

4170 | n/a | 'option) is a code block. The string argument passed to the ' |

4171 | n/a | 'built-in\n' |

4172 | n/a | 'functions "eval()" and "exec()" is a code block.\n' |

4173 | n/a | '\n' |

4174 | n/a | 'A code block is executed in an *execution frame*. A frame ' |

4175 | n/a | 'contains\n' |

4176 | n/a | 'some administrative information (used for debugging) and ' |

4177 | n/a | 'determines\n' |

4178 | n/a | "where and how execution continues after the code block's " |

4179 | n/a | 'execution has\n' |

4180 | n/a | 'completed.\n' |

4181 | n/a | '\n' |

4182 | n/a | '\n' |

4183 | n/a | 'Naming and binding\n' |

4184 | n/a | '==================\n' |

4185 | n/a | '\n' |

4186 | n/a | '\n' |

4187 | n/a | 'Binding of names\n' |

4188 | n/a | '----------------\n' |

4189 | n/a | '\n' |

4190 | n/a | '*Names* refer to objects. Names are introduced by name ' |

4191 | n/a | 'binding\n' |

4192 | n/a | 'operations.\n' |

4193 | n/a | '\n' |

4194 | n/a | 'The following constructs bind names: formal parameters to ' |

4195 | n/a | 'functions,\n' |

4196 | n/a | '"import" statements, class and function definitions (these bind ' |

4197 | n/a | 'the\n' |

4198 | n/a | 'class or function name in the defining block), and targets that ' |

4199 | n/a | 'are\n' |

4200 | n/a | 'identifiers if occurring in an assignment, "for" loop header, ' |

4201 | n/a | 'or after\n' |

4202 | n/a | '"as" in a "with" statement or "except" clause. The "import" ' |

4203 | n/a | 'statement\n' |

4204 | n/a | 'of the form "from ... import *" binds all names defined in the\n' |

4205 | n/a | 'imported module, except those beginning with an underscore. ' |

4206 | n/a | 'This form\n' |

4207 | n/a | 'may only be used at the module level.\n' |

4208 | n/a | '\n' |

4209 | n/a | 'A target occurring in a "del" statement is also considered ' |

4210 | n/a | 'bound for\n' |

4211 | n/a | 'this purpose (though the actual semantics are to unbind the ' |

4212 | n/a | 'name).\n' |

4213 | n/a | '\n' |

4214 | n/a | 'Each assignment or import statement occurs within a block ' |

4215 | n/a | 'defined by a\n' |

4216 | n/a | 'class or function definition or at the module level (the ' |

4217 | n/a | 'top-level\n' |

4218 | n/a | 'code block).\n' |

4219 | n/a | '\n' |

4220 | n/a | 'If a name is bound in a block, it is a local variable of that ' |

4221 | n/a | 'block,\n' |

4222 | n/a | 'unless declared as "nonlocal" or "global". If a name is bound ' |

4223 | n/a | 'at the\n' |

4224 | n/a | 'module level, it is a global variable. (The variables of the ' |

4225 | n/a | 'module\n' |

4226 | n/a | 'code block are local and global.) If a variable is used in a ' |

4227 | n/a | 'code\n' |

4228 | n/a | 'block but not defined there, it is a *free variable*.\n' |

4229 | n/a | '\n' |

4230 | n/a | 'Each occurrence of a name in the program text refers to the ' |

4231 | n/a | '*binding*\n' |

4232 | n/a | 'of that name established by the following name resolution ' |

4233 | n/a | 'rules.\n' |

4234 | n/a | '\n' |

4235 | n/a | '\n' |

4236 | n/a | 'Resolution of names\n' |

4237 | n/a | '-------------------\n' |

4238 | n/a | '\n' |

4239 | n/a | 'A *scope* defines the visibility of a name within a block. If ' |

4240 | n/a | 'a local\n' |

4241 | n/a | 'variable is defined in a block, its scope includes that block. ' |

4242 | n/a | 'If the\n' |

4243 | n/a | 'definition occurs in a function block, the scope extends to any ' |

4244 | n/a | 'blocks\n' |

4245 | n/a | 'contained within the defining one, unless a contained block ' |

4246 | n/a | 'introduces\n' |

4247 | n/a | 'a different binding for the name.\n' |

4248 | n/a | '\n' |

4249 | n/a | 'When a name is used in a code block, it is resolved using the ' |

4250 | n/a | 'nearest\n' |

4251 | n/a | 'enclosing scope. The set of all such scopes visible to a code ' |

4252 | n/a | 'block\n' |

4253 | n/a | "is called the block's *environment*.\n" |

4254 | n/a | '\n' |

4255 | n/a | 'When a name is not found at all, a "NameError" exception is ' |

4256 | n/a | 'raised. If\n' |

4257 | n/a | 'the current scope is a function scope, and the name refers to a ' |

4258 | n/a | 'local\n' |

4259 | n/a | 'variable that has not yet been bound to a value at the point ' |

4260 | n/a | 'where the\n' |

4261 | n/a | 'name is used, an "UnboundLocalError" exception is raised.\n' |

4262 | n/a | '"UnboundLocalError" is a subclass of "NameError".\n' |

4263 | n/a | '\n' |

4264 | n/a | 'If a name binding operation occurs anywhere within a code ' |

4265 | n/a | 'block, all\n' |

4266 | n/a | 'uses of the name within the block are treated as references to ' |

4267 | n/a | 'the\n' |

4268 | n/a | 'current block. This can lead to errors when a name is used ' |

4269 | n/a | 'within a\n' |

4270 | n/a | 'block before it is bound. This rule is subtle. Python lacks\n' |

4271 | n/a | 'declarations and allows name binding operations to occur ' |

4272 | n/a | 'anywhere\n' |

4273 | n/a | 'within a code block. The local variables of a code block can ' |

4274 | n/a | 'be\n' |

4275 | n/a | 'determined by scanning the entire text of the block for name ' |

4276 | n/a | 'binding\n' |

4277 | n/a | 'operations.\n' |

4278 | n/a | '\n' |

4279 | n/a | 'If the "global" statement occurs within a block, all uses of ' |

4280 | n/a | 'the name\n' |

4281 | n/a | 'specified in the statement refer to the binding of that name in ' |

4282 | n/a | 'the\n' |

4283 | n/a | 'top-level namespace. Names are resolved in the top-level ' |

4284 | n/a | 'namespace by\n' |

4285 | n/a | 'searching the global namespace, i.e. the namespace of the ' |

4286 | n/a | 'module\n' |

4287 | n/a | 'containing the code block, and the builtins namespace, the ' |

4288 | n/a | 'namespace\n' |

4289 | n/a | 'of the module "builtins". The global namespace is searched ' |

4290 | n/a | 'first. If\n' |

4291 | n/a | 'the name is not found there, the builtins namespace is ' |

4292 | n/a | 'searched. The\n' |

4293 | n/a | '"global" statement must precede all uses of the name.\n' |

4294 | n/a | '\n' |

4295 | n/a | 'The "global" statement has the same scope as a name binding ' |

4296 | n/a | 'operation\n' |

4297 | n/a | 'in the same block. If the nearest enclosing scope for a free ' |

4298 | n/a | 'variable\n' |

4299 | n/a | 'contains a global statement, the free variable is treated as a ' |

4300 | n/a | 'global.\n' |

4301 | n/a | '\n' |

4302 | n/a | 'The "nonlocal" statement causes corresponding names to refer ' |

4303 | n/a | 'to\n' |

4304 | n/a | 'previously bound variables in the nearest enclosing function ' |

4305 | n/a | 'scope.\n' |

4306 | n/a | '"SyntaxError" is raised at compile time if the given name does ' |

4307 | n/a | 'not\n' |

4308 | n/a | 'exist in any enclosing function scope.\n' |

4309 | n/a | '\n' |

4310 | n/a | 'The namespace for a module is automatically created the first ' |

4311 | n/a | 'time a\n' |

4312 | n/a | 'module is imported. The main module for a script is always ' |

4313 | n/a | 'called\n' |

4314 | n/a | '"__main__".\n' |

4315 | n/a | '\n' |

4316 | n/a | 'Class definition blocks and arguments to "exec()" and "eval()" ' |

4317 | n/a | 'are\n' |

4318 | n/a | 'special in the context of name resolution. A class definition ' |

4319 | n/a | 'is an\n' |

4320 | n/a | 'executable statement that may use and define names. These ' |

4321 | n/a | 'references\n' |

4322 | n/a | 'follow the normal rules for name resolution with an exception ' |

4323 | n/a | 'that\n' |

4324 | n/a | 'unbound local variables are looked up in the global namespace. ' |

4325 | n/a | 'The\n' |

4326 | n/a | 'namespace of the class definition becomes the attribute ' |

4327 | n/a | 'dictionary of\n' |

4328 | n/a | 'the class. The scope of names defined in a class block is ' |

4329 | n/a | 'limited to\n' |

4330 | n/a | 'the class block; it does not extend to the code blocks of ' |

4331 | n/a | 'methods --\n' |

4332 | n/a | 'this includes comprehensions and generator expressions since ' |

4333 | n/a | 'they are\n' |

4334 | n/a | 'implemented using a function scope. This means that the ' |

4335 | n/a | 'following\n' |

4336 | n/a | 'will fail:\n' |

4337 | n/a | '\n' |

4338 | n/a | ' class A:\n' |

4339 | n/a | ' a = 42\n' |

4340 | n/a | ' b = list(a + i for i in range(10))\n' |

4341 | n/a | '\n' |

4342 | n/a | '\n' |

4343 | n/a | 'Builtins and restricted execution\n' |

4344 | n/a | '---------------------------------\n' |

4345 | n/a | '\n' |

4346 | n/a | 'The builtins namespace associated with the execution of a code ' |

4347 | n/a | 'block\n' |

4348 | n/a | 'is actually found by looking up the name "__builtins__" in its ' |

4349 | n/a | 'global\n' |

4350 | n/a | 'namespace; this should be a dictionary or a module (in the ' |

4351 | n/a | 'latter case\n' |

4352 | n/a | "the module's dictionary is used). By default, when in the " |

4353 | n/a | '"__main__"\n' |

4354 | n/a | 'module, "__builtins__" is the built-in module "builtins"; when ' |

4355 | n/a | 'in any\n' |

4356 | n/a | 'other module, "__builtins__" is an alias for the dictionary of ' |

4357 | n/a | 'the\n' |

4358 | n/a | '"builtins" module itself. "__builtins__" can be set to a ' |

4359 | n/a | 'user-created\n' |

4360 | n/a | 'dictionary to create a weak form of restricted execution.\n' |

4361 | n/a | '\n' |

4362 | n/a | '**CPython implementation detail:** Users should not touch\n' |

4363 | n/a | '"__builtins__"; it is strictly an implementation detail. ' |

4364 | n/a | 'Users\n' |

4365 | n/a | 'wanting to override values in the builtins namespace should ' |

4366 | n/a | '"import"\n' |

4367 | n/a | 'the "builtins" module and modify its attributes appropriately.\n' |

4368 | n/a | '\n' |

4369 | n/a | '\n' |

4370 | n/a | 'Interaction with dynamic features\n' |

4371 | n/a | '---------------------------------\n' |

4372 | n/a | '\n' |

4373 | n/a | 'Name resolution of free variables occurs at runtime, not at ' |

4374 | n/a | 'compile\n' |

4375 | n/a | 'time. This means that the following code will print 42:\n' |

4376 | n/a | '\n' |

4377 | n/a | ' i = 10\n' |

4378 | n/a | ' def f():\n' |

4379 | n/a | ' print(i)\n' |

4380 | n/a | ' i = 42\n' |

4381 | n/a | ' f()\n' |

4382 | n/a | '\n' |

4383 | n/a | 'There are several cases where Python statements are illegal ' |

4384 | n/a | 'when used\n' |

4385 | n/a | 'in conjunction with nested scopes that contain free variables.\n' |

4386 | n/a | '\n' |

4387 | n/a | 'If a variable is referenced in an enclosing scope, it is ' |

4388 | n/a | 'illegal to\n' |

4389 | n/a | 'delete the name. An error will be reported at compile time.\n' |

4390 | n/a | '\n' |

4391 | n/a | 'The "eval()" and "exec()" functions do not have access to the ' |

4392 | n/a | 'full\n' |

4393 | n/a | 'environment for resolving names. Names may be resolved in the ' |

4394 | n/a | 'local\n' |

4395 | n/a | 'and global namespaces of the caller. Free variables are not ' |

4396 | n/a | 'resolved\n' |

4397 | n/a | 'in the nearest enclosing namespace, but in the global ' |

4398 | n/a | 'namespace. [1]\n' |

4399 | n/a | 'The "exec()" and "eval()" functions have optional arguments to\n' |

4400 | n/a | 'override the global and local namespace. If only one namespace ' |

4401 | n/a | 'is\n' |

4402 | n/a | 'specified, it is used for both.\n' |

4403 | n/a | '\n' |

4404 | n/a | '\n' |

4405 | n/a | 'Exceptions\n' |

4406 | n/a | '==========\n' |

4407 | n/a | '\n' |

4408 | n/a | 'Exceptions are a means of breaking out of the normal flow of ' |

4409 | n/a | 'control\n' |

4410 | n/a | 'of a code block in order to handle errors or other exceptional\n' |

4411 | n/a | 'conditions. An exception is *raised* at the point where the ' |

4412 | n/a | 'error is\n' |

4413 | n/a | 'detected; it may be *handled* by the surrounding code block or ' |

4414 | n/a | 'by any\n' |

4415 | n/a | 'code block that directly or indirectly invoked the code block ' |

4416 | n/a | 'where\n' |

4417 | n/a | 'the error occurred.\n' |

4418 | n/a | '\n' |

4419 | n/a | 'The Python interpreter raises an exception when it detects a ' |

4420 | n/a | 'run-time\n' |

4421 | n/a | 'error (such as division by zero). A Python program can also\n' |

4422 | n/a | 'explicitly raise an exception with the "raise" statement. ' |

4423 | n/a | 'Exception\n' |

4424 | n/a | 'handlers are specified with the "try" ... "except" statement. ' |

4425 | n/a | 'The\n' |

4426 | n/a | '"finally" clause of such a statement can be used to specify ' |

4427 | n/a | 'cleanup\n' |

4428 | n/a | 'code which does not handle the exception, but is executed ' |

4429 | n/a | 'whether an\n' |

4430 | n/a | 'exception occurred or not in the preceding code.\n' |

4431 | n/a | '\n' |

4432 | n/a | 'Python uses the "termination" model of error handling: an ' |

4433 | n/a | 'exception\n' |

4434 | n/a | 'handler can find out what happened and continue execution at an ' |

4435 | n/a | 'outer\n' |

4436 | n/a | 'level, but it cannot repair the cause of the error and retry ' |

4437 | n/a | 'the\n' |

4438 | n/a | 'failing operation (except by re-entering the offending piece of ' |

4439 | n/a | 'code\n' |

4440 | n/a | 'from the top).\n' |

4441 | n/a | '\n' |

4442 | n/a | 'When an exception is not handled at all, the interpreter ' |

4443 | n/a | 'terminates\n' |

4444 | n/a | 'execution of the program, or returns to its interactive main ' |

4445 | n/a | 'loop. In\n' |

4446 | n/a | 'either case, it prints a stack backtrace, except when the ' |

4447 | n/a | 'exception is\n' |

4448 | n/a | '"SystemExit".\n' |

4449 | n/a | '\n' |

4450 | n/a | 'Exceptions are identified by class instances. The "except" ' |

4451 | n/a | 'clause is\n' |

4452 | n/a | 'selected depending on the class of the instance: it must ' |

4453 | n/a | 'reference the\n' |

4454 | n/a | 'class of the instance or a base class thereof. The instance ' |

4455 | n/a | 'can be\n' |

4456 | n/a | 'received by the handler and can carry additional information ' |

4457 | n/a | 'about the\n' |

4458 | n/a | 'exceptional condition.\n' |

4459 | n/a | '\n' |

4460 | n/a | 'Note: Exception messages are not part of the Python API. ' |

4461 | n/a | 'Their\n' |

4462 | n/a | ' contents may change from one version of Python to the next ' |

4463 | n/a | 'without\n' |

4464 | n/a | ' warning and should not be relied on by code which will run ' |

4465 | n/a | 'under\n' |

4466 | n/a | ' multiple versions of the interpreter.\n' |

4467 | n/a | '\n' |

4468 | n/a | 'See also the description of the "try" statement in section The ' |

4469 | n/a | 'try\n' |

4470 | n/a | 'statement and "raise" statement in section The raise ' |

4471 | n/a | 'statement.\n' |

4472 | n/a | '\n' |

4473 | n/a | '-[ Footnotes ]-\n' |

4474 | n/a | '\n' |

4475 | n/a | '[1] This limitation occurs because the code that is executed ' |

4476 | n/a | 'by\n' |

4477 | n/a | ' these operations is not available at the time the module ' |

4478 | n/a | 'is\n' |

4479 | n/a | ' compiled.\n', |

4480 | n/a | 'exprlists': '\n' |

4481 | n/a | 'Expression lists\n' |

4482 | n/a | '****************\n' |

4483 | n/a | '\n' |

4484 | n/a | ' expression_list ::= expression ( "," expression )* [","]\n' |

4485 | n/a | ' starred_list ::= starred_item ( "," starred_item )* ' |

4486 | n/a | '[","]\n' |

4487 | n/a | ' starred_expression ::= expression | ( starred_item "," )* ' |

4488 | n/a | '[starred_item]\n' |

4489 | n/a | ' starred_item ::= expression | "*" or_expr\n' |

4490 | n/a | '\n' |

4491 | n/a | 'Except when part of a list or set display, an expression list\n' |

4492 | n/a | 'containing at least one comma yields a tuple. The length of ' |

4493 | n/a | 'the tuple\n' |

4494 | n/a | 'is the number of expressions in the list. The expressions are\n' |

4495 | n/a | 'evaluated from left to right.\n' |

4496 | n/a | '\n' |

4497 | n/a | 'An asterisk "*" denotes *iterable unpacking*. Its operand must ' |

4498 | n/a | 'be an\n' |

4499 | n/a | '*iterable*. The iterable is expanded into a sequence of items, ' |

4500 | n/a | 'which\n' |

4501 | n/a | 'are included in the new tuple, list, or set, at the site of ' |

4502 | n/a | 'the\n' |

4503 | n/a | 'unpacking.\n' |

4504 | n/a | '\n' |

4505 | n/a | 'New in version 3.5: Iterable unpacking in expression lists, ' |

4506 | n/a | 'originally\n' |

4507 | n/a | 'proposed by **PEP 448**.\n' |

4508 | n/a | '\n' |

4509 | n/a | 'The trailing comma is required only to create a single tuple ' |

4510 | n/a | '(a.k.a. a\n' |

4511 | n/a | '*singleton*); it is optional in all other cases. A single ' |

4512 | n/a | 'expression\n' |

4513 | n/a | "without a trailing comma doesn't create a tuple, but rather " |

4514 | n/a | 'yields the\n' |

4515 | n/a | 'value of that expression. (To create an empty tuple, use an ' |

4516 | n/a | 'empty pair\n' |

4517 | n/a | 'of parentheses: "()".)\n', |

4518 | n/a | 'floating': '\n' |

4519 | n/a | 'Floating point literals\n' |

4520 | n/a | '***********************\n' |

4521 | n/a | '\n' |

4522 | n/a | 'Floating point literals are described by the following lexical\n' |

4523 | n/a | 'definitions:\n' |

4524 | n/a | '\n' |

4525 | n/a | ' floatnumber ::= pointfloat | exponentfloat\n' |

4526 | n/a | ' pointfloat ::= [digitpart] fraction | digitpart "."\n' |

4527 | n/a | ' exponentfloat ::= (digitpart | pointfloat) exponent\n' |

4528 | n/a | ' digitpart ::= digit (["_"] digit)*\n' |

4529 | n/a | ' fraction ::= "." digitpart\n' |

4530 | n/a | ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n' |

4531 | n/a | '\n' |

4532 | n/a | 'Note that the integer and exponent parts are always interpreted ' |

4533 | n/a | 'using\n' |

4534 | n/a | 'radix 10. For example, "077e010" is legal, and denotes the same ' |

4535 | n/a | 'number\n' |

4536 | n/a | 'as "77e10". The allowed range of floating point literals is\n' |

4537 | n/a | 'implementation-dependent. As in integer literals, underscores ' |

4538 | n/a | 'are\n' |

4539 | n/a | 'supported for digit grouping.\n' |

4540 | n/a | '\n' |

4541 | n/a | 'Some examples of floating point literals:\n' |

4542 | n/a | '\n' |

4543 | n/a | ' 3.14 10. .001 1e100 3.14e-10 0e0 ' |

4544 | n/a | '3.14_15_93\n' |

4545 | n/a | '\n' |

4546 | n/a | 'Note that numeric literals do not include a sign; a phrase like ' |

4547 | n/a | '"-1"\n' |

4548 | n/a | 'is actually an expression composed of the unary operator "-" and ' |

4549 | n/a | 'the\n' |

4550 | n/a | 'literal "1".\n' |

4551 | n/a | '\n' |

4552 | n/a | 'Changed in version 3.6: Underscores are now allowed for ' |

4553 | n/a | 'grouping\n' |

4554 | n/a | 'purposes in literals.\n', |

4555 | n/a | 'for': '\n' |

4556 | n/a | 'The "for" statement\n' |

4557 | n/a | '*******************\n' |

4558 | n/a | '\n' |

4559 | n/a | 'The "for" statement is used to iterate over the elements of a ' |

4560 | n/a | 'sequence\n' |

4561 | n/a | '(such as a string, tuple or list) or other iterable object:\n' |

4562 | n/a | '\n' |

4563 | n/a | ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' |

4564 | n/a | ' ["else" ":" suite]\n' |

4565 | n/a | '\n' |

4566 | n/a | 'The expression list is evaluated once; it should yield an iterable\n' |

4567 | n/a | 'object. An iterator is created for the result of the\n' |

4568 | n/a | '"expression_list". The suite is then executed once for each item\n' |

4569 | n/a | 'provided by the iterator, in the order returned by the iterator. ' |

4570 | n/a | 'Each\n' |

4571 | n/a | 'item in turn is assigned to the target list using the standard rules\n' |

4572 | n/a | 'for assignments (see Assignment statements), and then the suite is\n' |

4573 | n/a | 'executed. When the items are exhausted (which is immediately when ' |

4574 | n/a | 'the\n' |

4575 | n/a | 'sequence is empty or an iterator raises a "StopIteration" ' |

4576 | n/a | 'exception),\n' |

4577 | n/a | 'the suite in the "else" clause, if present, is executed, and the ' |

4578 | n/a | 'loop\n' |

4579 | n/a | 'terminates.\n' |

4580 | n/a | '\n' |

4581 | n/a | 'A "break" statement executed in the first suite terminates the loop\n' |

4582 | n/a | 'without executing the "else" clause\'s suite. A "continue" ' |

4583 | n/a | 'statement\n' |

4584 | n/a | 'executed in the first suite skips the rest of the suite and ' |

4585 | n/a | 'continues\n' |

4586 | n/a | 'with the next item, or with the "else" clause if there is no next\n' |

4587 | n/a | 'item.\n' |

4588 | n/a | '\n' |

4589 | n/a | 'The for-loop makes assignments to the variables(s) in the target ' |

4590 | n/a | 'list.\n' |

4591 | n/a | 'This overwrites all previous assignments to those variables ' |

4592 | n/a | 'including\n' |

4593 | n/a | 'those made in the suite of the for-loop:\n' |

4594 | n/a | '\n' |

4595 | n/a | ' for i in range(10):\n' |

4596 | n/a | ' print(i)\n' |

4597 | n/a | ' i = 5 # this will not affect the for-loop\n' |

4598 | n/a | ' # because i will be overwritten with the ' |

4599 | n/a | 'next\n' |

4600 | n/a | ' # index in the range\n' |

4601 | n/a | '\n' |

4602 | n/a | 'Names in the target list are not deleted when the loop is finished,\n' |

4603 | n/a | 'but if the sequence is empty, they will not have been assigned to at\n' |

4604 | n/a | 'all by the loop. Hint: the built-in function "range()" returns an\n' |

4605 | n/a | 'iterator of integers suitable to emulate the effect of Pascal\'s "for ' |

4606 | n/a | 'i\n' |

4607 | n/a | ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n' |

4608 | n/a | '\n' |

4609 | n/a | 'Note: There is a subtlety when the sequence is being modified by the\n' |

4610 | n/a | ' loop (this can only occur for mutable sequences, i.e. lists). An\n' |

4611 | n/a | ' internal counter is used to keep track of which item is used next,\n' |

4612 | n/a | ' and this is incremented on each iteration. When this counter has\n' |

4613 | n/a | ' reached the length of the sequence the loop terminates. This ' |

4614 | n/a | 'means\n' |

4615 | n/a | ' that if the suite deletes the current (or a previous) item from ' |

4616 | n/a | 'the\n' |

4617 | n/a | ' sequence, the next item will be skipped (since it gets the index ' |

4618 | n/a | 'of\n' |

4619 | n/a | ' the current item which has already been treated). Likewise, if ' |

4620 | n/a | 'the\n' |

4621 | n/a | ' suite inserts an item in the sequence before the current item, the\n' |

4622 | n/a | ' current item will be treated again the next time through the loop.\n' |

4623 | n/a | ' This can lead to nasty bugs that can be avoided by making a\n' |

4624 | n/a | ' temporary copy using a slice of the whole sequence, e.g.,\n' |

4625 | n/a | '\n' |

4626 | n/a | ' for x in a[:]:\n' |

4627 | n/a | ' if x < 0: a.remove(x)\n', |

4628 | n/a | 'formatstrings': '\n' |

4629 | n/a | 'Format String Syntax\n' |

4630 | n/a | '********************\n' |

4631 | n/a | '\n' |

4632 | n/a | 'The "str.format()" method and the "Formatter" class share ' |

4633 | n/a | 'the same\n' |

4634 | n/a | 'syntax for format strings (although in the case of ' |

4635 | n/a | '"Formatter",\n' |

4636 | n/a | 'subclasses can define their own format string syntax). The ' |

4637 | n/a | 'syntax is\n' |

4638 | n/a | 'related to that of formatted string literals, but there ' |

4639 | n/a | 'are\n' |

4640 | n/a | 'differences.\n' |

4641 | n/a | '\n' |

4642 | n/a | 'Format strings contain "replacement fields" surrounded by ' |

4643 | n/a | 'curly braces\n' |

4644 | n/a | '"{}". Anything that is not contained in braces is ' |

4645 | n/a | 'considered literal\n' |

4646 | n/a | 'text, which is copied unchanged to the output. If you need ' |

4647 | n/a | 'to include\n' |

4648 | n/a | 'a brace character in the literal text, it can be escaped by ' |

4649 | n/a | 'doubling:\n' |

4650 | n/a | '"{{" and "}}".\n' |

4651 | n/a | '\n' |

4652 | n/a | 'The grammar for a replacement field is as follows:\n' |

4653 | n/a | '\n' |

4654 | n/a | ' replacement_field ::= "{" [field_name] ["!" ' |

4655 | n/a | 'conversion] [":" format_spec] "}"\n' |

4656 | n/a | ' field_name ::= arg_name ("." attribute_name | ' |

4657 | n/a | '"[" element_index "]")*\n' |

4658 | n/a | ' arg_name ::= [identifier | integer]\n' |

4659 | n/a | ' attribute_name ::= identifier\n' |

4660 | n/a | ' element_index ::= integer | index_string\n' |

4661 | n/a | ' index_string ::= <any source character except ' |

4662 | n/a | '"]"> +\n' |

4663 | n/a | ' conversion ::= "r" | "s" | "a"\n' |

4664 | n/a | ' format_spec ::= <described in the next ' |

4665 | n/a | 'section>\n' |

4666 | n/a | '\n' |

4667 | n/a | 'In less formal terms, the replacement field can start with ' |

4668 | n/a | 'a\n' |

4669 | n/a | '*field_name* that specifies the object whose value is to be ' |

4670 | n/a | 'formatted\n' |

4671 | n/a | 'and inserted into the output instead of the replacement ' |

4672 | n/a | 'field. The\n' |

4673 | n/a | '*field_name* is optionally followed by a *conversion* ' |

4674 | n/a | 'field, which is\n' |

4675 | n/a | 'preceded by an exclamation point "\'!\'", and a ' |

4676 | n/a | '*format_spec*, which is\n' |

4677 | n/a | 'preceded by a colon "\':\'". These specify a non-default ' |

4678 | n/a | 'format for the\n' |

4679 | n/a | 'replacement value.\n' |

4680 | n/a | '\n' |

4681 | n/a | 'See also the Format Specification Mini-Language section.\n' |

4682 | n/a | '\n' |

4683 | n/a | 'The *field_name* itself begins with an *arg_name* that is ' |

4684 | n/a | 'either a\n' |

4685 | n/a | "number or a keyword. If it's a number, it refers to a " |

4686 | n/a | 'positional\n' |

4687 | n/a | "argument, and if it's a keyword, it refers to a named " |

4688 | n/a | 'keyword\n' |

4689 | n/a | 'argument. If the numerical arg_names in a format string ' |

4690 | n/a | 'are 0, 1, 2,\n' |

4691 | n/a | '... in sequence, they can all be omitted (not just some) ' |

4692 | n/a | 'and the\n' |

4693 | n/a | 'numbers 0, 1, 2, ... will be automatically inserted in that ' |

4694 | n/a | 'order.\n' |

4695 | n/a | 'Because *arg_name* is not quote-delimited, it is not ' |

4696 | n/a | 'possible to\n' |

4697 | n/a | 'specify arbitrary dictionary keys (e.g., the strings ' |

4698 | n/a | '"\'10\'" or\n' |

4699 | n/a | '"\':-]\'") within a format string. The *arg_name* can be ' |

4700 | n/a | 'followed by any\n' |

4701 | n/a | 'number of index or attribute expressions. An expression of ' |

4702 | n/a | 'the form\n' |

4703 | n/a | '"\'.name\'" selects the named attribute using "getattr()", ' |

4704 | n/a | 'while an\n' |

4705 | n/a | 'expression of the form "\'[index]\'" does an index lookup ' |

4706 | n/a | 'using\n' |

4707 | n/a | '"__getitem__()".\n' |

4708 | n/a | '\n' |

4709 | n/a | 'Changed in version 3.1: The positional argument specifiers ' |

4710 | n/a | 'can be\n' |

4711 | n/a | 'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n' |

4712 | n/a | '\n' |

4713 | n/a | 'Some simple format string examples:\n' |

4714 | n/a | '\n' |

4715 | n/a | ' "First, thou shalt count to {0}" # References first ' |

4716 | n/a | 'positional argument\n' |

4717 | n/a | ' "Bring me a {}" # Implicitly ' |

4718 | n/a | 'references the first positional argument\n' |

4719 | n/a | ' "From {} to {}" # Same as "From {0} to ' |

4720 | n/a | '{1}"\n' |

4721 | n/a | ' "My quest is {name}" # References keyword ' |

4722 | n/a | "argument 'name'\n" |

4723 | n/a | ' "Weight in tons {0.weight}" # \'weight\' attribute ' |

4724 | n/a | 'of first positional arg\n' |

4725 | n/a | ' "Units destroyed: {players[0]}" # First element of ' |

4726 | n/a | "keyword argument 'players'.\n" |

4727 | n/a | '\n' |

4728 | n/a | 'The *conversion* field causes a type coercion before ' |

4729 | n/a | 'formatting.\n' |

4730 | n/a | 'Normally, the job of formatting a value is done by the ' |

4731 | n/a | '"__format__()"\n' |

4732 | n/a | 'method of the value itself. However, in some cases it is ' |

4733 | n/a | 'desirable to\n' |

4734 | n/a | 'force a type to be formatted as a string, overriding its ' |

4735 | n/a | 'own\n' |

4736 | n/a | 'definition of formatting. By converting the value to a ' |

4737 | n/a | 'string before\n' |

4738 | n/a | 'calling "__format__()", the normal formatting logic is ' |

4739 | n/a | 'bypassed.\n' |

4740 | n/a | '\n' |

4741 | n/a | 'Three conversion flags are currently supported: "\'!s\'" ' |

4742 | n/a | 'which calls\n' |

4743 | n/a | '"str()" on the value, "\'!r\'" which calls "repr()" and ' |

4744 | n/a | '"\'!a\'" which\n' |

4745 | n/a | 'calls "ascii()".\n' |

4746 | n/a | '\n' |

4747 | n/a | 'Some examples:\n' |

4748 | n/a | '\n' |

4749 | n/a | ' "Harold\'s a clever {0!s}" # Calls str() on the ' |

4750 | n/a | 'argument first\n' |

4751 | n/a | ' "Bring out the holy {name!r}" # Calls repr() on the ' |

4752 | n/a | 'argument first\n' |

4753 | n/a | ' "More {!a}" # Calls ascii() on the ' |

4754 | n/a | 'argument first\n' |

4755 | n/a | '\n' |

4756 | n/a | 'The *format_spec* field contains a specification of how the ' |

4757 | n/a | 'value\n' |

4758 | n/a | 'should be presented, including such details as field width, ' |

4759 | n/a | 'alignment,\n' |

4760 | n/a | 'padding, decimal precision and so on. Each value type can ' |

4761 | n/a | 'define its\n' |

4762 | n/a | 'own "formatting mini-language" or interpretation of the ' |

4763 | n/a | '*format_spec*.\n' |

4764 | n/a | '\n' |

4765 | n/a | 'Most built-in types support a common formatting ' |

4766 | n/a | 'mini-language, which\n' |

4767 | n/a | 'is described in the next section.\n' |

4768 | n/a | '\n' |

4769 | n/a | 'A *format_spec* field can also include nested replacement ' |

4770 | n/a | 'fields\n' |

4771 | n/a | 'within it. These nested replacement fields may contain a ' |

4772 | n/a | 'field name,\n' |

4773 | n/a | 'conversion flag and format specification, but deeper ' |

4774 | n/a | 'nesting is not\n' |

4775 | n/a | 'allowed. The replacement fields within the format_spec ' |

4776 | n/a | 'are\n' |

4777 | n/a | 'substituted before the *format_spec* string is interpreted. ' |

4778 | n/a | 'This\n' |

4779 | n/a | 'allows the formatting of a value to be dynamically ' |

4780 | n/a | 'specified.\n' |

4781 | n/a | '\n' |

4782 | n/a | 'See the Format examples section for some examples.\n' |

4783 | n/a | '\n' |

4784 | n/a | '\n' |

4785 | n/a | 'Format Specification Mini-Language\n' |

4786 | n/a | '==================================\n' |

4787 | n/a | '\n' |

4788 | n/a | '"Format specifications" are used within replacement fields ' |

4789 | n/a | 'contained\n' |

4790 | n/a | 'within a format string to define how individual values are ' |

4791 | n/a | 'presented\n' |

4792 | n/a | '(see Format String Syntax and Formatted string literals). ' |

4793 | n/a | 'They can\n' |

4794 | n/a | 'also be passed directly to the built-in "format()" ' |

4795 | n/a | 'function. Each\n' |

4796 | n/a | 'formattable type may define how the format specification is ' |

4797 | n/a | 'to be\n' |

4798 | n/a | 'interpreted.\n' |

4799 | n/a | '\n' |

4800 | n/a | 'Most built-in types implement the following options for ' |

4801 | n/a | 'format\n' |

4802 | n/a | 'specifications, although some of the formatting options are ' |

4803 | n/a | 'only\n' |

4804 | n/a | 'supported by the numeric types.\n' |

4805 | n/a | '\n' |

4806 | n/a | 'A general convention is that an empty format string ("""") ' |

4807 | n/a | 'produces\n' |

4808 | n/a | 'the same result as if you had called "str()" on the value. ' |

4809 | n/a | 'A non-empty\n' |

4810 | n/a | 'format string typically modifies the result.\n' |

4811 | n/a | '\n' |

4812 | n/a | 'The general form of a *standard format specifier* is:\n' |

4813 | n/a | '\n' |

4814 | n/a | ' format_spec ::= ' |

4815 | n/a | '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n' |

4816 | n/a | ' fill ::= <any character>\n' |

4817 | n/a | ' align ::= "<" | ">" | "=" | "^"\n' |

4818 | n/a | ' sign ::= "+" | "-" | " "\n' |

4819 | n/a | ' width ::= integer\n' |

4820 | n/a | ' grouping_option ::= "_" | ","\n' |

4821 | n/a | ' precision ::= integer\n' |

4822 | n/a | ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' |

4823 | n/a | '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' |

4824 | n/a | '\n' |

4825 | n/a | 'If a valid *align* value is specified, it can be preceded ' |

4826 | n/a | 'by a *fill*\n' |

4827 | n/a | 'character that can be any character and defaults to a space ' |

4828 | n/a | 'if\n' |

4829 | n/a | 'omitted. It is not possible to use a literal curly brace ' |

4830 | n/a | '(""{"" or\n' |

4831 | n/a | '""}"") as the *fill* character in a formatted string ' |

4832 | n/a | 'literal or when\n' |

4833 | n/a | 'using the "str.format()" method. However, it is possible ' |

4834 | n/a | 'to insert a\n' |

4835 | n/a | 'curly brace with a nested replacement field. This ' |

4836 | n/a | "limitation doesn't\n" |

4837 | n/a | 'affect the "format()" function.\n' |

4838 | n/a | '\n' |

4839 | n/a | 'The meaning of the various alignment options is as ' |

4840 | n/a | 'follows:\n' |

4841 | n/a | '\n' |

4842 | n/a | ' ' |

4843 | n/a | '+-----------+------------------------------------------------------------+\n' |

4844 | n/a | ' | Option | ' |

4845 | n/a | 'Meaning ' |

4846 | n/a | '|\n' |

4847 | n/a | ' ' |

4848 | n/a | '+===========+============================================================+\n' |

4849 | n/a | ' | "\'<\'" | Forces the field to be left-aligned ' |

4850 | n/a | 'within the available |\n' |

4851 | n/a | ' | | space (this is the default for most ' |

4852 | n/a | 'objects). |\n' |

4853 | n/a | ' ' |

4854 | n/a | '+-----------+------------------------------------------------------------+\n' |

4855 | n/a | ' | "\'>\'" | Forces the field to be right-aligned ' |

4856 | n/a | 'within the available |\n' |

4857 | n/a | ' | | space (this is the default for ' |

4858 | n/a | 'numbers). |\n' |

4859 | n/a | ' ' |

4860 | n/a | '+-----------+------------------------------------------------------------+\n' |

4861 | n/a | ' | "\'=\'" | Forces the padding to be placed after ' |

4862 | n/a | 'the sign (if any) |\n' |

4863 | n/a | ' | | but before the digits. This is used for ' |

4864 | n/a | 'printing fields |\n' |

4865 | n/a | " | | in the form '+000000120'. This alignment " |

4866 | n/a | 'option is only |\n' |

4867 | n/a | ' | | valid for numeric types. It becomes the ' |

4868 | n/a | "default when '0' |\n" |

4869 | n/a | ' | | immediately precedes the field ' |

4870 | n/a | 'width. |\n' |

4871 | n/a | ' ' |

4872 | n/a | '+-----------+------------------------------------------------------------+\n' |

4873 | n/a | ' | "\'^\'" | Forces the field to be centered within ' |

4874 | n/a | 'the available |\n' |

4875 | n/a | ' | | ' |

4876 | n/a | 'space. ' |

4877 | n/a | '|\n' |

4878 | n/a | ' ' |

4879 | n/a | '+-----------+------------------------------------------------------------+\n' |

4880 | n/a | '\n' |

4881 | n/a | 'Note that unless a minimum field width is defined, the ' |

4882 | n/a | 'field width\n' |

4883 | n/a | 'will always be the same size as the data to fill it, so ' |

4884 | n/a | 'that the\n' |

4885 | n/a | 'alignment option has no meaning in this case.\n' |

4886 | n/a | '\n' |

4887 | n/a | 'The *sign* option is only valid for number types, and can ' |

4888 | n/a | 'be one of\n' |

4889 | n/a | 'the following:\n' |

4890 | n/a | '\n' |

4891 | n/a | ' ' |

4892 | n/a | '+-----------+------------------------------------------------------------+\n' |

4893 | n/a | ' | Option | ' |

4894 | n/a | 'Meaning ' |

4895 | n/a | '|\n' |

4896 | n/a | ' ' |

4897 | n/a | '+===========+============================================================+\n' |

4898 | n/a | ' | "\'+\'" | indicates that a sign should be used for ' |

4899 | n/a | 'both positive as |\n' |

4900 | n/a | ' | | well as negative ' |

4901 | n/a | 'numbers. |\n' |

4902 | n/a | ' ' |

4903 | n/a | '+-----------+------------------------------------------------------------+\n' |

4904 | n/a | ' | "\'-\'" | indicates that a sign should be used ' |

4905 | n/a | 'only for negative |\n' |

4906 | n/a | ' | | numbers (this is the default ' |

4907 | n/a | 'behavior). |\n' |

4908 | n/a | ' ' |

4909 | n/a | '+-----------+------------------------------------------------------------+\n' |

4910 | n/a | ' | space | indicates that a leading space should be ' |

4911 | n/a | 'used on positive |\n' |

4912 | n/a | ' | | numbers, and a minus sign on negative ' |

4913 | n/a | 'numbers. |\n' |

4914 | n/a | ' ' |

4915 | n/a | '+-----------+------------------------------------------------------------+\n' |

4916 | n/a | '\n' |

4917 | n/a | 'The "\'#\'" option causes the "alternate form" to be used ' |

4918 | n/a | 'for the\n' |

4919 | n/a | 'conversion. The alternate form is defined differently for ' |

4920 | n/a | 'different\n' |

4921 | n/a | 'types. This option is only valid for integer, float, ' |

4922 | n/a | 'complex and\n' |

4923 | n/a | 'Decimal types. For integers, when binary, octal, or ' |

4924 | n/a | 'hexadecimal output\n' |

4925 | n/a | 'is used, this option adds the prefix respective "\'0b\'", ' |

4926 | n/a | '"\'0o\'", or\n' |

4927 | n/a | '"\'0x\'" to the output value. For floats, complex and ' |

4928 | n/a | 'Decimal the\n' |

4929 | n/a | 'alternate form causes the result of the conversion to ' |

4930 | n/a | 'always contain a\n' |

4931 | n/a | 'decimal-point character, even if no digits follow it. ' |

4932 | n/a | 'Normally, a\n' |

4933 | n/a | 'decimal-point character appears in the result of these ' |

4934 | n/a | 'conversions\n' |

4935 | n/a | 'only if a digit follows it. In addition, for "\'g\'" and ' |

4936 | n/a | '"\'G\'"\n' |

4937 | n/a | 'conversions, trailing zeros are not removed from the ' |

4938 | n/a | 'result.\n' |

4939 | n/a | '\n' |

4940 | n/a | 'The "\',\'" option signals the use of a comma for a ' |

4941 | n/a | 'thousands separator.\n' |

4942 | n/a | 'For a locale aware separator, use the "\'n\'" integer ' |

4943 | n/a | 'presentation type\n' |

4944 | n/a | 'instead.\n' |

4945 | n/a | '\n' |

4946 | n/a | 'Changed in version 3.1: Added the "\',\'" option (see also ' |

4947 | n/a | '**PEP 378**).\n' |

4948 | n/a | '\n' |

4949 | n/a | 'The "\'_\'" option signals the use of an underscore for a ' |

4950 | n/a | 'thousands\n' |

4951 | n/a | 'separator for floating point presentation types and for ' |

4952 | n/a | 'integer\n' |

4953 | n/a | 'presentation type "\'d\'". For integer presentation types ' |

4954 | n/a | '"\'b\'", "\'o\'",\n' |

4955 | n/a | '"\'x\'", and "\'X\'", underscores will be inserted every 4 ' |

4956 | n/a | 'digits. For\n' |

4957 | n/a | 'other presentation types, specifying this option is an ' |

4958 | n/a | 'error.\n' |

4959 | n/a | '\n' |

4960 | n/a | 'Changed in version 3.6: Added the "\'_\'" option (see also ' |

4961 | n/a | '**PEP 515**).\n' |

4962 | n/a | '\n' |

4963 | n/a | '*width* is a decimal integer defining the minimum field ' |

4964 | n/a | 'width. If not\n' |

4965 | n/a | 'specified, then the field width will be determined by the ' |

4966 | n/a | 'content.\n' |

4967 | n/a | '\n' |

4968 | n/a | 'When no explicit alignment is given, preceding the *width* ' |

4969 | n/a | 'field by a\n' |

4970 | n/a | 'zero ("\'0\'") character enables sign-aware zero-padding ' |

4971 | n/a | 'for numeric\n' |

4972 | n/a | 'types. This is equivalent to a *fill* character of "\'0\'" ' |

4973 | n/a | 'with an\n' |

4974 | n/a | '*alignment* type of "\'=\'".\n' |

4975 | n/a | '\n' |

4976 | n/a | 'The *precision* is a decimal number indicating how many ' |

4977 | n/a | 'digits should\n' |

4978 | n/a | 'be displayed after the decimal point for a floating point ' |

4979 | n/a | 'value\n' |

4980 | n/a | 'formatted with "\'f\'" and "\'F\'", or before and after the ' |

4981 | n/a | 'decimal point\n' |

4982 | n/a | 'for a floating point value formatted with "\'g\'" or ' |

4983 | n/a | '"\'G\'". For non-\n' |

4984 | n/a | 'number types the field indicates the maximum field size - ' |

4985 | n/a | 'in other\n' |

4986 | n/a | 'words, how many characters will be used from the field ' |

4987 | n/a | 'content. The\n' |

4988 | n/a | '*precision* is not allowed for integer values.\n' |

4989 | n/a | '\n' |

4990 | n/a | 'Finally, the *type* determines how the data should be ' |

4991 | n/a | 'presented.\n' |

4992 | n/a | '\n' |

4993 | n/a | 'The available string presentation types are:\n' |

4994 | n/a | '\n' |

4995 | n/a | ' ' |

4996 | n/a | '+-----------+------------------------------------------------------------+\n' |

4997 | n/a | ' | Type | ' |

4998 | n/a | 'Meaning ' |

4999 | n/a | '|\n' |

5000 | n/a | ' ' |

5001 | n/a | '+===========+============================================================+\n' |

5002 | n/a | ' | "\'s\'" | String format. This is the default type ' |

5003 | n/a | 'for strings and |\n' |

5004 | n/a | ' | | may be ' |

5005 | n/a | 'omitted. |\n' |

5006 | n/a | ' ' |

5007 | n/a | '+-----------+------------------------------------------------------------+\n' |

5008 | n/a | ' | None | The same as ' |

5009 | n/a | '"\'s\'". |\n' |

5010 | n/a | ' ' |

5011 | n/a | '+-----------+------------------------------------------------------------+\n' |

5012 | n/a | '\n' |

5013 | n/a | 'The available integer presentation types are:\n' |

5014 | n/a | '\n' |

5015 | n/a | ' ' |

5016 | n/a | '+-----------+------------------------------------------------------------+\n' |

5017 | n/a | ' | Type | ' |

5018 | n/a | 'Meaning ' |

5019 | n/a | '|\n' |

5020 | n/a | ' ' |

5021 | n/a | '+===========+============================================================+\n' |

5022 | n/a | ' | "\'b\'" | Binary format. Outputs the number in ' |

5023 | n/a | 'base 2. |\n' |

5024 | n/a | ' ' |

5025 | n/a | '+-----------+------------------------------------------------------------+\n' |

5026 | n/a | ' | "\'c\'" | Character. Converts the integer to the ' |

5027 | n/a | 'corresponding |\n' |

5028 | n/a | ' | | unicode character before ' |

5029 | n/a | 'printing. |\n' |

5030 | n/a | ' ' |

5031 | n/a | '+-----------+------------------------------------------------------------+\n' |

5032 | n/a | ' | "\'d\'" | Decimal Integer. Outputs the number in ' |

5033 | n/a | 'base 10. |\n' |

5034 | n/a | ' ' |

5035 | n/a | '+-----------+------------------------------------------------------------+\n' |

5036 | n/a | ' | "\'o\'" | Octal format. Outputs the number in base ' |

5037 | n/a | '8. |\n' |

5038 | n/a | ' ' |

5039 | n/a | '+-----------+------------------------------------------------------------+\n' |

5040 | n/a | ' | "\'x\'" | Hex format. Outputs the number in base ' |

5041 | n/a | '16, using lower- |\n' |

5042 | n/a | ' | | case letters for the digits above ' |

5043 | n/a | '9. |\n' |

5044 | n/a | ' ' |

5045 | n/a | '+-----------+------------------------------------------------------------+\n' |

5046 | n/a | ' | "\'X\'" | Hex format. Outputs the number in base ' |

5047 | n/a | '16, using upper- |\n' |

5048 | n/a | ' | | case letters for the digits above ' |

5049 | n/a | '9. |\n' |

5050 | n/a | ' ' |

5051 | n/a | '+-----------+------------------------------------------------------------+\n' |

5052 | n/a | ' | "\'n\'" | Number. This is the same as "\'d\'", ' |

5053 | n/a | 'except that it uses the |\n' |

5054 | n/a | ' | | current locale setting to insert the ' |

5055 | n/a | 'appropriate number |\n' |

5056 | n/a | ' | | separator ' |

5057 | n/a | 'characters. |\n' |

5058 | n/a | ' ' |

5059 | n/a | '+-----------+------------------------------------------------------------+\n' |

5060 | n/a | ' | None | The same as ' |

5061 | n/a | '"\'d\'". |\n' |

5062 | n/a | ' ' |

5063 | n/a | '+-----------+------------------------------------------------------------+\n' |

5064 | n/a | '\n' |

5065 | n/a | 'In addition to the above presentation types, integers can ' |

5066 | n/a | 'be formatted\n' |

5067 | n/a | 'with the floating point presentation types listed below ' |

5068 | n/a | '(except "\'n\'"\n' |

5069 | n/a | 'and None). When doing so, "float()" is used to convert the ' |

5070 | n/a | 'integer to\n' |

5071 | n/a | 'a floating point number before formatting.\n' |

5072 | n/a | '\n' |

5073 | n/a | 'The available presentation types for floating point and ' |

5074 | n/a | 'decimal values\n' |

5075 | n/a | 'are:\n' |

5076 | n/a | '\n' |

5077 | n/a | ' ' |

5078 | n/a | '+-----------+------------------------------------------------------------+\n' |

5079 | n/a | ' | Type | ' |

5080 | n/a | 'Meaning ' |

5081 | n/a | '|\n' |

5082 | n/a | ' ' |

5083 | n/a | '+===========+============================================================+\n' |

5084 | n/a | ' | "\'e\'" | Exponent notation. Prints the number in ' |

5085 | n/a | 'scientific |\n' |

5086 | n/a | " | | notation using the letter 'e' to indicate " |

5087 | n/a | 'the exponent. |\n' |

5088 | n/a | ' | | The default precision is ' |

5089 | n/a | '"6". |\n' |

5090 | n/a | ' ' |

5091 | n/a | '+-----------+------------------------------------------------------------+\n' |

5092 | n/a | ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' |

5093 | n/a | 'except it uses an upper |\n' |

5094 | n/a | " | | case 'E' as the separator " |

5095 | n/a | 'character. |\n' |

5096 | n/a | ' ' |

5097 | n/a | '+-----------+------------------------------------------------------------+\n' |

5098 | n/a | ' | "\'f\'" | Fixed point. Displays the number as a ' |

5099 | n/a | 'fixed-point number. |\n' |

5100 | n/a | ' | | The default precision is ' |

5101 | n/a | '"6". |\n' |

5102 | n/a | ' ' |

5103 | n/a | '+-----------+------------------------------------------------------------+\n' |

5104 | n/a | ' | "\'F\'" | Fixed point. Same as "\'f\'", but ' |

5105 | n/a | 'converts "nan" to "NAN" |\n' |

5106 | n/a | ' | | and "inf" to ' |

5107 | n/a | '"INF". |\n' |

5108 | n/a | ' ' |

5109 | n/a | '+-----------+------------------------------------------------------------+\n' |

5110 | n/a | ' | "\'g\'" | General format. For a given precision ' |

5111 | n/a | '"p >= 1", this |\n' |

5112 | n/a | ' | | rounds the number to "p" significant ' |

5113 | n/a | 'digits and then |\n' |

5114 | n/a | ' | | formats the result in either fixed-point ' |

5115 | n/a | 'format or in |\n' |

5116 | n/a | ' | | scientific notation, depending on its ' |

5117 | n/a | 'magnitude. The |\n' |

5118 | n/a | ' | | precise rules are as follows: suppose that ' |

5119 | n/a | 'the result |\n' |

5120 | n/a | ' | | formatted with presentation type "\'e\'" ' |

5121 | n/a | 'and precision "p-1" |\n' |

5122 | n/a | ' | | would have exponent "exp". Then if "-4 <= ' |

5123 | n/a | 'exp < p", the |\n' |

5124 | n/a | ' | | number is formatted with presentation type ' |

5125 | n/a | '"\'f\'" and |\n' |

5126 | n/a | ' | | precision "p-1-exp". Otherwise, the ' |

5127 | n/a | 'number is formatted |\n' |

5128 | n/a | ' | | with presentation type "\'e\'" and ' |

5129 | n/a | 'precision "p-1". In both |\n' |

5130 | n/a | ' | | cases insignificant trailing zeros are ' |

5131 | n/a | 'removed from the |\n' |

5132 | n/a | ' | | significand, and the decimal point is also ' |

5133 | n/a | 'removed if |\n' |

5134 | n/a | ' | | there are no remaining digits following ' |

5135 | n/a | 'it. Positive and |\n' |

5136 | n/a | ' | | negative infinity, positive and negative ' |

5137 | n/a | 'zero, and nans, |\n' |

5138 | n/a | ' | | are formatted as "inf", "-inf", "0", "-0" ' |

5139 | n/a | 'and "nan" |\n' |

5140 | n/a | ' | | respectively, regardless of the ' |

5141 | n/a | 'precision. A precision of |\n' |

5142 | n/a | ' | | "0" is treated as equivalent to a ' |

5143 | n/a | 'precision of "1". The |\n' |

5144 | n/a | ' | | default precision is ' |

5145 | n/a | '"6". |\n' |

5146 | n/a | ' ' |

5147 | n/a | '+-----------+------------------------------------------------------------+\n' |

5148 | n/a | ' | "\'G\'" | General format. Same as "\'g\'" except ' |

5149 | n/a | 'switches to "\'E\'" if |\n' |

5150 | n/a | ' | | the number gets too large. The ' |

5151 | n/a | 'representations of infinity |\n' |

5152 | n/a | ' | | and NaN are uppercased, ' |

5153 | n/a | 'too. |\n' |

5154 | n/a | ' ' |

5155 | n/a | '+-----------+------------------------------------------------------------+\n' |

5156 | n/a | ' | "\'n\'" | Number. This is the same as "\'g\'", ' |

5157 | n/a | 'except that it uses the |\n' |

5158 | n/a | ' | | current locale setting to insert the ' |

5159 | n/a | 'appropriate number |\n' |

5160 | n/a | ' | | separator ' |

5161 | n/a | 'characters. |\n' |

5162 | n/a | ' ' |

5163 | n/a | '+-----------+------------------------------------------------------------+\n' |

5164 | n/a | ' | "\'%\'" | Percentage. Multiplies the number by 100 ' |

5165 | n/a | 'and displays in |\n' |

5166 | n/a | ' | | fixed ("\'f\'") format, followed by a ' |

5167 | n/a | 'percent sign. |\n' |

5168 | n/a | ' ' |

5169 | n/a | '+-----------+------------------------------------------------------------+\n' |

5170 | n/a | ' | None | Similar to "\'g\'", except that ' |

5171 | n/a | 'fixed-point notation, when |\n' |

5172 | n/a | ' | | used, has at least one digit past the ' |

5173 | n/a | 'decimal point. The |\n' |

5174 | n/a | ' | | default precision is as high as needed to ' |

5175 | n/a | 'represent the |\n' |

5176 | n/a | ' | | particular value. The overall effect is to ' |

5177 | n/a | 'match the |\n' |

5178 | n/a | ' | | output of "str()" as altered by the other ' |

5179 | n/a | 'format |\n' |

5180 | n/a | ' | | ' |

5181 | n/a | 'modifiers. ' |

5182 | n/a | '|\n' |

5183 | n/a | ' ' |

5184 | n/a | '+-----------+------------------------------------------------------------+\n' |

5185 | n/a | '\n' |

5186 | n/a | '\n' |

5187 | n/a | 'Format examples\n' |

5188 | n/a | '===============\n' |

5189 | n/a | '\n' |

5190 | n/a | 'This section contains examples of the "str.format()" syntax ' |

5191 | n/a | 'and\n' |

5192 | n/a | 'comparison with the old "%"-formatting.\n' |

5193 | n/a | '\n' |

5194 | n/a | 'In most of the cases the syntax is similar to the old ' |

5195 | n/a | '"%"-formatting,\n' |

5196 | n/a | 'with the addition of the "{}" and with ":" used instead of ' |

5197 | n/a | '"%". For\n' |

5198 | n/a | 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n' |

5199 | n/a | '\n' |

5200 | n/a | 'The new format syntax also supports new and different ' |

5201 | n/a | 'options, shown\n' |

5202 | n/a | 'in the follow examples.\n' |

5203 | n/a | '\n' |

5204 | n/a | 'Accessing arguments by position:\n' |

5205 | n/a | '\n' |

5206 | n/a | " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" |

5207 | n/a | " 'a, b, c'\n" |

5208 | n/a | " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" |

5209 | n/a | " 'a, b, c'\n" |

5210 | n/a | " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" |

5211 | n/a | " 'c, b, a'\n" |

5212 | n/a | " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " |

5213 | n/a | 'argument sequence\n' |

5214 | n/a | " 'c, b, a'\n" |

5215 | n/a | " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " |

5216 | n/a | 'indices can be repeated\n' |

5217 | n/a | " 'abracadabra'\n" |

5218 | n/a | '\n' |

5219 | n/a | 'Accessing arguments by name:\n' |

5220 | n/a | '\n' |

5221 | n/a | " >>> 'Coordinates: {latitude}, " |

5222 | n/a | "{longitude}'.format(latitude='37.24N', " |

5223 | n/a | "longitude='-115.81W')\n" |

5224 | n/a | " 'Coordinates: 37.24N, -115.81W'\n" |

5225 | n/a | " >>> coord = {'latitude': '37.24N', 'longitude': " |

5226 | n/a | "'-115.81W'}\n" |

5227 | n/a | " >>> 'Coordinates: {latitude}, " |

5228 | n/a | "{longitude}'.format(**coord)\n" |

5229 | n/a | " 'Coordinates: 37.24N, -115.81W'\n" |

5230 | n/a | '\n' |

5231 | n/a | "Accessing arguments' attributes:\n" |

5232 | n/a | '\n' |

5233 | n/a | ' >>> c = 3-5j\n' |

5234 | n/a | " >>> ('The complex number {0} is formed from the real " |

5235 | n/a | "part {0.real} '\n" |

5236 | n/a | " ... 'and the imaginary part {0.imag}.').format(c)\n" |

5237 | n/a | " 'The complex number (3-5j) is formed from the real part " |

5238 | n/a | "3.0 and the imaginary part -5.0.'\n" |

5239 | n/a | ' >>> class Point:\n' |

5240 | n/a | ' ... def __init__(self, x, y):\n' |

5241 | n/a | ' ... self.x, self.y = x, y\n' |

5242 | n/a | ' ... def __str__(self):\n' |

5243 | n/a | " ... return 'Point({self.x}, " |

5244 | n/a | "{self.y})'.format(self=self)\n" |

5245 | n/a | ' ...\n' |

5246 | n/a | ' >>> str(Point(4, 2))\n' |

5247 | n/a | " 'Point(4, 2)'\n" |

5248 | n/a | '\n' |

5249 | n/a | "Accessing arguments' items:\n" |

5250 | n/a | '\n' |

5251 | n/a | ' >>> coord = (3, 5)\n' |

5252 | n/a | " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" |

5253 | n/a | " 'X: 3; Y: 5'\n" |

5254 | n/a | '\n' |

5255 | n/a | 'Replacing "%s" and "%r":\n' |

5256 | n/a | '\n' |

5257 | n/a | ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' |

5258 | n/a | '{!s}".format(\'test1\', \'test2\')\n' |

5259 | n/a | ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n' |

5260 | n/a | '\n' |

5261 | n/a | 'Aligning the text and specifying a width:\n' |

5262 | n/a | '\n' |

5263 | n/a | " >>> '{:<30}'.format('left aligned')\n" |

5264 | n/a | " 'left aligned '\n" |

5265 | n/a | " >>> '{:>30}'.format('right aligned')\n" |

5266 | n/a | " ' right aligned'\n" |

5267 | n/a | " >>> '{:^30}'.format('centered')\n" |

5268 | n/a | " ' centered '\n" |

5269 | n/a | " >>> '{:*^30}'.format('centered') # use '*' as a fill " |

5270 | n/a | 'char\n' |

5271 | n/a | " '***********centered***********'\n" |

5272 | n/a | '\n' |

5273 | n/a | 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' |

5274 | n/a | '\n' |

5275 | n/a | " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " |

5276 | n/a | 'always\n' |

5277 | n/a | " '+3.140000; -3.140000'\n" |

5278 | n/a | " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " |

5279 | n/a | 'for positive numbers\n' |

5280 | n/a | " ' 3.140000; -3.140000'\n" |

5281 | n/a | " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the " |

5282 | n/a | "minus -- same as '{:f}; {:f}'\n" |

5283 | n/a | " '3.140000; -3.140000'\n" |

5284 | n/a | '\n' |

5285 | n/a | 'Replacing "%x" and "%o" and converting the value to ' |

5286 | n/a | 'different bases:\n' |

5287 | n/a | '\n' |

5288 | n/a | ' >>> # format also supports binary numbers\n' |

5289 | n/a | ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' |

5290 | n/a | '{0:b}".format(42)\n' |

5291 | n/a | " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" |

5292 | n/a | ' >>> # with 0x, 0o, or 0b as prefix:\n' |

5293 | n/a | ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' |

5294 | n/a | '{0:#b}".format(42)\n' |

5295 | n/a | " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" |

5296 | n/a | '\n' |

5297 | n/a | 'Using the comma as a thousands separator:\n' |

5298 | n/a | '\n' |

5299 | n/a | " >>> '{:,}'.format(1234567890)\n" |

5300 | n/a | " '1,234,567,890'\n" |

5301 | n/a | '\n' |

5302 | n/a | 'Expressing a percentage:\n' |

5303 | n/a | '\n' |

5304 | n/a | ' >>> points = 19\n' |

5305 | n/a | ' >>> total = 22\n' |

5306 | n/a | " >>> 'Correct answers: {:.2%}'.format(points/total)\n" |

5307 | n/a | " 'Correct answers: 86.36%'\n" |

5308 | n/a | '\n' |

5309 | n/a | 'Using type-specific formatting:\n' |

5310 | n/a | '\n' |

5311 | n/a | ' >>> import datetime\n' |

5312 | n/a | ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' |

5313 | n/a | " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" |

5314 | n/a | " '2010-07-04 12:15:58'\n" |

5315 | n/a | '\n' |

5316 | n/a | 'Nesting arguments and more complex examples:\n' |

5317 | n/a | '\n' |

5318 | n/a | " >>> for align, text in zip('<^>', ['left', 'center', " |

5319 | n/a | "'right']):\n" |

5320 | n/a | " ... '{0:{fill}{align}16}'.format(text, fill=align, " |

5321 | n/a | 'align=align)\n' |

5322 | n/a | ' ...\n' |

5323 | n/a | " 'left<<<<<<<<<<<<'\n" |

5324 | n/a | " '^^^^^center^^^^^'\n" |

5325 | n/a | " '>>>>>>>>>>>right'\n" |

5326 | n/a | ' >>>\n' |

5327 | n/a | ' >>> octets = [192, 168, 0, 1]\n' |

5328 | n/a | " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" |

5329 | n/a | " 'C0A80001'\n" |

5330 | n/a | ' >>> int(_, 16)\n' |

5331 | n/a | ' 3232235521\n' |

5332 | n/a | ' >>>\n' |

5333 | n/a | ' >>> width = 5\n' |

5334 | n/a | ' >>> for num in range(5,12): #doctest: ' |

5335 | n/a | '+NORMALIZE_WHITESPACE\n' |

5336 | n/a | " ... for base in 'dXob':\n" |

5337 | n/a | " ... print('{0:{width}{base}}'.format(num, " |

5338 | n/a | "base=base, width=width), end=' ')\n" |

5339 | n/a | ' ... print()\n' |

5340 | n/a | ' ...\n' |

5341 | n/a | ' 5 5 5 101\n' |

5342 | n/a | ' 6 6 6 110\n' |

5343 | n/a | ' 7 7 7 111\n' |

5344 | n/a | ' 8 8 10 1000\n' |

5345 | n/a | ' 9 9 11 1001\n' |

5346 | n/a | ' 10 A 12 1010\n' |

5347 | n/a | ' 11 B 13 1011\n', |

5348 | n/a | 'function': '\n' |

5349 | n/a | 'Function definitions\n' |

5350 | n/a | '********************\n' |

5351 | n/a | '\n' |

5352 | n/a | 'A function definition defines a user-defined function object ' |

5353 | n/a | '(see\n' |

5354 | n/a | 'section The standard type hierarchy):\n' |

5355 | n/a | '\n' |

5356 | n/a | ' funcdef ::= [decorators] "def" funcname "(" ' |

5357 | n/a | '[parameter_list] ")" ["->" expression] ":" suite\n' |

5358 | n/a | ' decorators ::= decorator+\n' |

5359 | n/a | ' decorator ::= "@" dotted_name ["(" ' |

5360 | n/a | '[argument_list [","]] ")"] NEWLINE\n' |

5361 | n/a | ' dotted_name ::= identifier ("." identifier)*\n' |

5362 | n/a | ' parameter_list ::= defparameter ("," defparameter)* ' |

5363 | n/a | '["," [parameter_list_starargs]]\n' |

5364 | n/a | ' | parameter_list_starargs\n' |

5365 | n/a | ' parameter_list_starargs ::= "*" [parameter] ("," ' |

5366 | n/a | 'defparameter)* ["," ["**" parameter [","]]]\n' |

5367 | n/a | ' | "**" parameter [","]\n' |

5368 | n/a | ' parameter ::= identifier [":" expression]\n' |

5369 | n/a | ' defparameter ::= parameter ["=" expression]\n' |

5370 | n/a | ' funcname ::= identifier\n' |

5371 | n/a | '\n' |

5372 | n/a | 'A function definition is an executable statement. Its execution ' |

5373 | n/a | 'binds\n' |

5374 | n/a | 'the function name in the current local namespace to a function ' |

5375 | n/a | 'object\n' |

5376 | n/a | '(a wrapper around the executable code for the function). This\n' |

5377 | n/a | 'function object contains a reference to the current global ' |

5378 | n/a | 'namespace\n' |

5379 | n/a | 'as the global namespace to be used when the function is called.\n' |

5380 | n/a | '\n' |

5381 | n/a | 'The function definition does not execute the function body; this ' |

5382 | n/a | 'gets\n' |

5383 | n/a | 'executed only when the function is called. [3]\n' |

5384 | n/a | '\n' |

5385 | n/a | 'A function definition may be wrapped by one or more *decorator*\n' |

5386 | n/a | 'expressions. Decorator expressions are evaluated when the ' |

5387 | n/a | 'function is\n' |

5388 | n/a | 'defined, in the scope that contains the function definition. ' |

5389 | n/a | 'The\n' |

5390 | n/a | 'result must be a callable, which is invoked with the function ' |

5391 | n/a | 'object\n' |

5392 | n/a | 'as the only argument. The returned value is bound to the ' |

5393 | n/a | 'function name\n' |

5394 | n/a | 'instead of the function object. Multiple decorators are applied ' |

5395 | n/a | 'in\n' |

5396 | n/a | 'nested fashion. For example, the following code\n' |

5397 | n/a | '\n' |

5398 | n/a | ' @f1(arg)\n' |

5399 | n/a | ' @f2\n' |

5400 | n/a | ' def func(): pass\n' |

5401 | n/a | '\n' |

5402 | n/a | 'is roughly equivalent to\n' |

5403 | n/a | '\n' |

5404 | n/a | ' def func(): pass\n' |

5405 | n/a | ' func = f1(arg)(f2(func))\n' |

5406 | n/a | '\n' |

5407 | n/a | 'except that the original function is not temporarily bound to ' |

5408 | n/a | 'the name\n' |

5409 | n/a | '"func".\n' |

5410 | n/a | '\n' |

5411 | n/a | 'When one or more *parameters* have the form *parameter* "="\n' |

5412 | n/a | '*expression*, the function is said to have "default parameter ' |

5413 | n/a | 'values."\n' |

5414 | n/a | 'For a parameter with a default value, the corresponding ' |

5415 | n/a | '*argument* may\n' |

5416 | n/a | "be omitted from a call, in which case the parameter's default " |

5417 | n/a | 'value is\n' |

5418 | n/a | 'substituted. If a parameter has a default value, all following\n' |

5419 | n/a | 'parameters up until the ""*"" must also have a default value --- ' |

5420 | n/a | 'this\n' |

5421 | n/a | 'is a syntactic restriction that is not expressed by the ' |

5422 | n/a | 'grammar.\n' |

5423 | n/a | '\n' |

5424 | n/a | '**Default parameter values are evaluated from left to right when ' |

5425 | n/a | 'the\n' |

5426 | n/a | 'function definition is executed.** This means that the ' |

5427 | n/a | 'expression is\n' |

5428 | n/a | 'evaluated once, when the function is defined, and that the same ' |

5429 | n/a | '"pre-\n' |

5430 | n/a | 'computed" value is used for each call. This is especially ' |

5431 | n/a | 'important\n' |

5432 | n/a | 'to understand when a default parameter is a mutable object, such ' |

5433 | n/a | 'as a\n' |

5434 | n/a | 'list or a dictionary: if the function modifies the object (e.g. ' |

5435 | n/a | 'by\n' |

5436 | n/a | 'appending an item to a list), the default value is in effect ' |

5437 | n/a | 'modified.\n' |

5438 | n/a | 'This is generally not what was intended. A way around this is ' |

5439 | n/a | 'to use\n' |

5440 | n/a | '"None" as the default, and explicitly test for it in the body of ' |

5441 | n/a | 'the\n' |

5442 | n/a | 'function, e.g.:\n' |

5443 | n/a | '\n' |

5444 | n/a | ' def whats_on_the_telly(penguin=None):\n' |

5445 | n/a | ' if penguin is None:\n' |

5446 | n/a | ' penguin = []\n' |

5447 | n/a | ' penguin.append("property of the zoo")\n' |

5448 | n/a | ' return penguin\n' |

5449 | n/a | '\n' |

5450 | n/a | 'Function call semantics are described in more detail in section ' |

5451 | n/a | 'Calls.\n' |

5452 | n/a | 'A function call always assigns values to all parameters ' |

5453 | n/a | 'mentioned in\n' |

5454 | n/a | 'the parameter list, either from position arguments, from ' |

5455 | n/a | 'keyword\n' |

5456 | n/a | 'arguments, or from default values. If the form ""*identifier"" ' |

5457 | n/a | 'is\n' |

5458 | n/a | 'present, it is initialized to a tuple receiving any excess ' |

5459 | n/a | 'positional\n' |

5460 | n/a | 'parameters, defaulting to the empty tuple. If the form\n' |

5461 | n/a | '""**identifier"" is present, it is initialized to a new ordered\n' |

5462 | n/a | 'mapping receiving any excess keyword arguments, defaulting to a ' |

5463 | n/a | 'new\n' |

5464 | n/a | 'empty mapping of the same type. Parameters after ""*"" or\n' |

5465 | n/a | '""*identifier"" are keyword-only parameters and may only be ' |

5466 | n/a | 'passed\n' |

5467 | n/a | 'used keyword arguments.\n' |

5468 | n/a | '\n' |

5469 | n/a | 'Parameters may have annotations of the form "": expression"" ' |

5470 | n/a | 'following\n' |

5471 | n/a | 'the parameter name. Any parameter may have an annotation even ' |

5472 | n/a | 'those\n' |

5473 | n/a | 'of the form "*identifier" or "**identifier". Functions may ' |

5474 | n/a | 'have\n' |

5475 | n/a | '"return" annotation of the form ""-> expression"" after the ' |

5476 | n/a | 'parameter\n' |

5477 | n/a | 'list. These annotations can be any valid Python expression and ' |

5478 | n/a | 'are\n' |

5479 | n/a | 'evaluated when the function definition is executed. Annotations ' |

5480 | n/a | 'may\n' |

5481 | n/a | 'be evaluated in a different order than they appear in the source ' |

5482 | n/a | 'code.\n' |

5483 | n/a | 'The presence of annotations does not change the semantics of a\n' |

5484 | n/a | 'function. The annotation values are available as values of a\n' |

5485 | n/a | "dictionary keyed by the parameters' names in the " |

5486 | n/a | '"__annotations__"\n' |

5487 | n/a | 'attribute of the function object.\n' |

5488 | n/a | '\n' |

5489 | n/a | 'It is also possible to create anonymous functions (functions not ' |

5490 | n/a | 'bound\n' |

5491 | n/a | 'to a name), for immediate use in expressions. This uses lambda\n' |

5492 | n/a | 'expressions, described in section Lambdas. Note that the ' |

5493 | n/a | 'lambda\n' |

5494 | n/a | 'expression is merely a shorthand for a simplified function ' |

5495 | n/a | 'definition;\n' |

5496 | n/a | 'a function defined in a ""def"" statement can be passed around ' |

5497 | n/a | 'or\n' |

5498 | n/a | 'assigned to another name just like a function defined by a ' |

5499 | n/a | 'lambda\n' |

5500 | n/a | 'expression. The ""def"" form is actually more powerful since ' |

5501 | n/a | 'it\n' |

5502 | n/a | 'allows the execution of multiple statements and annotations.\n' |

5503 | n/a | '\n' |

5504 | n/a | "**Programmer's note:** Functions are first-class objects. A " |

5505 | n/a | '""def""\n' |

5506 | n/a | 'statement executed inside a function definition defines a local\n' |

5507 | n/a | 'function that can be returned or passed around. Free variables ' |

5508 | n/a | 'used\n' |

5509 | n/a | 'in the nested function can access the local variables of the ' |

5510 | n/a | 'function\n' |

5511 | n/a | 'containing the def. See section Naming and binding for ' |

5512 | n/a | 'details.\n' |

5513 | n/a | '\n' |

5514 | n/a | 'See also:\n' |

5515 | n/a | '\n' |

5516 | n/a | ' **PEP 3107** - Function Annotations\n' |

5517 | n/a | ' The original specification for function annotations.\n', |

5518 | n/a | 'global': '\n' |

5519 | n/a | 'The "global" statement\n' |

5520 | n/a | '**********************\n' |

5521 | n/a | '\n' |

5522 | n/a | ' global_stmt ::= "global" identifier ("," identifier)*\n' |

5523 | n/a | '\n' |

5524 | n/a | 'The "global" statement is a declaration which holds for the ' |

5525 | n/a | 'entire\n' |

5526 | n/a | 'current code block. It means that the listed identifiers are to ' |

5527 | n/a | 'be\n' |

5528 | n/a | 'interpreted as globals. It would be impossible to assign to a ' |

5529 | n/a | 'global\n' |

5530 | n/a | 'variable without "global", although free variables may refer to\n' |

5531 | n/a | 'globals without being declared global.\n' |

5532 | n/a | '\n' |

5533 | n/a | 'Names listed in a "global" statement must not be used in the same ' |

5534 | n/a | 'code\n' |

5535 | n/a | 'block textually preceding that "global" statement.\n' |

5536 | n/a | '\n' |

5537 | n/a | 'Names listed in a "global" statement must not be defined as ' |

5538 | n/a | 'formal\n' |

5539 | n/a | 'parameters or in a "for" loop control target, "class" definition,\n' |

5540 | n/a | 'function definition, "import" statement, or variable annotation.\n' |

5541 | n/a | '\n' |

5542 | n/a | '**CPython implementation detail:** The current implementation does ' |

5543 | n/a | 'not\n' |

5544 | n/a | 'enforce some of these restriction, but programs should not abuse ' |

5545 | n/a | 'this\n' |

5546 | n/a | 'freedom, as future implementations may enforce them or silently ' |

5547 | n/a | 'change\n' |

5548 | n/a | 'the meaning of the program.\n' |

5549 | n/a | '\n' |

5550 | n/a | '**Programmer\'s note:** the "global" is a directive to the ' |

5551 | n/a | 'parser. It\n' |

5552 | n/a | 'applies only to code parsed at the same time as the "global"\n' |

5553 | n/a | 'statement. In particular, a "global" statement contained in a ' |

5554 | n/a | 'string\n' |

5555 | n/a | 'or code object supplied to the built-in "exec()" function does ' |

5556 | n/a | 'not\n' |

5557 | n/a | 'affect the code block *containing* the function call, and code\n' |

5558 | n/a | 'contained in such a string is unaffected by "global" statements in ' |

5559 | n/a | 'the\n' |

5560 | n/a | 'code containing the function call. The same applies to the ' |

5561 | n/a | '"eval()"\n' |

5562 | n/a | 'and "compile()" functions.\n', |

5563 | n/a | 'id-classes': '\n' |

5564 | n/a | 'Reserved classes of identifiers\n' |

5565 | n/a | '*******************************\n' |

5566 | n/a | '\n' |

5567 | n/a | 'Certain classes of identifiers (besides keywords) have ' |

5568 | n/a | 'special\n' |

5569 | n/a | 'meanings. These classes are identified by the patterns of ' |

5570 | n/a | 'leading and\n' |

5571 | n/a | 'trailing underscore characters:\n' |

5572 | n/a | '\n' |

5573 | n/a | '"_*"\n' |

5574 | n/a | ' Not imported by "from module import *". The special ' |

5575 | n/a | 'identifier "_"\n' |

5576 | n/a | ' is used in the interactive interpreter to store the result ' |

5577 | n/a | 'of the\n' |

5578 | n/a | ' last evaluation; it is stored in the "builtins" module. ' |

5579 | n/a | 'When not\n' |

5580 | n/a | ' in interactive mode, "_" has no special meaning and is not ' |

5581 | n/a | 'defined.\n' |

5582 | n/a | ' See section The import statement.\n' |

5583 | n/a | '\n' |

5584 | n/a | ' Note: The name "_" is often used in conjunction with\n' |

5585 | n/a | ' internationalization; refer to the documentation for the\n' |

5586 | n/a | ' "gettext" module for more information on this ' |

5587 | n/a | 'convention.\n' |

5588 | n/a | '\n' |

5589 | n/a | '"__*__"\n' |

5590 | n/a | ' System-defined names. These names are defined by the ' |

5591 | n/a | 'interpreter\n' |

5592 | n/a | ' and its implementation (including the standard library). ' |

5593 | n/a | 'Current\n' |

5594 | n/a | ' system names are discussed in the Special method names ' |

5595 | n/a | 'section and\n' |

5596 | n/a | ' elsewhere. More will likely be defined in future versions ' |

5597 | n/a | 'of\n' |

5598 | n/a | ' Python. *Any* use of "__*__" names, in any context, that ' |

5599 | n/a | 'does not\n' |

5600 | n/a | ' follow explicitly documented use, is subject to breakage ' |

5601 | n/a | 'without\n' |

5602 | n/a | ' warning.\n' |

5603 | n/a | '\n' |

5604 | n/a | '"__*"\n' |

5605 | n/a | ' Class-private names. Names in this category, when used ' |

5606 | n/a | 'within the\n' |

5607 | n/a | ' context of a class definition, are re-written to use a ' |

5608 | n/a | 'mangled form\n' |

5609 | n/a | ' to help avoid name clashes between "private" attributes of ' |

5610 | n/a | 'base and\n' |

5611 | n/a | ' derived classes. See section Identifiers (Names).\n', |

5612 | n/a | 'identifiers': '\n' |

5613 | n/a | 'Identifiers and keywords\n' |

5614 | n/a | '************************\n' |

5615 | n/a | '\n' |

5616 | n/a | 'Identifiers (also referred to as *names*) are described by ' |

5617 | n/a | 'the\n' |

5618 | n/a | 'following lexical definitions.\n' |

5619 | n/a | '\n' |

5620 | n/a | 'The syntax of identifiers in Python is based on the Unicode ' |

5621 | n/a | 'standard\n' |

5622 | n/a | 'annex UAX-31, with elaboration and changes as defined below; ' |

5623 | n/a | 'see also\n' |

5624 | n/a | '**PEP 3131** for further details.\n' |

5625 | n/a | '\n' |

5626 | n/a | 'Within the ASCII range (U+0001..U+007F), the valid characters ' |

5627 | n/a | 'for\n' |

5628 | n/a | 'identifiers are the same as in Python 2.x: the uppercase and ' |

5629 | n/a | 'lowercase\n' |

5630 | n/a | 'letters "A" through "Z", the underscore "_" and, except for ' |

5631 | n/a | 'the first\n' |

5632 | n/a | 'character, the digits "0" through "9".\n' |

5633 | n/a | '\n' |

5634 | n/a | 'Python 3.0 introduces additional characters from outside the ' |

5635 | n/a | 'ASCII\n' |

5636 | n/a | 'range (see **PEP 3131**). For these characters, the ' |

5637 | n/a | 'classification\n' |

5638 | n/a | 'uses the version of the Unicode Character Database as ' |

5639 | n/a | 'included in the\n' |

5640 | n/a | '"unicodedata" module.\n' |

5641 | n/a | '\n' |

5642 | n/a | 'Identifiers are unlimited in length. Case is significant.\n' |

5643 | n/a | '\n' |

5644 | n/a | ' identifier ::= xid_start xid_continue*\n' |

5645 | n/a | ' id_start ::= <all characters in general categories Lu, ' |

5646 | n/a | 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the ' |

5647 | n/a | 'Other_ID_Start property>\n' |

5648 | n/a | ' id_continue ::= <all characters in id_start, plus ' |

5649 | n/a | 'characters in the categories Mn, Mc, Nd, Pc and others with ' |

5650 | n/a | 'the Other_ID_Continue property>\n' |

5651 | n/a | ' xid_start ::= <all characters in id_start whose NFKC ' |

5652 | n/a | 'normalization is in "id_start xid_continue*">\n' |

5653 | n/a | ' xid_continue ::= <all characters in id_continue whose NFKC ' |

5654 | n/a | 'normalization is in "id_continue*">\n' |

5655 | n/a | '\n' |

5656 | n/a | 'The Unicode category codes mentioned above stand for:\n' |

5657 | n/a | '\n' |

5658 | n/a | '* *Lu* - uppercase letters\n' |

5659 | n/a | '\n' |

5660 | n/a | '* *Ll* - lowercase letters\n' |

5661 | n/a | '\n' |

5662 | n/a | '* *Lt* - titlecase letters\n' |

5663 | n/a | '\n' |

5664 | n/a | '* *Lm* - modifier letters\n' |

5665 | n/a | '\n' |

5666 | n/a | '* *Lo* - other letters\n' |

5667 | n/a | '\n' |

5668 | n/a | '* *Nl* - letter numbers\n' |

5669 | n/a | '\n' |

5670 | n/a | '* *Mn* - nonspacing marks\n' |

5671 | n/a | '\n' |

5672 | n/a | '* *Mc* - spacing combining marks\n' |

5673 | n/a | '\n' |

5674 | n/a | '* *Nd* - decimal numbers\n' |

5675 | n/a | '\n' |

5676 | n/a | '* *Pc* - connector punctuations\n' |

5677 | n/a | '\n' |

5678 | n/a | '* *Other_ID_Start* - explicit list of characters in ' |

5679 | n/a | 'PropList.txt to\n' |

5680 | n/a | ' support backwards compatibility\n' |

5681 | n/a | '\n' |

5682 | n/a | '* *Other_ID_Continue* - likewise\n' |

5683 | n/a | '\n' |

5684 | n/a | 'All identifiers are converted into the normal form NFKC while ' |

5685 | n/a | 'parsing;\n' |

5686 | n/a | 'comparison of identifiers is based on NFKC.\n' |

5687 | n/a | '\n' |

5688 | n/a | 'A non-normative HTML file listing all valid identifier ' |

5689 | n/a | 'characters for\n' |

5690 | n/a | 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n' |

5691 | n/a | 'potsdam.de/home/loewis/table-3131.html.\n' |

5692 | n/a | '\n' |

5693 | n/a | '\n' |

5694 | n/a | 'Keywords\n' |

5695 | n/a | '========\n' |

5696 | n/a | '\n' |

5697 | n/a | 'The following identifiers are used as reserved words, or ' |

5698 | n/a | '*keywords* of\n' |

5699 | n/a | 'the language, and cannot be used as ordinary identifiers. ' |

5700 | n/a | 'They must\n' |

5701 | n/a | 'be spelled exactly as written here:\n' |

5702 | n/a | '\n' |

5703 | n/a | ' False class finally is return\n' |

5704 | n/a | ' None continue for lambda try\n' |

5705 | n/a | ' True def from nonlocal while\n' |

5706 | n/a | ' and del global not with\n' |

5707 | n/a | ' as elif if or yield\n' |

5708 | n/a | ' assert else import pass\n' |

5709 | n/a | ' break except in raise\n' |

5710 | n/a | '\n' |

5711 | n/a | '\n' |

5712 | n/a | 'Reserved classes of identifiers\n' |

5713 | n/a | '===============================\n' |

5714 | n/a | '\n' |

5715 | n/a | 'Certain classes of identifiers (besides keywords) have ' |

5716 | n/a | 'special\n' |

5717 | n/a | 'meanings. These classes are identified by the patterns of ' |

5718 | n/a | 'leading and\n' |

5719 | n/a | 'trailing underscore characters:\n' |

5720 | n/a | '\n' |

5721 | n/a | '"_*"\n' |

5722 | n/a | ' Not imported by "from module import *". The special ' |

5723 | n/a | 'identifier "_"\n' |

5724 | n/a | ' is used in the interactive interpreter to store the result ' |

5725 | n/a | 'of the\n' |

5726 | n/a | ' last evaluation; it is stored in the "builtins" module. ' |

5727 | n/a | 'When not\n' |

5728 | n/a | ' in interactive mode, "_" has no special meaning and is not ' |

5729 | n/a | 'defined.\n' |

5730 | n/a | ' See section The import statement.\n' |

5731 | n/a | '\n' |

5732 | n/a | ' Note: The name "_" is often used in conjunction with\n' |

5733 | n/a | ' internationalization; refer to the documentation for ' |

5734 | n/a | 'the\n' |

5735 | n/a | ' "gettext" module for more information on this ' |

5736 | n/a | 'convention.\n' |

5737 | n/a | '\n' |

5738 | n/a | '"__*__"\n' |

5739 | n/a | ' System-defined names. These names are defined by the ' |

5740 | n/a | 'interpreter\n' |

5741 | n/a | ' and its implementation (including the standard library). ' |

5742 | n/a | 'Current\n' |

5743 | n/a | ' system names are discussed in the Special method names ' |

5744 | n/a | 'section and\n' |

5745 | n/a | ' elsewhere. More will likely be defined in future versions ' |

5746 | n/a | 'of\n' |

5747 | n/a | ' Python. *Any* use of "__*__" names, in any context, that ' |

5748 | n/a | 'does not\n' |

5749 | n/a | ' follow explicitly documented use, is subject to breakage ' |

5750 | n/a | 'without\n' |

5751 | n/a | ' warning.\n' |

5752 | n/a | '\n' |

5753 | n/a | '"__*"\n' |

5754 | n/a | ' Class-private names. Names in this category, when used ' |

5755 | n/a | 'within the\n' |

5756 | n/a | ' context of a class definition, are re-written to use a ' |

5757 | n/a | 'mangled form\n' |

5758 | n/a | ' to help avoid name clashes between "private" attributes of ' |

5759 | n/a | 'base and\n' |

5760 | n/a | ' derived classes. See section Identifiers (Names).\n', |

5761 | n/a | 'if': '\n' |

5762 | n/a | 'The "if" statement\n' |

5763 | n/a | '******************\n' |

5764 | n/a | '\n' |

5765 | n/a | 'The "if" statement is used for conditional execution:\n' |

5766 | n/a | '\n' |

5767 | n/a | ' if_stmt ::= "if" expression ":" suite\n' |

5768 | n/a | ' ( "elif" expression ":" suite )*\n' |

5769 | n/a | ' ["else" ":" suite]\n' |

5770 | n/a | '\n' |

5771 | n/a | 'It selects exactly one of the suites by evaluating the expressions ' |

5772 | n/a | 'one\n' |

5773 | n/a | 'by one until one is found to be true (see section Boolean operations\n' |

5774 | n/a | 'for the definition of true and false); then that suite is executed\n' |

5775 | n/a | '(and no other part of the "if" statement is executed or evaluated).\n' |

5776 | n/a | 'If all expressions are false, the suite of the "else" clause, if\n' |

5777 | n/a | 'present, is executed.\n', |

5778 | n/a | 'imaginary': '\n' |

5779 | n/a | 'Imaginary literals\n' |

5780 | n/a | '******************\n' |

5781 | n/a | '\n' |

5782 | n/a | 'Imaginary literals are described by the following lexical ' |

5783 | n/a | 'definitions:\n' |

5784 | n/a | '\n' |

5785 | n/a | ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n' |

5786 | n/a | '\n' |

5787 | n/a | 'An imaginary literal yields a complex number with a real part ' |

5788 | n/a | 'of 0.0.\n' |

5789 | n/a | 'Complex numbers are represented as a pair of floating point ' |

5790 | n/a | 'numbers\n' |

5791 | n/a | 'and have the same restrictions on their range. To create a ' |

5792 | n/a | 'complex\n' |

5793 | n/a | 'number with a nonzero real part, add a floating point number to ' |

5794 | n/a | 'it,\n' |

5795 | n/a | 'e.g., "(3+4j)". Some examples of imaginary literals:\n' |

5796 | n/a | '\n' |

5797 | n/a | ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j ' |

5798 | n/a | '3.14_15_93j\n', |

5799 | n/a | 'import': '\n' |

5800 | n/a | 'The "import" statement\n' |

5801 | n/a | '**********************\n' |

5802 | n/a | '\n' |

5803 | n/a | ' import_stmt ::= "import" module ["as" name] ( "," module ' |

5804 | n/a | '["as" name] )*\n' |

5805 | n/a | ' | "from" relative_module "import" identifier ' |

5806 | n/a | '["as" name]\n' |

5807 | n/a | ' ( "," identifier ["as" name] )*\n' |

5808 | n/a | ' | "from" relative_module "import" "(" ' |

5809 | n/a | 'identifier ["as" name]\n' |

5810 | n/a | ' ( "," identifier ["as" name] )* [","] ")"\n' |

5811 | n/a | ' | "from" module "import" "*"\n' |

5812 | n/a | ' module ::= (identifier ".")* identifier\n' |

5813 | n/a | ' relative_module ::= "."* module | "."+\n' |

5814 | n/a | ' name ::= identifier\n' |

5815 | n/a | '\n' |

5816 | n/a | 'The basic import statement (no "from" clause) is executed in two\n' |

5817 | n/a | 'steps:\n' |

5818 | n/a | '\n' |

5819 | n/a | '1. find a module, loading and initializing it if necessary\n' |

5820 | n/a | '\n' |

5821 | n/a | '2. define a name or names in the local namespace for the scope\n' |

5822 | n/a | ' where the "import" statement occurs.\n' |

5823 | n/a | '\n' |

5824 | n/a | 'When the statement contains multiple clauses (separated by commas) ' |

5825 | n/a | 'the\n' |

5826 | n/a | 'two steps are carried out separately for each clause, just as ' |

5827 | n/a | 'though\n' |

5828 | n/a | 'the clauses had been separated out into individual import ' |

5829 | n/a | 'statements.\n' |

5830 | n/a | '\n' |

5831 | n/a | 'The details of the first step, finding and loading modules are\n' |

5832 | n/a | 'described in greater detail in the section on the import system, ' |

5833 | n/a | 'which\n' |

5834 | n/a | 'also describes the various types of packages and modules that can ' |

5835 | n/a | 'be\n' |

5836 | n/a | 'imported, as well as all the hooks that can be used to customize ' |

5837 | n/a | 'the\n' |

5838 | n/a | 'import system. Note that failures in this step may indicate ' |

5839 | n/a | 'either\n' |

5840 | n/a | 'that the module could not be located, *or* that an error occurred\n' |

5841 | n/a | 'while initializing the module, which includes execution of the\n' |

5842 | n/a | "module's code.\n" |

5843 | n/a | '\n' |

5844 | n/a | 'If the requested module is retrieved successfully, it will be ' |

5845 | n/a | 'made\n' |

5846 | n/a | 'available in the local namespace in one of three ways:\n' |

5847 | n/a | '\n' |

5848 | n/a | '* If the module name is followed by "as", then the name following\n' |

5849 | n/a | ' "as" is bound directly to the imported module.\n' |

5850 | n/a | '\n' |

5851 | n/a | '* If no other name is specified, and the module being imported is ' |

5852 | n/a | 'a\n' |

5853 | n/a | " top level module, the module's name is bound in the local " |

5854 | n/a | 'namespace\n' |

5855 | n/a | ' as a reference to the imported module\n' |

5856 | n/a | '\n' |

5857 | n/a | '* If the module being imported is *not* a top level module, then ' |

5858 | n/a | 'the\n' |

5859 | n/a | ' name of the top level package that contains the module is bound ' |

5860 | n/a | 'in\n' |

5861 | n/a | ' the local namespace as a reference to the top level package. ' |

5862 | n/a | 'The\n' |

5863 | n/a | ' imported module must be accessed using its full qualified name\n' |

5864 | n/a | ' rather than directly\n' |

5865 | n/a | '\n' |

5866 | n/a | 'The "from" form uses a slightly more complex process:\n' |

5867 | n/a | '\n' |

5868 | n/a | '1. find the module specified in the "from" clause, loading and\n' |

5869 | n/a | ' initializing it if necessary;\n' |

5870 | n/a | '\n' |

5871 | n/a | '2. for each of the identifiers specified in the "import" clauses:\n' |

5872 | n/a | '\n' |

5873 | n/a | ' 1. check if the imported module has an attribute by that name\n' |

5874 | n/a | '\n' |

5875 | n/a | ' 2. if not, attempt to import a submodule with that name and ' |

5876 | n/a | 'then\n' |

5877 | n/a | ' check the imported module again for that attribute\n' |

5878 | n/a | '\n' |

5879 | n/a | ' 3. if the attribute is not found, "ImportError" is raised.\n' |

5880 | n/a | '\n' |

5881 | n/a | ' 4. otherwise, a reference to that value is stored in the local\n' |

5882 | n/a | ' namespace, using the name in the "as" clause if it is ' |

5883 | n/a | 'present,\n' |

5884 | n/a | ' otherwise using the attribute name\n' |

5885 | n/a | '\n' |

5886 | n/a | 'Examples:\n' |

5887 | n/a | '\n' |

5888 | n/a | ' import foo # foo imported and bound locally\n' |

5889 | n/a | ' import foo.bar.baz # foo.bar.baz imported, foo bound ' |

5890 | n/a | 'locally\n' |

5891 | n/a | ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' |

5892 | n/a | 'fbb\n' |

5893 | n/a | ' from foo.bar import baz # foo.bar.baz imported and bound as ' |

5894 | n/a | 'baz\n' |

5895 | n/a | ' from foo import attr # foo imported and foo.attr bound as ' |

5896 | n/a | 'attr\n' |

5897 | n/a | '\n' |

5898 | n/a | 'If the list of identifiers is replaced by a star ("\'*\'"), all ' |

5899 | n/a | 'public\n' |

5900 | n/a | 'names defined in the module are bound in the local namespace for ' |

5901 | n/a | 'the\n' |

5902 | n/a | 'scope where the "import" statement occurs.\n' |

5903 | n/a | '\n' |

5904 | n/a | 'The *public names* defined by a module are determined by checking ' |

5905 | n/a | 'the\n' |

5906 | n/a | 'module\'s namespace for a variable named "__all__"; if defined, it ' |

5907 | n/a | 'must\n' |

5908 | n/a | 'be a sequence of strings which are names defined or imported by ' |

5909 | n/a | 'that\n' |

5910 | n/a | 'module. The names given in "__all__" are all considered public ' |

5911 | n/a | 'and\n' |

5912 | n/a | 'are required to exist. If "__all__" is not defined, the set of ' |

5913 | n/a | 'public\n' |

5914 | n/a | "names includes all names found in the module's namespace which do " |

5915 | n/a | 'not\n' |

5916 | n/a | 'begin with an underscore character ("\'_\'"). "__all__" should ' |

5917 | n/a | 'contain\n' |

5918 | n/a | 'the entire public API. It is intended to avoid accidentally ' |

5919 | n/a | 'exporting\n' |

5920 | n/a | 'items that are not part of the API (such as library modules which ' |

5921 | n/a | 'were\n' |

5922 | n/a | 'imported and used within the module).\n' |

5923 | n/a | '\n' |

5924 | n/a | 'The wild card form of import --- "from module import *" --- is ' |

5925 | n/a | 'only\n' |

5926 | n/a | 'allowed at the module level. Attempting to use it in class or\n' |

5927 | n/a | 'function definitions will raise a "SyntaxError".\n' |

5928 | n/a | '\n' |

5929 | n/a | 'When specifying what module to import you do not have to specify ' |

5930 | n/a | 'the\n' |

5931 | n/a | 'absolute name of the module. When a module or package is ' |

5932 | n/a | 'contained\n' |

5933 | n/a | 'within another package it is possible to make a relative import ' |

5934 | n/a | 'within\n' |

5935 | n/a | 'the same top package without having to mention the package name. ' |

5936 | n/a | 'By\n' |

5937 | n/a | 'using leading dots in the specified module or package after "from" ' |

5938 | n/a | 'you\n' |

5939 | n/a | 'can specify how high to traverse up the current package hierarchy\n' |

5940 | n/a | 'without specifying exact names. One leading dot means the current\n' |

5941 | n/a | 'package where the module making the import exists. Two dots means ' |

5942 | n/a | 'up\n' |

5943 | n/a | 'one package level. Three dots is up two levels, etc. So if you ' |

5944 | n/a | 'execute\n' |

5945 | n/a | '"from . import mod" from a module in the "pkg" package then you ' |

5946 | n/a | 'will\n' |

5947 | n/a | 'end up importing "pkg.mod". If you execute "from ..subpkg2 import ' |

5948 | n/a | 'mod"\n' |

5949 | n/a | 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n' |

5950 | n/a | 'specification for relative imports is contained within **PEP ' |

5951 | n/a | '328**.\n' |

5952 | n/a | '\n' |

5953 | n/a | '"importlib.import_module()" is provided to support applications ' |

5954 | n/a | 'that\n' |

5955 | n/a | 'determine dynamically the modules to be loaded.\n' |

5956 | n/a | '\n' |

5957 | n/a | '\n' |

5958 | n/a | 'Future statements\n' |

5959 | n/a | '=================\n' |

5960 | n/a | '\n' |

5961 | n/a | 'A *future statement* is a directive to the compiler that a ' |

5962 | n/a | 'particular\n' |

5963 | n/a | 'module should be compiled using syntax or semantics that will be\n' |

5964 | n/a | 'available in a specified future release of Python where the ' |

5965 | n/a | 'feature\n' |

5966 | n/a | 'becomes standard.\n' |

5967 | n/a | '\n' |

5968 | n/a | 'The future statement is intended to ease migration to future ' |

5969 | n/a | 'versions\n' |

5970 | n/a | 'of Python that introduce incompatible changes to the language. ' |

5971 | n/a | 'It\n' |

5972 | n/a | 'allows use of the new features on a per-module basis before the\n' |

5973 | n/a | 'release in which the feature becomes standard.\n' |

5974 | n/a | '\n' |

5975 | n/a | ' future_statement ::= "from" "__future__" "import" feature ["as" ' |

5976 | n/a | 'name]\n' |

5977 | n/a | ' ("," feature ["as" name])*\n' |

5978 | n/a | ' | "from" "__future__" "import" "(" feature ' |

5979 | n/a | '["as" name]\n' |

5980 | n/a | ' ("," feature ["as" name])* [","] ")"\n' |

5981 | n/a | ' feature ::= identifier\n' |

5982 | n/a | ' name ::= identifier\n' |

5983 | n/a | '\n' |

5984 | n/a | 'A future statement must appear near the top of the module. The ' |

5985 | n/a | 'only\n' |

5986 | n/a | 'lines that can appear before a future statement are:\n' |

5987 | n/a | '\n' |

5988 | n/a | '* the module docstring (if any),\n' |

5989 | n/a | '\n' |

5990 | n/a | '* comments,\n' |

5991 | n/a | '\n' |

5992 | n/a | '* blank lines, and\n' |

5993 | n/a | '\n' |

5994 | n/a | '* other future statements.\n' |

5995 | n/a | '\n' |

5996 | n/a | 'The features recognized by Python 3.0 are "absolute_import",\n' |

5997 | n/a | '"division", "generators", "unicode_literals", "print_function",\n' |

5998 | n/a | '"nested_scopes" and "with_statement". They are all redundant ' |

5999 | n/a | 'because\n' |

6000 | n/a | 'they are always enabled, and only kept for backwards ' |

6001 | n/a | 'compatibility.\n' |

6002 | n/a | '\n' |

6003 | n/a | 'A future statement is recognized and treated specially at compile\n' |

6004 | n/a | 'time: Changes to the semantics of core constructs are often\n' |

6005 | n/a | 'implemented by generating different code. It may even be the ' |

6006 | n/a | 'case\n' |

6007 | n/a | 'that a new feature introduces new incompatible syntax (such as a ' |

6008 | n/a | 'new\n' |

6009 | n/a | 'reserved word), in which case the compiler may need to parse the\n' |

6010 | n/a | 'module differently. Such decisions cannot be pushed off until\n' |

6011 | n/a | 'runtime.\n' |

6012 | n/a | '\n' |

6013 | n/a | 'For any given release, the compiler knows which feature names ' |

6014 | n/a | 'have\n' |

6015 | n/a | 'been defined, and raises a compile-time error if a future ' |

6016 | n/a | 'statement\n' |

6017 | n/a | 'contains a feature not known to it.\n' |

6018 | n/a | '\n' |

6019 | n/a | 'The direct runtime semantics are the same as for any import ' |

6020 | n/a | 'statement:\n' |

6021 | n/a | 'there is a standard module "__future__", described later, and it ' |

6022 | n/a | 'will\n' |

6023 | n/a | 'be imported in the usual way at the time the future statement is\n' |

6024 | n/a | 'executed.\n' |

6025 | n/a | '\n' |

6026 | n/a | 'The interesting runtime semantics depend on the specific feature\n' |

6027 | n/a | 'enabled by the future statement.\n' |

6028 | n/a | '\n' |

6029 | n/a | 'Note that there is nothing special about the statement:\n' |

6030 | n/a | '\n' |

6031 | n/a | ' import __future__ [as name]\n' |

6032 | n/a | '\n' |

6033 | n/a | "That is not a future statement; it's an ordinary import statement " |

6034 | n/a | 'with\n' |

6035 | n/a | 'no special semantics or syntax restrictions.\n' |

6036 | n/a | '\n' |

6037 | n/a | 'Code compiled by calls to the built-in functions "exec()" and\n' |

6038 | n/a | '"compile()" that occur in a module "M" containing a future ' |

6039 | n/a | 'statement\n' |

6040 | n/a | 'will, by default, use the new syntax or semantics associated with ' |

6041 | n/a | 'the\n' |

6042 | n/a | 'future statement. This can be controlled by optional arguments ' |

6043 | n/a | 'to\n' |

6044 | n/a | '"compile()" --- see the documentation of that function for ' |

6045 | n/a | 'details.\n' |

6046 | n/a | '\n' |

6047 | n/a | 'A future statement typed at an interactive interpreter prompt ' |

6048 | n/a | 'will\n' |

6049 | n/a | 'take effect for the rest of the interpreter session. If an\n' |

6050 | n/a | 'interpreter is started with the "-i" option, is passed a script ' |

6051 | n/a | 'name\n' |

6052 | n/a | 'to execute, and the script includes a future statement, it will be ' |

6053 | n/a | 'in\n' |

6054 | n/a | 'effect in the interactive session started after the script is\n' |

6055 | n/a | 'executed.\n' |

6056 | n/a | '\n' |

6057 | n/a | 'See also:\n' |

6058 | n/a | '\n' |

6059 | n/a | ' **PEP 236** - Back to the __future__\n' |

6060 | n/a | ' The original proposal for the __future__ mechanism.\n', |

6061 | n/a | 'in': '\n' |

6062 | n/a | 'Membership test operations\n' |

6063 | n/a | '**************************\n' |

6064 | n/a | '\n' |

6065 | n/a | 'The operators "in" and "not in" test for membership. "x in s"\n' |

6066 | n/a | 'evaluates to true if *x* is a member of *s*, and false otherwise. "x\n' |

6067 | n/a | 'not in s" returns the negation of "x in s". All built-in sequences\n' |

6068 | n/a | 'and set types support this as well as dictionary, for which "in" ' |

6069 | n/a | 'tests\n' |

6070 | n/a | 'whether the dictionary has a given key. For container types such as\n' |

6071 | n/a | 'list, tuple, set, frozenset, dict, or collections.deque, the\n' |

6072 | n/a | 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' |

6073 | n/a | 'y)".\n' |

6074 | n/a | '\n' |

6075 | n/a | 'For the string and bytes types, "x in y" is true if and only if *x* ' |

6076 | n/a | 'is\n' |

6077 | n/a | 'a substring of *y*. An equivalent test is "y.find(x) != -1". Empty\n' |

6078 | n/a | 'strings are always considered to be a substring of any other string,\n' |

6079 | n/a | 'so """ in "abc"" will return "True".\n' |

6080 | n/a | '\n' |

6081 | n/a | 'For user-defined classes which define the "__contains__()" method, "x\n' |

6082 | n/a | 'in y" is true if and only if "y.__contains__(x)" is true.\n' |

6083 | n/a | '\n' |

6084 | n/a | 'For user-defined classes which do not define "__contains__()" but do\n' |

6085 | n/a | 'define "__iter__()", "x in y" is true if some value "z" with "x == z"\n' |

6086 | n/a | 'is produced while iterating over "y". If an exception is raised\n' |

6087 | n/a | 'during the iteration, it is as if "in" raised that exception.\n' |

6088 | n/a | '\n' |

6089 | n/a | 'Lastly, the old-style iteration protocol is tried: if a class defines\n' |

6090 | n/a | '"__getitem__()", "x in y" is true if and only if there is a non-\n' |

6091 | n/a | 'negative integer index *i* such that "x == y[i]", and all lower\n' |

6092 | n/a | 'integer indices do not raise "IndexError" exception. (If any other\n' |

6093 | n/a | 'exception is raised, it is as if "in" raised that exception).\n' |

6094 | n/a | '\n' |

6095 | n/a | 'The operator "not in" is defined to have the inverse true value of\n' |

6096 | n/a | '"in".\n', |

6097 | n/a | 'integers': '\n' |

6098 | n/a | 'Integer literals\n' |

6099 | n/a | '****************\n' |

6100 | n/a | '\n' |

6101 | n/a | 'Integer literals are described by the following lexical ' |

6102 | n/a | 'definitions:\n' |

6103 | n/a | '\n' |

6104 | n/a | ' integer ::= decinteger | bininteger | octinteger | ' |

6105 | n/a | 'hexinteger\n' |

6106 | n/a | ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] ' |

6107 | n/a | '"0")*\n' |

6108 | n/a | ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n' |

6109 | n/a | ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n' |

6110 | n/a | ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n' |

6111 | n/a | ' nonzerodigit ::= "1"..."9"\n' |

6112 | n/a | ' digit ::= "0"..."9"\n' |

6113 | n/a | ' bindigit ::= "0" | "1"\n' |

6114 | n/a | ' octdigit ::= "0"..."7"\n' |

6115 | n/a | ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' |

6116 | n/a | '\n' |

6117 | n/a | 'There is no limit for the length of integer literals apart from ' |

6118 | n/a | 'what\n' |

6119 | n/a | 'can be stored in available memory.\n' |

6120 | n/a | '\n' |

6121 | n/a | 'Underscores are ignored for determining the numeric value of ' |

6122 | n/a | 'the\n' |

6123 | n/a | 'literal. They can be used to group digits for enhanced ' |

6124 | n/a | 'readability.\n' |

6125 | n/a | 'One underscore can occur between digits, and after base ' |

6126 | n/a | 'specifiers\n' |

6127 | n/a | 'like "0x".\n' |

6128 | n/a | '\n' |

6129 | n/a | 'Note that leading zeros in a non-zero decimal number are not ' |

6130 | n/a | 'allowed.\n' |

6131 | n/a | 'This is for disambiguation with C-style octal literals, which ' |

6132 | n/a | 'Python\n' |

6133 | n/a | 'used before version 3.0.\n' |

6134 | n/a | '\n' |

6135 | n/a | 'Some examples of integer literals:\n' |

6136 | n/a | '\n' |

6137 | n/a | ' 7 2147483647 0o177 0b100110111\n' |

6138 | n/a | ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n' |

6139 | n/a | ' 100_000_000_000 0b_1110_0101\n' |

6140 | n/a | '\n' |

6141 | n/a | 'Changed in version 3.6: Underscores are now allowed for ' |

6142 | n/a | 'grouping\n' |

6143 | n/a | 'purposes in literals.\n', |

6144 | n/a | 'lambda': '\n' |

6145 | n/a | 'Lambdas\n' |

6146 | n/a | '*******\n' |

6147 | n/a | '\n' |

6148 | n/a | ' lambda_expr ::= "lambda" [parameter_list]: expression\n' |

6149 | n/a | ' lambda_expr_nocond ::= "lambda" [parameter_list]: ' |

6150 | n/a | 'expression_nocond\n' |

6151 | n/a | '\n' |

6152 | n/a | 'Lambda expressions (sometimes called lambda forms) are used to ' |

6153 | n/a | 'create\n' |

6154 | n/a | 'anonymous functions. The expression "lambda arguments: ' |

6155 | n/a | 'expression"\n' |

6156 | n/a | 'yields a function object. The unnamed object behaves like a ' |

6157 | n/a | 'function\n' |

6158 | n/a | 'object defined with:\n' |

6159 | n/a | '\n' |

6160 | n/a | ' def <lambda>(arguments):\n' |

6161 | n/a | ' return expression\n' |

6162 | n/a | '\n' |

6163 | n/a | 'See section Function definitions for the syntax of parameter ' |

6164 | n/a | 'lists.\n' |

6165 | n/a | 'Note that functions created with lambda expressions cannot ' |

6166 | n/a | 'contain\n' |

6167 | n/a | 'statements or annotations.\n', |

6168 | n/a | 'lists': '\n' |

6169 | n/a | 'List displays\n' |

6170 | n/a | '*************\n' |

6171 | n/a | '\n' |

6172 | n/a | 'A list display is a possibly empty series of expressions enclosed ' |

6173 | n/a | 'in\n' |

6174 | n/a | 'square brackets:\n' |

6175 | n/a | '\n' |

6176 | n/a | ' list_display ::= "[" [starred_list | comprehension] "]"\n' |

6177 | n/a | '\n' |

6178 | n/a | 'A list display yields a new list object, the contents being ' |

6179 | n/a | 'specified\n' |

6180 | n/a | 'by either a list of expressions or a comprehension. When a comma-\n' |

6181 | n/a | 'separated list of expressions is supplied, its elements are ' |

6182 | n/a | 'evaluated\n' |

6183 | n/a | 'from left to right and placed into the list object in that order.\n' |

6184 | n/a | 'When a comprehension is supplied, the list is constructed from the\n' |

6185 | n/a | 'elements resulting from the comprehension.\n', |

6186 | n/a | 'naming': '\n' |

6187 | n/a | 'Naming and binding\n' |

6188 | n/a | '******************\n' |

6189 | n/a | '\n' |

6190 | n/a | '\n' |

6191 | n/a | 'Binding of names\n' |

6192 | n/a | '================\n' |

6193 | n/a | '\n' |

6194 | n/a | '*Names* refer to objects. Names are introduced by name binding\n' |

6195 | n/a | 'operations.\n' |

6196 | n/a | '\n' |

6197 | n/a | 'The following constructs bind names: formal parameters to ' |

6198 | n/a | 'functions,\n' |

6199 | n/a | '"import" statements, class and function definitions (these bind ' |

6200 | n/a | 'the\n' |

6201 | n/a | 'class or function name in the defining block), and targets that ' |

6202 | n/a | 'are\n' |

6203 | n/a | 'identifiers if occurring in an assignment, "for" loop header, or ' |

6204 | n/a | 'after\n' |

6205 | n/a | '"as" in a "with" statement or "except" clause. The "import" ' |

6206 | n/a | 'statement\n' |

6207 | n/a | 'of the form "from ... import *" binds all names defined in the\n' |

6208 | n/a | 'imported module, except those beginning with an underscore. This ' |

6209 | n/a | 'form\n' |

6210 | n/a | 'may only be used at the module level.\n' |

6211 | n/a | '\n' |

6212 | n/a | 'A target occurring in a "del" statement is also considered bound ' |

6213 | n/a | 'for\n' |

6214 | n/a | 'this purpose (though the actual semantics are to unbind the ' |

6215 | n/a | 'name).\n' |

6216 | n/a | '\n' |

6217 | n/a | 'Each assignment or import statement occurs within a block defined ' |

6218 | n/a | 'by a\n' |

6219 | n/a | 'class or function definition or at the module level (the ' |

6220 | n/a | 'top-level\n' |

6221 | n/a | 'code block).\n' |

6222 | n/a | '\n' |

6223 | n/a | 'If a name is bound in a block, it is a local variable of that ' |

6224 | n/a | 'block,\n' |

6225 | n/a | 'unless declared as "nonlocal" or "global". If a name is bound at ' |

6226 | n/a | 'the\n' |

6227 | n/a | 'module level, it is a global variable. (The variables of the ' |

6228 | n/a | 'module\n' |

6229 | n/a | 'code block are local and global.) If a variable is used in a ' |

6230 | n/a | 'code\n' |

6231 | n/a | 'block but not defined there, it is a *free variable*.\n' |

6232 | n/a | '\n' |

6233 | n/a | 'Each occurrence of a name in the program text refers to the ' |

6234 | n/a | '*binding*\n' |

6235 | n/a | 'of that name established by the following name resolution rules.\n' |

6236 | n/a | '\n' |

6237 | n/a | '\n' |

6238 | n/a | 'Resolution of names\n' |

6239 | n/a | '===================\n' |

6240 | n/a | '\n' |

6241 | n/a | 'A *scope* defines the visibility of a name within a block. If a ' |

6242 | n/a | 'local\n' |

6243 | n/a | 'variable is defined in a block, its scope includes that block. If ' |

6244 | n/a | 'the\n' |

6245 | n/a | 'definition occurs in a function block, the scope extends to any ' |

6246 | n/a | 'blocks\n' |

6247 | n/a | 'contained within the defining one, unless a contained block ' |

6248 | n/a | 'introduces\n' |

6249 | n/a | 'a different binding for the name.\n' |

6250 | n/a | '\n' |

6251 | n/a | 'When a name is used in a code block, it is resolved using the ' |

6252 | n/a | 'nearest\n' |

6253 | n/a | 'enclosing scope. The set of all such scopes visible to a code ' |

6254 | n/a | 'block\n' |

6255 | n/a | "is called the block's *environment*.\n" |

6256 | n/a | '\n' |

6257 | n/a | 'When a name is not found at all, a "NameError" exception is ' |

6258 | n/a | 'raised. If\n' |

6259 | n/a | 'the current scope is a function scope, and the name refers to a ' |

6260 | n/a | 'local\n' |

6261 | n/a | 'variable that has not yet been bound to a value at the point where ' |

6262 | n/a | 'the\n' |

6263 | n/a | 'name is used, an "UnboundLocalError" exception is raised.\n' |

6264 | n/a | '"UnboundLocalError" is a subclass of "NameError".\n' |

6265 | n/a | '\n' |

6266 | n/a | 'If a name binding operation occurs anywhere within a code block, ' |

6267 | n/a | 'all\n' |

6268 | n/a | 'uses of the name within the block are treated as references to ' |

6269 | n/a | 'the\n' |

6270 | n/a | 'current block. This can lead to errors when a name is used within ' |

6271 | n/a | 'a\n' |

6272 | n/a | 'block before it is bound. This rule is subtle. Python lacks\n' |

6273 | n/a | 'declarations and allows name binding operations to occur anywhere\n' |

6274 | n/a | 'within a code block. The local variables of a code block can be\n' |

6275 | n/a | 'determined by scanning the entire text of the block for name ' |

6276 | n/a | 'binding\n' |

6277 | n/a | 'operations.\n' |

6278 | n/a | '\n' |

6279 | n/a | 'If the "global" statement occurs within a block, all uses of the ' |

6280 | n/a | 'name\n' |

6281 | n/a | 'specified in the statement refer to the binding of that name in ' |

6282 | n/a | 'the\n' |

6283 | n/a | 'top-level namespace. Names are resolved in the top-level ' |

6284 | n/a | 'namespace by\n' |

6285 | n/a | 'searching the global namespace, i.e. the namespace of the module\n' |

6286 | n/a | 'containing the code block, and the builtins namespace, the ' |

6287 | n/a | 'namespace\n' |

6288 | n/a | 'of the module "builtins". The global namespace is searched ' |

6289 | n/a | 'first. If\n' |

6290 | n/a | 'the name is not found there, the builtins namespace is searched. ' |

6291 | n/a | 'The\n' |

6292 | n/a | '"global" statement must precede all uses of the name.\n' |

6293 | n/a | '\n' |

6294 | n/a | 'The "global" statement has the same scope as a name binding ' |

6295 | n/a | 'operation\n' |

6296 | n/a | 'in the same block. If the nearest enclosing scope for a free ' |

6297 | n/a | 'variable\n' |

6298 | n/a | 'contains a global statement, the free variable is treated as a ' |

6299 | n/a | 'global.\n' |

6300 | n/a | '\n' |

6301 | n/a | 'The "nonlocal" statement causes corresponding names to refer to\n' |

6302 | n/a | 'previously bound variables in the nearest enclosing function ' |

6303 | n/a | 'scope.\n' |

6304 | n/a | '"SyntaxError" is raised at compile time if the given name does ' |

6305 | n/a | 'not\n' |

6306 | n/a | 'exist in any enclosing function scope.\n' |

6307 | n/a | '\n' |

6308 | n/a | 'The namespace for a module is automatically created the first time ' |

6309 | n/a | 'a\n' |

6310 | n/a | 'module is imported. The main module for a script is always ' |

6311 | n/a | 'called\n' |

6312 | n/a | '"__main__".\n' |

6313 | n/a | '\n' |

6314 | n/a | 'Class definition blocks and arguments to "exec()" and "eval()" ' |

6315 | n/a | 'are\n' |

6316 | n/a | 'special in the context of name resolution. A class definition is ' |

6317 | n/a | 'an\n' |

6318 | n/a | 'executable statement that may use and define names. These ' |

6319 | n/a | 'references\n' |

6320 | n/a | 'follow the normal rules for name resolution with an exception ' |

6321 | n/a | 'that\n' |

6322 | n/a | 'unbound local variables are looked up in the global namespace. ' |

6323 | n/a | 'The\n' |

6324 | n/a | 'namespace of the class definition becomes the attribute dictionary ' |

6325 | n/a | 'of\n' |

6326 | n/a | 'the class. The scope of names defined in a class block is limited ' |

6327 | n/a | 'to\n' |

6328 | n/a | 'the class block; it does not extend to the code blocks of methods ' |

6329 | n/a | '--\n' |

6330 | n/a | 'this includes comprehensions and generator expressions since they ' |

6331 | n/a | 'are\n' |

6332 | n/a | 'implemented using a function scope. This means that the ' |

6333 | n/a | 'following\n' |

6334 | n/a | 'will fail:\n' |

6335 | n/a | '\n' |

6336 | n/a | ' class A:\n' |

6337 | n/a | ' a = 42\n' |

6338 | n/a | ' b = list(a + i for i in range(10))\n' |

6339 | n/a | '\n' |

6340 | n/a | '\n' |

6341 | n/a | 'Builtins and restricted execution\n' |

6342 | n/a | '=================================\n' |

6343 | n/a | '\n' |

6344 | n/a | 'The builtins namespace associated with the execution of a code ' |

6345 | n/a | 'block\n' |

6346 | n/a | 'is actually found by looking up the name "__builtins__" in its ' |

6347 | n/a | 'global\n' |

6348 | n/a | 'namespace; this should be a dictionary or a module (in the latter ' |

6349 | n/a | 'case\n' |

6350 | n/a | "the module's dictionary is used). By default, when in the " |

6351 | n/a | '"__main__"\n' |

6352 | n/a | 'module, "__builtins__" is the built-in module "builtins"; when in ' |

6353 | n/a | 'any\n' |

6354 | n/a | 'other module, "__builtins__" is an alias for the dictionary of ' |

6355 | n/a | 'the\n' |

6356 | n/a | '"builtins" module itself. "__builtins__" can be set to a ' |

6357 | n/a | 'user-created\n' |

6358 | n/a | 'dictionary to create a weak form of restricted execution.\n' |

6359 | n/a | '\n' |

6360 | n/a | '**CPython implementation detail:** Users should not touch\n' |

6361 | n/a | '"__builtins__"; it is strictly an implementation detail. Users\n' |

6362 | n/a | 'wanting to override values in the builtins namespace should ' |

6363 | n/a | '"import"\n' |

6364 | n/a | 'the "builtins" module and modify its attributes appropriately.\n' |

6365 | n/a | '\n' |

6366 | n/a | '\n' |

6367 | n/a | 'Interaction with dynamic features\n' |

6368 | n/a | '=================================\n' |

6369 | n/a | '\n' |

6370 | n/a | 'Name resolution of free variables occurs at runtime, not at ' |

6371 | n/a | 'compile\n' |

6372 | n/a | 'time. This means that the following code will print 42:\n' |

6373 | n/a | '\n' |

6374 | n/a | ' i = 10\n' |

6375 | n/a | ' def f():\n' |

6376 | n/a | ' print(i)\n' |

6377 | n/a | ' i = 42\n' |

6378 | n/a | ' f()\n' |

6379 | n/a | '\n' |

6380 | n/a | 'There are several cases where Python statements are illegal when ' |

6381 | n/a | 'used\n' |

6382 | n/a | 'in conjunction with nested scopes that contain free variables.\n' |

6383 | n/a | '\n' |

6384 | n/a | 'If a variable is referenced in an enclosing scope, it is illegal ' |

6385 | n/a | 'to\n' |

6386 | n/a | 'delete the name. An error will be reported at compile time.\n' |

6387 | n/a | '\n' |

6388 | n/a | 'The "eval()" and "exec()" functions do not have access to the ' |

6389 | n/a | 'full\n' |

6390 | n/a | 'environment for resolving names. Names may be resolved in the ' |

6391 | n/a | 'local\n' |

6392 | n/a | 'and global namespaces of the caller. Free variables are not ' |

6393 | n/a | 'resolved\n' |

6394 | n/a | 'in the nearest enclosing namespace, but in the global namespace. ' |

6395 | n/a | '[1]\n' |

6396 | n/a | 'The "exec()" and "eval()" functions have optional arguments to\n' |

6397 | n/a | 'override the global and local namespace. If only one namespace ' |

6398 | n/a | 'is\n' |

6399 | n/a | 'specified, it is used for both.\n', |

6400 | n/a | 'nonlocal': '\n' |

6401 | n/a | 'The "nonlocal" statement\n' |

6402 | n/a | '************************\n' |

6403 | n/a | '\n' |

6404 | n/a | ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' |

6405 | n/a | '\n' |

6406 | n/a | 'The "nonlocal" statement causes the listed identifiers to refer ' |

6407 | n/a | 'to\n' |

6408 | n/a | 'previously bound variables in the nearest enclosing scope ' |

6409 | n/a | 'excluding\n' |

6410 | n/a | 'globals. This is important because the default behavior for ' |

6411 | n/a | 'binding is\n' |

6412 | n/a | 'to search the local namespace first. The statement allows\n' |

6413 | n/a | 'encapsulated code to rebind variables outside of the local ' |

6414 | n/a | 'scope\n' |

6415 | n/a | 'besides the global (module) scope.\n' |

6416 | n/a | '\n' |

6417 | n/a | 'Names listed in a "nonlocal" statement, unlike those listed in ' |

6418 | n/a | 'a\n' |

6419 | n/a | '"global" statement, must refer to pre-existing bindings in an\n' |

6420 | n/a | 'enclosing scope (the scope in which a new binding should be ' |

6421 | n/a | 'created\n' |

6422 | n/a | 'cannot be determined unambiguously).\n' |

6423 | n/a | '\n' |

6424 | n/a | 'Names listed in a "nonlocal" statement must not collide with ' |

6425 | n/a | 'pre-\n' |

6426 | n/a | 'existing bindings in the local scope.\n' |

6427 | n/a | '\n' |

6428 | n/a | 'See also:\n' |

6429 | n/a | '\n' |

6430 | n/a | ' **PEP 3104** - Access to Names in Outer Scopes\n' |

6431 | n/a | ' The specification for the "nonlocal" statement.\n', |

6432 | n/a | 'numbers': '\n' |

6433 | n/a | 'Numeric literals\n' |

6434 | n/a | '****************\n' |

6435 | n/a | '\n' |

6436 | n/a | 'There are three types of numeric literals: integers, floating ' |

6437 | n/a | 'point\n' |

6438 | n/a | 'numbers, and imaginary numbers. There are no complex literals\n' |

6439 | n/a | '(complex numbers can be formed by adding a real number and an\n' |

6440 | n/a | 'imaginary number).\n' |

6441 | n/a | '\n' |

6442 | n/a | 'Note that numeric literals do not include a sign; a phrase like ' |

6443 | n/a | '"-1"\n' |

6444 | n/a | 'is actually an expression composed of the unary operator \'"-"\' ' |

6445 | n/a | 'and the\n' |

6446 | n/a | 'literal "1".\n', |

6447 | n/a | 'numeric-types': '\n' |

6448 | n/a | 'Emulating numeric types\n' |

6449 | n/a | '***********************\n' |

6450 | n/a | '\n' |

6451 | n/a | 'The following methods can be defined to emulate numeric ' |

6452 | n/a | 'objects.\n' |

6453 | n/a | 'Methods corresponding to operations that are not supported ' |

6454 | n/a | 'by the\n' |

6455 | n/a | 'particular kind of number implemented (e.g., bitwise ' |

6456 | n/a | 'operations for\n' |

6457 | n/a | 'non-integral numbers) should be left undefined.\n' |

6458 | n/a | '\n' |

6459 | n/a | 'object.__add__(self, other)\n' |

6460 | n/a | 'object.__sub__(self, other)\n' |

6461 | n/a | 'object.__mul__(self, other)\n' |

6462 | n/a | 'object.__matmul__(self, other)\n' |

6463 | n/a | 'object.__truediv__(self, other)\n' |

6464 | n/a | 'object.__floordiv__(self, other)\n' |

6465 | n/a | 'object.__mod__(self, other)\n' |

6466 | n/a | 'object.__divmod__(self, other)\n' |

6467 | n/a | 'object.__pow__(self, other[, modulo])\n' |

6468 | n/a | 'object.__lshift__(self, other)\n' |

6469 | n/a | 'object.__rshift__(self, other)\n' |

6470 | n/a | 'object.__and__(self, other)\n' |

6471 | n/a | 'object.__xor__(self, other)\n' |

6472 | n/a | 'object.__or__(self, other)\n' |

6473 | n/a | '\n' |

6474 | n/a | ' These methods are called to implement the binary ' |

6475 | n/a | 'arithmetic\n' |

6476 | n/a | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |

6477 | n/a | '"divmod()",\n' |

6478 | n/a | ' "pow()", "**", "<<", ">>", "&", "^", "|"). For ' |

6479 | n/a | 'instance, to\n' |

6480 | n/a | ' evaluate the expression "x + y", where *x* is an ' |

6481 | n/a | 'instance of a\n' |

6482 | n/a | ' class that has an "__add__()" method, "x.__add__(y)" is ' |

6483 | n/a | 'called.\n' |

6484 | n/a | ' The "__divmod__()" method should be the equivalent to ' |

6485 | n/a | 'using\n' |

6486 | n/a | ' "__floordiv__()" and "__mod__()"; it should not be ' |

6487 | n/a | 'related to\n' |

6488 | n/a | ' "__truediv__()". Note that "__pow__()" should be ' |

6489 | n/a | 'defined to accept\n' |

6490 | n/a | ' an optional third argument if the ternary version of the ' |

6491 | n/a | 'built-in\n' |

6492 | n/a | ' "pow()" function is to be supported.\n' |

6493 | n/a | '\n' |

6494 | n/a | ' If one of those methods does not support the operation ' |

6495 | n/a | 'with the\n' |

6496 | n/a | ' supplied arguments, it should return "NotImplemented".\n' |

6497 | n/a | '\n' |

6498 | n/a | 'object.__radd__(self, other)\n' |

6499 | n/a | 'object.__rsub__(self, other)\n' |

6500 | n/a | 'object.__rmul__(self, other)\n' |

6501 | n/a | 'object.__rmatmul__(self, other)\n' |

6502 | n/a | 'object.__rtruediv__(self, other)\n' |

6503 | n/a | 'object.__rfloordiv__(self, other)\n' |

6504 | n/a | 'object.__rmod__(self, other)\n' |

6505 | n/a | 'object.__rdivmod__(self, other)\n' |

6506 | n/a | 'object.__rpow__(self, other)\n' |

6507 | n/a | 'object.__rlshift__(self, other)\n' |

6508 | n/a | 'object.__rrshift__(self, other)\n' |

6509 | n/a | 'object.__rand__(self, other)\n' |

6510 | n/a | 'object.__rxor__(self, other)\n' |

6511 | n/a | 'object.__ror__(self, other)\n' |

6512 | n/a | '\n' |

6513 | n/a | ' These methods are called to implement the binary ' |

6514 | n/a | 'arithmetic\n' |

6515 | n/a | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |

6516 | n/a | '"divmod()",\n' |

6517 | n/a | ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' |

6518 | n/a | '(swapped)\n' |

6519 | n/a | ' operands. These functions are only called if the left ' |

6520 | n/a | 'operand does\n' |

6521 | n/a | ' not support the corresponding operation [3] and the ' |

6522 | n/a | 'operands are of\n' |

6523 | n/a | ' different types. [4] For instance, to evaluate the ' |

6524 | n/a | 'expression "x -\n' |

6525 | n/a | ' y", where *y* is an instance of a class that has an ' |

6526 | n/a | '"__rsub__()"\n' |

6527 | n/a | ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' |

6528 | n/a | 'returns\n' |

6529 | n/a | ' *NotImplemented*.\n' |

6530 | n/a | '\n' |

6531 | n/a | ' Note that ternary "pow()" will not try calling ' |

6532 | n/a | '"__rpow__()" (the\n' |

6533 | n/a | ' coercion rules would become too complicated).\n' |

6534 | n/a | '\n' |

6535 | n/a | " Note: If the right operand's type is a subclass of the " |

6536 | n/a | 'left\n' |

6537 | n/a | " operand's type and that subclass provides the " |

6538 | n/a | 'reflected method\n' |

6539 | n/a | ' for the operation, this method will be called before ' |

6540 | n/a | 'the left\n' |

6541 | n/a | " operand's non-reflected method. This behavior allows " |

6542 | n/a | 'subclasses\n' |

6543 | n/a | " to override their ancestors' operations.\n" |

6544 | n/a | '\n' |

6545 | n/a | 'object.__iadd__(self, other)\n' |

6546 | n/a | 'object.__isub__(self, other)\n' |

6547 | n/a | 'object.__imul__(self, other)\n' |

6548 | n/a | 'object.__imatmul__(self, other)\n' |

6549 | n/a | 'object.__itruediv__(self, other)\n' |

6550 | n/a | 'object.__ifloordiv__(self, other)\n' |

6551 | n/a | 'object.__imod__(self, other)\n' |

6552 | n/a | 'object.__ipow__(self, other[, modulo])\n' |

6553 | n/a | 'object.__ilshift__(self, other)\n' |

6554 | n/a | 'object.__irshift__(self, other)\n' |

6555 | n/a | 'object.__iand__(self, other)\n' |

6556 | n/a | 'object.__ixor__(self, other)\n' |

6557 | n/a | 'object.__ior__(self, other)\n' |

6558 | n/a | '\n' |

6559 | n/a | ' These methods are called to implement the augmented ' |

6560 | n/a | 'arithmetic\n' |

6561 | n/a | ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' |

6562 | n/a | '"**=",\n' |

6563 | n/a | ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' |

6564 | n/a | 'attempt to\n' |

6565 | n/a | ' do the operation in-place (modifying *self*) and return ' |

6566 | n/a | 'the result\n' |

6567 | n/a | ' (which could be, but does not have to be, *self*). If a ' |

6568 | n/a | 'specific\n' |

6569 | n/a | ' method is not defined, the augmented assignment falls ' |

6570 | n/a | 'back to the\n' |

6571 | n/a | ' normal methods. For instance, if *x* is an instance of ' |

6572 | n/a | 'a class\n' |

6573 | n/a | ' with an "__iadd__()" method, "x += y" is equivalent to ' |

6574 | n/a | '"x =\n' |

6575 | n/a | ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' |

6576 | n/a | '"y.__radd__(x)" are\n' |

6577 | n/a | ' considered, as with the evaluation of "x + y". In ' |

6578 | n/a | 'certain\n' |

6579 | n/a | ' situations, augmented assignment can result in ' |

6580 | n/a | 'unexpected errors\n' |

6581 | n/a | " (see Why does a_tuple[i] += ['item'] raise an exception " |

6582 | n/a | 'when the\n' |

6583 | n/a | ' addition works?), but this behavior is in fact part of ' |

6584 | n/a | 'the data\n' |

6585 | n/a | ' model.\n' |

6586 | n/a | '\n' |

6587 | n/a | 'object.__neg__(self)\n' |

6588 | n/a | 'object.__pos__(self)\n' |

6589 | n/a | 'object.__abs__(self)\n' |

6590 | n/a | 'object.__invert__(self)\n' |

6591 | n/a | '\n' |

6592 | n/a | ' Called to implement the unary arithmetic operations ' |

6593 | n/a | '("-", "+",\n' |

6594 | n/a | ' "abs()" and "~").\n' |

6595 | n/a | '\n' |

6596 | n/a | 'object.__complex__(self)\n' |

6597 | n/a | 'object.__int__(self)\n' |

6598 | n/a | 'object.__float__(self)\n' |

6599 | n/a | 'object.__round__(self[, n])\n' |

6600 | n/a | '\n' |

6601 | n/a | ' Called to implement the built-in functions "complex()", ' |

6602 | n/a | '"int()",\n' |

6603 | n/a | ' "float()" and "round()". Should return a value of the ' |

6604 | n/a | 'appropriate\n' |

6605 | n/a | ' type.\n' |

6606 | n/a | '\n' |

6607 | n/a | 'object.__index__(self)\n' |

6608 | n/a | '\n' |

6609 | n/a | ' Called to implement "operator.index()", and whenever ' |

6610 | n/a | 'Python needs\n' |

6611 | n/a | ' to losslessly convert the numeric object to an integer ' |

6612 | n/a | 'object (such\n' |

6613 | n/a | ' as in slicing, or in the built-in "bin()", "hex()" and ' |

6614 | n/a | '"oct()"\n' |

6615 | n/a | ' functions). Presence of this method indicates that the ' |

6616 | n/a | 'numeric\n' |

6617 | n/a | ' object is an integer type. Must return an integer.\n' |

6618 | n/a | '\n' |

6619 | n/a | ' Note: In order to have a coherent integer type class, ' |

6620 | n/a | 'when\n' |

6621 | n/a | ' "__index__()" is defined "__int__()" should also be ' |

6622 | n/a | 'defined, and\n' |

6623 | n/a | ' both should return the same value.\n', |

6624 | n/a | 'objects': '\n' |

6625 | n/a | 'Objects, values and types\n' |

6626 | n/a | '*************************\n' |

6627 | n/a | '\n' |

6628 | n/a | "*Objects* are Python's abstraction for data. All data in a " |

6629 | n/a | 'Python\n' |

6630 | n/a | 'program is represented by objects or by relations between ' |

6631 | n/a | 'objects. (In\n' |

6632 | n/a | 'a sense, and in conformance to Von Neumann\'s model of a "stored\n' |

6633 | n/a | 'program computer," code is also represented by objects.)\n' |

6634 | n/a | '\n' |

6635 | n/a | "Every object has an identity, a type and a value. An object's\n" |

6636 | n/a | '*identity* never changes once it has been created; you may think ' |

6637 | n/a | 'of it\n' |

6638 | n/a | 'as the object\'s address in memory. The \'"is"\' operator ' |

6639 | n/a | 'compares the\n' |

6640 | n/a | 'identity of two objects; the "id()" function returns an integer\n' |

6641 | n/a | 'representing its identity.\n' |

6642 | n/a | '\n' |

6643 | n/a | '**CPython implementation detail:** For CPython, "id(x)" is the ' |

6644 | n/a | 'memory\n' |

6645 | n/a | 'address where "x" is stored.\n' |

6646 | n/a | '\n' |

6647 | n/a | "An object's type determines the operations that the object " |

6648 | n/a | 'supports\n' |

6649 | n/a | '(e.g., "does it have a length?") and also defines the possible ' |

6650 | n/a | 'values\n' |

6651 | n/a | 'for objects of that type. The "type()" function returns an ' |

6652 | n/a | "object's\n" |

6653 | n/a | 'type (which is an object itself). Like its identity, an ' |

6654 | n/a | "object's\n" |

6655 | n/a | '*type* is also unchangeable. [1]\n' |

6656 | n/a | '\n' |

6657 | n/a | 'The *value* of some objects can change. Objects whose value can\n' |

6658 | n/a | 'change are said to be *mutable*; objects whose value is ' |

6659 | n/a | 'unchangeable\n' |

6660 | n/a | 'once they are created are called *immutable*. (The value of an\n' |

6661 | n/a | 'immutable container object that contains a reference to a ' |

6662 | n/a | 'mutable\n' |

6663 | n/a | "object can change when the latter's value is changed; however " |

6664 | n/a | 'the\n' |

6665 | n/a | 'container is still considered immutable, because the collection ' |

6666 | n/a | 'of\n' |

6667 | n/a | 'objects it contains cannot be changed. So, immutability is not\n' |

6668 | n/a | 'strictly the same as having an unchangeable value, it is more ' |

6669 | n/a | 'subtle.)\n' |

6670 | n/a | "An object's mutability is determined by its type; for instance,\n" |

6671 | n/a | 'numbers, strings and tuples are immutable, while dictionaries ' |

6672 | n/a | 'and\n' |

6673 | n/a | 'lists are mutable.\n' |

6674 | n/a | '\n' |

6675 | n/a | 'Objects are never explicitly destroyed; however, when they ' |

6676 | n/a | 'become\n' |

6677 | n/a | 'unreachable they may be garbage-collected. An implementation is\n' |

6678 | n/a | 'allowed to postpone garbage collection or omit it altogether --- ' |

6679 | n/a | 'it is\n' |

6680 | n/a | 'a matter of implementation quality how garbage collection is\n' |

6681 | n/a | 'implemented, as long as no objects are collected that are still\n' |

6682 | n/a | 'reachable.\n' |

6683 | n/a | '\n' |

6684 | n/a | '**CPython implementation detail:** CPython currently uses a ' |

6685 | n/a | 'reference-\n' |

6686 | n/a | 'counting scheme with (optional) delayed detection of cyclically ' |

6687 | n/a | 'linked\n' |

6688 | n/a | 'garbage, which collects most objects as soon as they become\n' |

6689 | n/a | 'unreachable, but is not guaranteed to collect garbage containing\n' |

6690 | n/a | 'circular references. See the documentation of the "gc" module ' |

6691 | n/a | 'for\n' |

6692 | n/a | 'information on controlling the collection of cyclic garbage. ' |

6693 | n/a | 'Other\n' |

6694 | n/a | 'implementations act differently and CPython may change. Do not ' |

6695 | n/a | 'depend\n' |

6696 | n/a | 'on immediate finalization of objects when they become unreachable ' |

6697 | n/a | '(so\n' |

6698 | n/a | 'you should always close files explicitly).\n' |

6699 | n/a | '\n' |

6700 | n/a | "Note that the use of the implementation's tracing or debugging\n" |

6701 | n/a | 'facilities may keep objects alive that would normally be ' |

6702 | n/a | 'collectable.\n' |

6703 | n/a | 'Also note that catching an exception with a \'"try"..."except"\'\n' |

6704 | n/a | 'statement may keep objects alive.\n' |

6705 | n/a | '\n' |

6706 | n/a | 'Some objects contain references to "external" resources such as ' |

6707 | n/a | 'open\n' |

6708 | n/a | 'files or windows. It is understood that these resources are ' |

6709 | n/a | 'freed\n' |

6710 | n/a | 'when the object is garbage-collected, but since garbage ' |

6711 | n/a | 'collection is\n' |

6712 | n/a | 'not guaranteed to happen, such objects also provide an explicit ' |

6713 | n/a | 'way to\n' |

6714 | n/a | 'release the external resource, usually a "close()" method. ' |

6715 | n/a | 'Programs\n' |

6716 | n/a | 'are strongly recommended to explicitly close such objects. The\n' |

6717 | n/a | '\'"try"..."finally"\' statement and the \'"with"\' statement ' |

6718 | n/a | 'provide\n' |

6719 | n/a | 'convenient ways to do this.\n' |

6720 | n/a | '\n' |

6721 | n/a | 'Some objects contain references to other objects; these are ' |

6722 | n/a | 'called\n' |

6723 | n/a | '*containers*. Examples of containers are tuples, lists and\n' |

6724 | n/a | "dictionaries. The references are part of a container's value. " |

6725 | n/a | 'In\n' |

6726 | n/a | 'most cases, when we talk about the value of a container, we imply ' |

6727 | n/a | 'the\n' |

6728 | n/a | 'values, not the identities of the contained objects; however, ' |

6729 | n/a | 'when we\n' |

6730 | n/a | 'talk about the mutability of a container, only the identities of ' |

6731 | n/a | 'the\n' |

6732 | n/a | 'immediately contained objects are implied. So, if an immutable\n' |

6733 | n/a | 'container (like a tuple) contains a reference to a mutable ' |

6734 | n/a | 'object, its\n' |

6735 | n/a | 'value changes if that mutable object is changed.\n' |

6736 | n/a | '\n' |

6737 | n/a | 'Types affect almost all aspects of object behavior. Even the\n' |

6738 | n/a | 'importance of object identity is affected in some sense: for ' |

6739 | n/a | 'immutable\n' |

6740 | n/a | 'types, operations that compute new values may actually return a\n' |

6741 | n/a | 'reference to any existing object with the same type and value, ' |

6742 | n/a | 'while\n' |

6743 | n/a | 'for mutable objects this is not allowed. E.g., after "a = 1; b = ' |

6744 | n/a | '1",\n' |

6745 | n/a | '"a" and "b" may or may not refer to the same object with the ' |

6746 | n/a | 'value\n' |

6747 | n/a | 'one, depending on the implementation, but after "c = []; d = []", ' |

6748 | n/a | '"c"\n' |

6749 | n/a | 'and "d" are guaranteed to refer to two different, unique, newly\n' |

6750 | n/a | 'created empty lists. (Note that "c = d = []" assigns the same ' |

6751 | n/a | 'object\n' |

6752 | n/a | 'to both "c" and "d".)\n', |

6753 | n/a | 'operator-summary': '\n' |

6754 | n/a | 'Operator precedence\n' |

6755 | n/a | '*******************\n' |

6756 | n/a | '\n' |

6757 | n/a | 'The following table summarizes the operator precedence ' |

6758 | n/a | 'in Python, from\n' |

6759 | n/a | 'lowest precedence (least binding) to highest precedence ' |

6760 | n/a | '(most\n' |

6761 | n/a | 'binding). Operators in the same box have the same ' |

6762 | n/a | 'precedence. Unless\n' |

6763 | n/a | 'the syntax is explicitly given, operators are binary. ' |

6764 | n/a | 'Operators in\n' |

6765 | n/a | 'the same box group left to right (except for ' |

6766 | n/a | 'exponentiation, which\n' |

6767 | n/a | 'groups from right to left).\n' |

6768 | n/a | '\n' |

6769 | n/a | 'Note that comparisons, membership tests, and identity ' |

6770 | n/a | 'tests, all have\n' |

6771 | n/a | 'the same precedence and have a left-to-right chaining ' |

6772 | n/a | 'feature as\n' |

6773 | n/a | 'described in the Comparisons section.\n' |

6774 | n/a | '\n' |

6775 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6776 | n/a | '| Operator | ' |

6777 | n/a | 'Description |\n' |

6778 | n/a | '+=================================================+=======================================+\n' |

6779 | n/a | '| "lambda" | ' |

6780 | n/a | 'Lambda expression |\n' |

6781 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6782 | n/a | '| "if" -- "else" | ' |

6783 | n/a | 'Conditional expression |\n' |

6784 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6785 | n/a | '| "or" | ' |

6786 | n/a | 'Boolean OR |\n' |

6787 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6788 | n/a | '| "and" | ' |

6789 | n/a | 'Boolean AND |\n' |

6790 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6791 | n/a | '| "not" "x" | ' |

6792 | n/a | 'Boolean NOT |\n' |

6793 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6794 | n/a | '| "in", "not in", "is", "is not", "<", "<=", ">", | ' |

6795 | n/a | 'Comparisons, including membership |\n' |

6796 | n/a | '| ">=", "!=", "==" | ' |

6797 | n/a | 'tests and identity tests |\n' |

6798 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6799 | n/a | '| "|" | ' |

6800 | n/a | 'Bitwise OR |\n' |

6801 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6802 | n/a | '| "^" | ' |

6803 | n/a | 'Bitwise XOR |\n' |

6804 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6805 | n/a | '| "&" | ' |

6806 | n/a | 'Bitwise AND |\n' |

6807 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6808 | n/a | '| "<<", ">>" | ' |

6809 | n/a | 'Shifts |\n' |

6810 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6811 | n/a | '| "+", "-" | ' |

6812 | n/a | 'Addition and subtraction |\n' |

6813 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6814 | n/a | '| "*", "@", "/", "//", "%" | ' |

6815 | n/a | 'Multiplication, matrix multiplication |\n' |

6816 | n/a | '| | ' |

6817 | n/a | 'division, remainder [5] |\n' |

6818 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6819 | n/a | '| "+x", "-x", "~x" | ' |

6820 | n/a | 'Positive, negative, bitwise NOT |\n' |

6821 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6822 | n/a | '| "**" | ' |

6823 | n/a | 'Exponentiation [6] |\n' |

6824 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6825 | n/a | '| "await" "x" | ' |

6826 | n/a | 'Await expression |\n' |

6827 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6828 | n/a | '| "x[index]", "x[index:index]", | ' |

6829 | n/a | 'Subscription, slicing, call, |\n' |

6830 | n/a | '| "x(arguments...)", "x.attribute" | ' |

6831 | n/a | 'attribute reference |\n' |

6832 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6833 | n/a | '| "(expressions...)", "[expressions...]", "{key: | ' |

6834 | n/a | 'Binding or tuple display, list |\n' |

6835 | n/a | '| value...}", "{expressions...}" | ' |

6836 | n/a | 'display, dictionary display, set |\n' |

6837 | n/a | '| | ' |

6838 | n/a | 'display |\n' |

6839 | n/a | '+-------------------------------------------------+---------------------------------------+\n' |

6840 | n/a | '\n' |

6841 | n/a | '-[ Footnotes ]-\n' |

6842 | n/a | '\n' |

6843 | n/a | '[1] While "abs(x%y) < abs(y)" is true mathematically, ' |

6844 | n/a | 'for floats\n' |

6845 | n/a | ' it may not be true numerically due to roundoff. For ' |

6846 | n/a | 'example, and\n' |

6847 | n/a | ' assuming a platform on which a Python float is an ' |

6848 | n/a | 'IEEE 754 double-\n' |

6849 | n/a | ' precision number, in order that "-1e-100 % 1e100" ' |

6850 | n/a | 'have the same\n' |

6851 | n/a | ' sign as "1e100", the computed result is "-1e-100 + ' |

6852 | n/a | '1e100", which\n' |

6853 | n/a | ' is numerically exactly equal to "1e100". The ' |

6854 | n/a | 'function\n' |

6855 | n/a | ' "math.fmod()" returns a result whose sign matches ' |

6856 | n/a | 'the sign of the\n' |

6857 | n/a | ' first argument instead, and so returns "-1e-100" in ' |

6858 | n/a | 'this case.\n' |

6859 | n/a | ' Which approach is more appropriate depends on the ' |

6860 | n/a | 'application.\n' |

6861 | n/a | '\n' |

6862 | n/a | '[2] If x is very close to an exact integer multiple of ' |

6863 | n/a | "y, it's\n" |

6864 | n/a | ' possible for "x//y" to be one larger than ' |

6865 | n/a | '"(x-x%y)//y" due to\n' |

6866 | n/a | ' rounding. In such cases, Python returns the latter ' |

6867 | n/a | 'result, in\n' |

6868 | n/a | ' order to preserve that "divmod(x,y)[0] * y + x % y" ' |

6869 | n/a | 'be very close\n' |

6870 | n/a | ' to "x".\n' |

6871 | n/a | '\n' |

6872 | n/a | '[3] The Unicode standard distinguishes between *code ' |

6873 | n/a | 'points* (e.g.\n' |

6874 | n/a | ' U+0041) and *abstract characters* (e.g. "LATIN ' |

6875 | n/a | 'CAPITAL LETTER A").\n' |

6876 | n/a | ' While most abstract characters in Unicode are only ' |

6877 | n/a | 'represented\n' |

6878 | n/a | ' using one code point, there is a number of abstract ' |

6879 | n/a | 'characters\n' |

6880 | n/a | ' that can in addition be represented using a sequence ' |

6881 | n/a | 'of more than\n' |

6882 | n/a | ' one code point. For example, the abstract character ' |

6883 | n/a | '"LATIN\n' |

6884 | n/a | ' CAPITAL LETTER C WITH CEDILLA" can be represented as ' |

6885 | n/a | 'a single\n' |

6886 | n/a | ' *precomposed character* at code position U+00C7, or ' |

6887 | n/a | 'as a sequence\n' |

6888 | n/a | ' of a *base character* at code position U+0043 (LATIN ' |

6889 | n/a | 'CAPITAL\n' |

6890 | n/a | ' LETTER C), followed by a *combining character* at ' |

6891 | n/a | 'code position\n' |

6892 | n/a | ' U+0327 (COMBINING CEDILLA).\n' |

6893 | n/a | '\n' |

6894 | n/a | ' The comparison operators on strings compare at the ' |

6895 | n/a | 'level of\n' |

6896 | n/a | ' Unicode code points. This may be counter-intuitive ' |

6897 | n/a | 'to humans. For\n' |

6898 | n/a | ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", ' |

6899 | n/a | 'even though both\n' |

6900 | n/a | ' strings represent the same abstract character "LATIN ' |

6901 | n/a | 'CAPITAL\n' |

6902 | n/a | ' LETTER C WITH CEDILLA".\n' |

6903 | n/a | '\n' |

6904 | n/a | ' To compare strings at the level of abstract ' |

6905 | n/a | 'characters (that is,\n' |

6906 | n/a | ' in a way intuitive to humans), use ' |

6907 | n/a | '"unicodedata.normalize()".\n' |

6908 | n/a | '\n' |

6909 | n/a | '[4] Due to automatic garbage-collection, free lists, and ' |

6910 | n/a | 'the\n' |

6911 | n/a | ' dynamic nature of descriptors, you may notice ' |

6912 | n/a | 'seemingly unusual\n' |

6913 | n/a | ' behaviour in certain uses of the "is" operator, like ' |

6914 | n/a | 'those\n' |

6915 | n/a | ' involving comparisons between instance methods, or ' |

6916 | n/a | 'constants.\n' |

6917 | n/a | ' Check their documentation for more info.\n' |

6918 | n/a | '\n' |

6919 | n/a | '[5] The "%" operator is also used for string formatting; ' |

6920 | n/a | 'the same\n' |

6921 | n/a | ' precedence applies.\n' |

6922 | n/a | '\n' |

6923 | n/a | '[6] The power operator "**" binds less tightly than an ' |

6924 | n/a | 'arithmetic\n' |

6925 | n/a | ' or bitwise unary operator on its right, that is, ' |

6926 | n/a | '"2**-1" is "0.5".\n', |

6927 | n/a | 'pass': '\n' |

6928 | n/a | 'The "pass" statement\n' |

6929 | n/a | '********************\n' |

6930 | n/a | '\n' |

6931 | n/a | ' pass_stmt ::= "pass"\n' |

6932 | n/a | '\n' |

6933 | n/a | '"pass" is a null operation --- when it is executed, nothing ' |

6934 | n/a | 'happens.\n' |

6935 | n/a | 'It is useful as a placeholder when a statement is required\n' |

6936 | n/a | 'syntactically, but no code needs to be executed, for example:\n' |

6937 | n/a | '\n' |

6938 | n/a | ' def f(arg): pass # a function that does nothing (yet)\n' |

6939 | n/a | '\n' |

6940 | n/a | ' class C: pass # a class with no methods (yet)\n', |

6941 | n/a | 'power': '\n' |

6942 | n/a | 'The power operator\n' |

6943 | n/a | '******************\n' |

6944 | n/a | '\n' |

6945 | n/a | 'The power operator binds more tightly than unary operators on its\n' |

6946 | n/a | 'left; it binds less tightly than unary operators on its right. ' |

6947 | n/a | 'The\n' |

6948 | n/a | 'syntax is:\n' |

6949 | n/a | '\n' |

6950 | n/a | ' power ::= ( await_expr | primary ) ["**" u_expr]\n' |

6951 | n/a | '\n' |

6952 | n/a | 'Thus, in an unparenthesized sequence of power and unary operators, ' |

6953 | n/a | 'the\n' |

6954 | n/a | 'operators are evaluated from right to left (this does not ' |

6955 | n/a | 'constrain\n' |

6956 | n/a | 'the evaluation order for the operands): "-1**2" results in "-1".\n' |

6957 | n/a | '\n' |

6958 | n/a | 'The power operator has the same semantics as the built-in "pow()"\n' |

6959 | n/a | 'function, when called with two arguments: it yields its left ' |

6960 | n/a | 'argument\n' |

6961 | n/a | 'raised to the power of its right argument. The numeric arguments ' |

6962 | n/a | 'are\n' |

6963 | n/a | 'first converted to a common type, and the result is of that type.\n' |

6964 | n/a | '\n' |

6965 | n/a | 'For int operands, the result has the same type as the operands ' |

6966 | n/a | 'unless\n' |

6967 | n/a | 'the second argument is negative; in that case, all arguments are\n' |

6968 | n/a | 'converted to float and a float result is delivered. For example,\n' |

6969 | n/a | '"10**2" returns "100", but "10**-2" returns "0.01".\n' |

6970 | n/a | '\n' |

6971 | n/a | 'Raising "0.0" to a negative power results in a ' |

6972 | n/a | '"ZeroDivisionError".\n' |

6973 | n/a | 'Raising a negative number to a fractional power results in a ' |

6974 | n/a | '"complex"\n' |

6975 | n/a | 'number. (In earlier versions it raised a "ValueError".)\n', |

6976 | n/a | 'raise': '\n' |

6977 | n/a | 'The "raise" statement\n' |

6978 | n/a | '*********************\n' |

6979 | n/a | '\n' |

6980 | n/a | ' raise_stmt ::= "raise" [expression ["from" expression]]\n' |

6981 | n/a | '\n' |

6982 | n/a | 'If no expressions are present, "raise" re-raises the last ' |

6983 | n/a | 'exception\n' |

6984 | n/a | 'that was active in the current scope. If no exception is active ' |

6985 | n/a | 'in\n' |

6986 | n/a | 'the current scope, a "RuntimeError" exception is raised indicating\n' |

6987 | n/a | 'that this is an error.\n' |

6988 | n/a | '\n' |

6989 | n/a | 'Otherwise, "raise" evaluates the first expression as the exception\n' |

6990 | n/a | 'object. It must be either a subclass or an instance of\n' |

6991 | n/a | '"BaseException". If it is a class, the exception instance will be\n' |

6992 | n/a | 'obtained when needed by instantiating the class with no arguments.\n' |

6993 | n/a | '\n' |

6994 | n/a | "The *type* of the exception is the exception instance's class, the\n" |

6995 | n/a | '*value* is the instance itself.\n' |

6996 | n/a | '\n' |

6997 | n/a | 'A traceback object is normally created automatically when an ' |

6998 | n/a | 'exception\n' |

6999 | n/a | 'is raised and attached to it as the "__traceback__" attribute, ' |

7000 | n/a | 'which\n' |

7001 | n/a | 'is writable. You can create an exception and set your own traceback ' |

7002 | n/a | 'in\n' |

7003 | n/a | 'one step using the "with_traceback()" exception method (which ' |

7004 | n/a | 'returns\n' |

7005 | n/a | 'the same exception instance, with its traceback set to its ' |

7006 | n/a | 'argument),\n' |

7007 | n/a | 'like so:\n' |

7008 | n/a | '\n' |

7009 | n/a | ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' |

7010 | n/a | '\n' |

7011 | n/a | 'The "from" clause is used for exception chaining: if given, the ' |

7012 | n/a | 'second\n' |

7013 | n/a | '*expression* must be another exception class or instance, which ' |

7014 | n/a | 'will\n' |

7015 | n/a | 'then be attached to the raised exception as the "__cause__" ' |

7016 | n/a | 'attribute\n' |

7017 | n/a | '(which is writable). If the raised exception is not handled, both\n' |

7018 | n/a | 'exceptions will be printed:\n' |

7019 | n/a | '\n' |

7020 | n/a | ' >>> try:\n' |

7021 | n/a | ' ... print(1 / 0)\n' |

7022 | n/a | ' ... except Exception as exc:\n' |

7023 | n/a | ' ... raise RuntimeError("Something bad happened") from exc\n' |

7024 | n/a | ' ...\n' |

7025 | n/a | ' Traceback (most recent call last):\n' |

7026 | n/a | ' File "<stdin>", line 2, in <module>\n' |

7027 | n/a | ' ZeroDivisionError: int division or modulo by zero\n' |

7028 | n/a | '\n' |

7029 | n/a | ' The above exception was the direct cause of the following ' |

7030 | n/a | 'exception:\n' |

7031 | n/a | '\n' |

7032 | n/a | ' Traceback (most recent call last):\n' |

7033 | n/a | ' File "<stdin>", line 4, in <module>\n' |

7034 | n/a | ' RuntimeError: Something bad happened\n' |

7035 | n/a | '\n' |

7036 | n/a | 'A similar mechanism works implicitly if an exception is raised ' |

7037 | n/a | 'inside\n' |

7038 | n/a | 'an exception handler or a "finally" clause: the previous exception ' |

7039 | n/a | 'is\n' |

7040 | n/a | 'then attached as the new exception\'s "__context__" attribute:\n' |

7041 | n/a | '\n' |

7042 | n/a | ' >>> try:\n' |

7043 |