Georg Brandl | 0f25cea | 2012-03-04 16:12:09 +0100 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 2 | # Autogenerated by Sphinx on Mon May 6 20:27:55 2019 |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3 | topics = {'assert': 'The "assert" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4 | '**********************\n' |
| 5 | '\n' |
| 6 | 'Assert statements are a convenient way to insert debugging ' |
| 7 | 'assertions\n' |
| 8 | 'into a program:\n' |
| 9 | '\n' |
| 10 | ' assert_stmt ::= "assert" expression ["," expression]\n' |
| 11 | '\n' |
| 12 | 'The simple form, "assert expression", is equivalent to\n' |
| 13 | '\n' |
| 14 | ' if __debug__:\n' |
| 15 | ' if not expression: raise AssertionError\n' |
| 16 | '\n' |
| 17 | 'The extended form, "assert expression1, expression2", is ' |
| 18 | 'equivalent to\n' |
| 19 | '\n' |
| 20 | ' if __debug__:\n' |
| 21 | ' if not expression1: raise AssertionError(expression2)\n' |
| 22 | '\n' |
| 23 | 'These equivalences assume that "__debug__" and "AssertionError" ' |
| 24 | 'refer\n' |
| 25 | 'to the built-in variables with those names. In the current\n' |
| 26 | 'implementation, the built-in variable "__debug__" is "True" under\n' |
| 27 | 'normal circumstances, "False" when optimization is requested ' |
| 28 | '(command\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 29 | 'line option "-O"). The current code generator emits no code for ' |
| 30 | 'an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 31 | 'assert statement when optimization is requested at compile time. ' |
| 32 | 'Note\n' |
| 33 | 'that it is unnecessary to include the source code for the ' |
| 34 | 'expression\n' |
| 35 | 'that failed in the error message; it will be displayed as part of ' |
| 36 | 'the\n' |
| 37 | 'stack trace.\n' |
| 38 | '\n' |
| 39 | 'Assignments to "__debug__" are illegal. The value for the ' |
| 40 | 'built-in\n' |
| 41 | 'variable is determined when the interpreter starts.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 42 | 'assignment': 'Assignment statements\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 43 | '*********************\n' |
| 44 | '\n' |
| 45 | 'Assignment statements are used to (re)bind names to values and ' |
| 46 | 'to\n' |
| 47 | 'modify attributes or items of mutable objects:\n' |
| 48 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 49 | ' assignment_stmt ::= (target_list "=")+ (starred_expression ' |
| 50 | '| yield_expression)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 51 | ' target_list ::= target ("," target)* [","]\n' |
| 52 | ' target ::= identifier\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 53 | ' | "(" [target_list] ")"\n' |
| 54 | ' | "[" [target_list] "]"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 55 | ' | attributeref\n' |
| 56 | ' | subscription\n' |
| 57 | ' | slicing\n' |
| 58 | ' | "*" target\n' |
| 59 | '\n' |
| 60 | '(See section Primaries for the syntax definitions for ' |
| 61 | '*attributeref*,\n' |
| 62 | '*subscription*, and *slicing*.)\n' |
| 63 | '\n' |
| 64 | 'An assignment statement evaluates the expression list ' |
| 65 | '(remember that\n' |
| 66 | 'this can be a single expression or a comma-separated list, the ' |
| 67 | 'latter\n' |
| 68 | 'yielding a tuple) and assigns the single resulting object to ' |
| 69 | 'each of\n' |
| 70 | 'the target lists, from left to right.\n' |
| 71 | '\n' |
| 72 | 'Assignment is defined recursively depending on the form of the ' |
| 73 | 'target\n' |
| 74 | '(list). When a target is part of a mutable object (an ' |
| 75 | 'attribute\n' |
| 76 | 'reference, subscription or slicing), the mutable object must\n' |
| 77 | 'ultimately perform the assignment and decide about its ' |
| 78 | 'validity, and\n' |
| 79 | 'may raise an exception if the assignment is unacceptable. The ' |
| 80 | 'rules\n' |
| 81 | 'observed by various types and the exceptions raised are given ' |
| 82 | 'with the\n' |
| 83 | 'definition of the object types (see section The standard type\n' |
| 84 | 'hierarchy).\n' |
| 85 | '\n' |
| 86 | 'Assignment of an object to a target list, optionally enclosed ' |
| 87 | 'in\n' |
| 88 | 'parentheses or square brackets, is recursively defined as ' |
| 89 | 'follows.\n' |
| 90 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 91 | '* If the target list is a single target with no trailing ' |
| 92 | 'comma,\n' |
| 93 | ' optionally in parentheses, the object is assigned to that ' |
| 94 | 'target.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 95 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 96 | '* Else: The object must be an iterable with the same number of ' |
| 97 | 'items\n' |
| 98 | ' as there are targets in the target list, and the items are ' |
| 99 | 'assigned,\n' |
| 100 | ' from left to right, to the corresponding targets.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 101 | '\n' |
| 102 | ' * If the target list contains one target prefixed with an\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 103 | ' asterisk, called a “starred” target: The object must be ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 104 | 'an\n' |
| 105 | ' iterable with at least as many items as there are targets ' |
| 106 | 'in the\n' |
| 107 | ' target list, minus one. The first items of the iterable ' |
| 108 | 'are\n' |
| 109 | ' assigned, from left to right, to the targets before the ' |
| 110 | 'starred\n' |
| 111 | ' target. The final items of the iterable are assigned to ' |
| 112 | 'the\n' |
| 113 | ' targets after the starred target. A list of the remaining ' |
| 114 | 'items\n' |
| 115 | ' in the iterable is then assigned to the starred target ' |
| 116 | '(the list\n' |
| 117 | ' can be empty).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 118 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 119 | ' * Else: The object must be an iterable with the same number ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 120 | 'of\n' |
| 121 | ' items as there are targets in the target list, and the ' |
| 122 | 'items are\n' |
| 123 | ' assigned, from left to right, to the corresponding ' |
| 124 | 'targets.\n' |
| 125 | '\n' |
| 126 | 'Assignment of an object to a single target is recursively ' |
| 127 | 'defined as\n' |
| 128 | 'follows.\n' |
| 129 | '\n' |
| 130 | '* If the target is an identifier (name):\n' |
| 131 | '\n' |
| 132 | ' * If the name does not occur in a "global" or "nonlocal" ' |
| 133 | 'statement\n' |
| 134 | ' in the current code block: the name is bound to the object ' |
| 135 | 'in the\n' |
| 136 | ' current local namespace.\n' |
| 137 | '\n' |
| 138 | ' * Otherwise: the name is bound to the object in the global\n' |
| 139 | ' namespace or the outer namespace determined by ' |
| 140 | '"nonlocal",\n' |
| 141 | ' respectively.\n' |
| 142 | '\n' |
| 143 | ' The name is rebound if it was already bound. This may cause ' |
| 144 | 'the\n' |
| 145 | ' reference count for the object previously bound to the name ' |
| 146 | 'to reach\n' |
| 147 | ' zero, causing the object to be deallocated and its ' |
| 148 | 'destructor (if it\n' |
| 149 | ' has one) to be called.\n' |
| 150 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 151 | '* If the target is an attribute reference: The primary ' |
| 152 | 'expression in\n' |
| 153 | ' the reference is evaluated. It should yield an object with\n' |
| 154 | ' assignable attributes; if this is not the case, "TypeError" ' |
| 155 | 'is\n' |
| 156 | ' raised. That object is then asked to assign the assigned ' |
| 157 | 'object to\n' |
| 158 | ' the given attribute; if it cannot perform the assignment, it ' |
| 159 | 'raises\n' |
| 160 | ' an exception (usually but not necessarily ' |
| 161 | '"AttributeError").\n' |
| 162 | '\n' |
| 163 | ' Note: If the object is a class instance and the attribute ' |
| 164 | 'reference\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 165 | ' occurs on both sides of the assignment operator, the ' |
| 166 | 'right-hand side\n' |
| 167 | ' expression, "a.x" can access either an instance attribute or ' |
| 168 | '(if no\n' |
| 169 | ' instance attribute exists) a class attribute. The left-hand ' |
| 170 | 'side\n' |
| 171 | ' target "a.x" is always set as an instance attribute, ' |
| 172 | 'creating it if\n' |
| 173 | ' necessary. Thus, the two occurrences of "a.x" do not ' |
| 174 | 'necessarily\n' |
| 175 | ' refer to the same attribute: if the right-hand side ' |
| 176 | 'expression\n' |
| 177 | ' refers to a class attribute, the left-hand side creates a ' |
| 178 | 'new\n' |
| 179 | ' instance attribute as the target of the assignment:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 180 | '\n' |
| 181 | ' class Cls:\n' |
| 182 | ' x = 3 # class variable\n' |
| 183 | ' inst = Cls()\n' |
| 184 | ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x ' |
| 185 | 'as 3\n' |
| 186 | '\n' |
| 187 | ' This description does not necessarily apply to descriptor\n' |
| 188 | ' attributes, such as properties created with "property()".\n' |
| 189 | '\n' |
| 190 | '* If the target is a subscription: The primary expression in ' |
| 191 | 'the\n' |
| 192 | ' reference is evaluated. It should yield either a mutable ' |
| 193 | 'sequence\n' |
| 194 | ' object (such as a list) or a mapping object (such as a ' |
| 195 | 'dictionary).\n' |
| 196 | ' Next, the subscript expression is evaluated.\n' |
| 197 | '\n' |
| 198 | ' If the primary is a mutable sequence object (such as a ' |
| 199 | 'list), the\n' |
| 200 | ' subscript must yield an integer. If it is negative, the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 201 | 'sequence’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 202 | ' length is added to it. The resulting value must be a ' |
| 203 | 'nonnegative\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 204 | ' integer less than the sequence’s length, and the sequence is ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 205 | 'asked\n' |
| 206 | ' to assign the assigned object to its item with that index. ' |
| 207 | 'If the\n' |
| 208 | ' index is out of range, "IndexError" is raised (assignment to ' |
| 209 | 'a\n' |
| 210 | ' subscripted sequence cannot add new items to a list).\n' |
| 211 | '\n' |
| 212 | ' If the primary is a mapping object (such as a dictionary), ' |
| 213 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 214 | ' subscript must have a type compatible with the mapping’s key ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 215 | 'type,\n' |
| 216 | ' and the mapping is then asked to create a key/datum pair ' |
| 217 | 'which maps\n' |
| 218 | ' the subscript to the assigned object. This can either ' |
| 219 | 'replace an\n' |
| 220 | ' existing key/value pair with the same key value, or insert a ' |
| 221 | 'new\n' |
| 222 | ' key/value pair (if no key with the same value existed).\n' |
| 223 | '\n' |
| 224 | ' For user-defined objects, the "__setitem__()" method is ' |
| 225 | 'called with\n' |
| 226 | ' appropriate arguments.\n' |
| 227 | '\n' |
| 228 | '* If the target is a slicing: The primary expression in the\n' |
| 229 | ' reference is evaluated. It should yield a mutable sequence ' |
| 230 | 'object\n' |
| 231 | ' (such as a list). The assigned object should be a sequence ' |
| 232 | 'object\n' |
| 233 | ' of the same type. Next, the lower and upper bound ' |
| 234 | 'expressions are\n' |
| 235 | ' evaluated, insofar they are present; defaults are zero and ' |
| 236 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 237 | ' sequence’s length. The bounds should evaluate to integers. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 238 | 'If\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 239 | ' either bound is negative, the sequence’s length is added to ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 240 | 'it. The\n' |
| 241 | ' resulting bounds are clipped to lie between zero and the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 242 | 'sequence’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 243 | ' length, inclusive. Finally, the sequence object is asked to ' |
| 244 | 'replace\n' |
| 245 | ' the slice with the items of the assigned sequence. The ' |
| 246 | 'length of\n' |
| 247 | ' the slice may be different from the length of the assigned ' |
| 248 | 'sequence,\n' |
| 249 | ' thus changing the length of the target sequence, if the ' |
| 250 | 'target\n' |
| 251 | ' sequence allows it.\n' |
| 252 | '\n' |
| 253 | '**CPython implementation detail:** In the current ' |
| 254 | 'implementation, the\n' |
| 255 | 'syntax for targets is taken to be the same as for expressions, ' |
| 256 | 'and\n' |
| 257 | 'invalid syntax is rejected during the code generation phase, ' |
| 258 | 'causing\n' |
| 259 | 'less detailed error messages.\n' |
| 260 | '\n' |
| 261 | 'Although the definition of assignment implies that overlaps ' |
| 262 | 'between\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 263 | 'the left-hand side and the right-hand side are ‘simultaneous’ ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 264 | '(for\n' |
| 265 | 'example "a, b = b, a" swaps two variables), overlaps *within* ' |
| 266 | 'the\n' |
| 267 | 'collection of assigned-to variables occur left-to-right, ' |
| 268 | 'sometimes\n' |
| 269 | 'resulting in confusion. For instance, the following program ' |
| 270 | 'prints\n' |
| 271 | '"[0, 2]":\n' |
| 272 | '\n' |
| 273 | ' x = [0, 1]\n' |
| 274 | ' i = 0\n' |
| 275 | ' i, x[i] = 1, 2 # i is updated, then x[i] is ' |
| 276 | 'updated\n' |
| 277 | ' print(x)\n' |
| 278 | '\n' |
| 279 | 'See also:\n' |
| 280 | '\n' |
| 281 | ' **PEP 3132** - Extended Iterable Unpacking\n' |
| 282 | ' The specification for the "*target" feature.\n' |
| 283 | '\n' |
| 284 | '\n' |
| 285 | 'Augmented assignment statements\n' |
| 286 | '===============================\n' |
| 287 | '\n' |
| 288 | 'Augmented assignment is the combination, in a single ' |
| 289 | 'statement, of a\n' |
| 290 | 'binary operation and an assignment statement:\n' |
| 291 | '\n' |
| 292 | ' augmented_assignment_stmt ::= augtarget augop ' |
| 293 | '(expression_list | yield_expression)\n' |
| 294 | ' augtarget ::= identifier | attributeref | ' |
| 295 | 'subscription | slicing\n' |
| 296 | ' augop ::= "+=" | "-=" | "*=" | "@=" | ' |
| 297 | '"/=" | "//=" | "%=" | "**="\n' |
| 298 | ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' |
| 299 | '\n' |
| 300 | '(See section Primaries for the syntax definitions of the last ' |
| 301 | 'three\n' |
| 302 | 'symbols.)\n' |
| 303 | '\n' |
| 304 | 'An augmented assignment evaluates the target (which, unlike ' |
| 305 | 'normal\n' |
| 306 | 'assignment statements, cannot be an unpacking) and the ' |
| 307 | 'expression\n' |
| 308 | 'list, performs the binary operation specific to the type of ' |
| 309 | 'assignment\n' |
| 310 | 'on the two operands, and assigns the result to the original ' |
| 311 | 'target.\n' |
| 312 | 'The target is only evaluated once.\n' |
| 313 | '\n' |
| 314 | 'An augmented assignment expression like "x += 1" can be ' |
| 315 | 'rewritten as\n' |
| 316 | '"x = x + 1" to achieve a similar, but not exactly equal ' |
| 317 | 'effect. In the\n' |
| 318 | 'augmented version, "x" is only evaluated once. Also, when ' |
| 319 | 'possible,\n' |
| 320 | 'the actual operation is performed *in-place*, meaning that ' |
| 321 | 'rather than\n' |
| 322 | 'creating a new object and assigning that to the target, the ' |
| 323 | 'old object\n' |
| 324 | 'is modified instead.\n' |
| 325 | '\n' |
| 326 | 'Unlike normal assignments, augmented assignments evaluate the ' |
| 327 | 'left-\n' |
| 328 | 'hand side *before* evaluating the right-hand side. For ' |
| 329 | 'example, "a[i]\n' |
| 330 | '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' |
| 331 | 'performs\n' |
| 332 | 'the addition, and lastly, it writes the result back to ' |
| 333 | '"a[i]".\n' |
| 334 | '\n' |
| 335 | 'With the exception of assigning to tuples and multiple targets ' |
| 336 | 'in a\n' |
| 337 | 'single statement, the assignment done by augmented assignment\n' |
| 338 | 'statements is handled the same way as normal assignments. ' |
| 339 | 'Similarly,\n' |
| 340 | 'with the exception of the possible *in-place* behavior, the ' |
| 341 | 'binary\n' |
| 342 | 'operation performed by augmented assignment is the same as the ' |
| 343 | 'normal\n' |
| 344 | 'binary operations.\n' |
| 345 | '\n' |
| 346 | 'For targets which are attribute references, the same caveat ' |
| 347 | 'about\n' |
| 348 | 'class and instance attributes applies as for regular ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 349 | 'assignments.\n' |
| 350 | '\n' |
| 351 | '\n' |
| 352 | 'Annotated assignment statements\n' |
| 353 | '===============================\n' |
| 354 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 355 | '*Annotation* assignment is the combination, in a single ' |
| 356 | 'statement, of\n' |
| 357 | 'a variable or attribute annotation and an optional assignment\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 358 | 'statement:\n' |
| 359 | '\n' |
| 360 | ' annotated_assignment_stmt ::= augtarget ":" expression ["=" ' |
| 361 | 'expression]\n' |
| 362 | '\n' |
| 363 | 'The difference from normal Assignment statements is that only ' |
| 364 | 'single\n' |
| 365 | 'target and only single right hand side value is allowed.\n' |
| 366 | '\n' |
| 367 | 'For simple names as assignment targets, if in class or module ' |
| 368 | 'scope,\n' |
| 369 | 'the annotations are evaluated and stored in a special class or ' |
| 370 | 'module\n' |
| 371 | 'attribute "__annotations__" that is a dictionary mapping from ' |
| 372 | 'variable\n' |
| 373 | 'names (mangled if private) to evaluated annotations. This ' |
| 374 | 'attribute is\n' |
| 375 | 'writable and is automatically created at the start of class or ' |
| 376 | 'module\n' |
| 377 | 'body execution, if annotations are found statically.\n' |
| 378 | '\n' |
| 379 | 'For expressions as assignment targets, the annotations are ' |
| 380 | 'evaluated\n' |
| 381 | 'if in class or module scope, but not stored.\n' |
| 382 | '\n' |
| 383 | 'If a name is annotated in a function scope, then this name is ' |
| 384 | 'local\n' |
| 385 | 'for that scope. Annotations are never evaluated and stored in ' |
| 386 | 'function\n' |
| 387 | 'scopes.\n' |
| 388 | '\n' |
| 389 | 'If the right hand side is present, an annotated assignment ' |
| 390 | 'performs\n' |
| 391 | 'the actual assignment before evaluating annotations (where\n' |
| 392 | 'applicable). If the right hand side is not present for an ' |
| 393 | 'expression\n' |
| 394 | 'target, then the interpreter evaluates the target except for ' |
| 395 | 'the last\n' |
| 396 | '"__setitem__()" or "__setattr__()" call.\n' |
| 397 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 398 | 'See also:\n' |
| 399 | '\n' |
| 400 | ' **PEP 526** - Syntax for Variable Annotations\n' |
| 401 | ' The proposal that added syntax for annotating the types ' |
| 402 | 'of\n' |
| 403 | ' variables (including class variables and instance ' |
| 404 | 'variables),\n' |
| 405 | ' instead of expressing them through comments.\n' |
| 406 | '\n' |
| 407 | ' **PEP 484** - Type hints\n' |
| 408 | ' The proposal that added the "typing" module to provide a ' |
| 409 | 'standard\n' |
| 410 | ' syntax for type annotations that can be used in static ' |
| 411 | 'analysis\n' |
| 412 | ' tools and IDEs.\n', |
| 413 | 'async': 'Coroutines\n' |
| 414 | '**********\n' |
| 415 | '\n' |
| 416 | 'New in version 3.5.\n' |
| 417 | '\n' |
| 418 | '\n' |
| 419 | 'Coroutine function definition\n' |
| 420 | '=============================\n' |
| 421 | '\n' |
| 422 | ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' |
| 423 | '[parameter_list] ")"\n' |
| 424 | ' ["->" expression] ":" suite\n' |
| 425 | '\n' |
| 426 | 'Execution of Python coroutines can be suspended and resumed at ' |
| 427 | 'many\n' |
| 428 | 'points (see *coroutine*). Inside the body of a coroutine ' |
| 429 | 'function,\n' |
| 430 | '"await" and "async" identifiers become reserved keywords; "await"\n' |
| 431 | 'expressions, "async for" and "async with" can only be used in\n' |
| 432 | 'coroutine function bodies.\n' |
| 433 | '\n' |
| 434 | 'Functions defined with "async def" syntax are always coroutine\n' |
| 435 | 'functions, even if they do not contain "await" or "async" ' |
| 436 | 'keywords.\n' |
| 437 | '\n' |
| 438 | 'It is a "SyntaxError" to use a "yield from" expression inside the ' |
| 439 | 'body\n' |
| 440 | 'of a coroutine function.\n' |
| 441 | '\n' |
| 442 | 'An example of a coroutine function:\n' |
| 443 | '\n' |
| 444 | ' async def func(param1, param2):\n' |
| 445 | ' do_stuff()\n' |
| 446 | ' await some_coroutine()\n' |
| 447 | '\n' |
| 448 | '\n' |
| 449 | 'The "async for" statement\n' |
| 450 | '=========================\n' |
| 451 | '\n' |
| 452 | ' async_for_stmt ::= "async" for_stmt\n' |
| 453 | '\n' |
| 454 | 'An *asynchronous iterable* is able to call asynchronous code in ' |
| 455 | 'its\n' |
| 456 | '*iter* implementation, and *asynchronous iterator* can call\n' |
| 457 | 'asynchronous code in its *next* method.\n' |
| 458 | '\n' |
| 459 | 'The "async for" statement allows convenient iteration over\n' |
| 460 | 'asynchronous iterators.\n' |
| 461 | '\n' |
| 462 | 'The following code:\n' |
| 463 | '\n' |
| 464 | ' async for TARGET in ITER:\n' |
| 465 | ' BLOCK\n' |
| 466 | ' else:\n' |
| 467 | ' BLOCK2\n' |
| 468 | '\n' |
| 469 | 'Is semantically equivalent to:\n' |
| 470 | '\n' |
| 471 | ' iter = (ITER)\n' |
| 472 | ' iter = type(iter).__aiter__(iter)\n' |
| 473 | ' running = True\n' |
| 474 | ' while running:\n' |
| 475 | ' try:\n' |
| 476 | ' TARGET = await type(iter).__anext__(iter)\n' |
| 477 | ' except StopAsyncIteration:\n' |
| 478 | ' running = False\n' |
| 479 | ' else:\n' |
| 480 | ' BLOCK\n' |
| 481 | ' else:\n' |
| 482 | ' BLOCK2\n' |
| 483 | '\n' |
| 484 | 'See also "__aiter__()" and "__anext__()" for details.\n' |
| 485 | '\n' |
| 486 | 'It is a "SyntaxError" to use an "async for" statement outside the ' |
| 487 | 'body\n' |
| 488 | 'of a coroutine function.\n' |
| 489 | '\n' |
| 490 | '\n' |
| 491 | 'The "async with" statement\n' |
| 492 | '==========================\n' |
| 493 | '\n' |
| 494 | ' async_with_stmt ::= "async" with_stmt\n' |
| 495 | '\n' |
| 496 | 'An *asynchronous context manager* is a *context manager* that is ' |
| 497 | 'able\n' |
| 498 | 'to suspend execution in its *enter* and *exit* methods.\n' |
| 499 | '\n' |
| 500 | 'The following code:\n' |
| 501 | '\n' |
| 502 | ' async with EXPR as VAR:\n' |
| 503 | ' BLOCK\n' |
| 504 | '\n' |
| 505 | 'Is semantically equivalent to:\n' |
| 506 | '\n' |
| 507 | ' mgr = (EXPR)\n' |
| 508 | ' aexit = type(mgr).__aexit__\n' |
| 509 | ' aenter = type(mgr).__aenter__(mgr)\n' |
| 510 | '\n' |
| 511 | ' VAR = await aenter\n' |
| 512 | ' try:\n' |
| 513 | ' BLOCK\n' |
| 514 | ' except:\n' |
| 515 | ' if not await aexit(mgr, *sys.exc_info()):\n' |
| 516 | ' raise\n' |
| 517 | ' else:\n' |
| 518 | ' await aexit(mgr, None, None, None)\n' |
| 519 | '\n' |
| 520 | 'See also "__aenter__()" and "__aexit__()" for details.\n' |
| 521 | '\n' |
| 522 | 'It is a "SyntaxError" to use an "async with" statement outside the\n' |
| 523 | 'body of a coroutine function.\n' |
| 524 | '\n' |
| 525 | 'See also:\n' |
| 526 | '\n' |
| 527 | ' **PEP 492** - Coroutines with async and await syntax\n' |
| 528 | ' The proposal that made coroutines a proper standalone concept ' |
| 529 | 'in\n' |
| 530 | ' Python, and added supporting syntax.\n' |
| 531 | '\n' |
| 532 | '-[ Footnotes ]-\n' |
| 533 | '\n' |
| 534 | '[1] The exception is propagated to the invocation stack unless\n' |
| 535 | ' there is a "finally" clause which happens to raise another\n' |
| 536 | ' exception. That new exception causes the old one to be lost.\n' |
| 537 | '\n' |
| 538 | '[2] A string literal appearing as the first statement in the\n' |
| 539 | ' function body is transformed into the function’s "__doc__"\n' |
| 540 | ' attribute and therefore the function’s *docstring*.\n' |
| 541 | '\n' |
| 542 | '[3] A string literal appearing as the first statement in the class\n' |
| 543 | ' body is transformed into the namespace’s "__doc__" item and\n' |
| 544 | ' therefore the class’s *docstring*.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 545 | 'atom-identifiers': 'Identifiers (Names)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 546 | '*******************\n' |
| 547 | '\n' |
| 548 | 'An identifier occurring as an atom is a name. See ' |
| 549 | 'section Identifiers\n' |
| 550 | 'and keywords for lexical definition and section Naming ' |
| 551 | 'and binding for\n' |
| 552 | 'documentation of naming and binding.\n' |
| 553 | '\n' |
| 554 | 'When the name is bound to an object, evaluation of the ' |
| 555 | 'atom yields\n' |
| 556 | 'that object. When a name is not bound, an attempt to ' |
| 557 | 'evaluate it\n' |
| 558 | 'raises a "NameError" exception.\n' |
| 559 | '\n' |
| 560 | '**Private name mangling:** When an identifier that ' |
| 561 | 'textually occurs in\n' |
| 562 | 'a class definition begins with two or more underscore ' |
| 563 | 'characters and\n' |
| 564 | 'does not end in two or more underscores, it is ' |
| 565 | 'considered a *private\n' |
| 566 | 'name* of that class. Private names are transformed to a ' |
| 567 | 'longer form\n' |
| 568 | 'before code is generated for them. The transformation ' |
| 569 | 'inserts the\n' |
| 570 | 'class name, with leading underscores removed and a ' |
| 571 | 'single underscore\n' |
| 572 | 'inserted, in front of the name. For example, the ' |
| 573 | 'identifier "__spam"\n' |
| 574 | 'occurring in a class named "Ham" will be transformed to ' |
| 575 | '"_Ham__spam".\n' |
| 576 | 'This transformation is independent of the syntactical ' |
| 577 | 'context in which\n' |
| 578 | 'the identifier is used. If the transformed name is ' |
| 579 | 'extremely long\n' |
| 580 | '(longer than 255 characters), implementation defined ' |
| 581 | 'truncation may\n' |
| 582 | 'happen. If the class name consists only of underscores, ' |
| 583 | 'no\n' |
| 584 | 'transformation is done.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 585 | 'atom-literals': 'Literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 586 | '********\n' |
| 587 | '\n' |
| 588 | 'Python supports string and bytes literals and various ' |
| 589 | 'numeric\n' |
| 590 | 'literals:\n' |
| 591 | '\n' |
| 592 | ' literal ::= stringliteral | bytesliteral\n' |
| 593 | ' | integer | floatnumber | imagnumber\n' |
| 594 | '\n' |
| 595 | 'Evaluation of a literal yields an object of the given type ' |
| 596 | '(string,\n' |
| 597 | 'bytes, integer, floating point number, complex number) with ' |
| 598 | 'the given\n' |
| 599 | 'value. The value may be approximated in the case of ' |
| 600 | 'floating point\n' |
| 601 | 'and imaginary (complex) literals. See section Literals for ' |
| 602 | 'details.\n' |
| 603 | '\n' |
| 604 | 'All literals correspond to immutable data types, and hence ' |
| 605 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 606 | 'object’s identity is less important than its value. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 607 | 'Multiple\n' |
| 608 | 'evaluations of literals with the same value (either the ' |
| 609 | 'same\n' |
| 610 | 'occurrence in the program text or a different occurrence) ' |
| 611 | 'may obtain\n' |
| 612 | 'the same object or a different object with the same ' |
| 613 | 'value.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 614 | 'attribute-access': 'Customizing attribute access\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 615 | '****************************\n' |
| 616 | '\n' |
| 617 | 'The following methods can be defined to customize the ' |
| 618 | 'meaning of\n' |
| 619 | 'attribute access (use of, assignment to, or deletion of ' |
| 620 | '"x.name") for\n' |
| 621 | 'class instances.\n' |
| 622 | '\n' |
| 623 | 'object.__getattr__(self, name)\n' |
| 624 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 625 | ' Called when the default attribute access fails with ' |
| 626 | 'an\n' |
| 627 | ' "AttributeError" (either "__getattribute__()" raises ' |
| 628 | 'an\n' |
| 629 | ' "AttributeError" because *name* is not an instance ' |
| 630 | 'attribute or an\n' |
| 631 | ' attribute in the class tree for "self"; or ' |
| 632 | '"__get__()" of a *name*\n' |
| 633 | ' property raises "AttributeError"). This method ' |
| 634 | 'should either\n' |
| 635 | ' return the (computed) attribute value or raise an ' |
| 636 | '"AttributeError"\n' |
| 637 | ' exception.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 638 | '\n' |
| 639 | ' Note that if the attribute is found through the ' |
| 640 | 'normal mechanism,\n' |
| 641 | ' "__getattr__()" is not called. (This is an ' |
| 642 | 'intentional asymmetry\n' |
| 643 | ' between "__getattr__()" and "__setattr__()".) This is ' |
| 644 | 'done both for\n' |
| 645 | ' efficiency reasons and because otherwise ' |
| 646 | '"__getattr__()" would have\n' |
| 647 | ' no way to access other attributes of the instance. ' |
| 648 | 'Note that at\n' |
| 649 | ' least for instance variables, you can fake total ' |
| 650 | 'control by not\n' |
| 651 | ' inserting any values in the instance attribute ' |
| 652 | 'dictionary (but\n' |
| 653 | ' instead inserting them in another object). See the\n' |
| 654 | ' "__getattribute__()" method below for a way to ' |
| 655 | 'actually get total\n' |
| 656 | ' control over attribute access.\n' |
| 657 | '\n' |
| 658 | 'object.__getattribute__(self, name)\n' |
| 659 | '\n' |
| 660 | ' Called unconditionally to implement attribute ' |
| 661 | 'accesses for\n' |
| 662 | ' instances of the class. If the class also defines ' |
| 663 | '"__getattr__()",\n' |
| 664 | ' the latter will not be called unless ' |
| 665 | '"__getattribute__()" either\n' |
| 666 | ' calls it explicitly or raises an "AttributeError". ' |
| 667 | 'This method\n' |
| 668 | ' should return the (computed) attribute value or raise ' |
| 669 | 'an\n' |
| 670 | ' "AttributeError" exception. In order to avoid ' |
| 671 | 'infinite recursion in\n' |
| 672 | ' this method, its implementation should always call ' |
| 673 | 'the base class\n' |
| 674 | ' method with the same name to access any attributes it ' |
| 675 | 'needs, for\n' |
| 676 | ' example, "object.__getattribute__(self, name)".\n' |
| 677 | '\n' |
| 678 | ' Note: This method may still be bypassed when looking ' |
| 679 | 'up special\n' |
| 680 | ' methods as the result of implicit invocation via ' |
| 681 | 'language syntax\n' |
| 682 | ' or built-in functions. See Special method lookup.\n' |
| 683 | '\n' |
| 684 | 'object.__setattr__(self, name, value)\n' |
| 685 | '\n' |
| 686 | ' Called when an attribute assignment is attempted. ' |
| 687 | 'This is called\n' |
| 688 | ' instead of the normal mechanism (i.e. store the value ' |
| 689 | 'in the\n' |
| 690 | ' instance dictionary). *name* is the attribute name, ' |
| 691 | '*value* is the\n' |
| 692 | ' value to be assigned to it.\n' |
| 693 | '\n' |
| 694 | ' If "__setattr__()" wants to assign to an instance ' |
| 695 | 'attribute, it\n' |
| 696 | ' should call the base class method with the same name, ' |
| 697 | 'for example,\n' |
| 698 | ' "object.__setattr__(self, name, value)".\n' |
| 699 | '\n' |
| 700 | 'object.__delattr__(self, name)\n' |
| 701 | '\n' |
| 702 | ' Like "__setattr__()" but for attribute deletion ' |
| 703 | 'instead of\n' |
| 704 | ' assignment. This should only be implemented if "del ' |
| 705 | 'obj.name" is\n' |
| 706 | ' meaningful for the object.\n' |
| 707 | '\n' |
| 708 | 'object.__dir__(self)\n' |
| 709 | '\n' |
| 710 | ' Called when "dir()" is called on the object. A ' |
| 711 | 'sequence must be\n' |
| 712 | ' returned. "dir()" converts the returned sequence to a ' |
| 713 | 'list and\n' |
| 714 | ' sorts it.\n' |
| 715 | '\n' |
| 716 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 717 | 'Customizing module attribute access\n' |
| 718 | '===================================\n' |
| 719 | '\n' |
| 720 | 'Special names "__getattr__" and "__dir__" can be also ' |
| 721 | 'used to\n' |
| 722 | 'customize access to module attributes. The "__getattr__" ' |
| 723 | 'function at\n' |
| 724 | 'the module level should accept one argument which is the ' |
| 725 | 'name of an\n' |
| 726 | 'attribute and return the computed value or raise an ' |
| 727 | '"AttributeError".\n' |
| 728 | 'If an attribute is not found on a module object through ' |
| 729 | 'the normal\n' |
| 730 | 'lookup, i.e. "object.__getattribute__()", then ' |
| 731 | '"__getattr__" is\n' |
| 732 | 'searched in the module "__dict__" before raising an ' |
| 733 | '"AttributeError".\n' |
| 734 | 'If found, it is called with the attribute name and the ' |
| 735 | 'result is\n' |
| 736 | 'returned.\n' |
| 737 | '\n' |
| 738 | 'The "__dir__" function should accept no arguments, and ' |
| 739 | 'return a list\n' |
| 740 | 'of strings that represents the names accessible on ' |
| 741 | 'module. If present,\n' |
| 742 | 'this function overrides the standard "dir()" search on a ' |
| 743 | 'module.\n' |
| 744 | '\n' |
| 745 | 'For a more fine grained customization of the module ' |
| 746 | 'behavior (setting\n' |
| 747 | 'attributes, properties, etc.), one can set the ' |
| 748 | '"__class__" attribute\n' |
| 749 | 'of a module object to a subclass of "types.ModuleType". ' |
| 750 | 'For example:\n' |
| 751 | '\n' |
| 752 | ' import sys\n' |
| 753 | ' from types import ModuleType\n' |
| 754 | '\n' |
| 755 | ' class VerboseModule(ModuleType):\n' |
| 756 | ' def __repr__(self):\n' |
| 757 | " return f'Verbose {self.__name__}'\n" |
| 758 | '\n' |
| 759 | ' def __setattr__(self, attr, value):\n' |
| 760 | " print(f'Setting {attr}...')\n" |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 761 | ' super().__setattr__(attr, value)\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 762 | '\n' |
| 763 | ' sys.modules[__name__].__class__ = VerboseModule\n' |
| 764 | '\n' |
| 765 | 'Note: Defining module "__getattr__" and setting module ' |
| 766 | '"__class__"\n' |
| 767 | ' only affect lookups made using the attribute access ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 768 | 'syntax –\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 769 | ' directly accessing the module globals (whether by code ' |
| 770 | 'within the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 771 | ' module, or via a reference to the module’s globals ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 772 | 'dictionary) is\n' |
| 773 | ' unaffected.\n' |
| 774 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 775 | 'Changed in version 3.5: "__class__" module attribute is ' |
| 776 | 'now writable.\n' |
| 777 | '\n' |
| 778 | 'New in version 3.7: "__getattr__" and "__dir__" module ' |
| 779 | 'attributes.\n' |
| 780 | '\n' |
| 781 | 'See also:\n' |
| 782 | '\n' |
| 783 | ' **PEP 562** - Module __getattr__ and __dir__\n' |
| 784 | ' Describes the "__getattr__" and "__dir__" functions ' |
| 785 | 'on modules.\n' |
| 786 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 787 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 788 | 'Implementing Descriptors\n' |
| 789 | '========================\n' |
| 790 | '\n' |
| 791 | 'The following methods only apply when an instance of the ' |
| 792 | 'class\n' |
| 793 | 'containing the method (a so-called *descriptor* class) ' |
| 794 | 'appears in an\n' |
| 795 | '*owner* class (the descriptor must be in either the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 796 | 'owner’s class\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 797 | 'dictionary or in the class dictionary for one of its ' |
| 798 | 'parents). In the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 799 | 'examples below, “the attribute” refers to the attribute ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 800 | 'whose name is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 801 | 'the key of the property in the owner class’ "__dict__".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 802 | '\n' |
| 803 | 'object.__get__(self, instance, owner)\n' |
| 804 | '\n' |
| 805 | ' Called to get the attribute of the owner class (class ' |
| 806 | 'attribute\n' |
| 807 | ' access) or of an instance of that class (instance ' |
| 808 | 'attribute\n' |
| 809 | ' access). *owner* is always the owner class, while ' |
| 810 | '*instance* is the\n' |
| 811 | ' instance that the attribute was accessed through, or ' |
| 812 | '"None" when\n' |
| 813 | ' the attribute is accessed through the *owner*. This ' |
| 814 | 'method should\n' |
| 815 | ' return the (computed) attribute value or raise an ' |
| 816 | '"AttributeError"\n' |
| 817 | ' exception.\n' |
| 818 | '\n' |
| 819 | 'object.__set__(self, instance, value)\n' |
| 820 | '\n' |
| 821 | ' Called to set the attribute on an instance *instance* ' |
| 822 | 'of the owner\n' |
| 823 | ' class to a new value, *value*.\n' |
| 824 | '\n' |
| 825 | 'object.__delete__(self, instance)\n' |
| 826 | '\n' |
| 827 | ' Called to delete the attribute on an instance ' |
| 828 | '*instance* of the\n' |
| 829 | ' owner class.\n' |
| 830 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 831 | 'object.__set_name__(self, owner, name)\n' |
| 832 | '\n' |
| 833 | ' Called at the time the owning class *owner* is ' |
| 834 | 'created. The\n' |
| 835 | ' descriptor has been assigned to *name*.\n' |
| 836 | '\n' |
| 837 | ' New in version 3.6.\n' |
| 838 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 839 | 'The attribute "__objclass__" is interpreted by the ' |
| 840 | '"inspect" module as\n' |
| 841 | 'specifying the class where this object was defined ' |
| 842 | '(setting this\n' |
| 843 | 'appropriately can assist in runtime introspection of ' |
| 844 | 'dynamic class\n' |
| 845 | 'attributes). For callables, it may indicate that an ' |
| 846 | 'instance of the\n' |
| 847 | 'given type (or a subclass) is expected or required as ' |
| 848 | 'the first\n' |
| 849 | 'positional argument (for example, CPython sets this ' |
| 850 | 'attribute for\n' |
| 851 | 'unbound methods that are implemented in C).\n' |
| 852 | '\n' |
| 853 | '\n' |
| 854 | 'Invoking Descriptors\n' |
| 855 | '====================\n' |
| 856 | '\n' |
| 857 | 'In general, a descriptor is an object attribute with ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 858 | '“binding\n' |
| 859 | 'behavior”, one whose attribute access has been ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 860 | 'overridden by methods\n' |
| 861 | 'in the descriptor protocol: "__get__()", "__set__()", ' |
| 862 | 'and\n' |
| 863 | '"__delete__()". If any of those methods are defined for ' |
| 864 | 'an object, it\n' |
| 865 | 'is said to be a descriptor.\n' |
| 866 | '\n' |
| 867 | 'The default behavior for attribute access is to get, ' |
| 868 | 'set, or delete\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 869 | 'the attribute from an object’s dictionary. For instance, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 870 | '"a.x" has a\n' |
| 871 | 'lookup chain starting with "a.__dict__[\'x\']", then\n' |
| 872 | '"type(a).__dict__[\'x\']", and continuing through the ' |
| 873 | 'base classes of\n' |
| 874 | '"type(a)" excluding metaclasses.\n' |
| 875 | '\n' |
| 876 | 'However, if the looked-up value is an object defining ' |
| 877 | 'one of the\n' |
| 878 | 'descriptor methods, then Python may override the default ' |
| 879 | 'behavior and\n' |
| 880 | 'invoke the descriptor method instead. Where this occurs ' |
| 881 | 'in the\n' |
| 882 | 'precedence chain depends on which descriptor methods ' |
| 883 | 'were defined and\n' |
| 884 | 'how they were called.\n' |
| 885 | '\n' |
| 886 | 'The starting point for descriptor invocation is a ' |
| 887 | 'binding, "a.x". How\n' |
| 888 | 'the arguments are assembled depends on "a":\n' |
| 889 | '\n' |
| 890 | 'Direct Call\n' |
| 891 | ' The simplest and least common call is when user code ' |
| 892 | 'directly\n' |
| 893 | ' invokes a descriptor method: "x.__get__(a)".\n' |
| 894 | '\n' |
| 895 | 'Instance Binding\n' |
| 896 | ' If binding to an object instance, "a.x" is ' |
| 897 | 'transformed into the\n' |
| 898 | ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' |
| 899 | '\n' |
| 900 | 'Class Binding\n' |
| 901 | ' If binding to a class, "A.x" is transformed into the ' |
| 902 | 'call:\n' |
| 903 | ' "A.__dict__[\'x\'].__get__(None, A)".\n' |
| 904 | '\n' |
| 905 | 'Super Binding\n' |
| 906 | ' If "a" is an instance of "super", then the binding ' |
| 907 | '"super(B,\n' |
| 908 | ' obj).m()" searches "obj.__class__.__mro__" for the ' |
| 909 | 'base class "A"\n' |
| 910 | ' immediately preceding "B" and then invokes the ' |
| 911 | 'descriptor with the\n' |
| 912 | ' call: "A.__dict__[\'m\'].__get__(obj, ' |
| 913 | 'obj.__class__)".\n' |
| 914 | '\n' |
| 915 | 'For instance bindings, the precedence of descriptor ' |
| 916 | 'invocation depends\n' |
| 917 | 'on the which descriptor methods are defined. A ' |
| 918 | 'descriptor can define\n' |
| 919 | 'any combination of "__get__()", "__set__()" and ' |
| 920 | '"__delete__()". If it\n' |
| 921 | 'does not define "__get__()", then accessing the ' |
| 922 | 'attribute will return\n' |
| 923 | 'the descriptor object itself unless there is a value in ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 924 | 'the object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 925 | 'instance dictionary. If the descriptor defines ' |
| 926 | '"__set__()" and/or\n' |
| 927 | '"__delete__()", it is a data descriptor; if it defines ' |
| 928 | 'neither, it is\n' |
| 929 | 'a non-data descriptor. Normally, data descriptors ' |
| 930 | 'define both\n' |
| 931 | '"__get__()" and "__set__()", while non-data descriptors ' |
| 932 | 'have just the\n' |
| 933 | '"__get__()" method. Data descriptors with "__set__()" ' |
| 934 | 'and "__get__()"\n' |
| 935 | 'defined always override a redefinition in an instance ' |
| 936 | 'dictionary. In\n' |
| 937 | 'contrast, non-data descriptors can be overridden by ' |
| 938 | 'instances.\n' |
| 939 | '\n' |
| 940 | 'Python methods (including "staticmethod()" and ' |
| 941 | '"classmethod()") are\n' |
| 942 | 'implemented as non-data descriptors. Accordingly, ' |
| 943 | 'instances can\n' |
| 944 | 'redefine and override methods. This allows individual ' |
| 945 | 'instances to\n' |
| 946 | 'acquire behaviors that differ from other instances of ' |
| 947 | 'the same class.\n' |
| 948 | '\n' |
| 949 | 'The "property()" function is implemented as a data ' |
| 950 | 'descriptor.\n' |
| 951 | 'Accordingly, instances cannot override the behavior of a ' |
| 952 | 'property.\n' |
| 953 | '\n' |
| 954 | '\n' |
| 955 | '__slots__\n' |
| 956 | '=========\n' |
| 957 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 958 | '*__slots__* allow us to explicitly declare data members ' |
| 959 | '(like\n' |
| 960 | 'properties) and deny the creation of *__dict__* and ' |
| 961 | '*__weakref__*\n' |
| 962 | '(unless explicitly declared in *__slots__* or available ' |
| 963 | 'in a parent.)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 964 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 965 | 'The space saved over using *__dict__* can be ' |
Łukasz Langa | 23f4589 | 2019-02-25 13:08:32 +0100 | [diff] [blame] | 966 | 'significant. Attribute\n' |
| 967 | 'lookup speed can be significantly improved as well.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 968 | '\n' |
| 969 | 'object.__slots__\n' |
| 970 | '\n' |
| 971 | ' This class variable can be assigned a string, ' |
| 972 | 'iterable, or sequence\n' |
| 973 | ' of strings with variable names used by instances. ' |
| 974 | '*__slots__*\n' |
| 975 | ' reserves space for the declared variables and ' |
| 976 | 'prevents the\n' |
| 977 | ' automatic creation of *__dict__* and *__weakref__* ' |
| 978 | 'for each\n' |
| 979 | ' instance.\n' |
| 980 | '\n' |
| 981 | '\n' |
| 982 | 'Notes on using *__slots__*\n' |
| 983 | '--------------------------\n' |
| 984 | '\n' |
| 985 | '* When inheriting from a class without *__slots__*, the ' |
| 986 | '*__dict__*\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 987 | ' and *__weakref__* attribute of the instances will ' |
| 988 | 'always be\n' |
| 989 | ' accessible.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 990 | '\n' |
| 991 | '* Without a *__dict__* variable, instances cannot be ' |
| 992 | 'assigned new\n' |
| 993 | ' variables not listed in the *__slots__* definition. ' |
| 994 | 'Attempts to\n' |
| 995 | ' assign to an unlisted variable name raises ' |
| 996 | '"AttributeError". If\n' |
| 997 | ' dynamic assignment of new variables is desired, then ' |
| 998 | 'add\n' |
| 999 | ' "\'__dict__\'" to the sequence of strings in the ' |
| 1000 | '*__slots__*\n' |
| 1001 | ' declaration.\n' |
| 1002 | '\n' |
| 1003 | '* Without a *__weakref__* variable for each instance, ' |
| 1004 | 'classes\n' |
| 1005 | ' defining *__slots__* do not support weak references to ' |
| 1006 | 'its\n' |
| 1007 | ' instances. If weak reference support is needed, then ' |
| 1008 | 'add\n' |
| 1009 | ' "\'__weakref__\'" to the sequence of strings in the ' |
| 1010 | '*__slots__*\n' |
| 1011 | ' declaration.\n' |
| 1012 | '\n' |
| 1013 | '* *__slots__* are implemented at the class level by ' |
| 1014 | 'creating\n' |
| 1015 | ' descriptors (Implementing Descriptors) for each ' |
| 1016 | 'variable name. As a\n' |
| 1017 | ' result, class attributes cannot be used to set default ' |
| 1018 | 'values for\n' |
| 1019 | ' instance variables defined by *__slots__*; otherwise, ' |
| 1020 | 'the class\n' |
| 1021 | ' attribute would overwrite the descriptor assignment.\n' |
| 1022 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1023 | '* The action of a *__slots__* declaration is not limited ' |
| 1024 | 'to the\n' |
| 1025 | ' class where it is defined. *__slots__* declared in ' |
| 1026 | 'parents are\n' |
| 1027 | ' available in child classes. However, child subclasses ' |
| 1028 | 'will get a\n' |
| 1029 | ' *__dict__* and *__weakref__* unless they also define ' |
| 1030 | '*__slots__*\n' |
| 1031 | ' (which should only contain names of any *additional* ' |
| 1032 | 'slots).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1033 | '\n' |
| 1034 | '* If a class defines a slot also defined in a base ' |
| 1035 | 'class, the\n' |
| 1036 | ' instance variable defined by the base class slot is ' |
| 1037 | 'inaccessible\n' |
| 1038 | ' (except by retrieving its descriptor directly from the ' |
| 1039 | 'base class).\n' |
| 1040 | ' This renders the meaning of the program undefined. In ' |
| 1041 | 'the future, a\n' |
| 1042 | ' check may be added to prevent this.\n' |
| 1043 | '\n' |
| 1044 | '* Nonempty *__slots__* does not work for classes derived ' |
| 1045 | 'from\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1046 | ' “variable-length” built-in types such as "int", ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1047 | '"bytes" and "tuple".\n' |
| 1048 | '\n' |
| 1049 | '* Any non-string iterable may be assigned to ' |
| 1050 | '*__slots__*. Mappings\n' |
| 1051 | ' may also be used; however, in the future, special ' |
| 1052 | 'meaning may be\n' |
| 1053 | ' assigned to the values corresponding to each key.\n' |
| 1054 | '\n' |
| 1055 | '* *__class__* assignment works only if both classes have ' |
| 1056 | 'the same\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1057 | ' *__slots__*.\n' |
| 1058 | '\n' |
| 1059 | '* Multiple inheritance with multiple slotted parent ' |
| 1060 | 'classes can be\n' |
| 1061 | ' used, but only one parent is allowed to have ' |
| 1062 | 'attributes created by\n' |
| 1063 | ' slots (the other bases must have empty slot layouts) - ' |
| 1064 | 'violations\n' |
| 1065 | ' raise "TypeError".\n', |
| 1066 | 'attribute-references': 'Attribute references\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1067 | '********************\n' |
| 1068 | '\n' |
| 1069 | 'An attribute reference is a primary followed by a ' |
| 1070 | 'period and a name:\n' |
| 1071 | '\n' |
| 1072 | ' attributeref ::= primary "." identifier\n' |
| 1073 | '\n' |
| 1074 | 'The primary must evaluate to an object of a type ' |
| 1075 | 'that supports\n' |
| 1076 | 'attribute references, which most objects do. This ' |
| 1077 | 'object is then\n' |
| 1078 | 'asked to produce the attribute whose name is the ' |
| 1079 | 'identifier. This\n' |
| 1080 | 'production can be customized by overriding the ' |
| 1081 | '"__getattr__()" method.\n' |
| 1082 | 'If this attribute is not available, the exception ' |
| 1083 | '"AttributeError" is\n' |
| 1084 | 'raised. Otherwise, the type and value of the object ' |
| 1085 | 'produced is\n' |
| 1086 | 'determined by the object. Multiple evaluations of ' |
| 1087 | 'the same attribute\n' |
| 1088 | 'reference may yield different objects.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1089 | 'augassign': 'Augmented assignment statements\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1090 | '*******************************\n' |
| 1091 | '\n' |
| 1092 | 'Augmented assignment is the combination, in a single statement, ' |
| 1093 | 'of a\n' |
| 1094 | 'binary operation and an assignment statement:\n' |
| 1095 | '\n' |
| 1096 | ' augmented_assignment_stmt ::= augtarget augop ' |
| 1097 | '(expression_list | yield_expression)\n' |
| 1098 | ' augtarget ::= identifier | attributeref | ' |
| 1099 | 'subscription | slicing\n' |
| 1100 | ' augop ::= "+=" | "-=" | "*=" | "@=" | ' |
| 1101 | '"/=" | "//=" | "%=" | "**="\n' |
| 1102 | ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' |
| 1103 | '\n' |
| 1104 | '(See section Primaries for the syntax definitions of the last ' |
| 1105 | 'three\n' |
| 1106 | 'symbols.)\n' |
| 1107 | '\n' |
| 1108 | 'An augmented assignment evaluates the target (which, unlike ' |
| 1109 | 'normal\n' |
| 1110 | 'assignment statements, cannot be an unpacking) and the ' |
| 1111 | 'expression\n' |
| 1112 | 'list, performs the binary operation specific to the type of ' |
| 1113 | 'assignment\n' |
| 1114 | 'on the two operands, and assigns the result to the original ' |
| 1115 | 'target.\n' |
| 1116 | 'The target is only evaluated once.\n' |
| 1117 | '\n' |
| 1118 | 'An augmented assignment expression like "x += 1" can be ' |
| 1119 | 'rewritten as\n' |
| 1120 | '"x = x + 1" to achieve a similar, but not exactly equal effect. ' |
| 1121 | 'In the\n' |
| 1122 | 'augmented version, "x" is only evaluated once. Also, when ' |
| 1123 | 'possible,\n' |
| 1124 | 'the actual operation is performed *in-place*, meaning that ' |
| 1125 | 'rather than\n' |
| 1126 | 'creating a new object and assigning that to the target, the old ' |
| 1127 | 'object\n' |
| 1128 | 'is modified instead.\n' |
| 1129 | '\n' |
| 1130 | 'Unlike normal assignments, augmented assignments evaluate the ' |
| 1131 | 'left-\n' |
| 1132 | 'hand side *before* evaluating the right-hand side. For ' |
| 1133 | 'example, "a[i]\n' |
| 1134 | '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' |
| 1135 | 'performs\n' |
| 1136 | 'the addition, and lastly, it writes the result back to "a[i]".\n' |
| 1137 | '\n' |
| 1138 | 'With the exception of assigning to tuples and multiple targets ' |
| 1139 | 'in a\n' |
| 1140 | 'single statement, the assignment done by augmented assignment\n' |
| 1141 | 'statements is handled the same way as normal assignments. ' |
| 1142 | 'Similarly,\n' |
| 1143 | 'with the exception of the possible *in-place* behavior, the ' |
| 1144 | 'binary\n' |
| 1145 | 'operation performed by augmented assignment is the same as the ' |
| 1146 | 'normal\n' |
| 1147 | 'binary operations.\n' |
| 1148 | '\n' |
| 1149 | 'For targets which are attribute references, the same caveat ' |
| 1150 | 'about\n' |
| 1151 | 'class and instance attributes applies as for regular ' |
| 1152 | 'assignments.\n', |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 1153 | 'await': 'Await expression\n' |
| 1154 | '****************\n' |
| 1155 | '\n' |
| 1156 | 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n' |
| 1157 | 'only be used inside a *coroutine function*.\n' |
| 1158 | '\n' |
| 1159 | ' await_expr ::= "await" primary\n' |
| 1160 | '\n' |
| 1161 | 'New in version 3.5.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1162 | 'binary': 'Binary arithmetic operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1163 | '****************************\n' |
| 1164 | '\n' |
| 1165 | 'The binary arithmetic operations have the conventional priority\n' |
| 1166 | 'levels. Note that some of these operations also apply to certain ' |
| 1167 | 'non-\n' |
| 1168 | 'numeric types. Apart from the power operator, there are only two\n' |
| 1169 | 'levels, one for multiplicative operators and one for additive\n' |
| 1170 | 'operators:\n' |
| 1171 | '\n' |
| 1172 | ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1173 | ' m_expr "//" u_expr | m_expr "/" u_expr |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1174 | ' m_expr "%" u_expr\n' |
| 1175 | ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' |
| 1176 | '\n' |
| 1177 | 'The "*" (multiplication) operator yields the product of its ' |
| 1178 | 'arguments.\n' |
| 1179 | 'The arguments must either both be numbers, or one argument must be ' |
| 1180 | 'an\n' |
| 1181 | 'integer and the other must be a sequence. In the former case, the\n' |
| 1182 | 'numbers are converted to a common type and then multiplied ' |
| 1183 | 'together.\n' |
| 1184 | 'In the latter case, sequence repetition is performed; a negative\n' |
| 1185 | 'repetition factor yields an empty sequence.\n' |
| 1186 | '\n' |
| 1187 | 'The "@" (at) operator is intended to be used for matrix\n' |
| 1188 | 'multiplication. No builtin Python types implement this operator.\n' |
| 1189 | '\n' |
| 1190 | 'New in version 3.5.\n' |
| 1191 | '\n' |
| 1192 | 'The "/" (division) and "//" (floor division) operators yield the\n' |
| 1193 | 'quotient of their arguments. The numeric arguments are first\n' |
| 1194 | 'converted to a common type. Division of integers yields a float, ' |
| 1195 | 'while\n' |
| 1196 | 'floor division of integers results in an integer; the result is ' |
| 1197 | 'that\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1198 | 'of mathematical division with the ‘floor’ function applied to the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1199 | 'result. Division by zero raises the "ZeroDivisionError" ' |
| 1200 | 'exception.\n' |
| 1201 | '\n' |
| 1202 | 'The "%" (modulo) operator yields the remainder from the division ' |
| 1203 | 'of\n' |
| 1204 | 'the first argument by the second. The numeric arguments are ' |
| 1205 | 'first\n' |
| 1206 | 'converted to a common type. A zero right argument raises the\n' |
| 1207 | '"ZeroDivisionError" exception. The arguments may be floating ' |
| 1208 | 'point\n' |
| 1209 | 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' |
| 1210 | '"4*0.7 +\n' |
| 1211 | '0.34".) The modulo operator always yields a result with the same ' |
| 1212 | 'sign\n' |
| 1213 | 'as its second operand (or zero); the absolute value of the result ' |
| 1214 | 'is\n' |
| 1215 | 'strictly smaller than the absolute value of the second operand ' |
| 1216 | '[1].\n' |
| 1217 | '\n' |
| 1218 | 'The floor division and modulo operators are connected by the ' |
| 1219 | 'following\n' |
| 1220 | 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are ' |
| 1221 | 'also\n' |
| 1222 | 'connected with the built-in function "divmod()": "divmod(x, y) ==\n' |
| 1223 | '(x//y, x%y)". [2].\n' |
| 1224 | '\n' |
| 1225 | 'In addition to performing the modulo operation on numbers, the ' |
| 1226 | '"%"\n' |
| 1227 | 'operator is also overloaded by string objects to perform ' |
| 1228 | 'old-style\n' |
| 1229 | 'string formatting (also known as interpolation). The syntax for\n' |
| 1230 | 'string formatting is described in the Python Library Reference,\n' |
| 1231 | 'section printf-style String Formatting.\n' |
| 1232 | '\n' |
| 1233 | 'The floor division operator, the modulo operator, and the ' |
| 1234 | '"divmod()"\n' |
| 1235 | 'function are not defined for complex numbers. Instead, convert to ' |
| 1236 | 'a\n' |
| 1237 | 'floating point number using the "abs()" function if appropriate.\n' |
| 1238 | '\n' |
| 1239 | 'The "+" (addition) operator yields the sum of its arguments. The\n' |
| 1240 | 'arguments must either both be numbers or both be sequences of the ' |
| 1241 | 'same\n' |
| 1242 | 'type. In the former case, the numbers are converted to a common ' |
| 1243 | 'type\n' |
| 1244 | 'and then added together. In the latter case, the sequences are\n' |
| 1245 | 'concatenated.\n' |
| 1246 | '\n' |
| 1247 | 'The "-" (subtraction) operator yields the difference of its ' |
| 1248 | 'arguments.\n' |
| 1249 | 'The numeric arguments are first converted to a common type.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1250 | 'bitwise': 'Binary bitwise operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1251 | '*************************\n' |
| 1252 | '\n' |
| 1253 | 'Each of the three bitwise operations has a different priority ' |
| 1254 | 'level:\n' |
| 1255 | '\n' |
| 1256 | ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' |
| 1257 | ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' |
| 1258 | ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' |
| 1259 | '\n' |
| 1260 | 'The "&" operator yields the bitwise AND of its arguments, which ' |
| 1261 | 'must\n' |
| 1262 | 'be integers.\n' |
| 1263 | '\n' |
| 1264 | 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' |
| 1265 | 'arguments, which must be integers.\n' |
| 1266 | '\n' |
| 1267 | 'The "|" operator yields the bitwise (inclusive) OR of its ' |
| 1268 | 'arguments,\n' |
| 1269 | 'which must be integers.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1270 | 'bltin-code-objects': 'Code Objects\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1271 | '************\n' |
| 1272 | '\n' |
| 1273 | 'Code objects are used by the implementation to ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1274 | 'represent “pseudo-\n' |
| 1275 | 'compiled” executable Python code such as a function ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1276 | 'body. They differ\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1277 | 'from function objects because they don’t contain a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1278 | 'reference to their\n' |
| 1279 | 'global execution environment. Code objects are ' |
| 1280 | 'returned by the built-\n' |
| 1281 | 'in "compile()" function and can be extracted from ' |
| 1282 | 'function objects\n' |
| 1283 | 'through their "__code__" attribute. See also the ' |
| 1284 | '"code" module.\n' |
| 1285 | '\n' |
| 1286 | 'A code object can be executed or evaluated by passing ' |
| 1287 | 'it (instead of a\n' |
| 1288 | 'source string) to the "exec()" or "eval()" built-in ' |
| 1289 | 'functions.\n' |
| 1290 | '\n' |
| 1291 | 'See The standard type hierarchy for more ' |
| 1292 | 'information.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1293 | 'bltin-ellipsis-object': 'The Ellipsis Object\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1294 | '*******************\n' |
| 1295 | '\n' |
| 1296 | 'This object is commonly used by slicing (see ' |
| 1297 | 'Slicings). It supports\n' |
| 1298 | 'no special operations. There is exactly one ' |
| 1299 | 'ellipsis object, named\n' |
| 1300 | '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' |
| 1301 | 'produces the\n' |
| 1302 | '"Ellipsis" singleton.\n' |
| 1303 | '\n' |
| 1304 | 'It is written as "Ellipsis" or "...".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1305 | 'bltin-null-object': 'The Null Object\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1306 | '***************\n' |
| 1307 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1308 | 'This object is returned by functions that don’t ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1309 | 'explicitly return a\n' |
| 1310 | 'value. It supports no special operations. There is ' |
| 1311 | 'exactly one null\n' |
| 1312 | 'object, named "None" (a built-in name). "type(None)()" ' |
| 1313 | 'produces the\n' |
| 1314 | 'same singleton.\n' |
| 1315 | '\n' |
| 1316 | 'It is written as "None".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1317 | 'bltin-type-objects': 'Type Objects\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1318 | '************\n' |
| 1319 | '\n' |
| 1320 | 'Type objects represent the various object types. An ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1321 | 'object’s type is\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1322 | 'accessed by the built-in function "type()". There are ' |
| 1323 | 'no special\n' |
| 1324 | 'operations on types. The standard module "types" ' |
| 1325 | 'defines names for\n' |
| 1326 | 'all standard built-in types.\n' |
| 1327 | '\n' |
| 1328 | 'Types are written like this: "<class \'int\'>".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1329 | 'booleans': 'Boolean operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1330 | '******************\n' |
| 1331 | '\n' |
| 1332 | ' or_test ::= and_test | or_test "or" and_test\n' |
| 1333 | ' and_test ::= not_test | and_test "and" not_test\n' |
| 1334 | ' not_test ::= comparison | "not" not_test\n' |
| 1335 | '\n' |
| 1336 | 'In the context of Boolean operations, and also when expressions ' |
| 1337 | 'are\n' |
| 1338 | 'used by control flow statements, the following values are ' |
| 1339 | 'interpreted\n' |
| 1340 | 'as false: "False", "None", numeric zero of all types, and empty\n' |
| 1341 | 'strings and containers (including strings, tuples, lists,\n' |
| 1342 | 'dictionaries, sets and frozensets). All other values are ' |
| 1343 | 'interpreted\n' |
| 1344 | 'as true. User-defined objects can customize their truth value ' |
| 1345 | 'by\n' |
| 1346 | 'providing a "__bool__()" method.\n' |
| 1347 | '\n' |
| 1348 | 'The operator "not" yields "True" if its argument is false, ' |
| 1349 | '"False"\n' |
| 1350 | 'otherwise.\n' |
| 1351 | '\n' |
| 1352 | 'The expression "x and y" first evaluates *x*; if *x* is false, ' |
| 1353 | 'its\n' |
| 1354 | 'value is returned; otherwise, *y* is evaluated and the resulting ' |
| 1355 | 'value\n' |
| 1356 | 'is returned.\n' |
| 1357 | '\n' |
| 1358 | 'The expression "x or y" first evaluates *x*; if *x* is true, its ' |
| 1359 | 'value\n' |
| 1360 | 'is returned; otherwise, *y* is evaluated and the resulting value ' |
| 1361 | 'is\n' |
| 1362 | 'returned.\n' |
| 1363 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1364 | 'Note that neither "and" nor "or" restrict the value and type ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1365 | 'they\n' |
| 1366 | 'return to "False" and "True", but rather return the last ' |
| 1367 | 'evaluated\n' |
| 1368 | 'argument. This is sometimes useful, e.g., if "s" is a string ' |
| 1369 | 'that\n' |
| 1370 | 'should be replaced by a default value if it is empty, the ' |
| 1371 | 'expression\n' |
| 1372 | '"s or \'foo\'" yields the desired value. Because "not" has to ' |
| 1373 | 'create a\n' |
| 1374 | 'new value, it returns a boolean value regardless of the type of ' |
| 1375 | 'its\n' |
| 1376 | 'argument (for example, "not \'foo\'" produces "False" rather ' |
| 1377 | 'than "\'\'".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1378 | 'break': 'The "break" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1379 | '*********************\n' |
| 1380 | '\n' |
| 1381 | ' break_stmt ::= "break"\n' |
| 1382 | '\n' |
| 1383 | '"break" may only occur syntactically nested in a "for" or "while"\n' |
| 1384 | 'loop, but not nested in a function or class definition within that\n' |
| 1385 | 'loop.\n' |
| 1386 | '\n' |
| 1387 | 'It terminates the nearest enclosing loop, skipping the optional ' |
| 1388 | '"else"\n' |
| 1389 | 'clause if the loop has one.\n' |
| 1390 | '\n' |
| 1391 | 'If a "for" loop is terminated by "break", the loop control target\n' |
| 1392 | 'keeps its current value.\n' |
| 1393 | '\n' |
| 1394 | 'When "break" passes control out of a "try" statement with a ' |
| 1395 | '"finally"\n' |
| 1396 | 'clause, that "finally" clause is executed before really leaving ' |
| 1397 | 'the\n' |
| 1398 | 'loop.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1399 | 'callable-types': 'Emulating callable objects\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1400 | '**************************\n' |
| 1401 | '\n' |
| 1402 | 'object.__call__(self[, args...])\n' |
| 1403 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1404 | ' Called when the instance is “called” as a function; if ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1405 | 'this method\n' |
| 1406 | ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' |
| 1407 | ' "x.__call__(arg1, arg2, ...)".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1408 | 'calls': 'Calls\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1409 | '*****\n' |
| 1410 | '\n' |
| 1411 | 'A call calls a callable object (e.g., a *function*) with a ' |
| 1412 | 'possibly\n' |
| 1413 | 'empty series of *arguments*:\n' |
| 1414 | '\n' |
| 1415 | ' call ::= primary "(" [argument_list [","] | ' |
| 1416 | 'comprehension] ")"\n' |
| 1417 | ' argument_list ::= positional_arguments ["," ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1418 | 'starred_and_keywords]\n' |
| 1419 | ' ["," keywords_arguments]\n' |
| 1420 | ' | starred_and_keywords ["," ' |
| 1421 | 'keywords_arguments]\n' |
| 1422 | ' | keywords_arguments\n' |
| 1423 | ' positional_arguments ::= ["*"] expression ("," ["*"] ' |
| 1424 | 'expression)*\n' |
| 1425 | ' starred_and_keywords ::= ("*" expression | keyword_item)\n' |
| 1426 | ' ("," "*" expression | "," ' |
| 1427 | 'keyword_item)*\n' |
| 1428 | ' keywords_arguments ::= (keyword_item | "**" expression)\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1429 | ' ("," keyword_item | "," "**" ' |
| 1430 | 'expression)*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1431 | ' keyword_item ::= identifier "=" expression\n' |
| 1432 | '\n' |
| 1433 | 'An optional trailing comma may be present after the positional and\n' |
| 1434 | 'keyword arguments but does not affect the semantics.\n' |
| 1435 | '\n' |
| 1436 | 'The primary must evaluate to a callable object (user-defined\n' |
| 1437 | 'functions, built-in functions, methods of built-in objects, class\n' |
| 1438 | 'objects, methods of class instances, and all objects having a\n' |
| 1439 | '"__call__()" method are callable). All argument expressions are\n' |
| 1440 | 'evaluated before the call is attempted. Please refer to section\n' |
| 1441 | 'Function definitions for the syntax of formal *parameter* lists.\n' |
| 1442 | '\n' |
| 1443 | 'If keyword arguments are present, they are first converted to\n' |
| 1444 | 'positional arguments, as follows. First, a list of unfilled slots ' |
| 1445 | 'is\n' |
| 1446 | 'created for the formal parameters. If there are N positional\n' |
| 1447 | 'arguments, they are placed in the first N slots. Next, for each\n' |
| 1448 | 'keyword argument, the identifier is used to determine the\n' |
| 1449 | 'corresponding slot (if the identifier is the same as the first ' |
| 1450 | 'formal\n' |
| 1451 | 'parameter name, the first slot is used, and so on). If the slot ' |
| 1452 | 'is\n' |
| 1453 | 'already filled, a "TypeError" exception is raised. Otherwise, the\n' |
| 1454 | 'value of the argument is placed in the slot, filling it (even if ' |
| 1455 | 'the\n' |
| 1456 | 'expression is "None", it fills the slot). When all arguments have\n' |
| 1457 | 'been processed, the slots that are still unfilled are filled with ' |
| 1458 | 'the\n' |
| 1459 | 'corresponding default value from the function definition. ' |
| 1460 | '(Default\n' |
| 1461 | 'values are calculated, once, when the function is defined; thus, a\n' |
| 1462 | 'mutable object such as a list or dictionary used as default value ' |
| 1463 | 'will\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1464 | 'be shared by all calls that don’t specify an argument value for ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1465 | 'the\n' |
| 1466 | 'corresponding slot; this should usually be avoided.) If there are ' |
| 1467 | 'any\n' |
| 1468 | 'unfilled slots for which no default value is specified, a ' |
| 1469 | '"TypeError"\n' |
| 1470 | 'exception is raised. Otherwise, the list of filled slots is used ' |
| 1471 | 'as\n' |
| 1472 | 'the argument list for the call.\n' |
| 1473 | '\n' |
| 1474 | '**CPython implementation detail:** An implementation may provide\n' |
| 1475 | 'built-in functions whose positional parameters do not have names, ' |
| 1476 | 'even\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1477 | 'if they are ‘named’ for the purpose of documentation, and which\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1478 | 'therefore cannot be supplied by keyword. In CPython, this is the ' |
| 1479 | 'case\n' |
| 1480 | 'for functions implemented in C that use "PyArg_ParseTuple()" to ' |
| 1481 | 'parse\n' |
| 1482 | 'their arguments.\n' |
| 1483 | '\n' |
| 1484 | 'If there are more positional arguments than there are formal ' |
| 1485 | 'parameter\n' |
| 1486 | 'slots, a "TypeError" exception is raised, unless a formal ' |
| 1487 | 'parameter\n' |
| 1488 | 'using the syntax "*identifier" is present; in this case, that ' |
| 1489 | 'formal\n' |
| 1490 | 'parameter receives a tuple containing the excess positional ' |
| 1491 | 'arguments\n' |
| 1492 | '(or an empty tuple if there were no excess positional arguments).\n' |
| 1493 | '\n' |
| 1494 | 'If any keyword argument does not correspond to a formal parameter\n' |
| 1495 | 'name, a "TypeError" exception is raised, unless a formal parameter\n' |
| 1496 | 'using the syntax "**identifier" is present; in this case, that ' |
| 1497 | 'formal\n' |
| 1498 | 'parameter receives a dictionary containing the excess keyword\n' |
| 1499 | 'arguments (using the keywords as keys and the argument values as\n' |
| 1500 | 'corresponding values), or a (new) empty dictionary if there were ' |
| 1501 | 'no\n' |
| 1502 | 'excess keyword arguments.\n' |
| 1503 | '\n' |
| 1504 | 'If the syntax "*expression" appears in the function call, ' |
| 1505 | '"expression"\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1506 | 'must evaluate to an *iterable*. Elements from these iterables are\n' |
| 1507 | 'treated as if they were additional positional arguments. For the ' |
| 1508 | 'call\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1509 | '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, ' |
| 1510 | '*yM*,\n' |
| 1511 | 'this is equivalent to a call with M+4 positional arguments *x1*, ' |
| 1512 | '*x2*,\n' |
| 1513 | '*y1*, …, *yM*, *x3*, *x4*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1514 | '\n' |
| 1515 | 'A consequence of this is that although the "*expression" syntax ' |
| 1516 | 'may\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1517 | 'appear *after* explicit keyword arguments, it is processed ' |
| 1518 | '*before*\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1519 | 'the keyword arguments (and any "**expression" arguments – see ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1520 | 'below).\n' |
| 1521 | 'So:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1522 | '\n' |
| 1523 | ' >>> def f(a, b):\n' |
| 1524 | ' ... print(a, b)\n' |
| 1525 | ' ...\n' |
| 1526 | ' >>> f(b=1, *(2,))\n' |
| 1527 | ' 2 1\n' |
| 1528 | ' >>> f(a=1, *(2,))\n' |
| 1529 | ' Traceback (most recent call last):\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1530 | ' File "<stdin>", line 1, in <module>\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1531 | " TypeError: f() got multiple values for keyword argument 'a'\n" |
| 1532 | ' >>> f(1, *(2,))\n' |
| 1533 | ' 1 2\n' |
| 1534 | '\n' |
| 1535 | 'It is unusual for both keyword arguments and the "*expression" ' |
| 1536 | 'syntax\n' |
| 1537 | 'to be used in the same call, so in practice this confusion does ' |
| 1538 | 'not\n' |
| 1539 | 'arise.\n' |
| 1540 | '\n' |
| 1541 | 'If the syntax "**expression" appears in the function call,\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1542 | '"expression" must evaluate to a *mapping*, the contents of which ' |
| 1543 | 'are\n' |
| 1544 | 'treated as additional keyword arguments. If a keyword is already\n' |
| 1545 | 'present (as an explicit keyword argument, or from another ' |
| 1546 | 'unpacking),\n' |
| 1547 | 'a "TypeError" exception is raised.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1548 | '\n' |
| 1549 | 'Formal parameters using the syntax "*identifier" or "**identifier"\n' |
| 1550 | 'cannot be used as positional argument slots or as keyword argument\n' |
| 1551 | 'names.\n' |
| 1552 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1553 | 'Changed in version 3.5: Function calls accept any number of "*" ' |
| 1554 | 'and\n' |
| 1555 | '"**" unpackings, positional arguments may follow iterable ' |
| 1556 | 'unpackings\n' |
| 1557 | '("*"), and keyword arguments may follow dictionary unpackings ' |
| 1558 | '("**").\n' |
| 1559 | 'Originally proposed by **PEP 448**.\n' |
| 1560 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1561 | 'A call always returns some value, possibly "None", unless it raises ' |
| 1562 | 'an\n' |
| 1563 | 'exception. How this value is computed depends on the type of the\n' |
| 1564 | 'callable object.\n' |
| 1565 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1566 | 'If it is—\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1567 | '\n' |
| 1568 | 'a user-defined function:\n' |
| 1569 | ' The code block for the function is executed, passing it the\n' |
| 1570 | ' argument list. The first thing the code block will do is bind ' |
| 1571 | 'the\n' |
| 1572 | ' formal parameters to the arguments; this is described in ' |
| 1573 | 'section\n' |
| 1574 | ' Function definitions. When the code block executes a "return"\n' |
| 1575 | ' statement, this specifies the return value of the function ' |
| 1576 | 'call.\n' |
| 1577 | '\n' |
| 1578 | 'a built-in function or method:\n' |
| 1579 | ' The result is up to the interpreter; see Built-in Functions for ' |
| 1580 | 'the\n' |
| 1581 | ' descriptions of built-in functions and methods.\n' |
| 1582 | '\n' |
| 1583 | 'a class object:\n' |
| 1584 | ' A new instance of that class is returned.\n' |
| 1585 | '\n' |
| 1586 | 'a class instance method:\n' |
| 1587 | ' The corresponding user-defined function is called, with an ' |
| 1588 | 'argument\n' |
| 1589 | ' list that is one longer than the argument list of the call: the\n' |
| 1590 | ' instance becomes the first argument.\n' |
| 1591 | '\n' |
| 1592 | 'a class instance:\n' |
| 1593 | ' The class must define a "__call__()" method; the effect is then ' |
| 1594 | 'the\n' |
| 1595 | ' same as if that method was called.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1596 | 'class': 'Class definitions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1597 | '*****************\n' |
| 1598 | '\n' |
| 1599 | 'A class definition defines a class object (see section The ' |
| 1600 | 'standard\n' |
| 1601 | 'type hierarchy):\n' |
| 1602 | '\n' |
| 1603 | ' classdef ::= [decorators] "class" classname [inheritance] ":" ' |
| 1604 | 'suite\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1605 | ' inheritance ::= "(" [argument_list] ")"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1606 | ' classname ::= identifier\n' |
| 1607 | '\n' |
| 1608 | 'A class definition is an executable statement. The inheritance ' |
| 1609 | 'list\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 1610 | 'usually gives a list of base classes (see Metaclasses for more\n' |
| 1611 | 'advanced uses), so each item in the list should evaluate to a ' |
| 1612 | 'class\n' |
| 1613 | 'object which allows subclassing. Classes without an inheritance ' |
| 1614 | 'list\n' |
| 1615 | 'inherit, by default, from the base class "object"; hence,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1616 | '\n' |
| 1617 | ' class Foo:\n' |
| 1618 | ' pass\n' |
| 1619 | '\n' |
| 1620 | 'is equivalent to\n' |
| 1621 | '\n' |
| 1622 | ' class Foo(object):\n' |
| 1623 | ' pass\n' |
| 1624 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1625 | 'The class’s suite is then executed in a new execution frame (see\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1626 | 'Naming and binding), using a newly created local namespace and the\n' |
| 1627 | 'original global namespace. (Usually, the suite contains mostly\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1628 | 'function definitions.) When the class’s suite finishes execution, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1629 | 'its\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1630 | 'execution frame is discarded but its local namespace is saved. [3] ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1631 | 'A\n' |
| 1632 | 'class object is then created using the inheritance list for the ' |
| 1633 | 'base\n' |
| 1634 | 'classes and the saved local namespace for the attribute ' |
| 1635 | 'dictionary.\n' |
| 1636 | 'The class name is bound to this class object in the original local\n' |
| 1637 | 'namespace.\n' |
| 1638 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 1639 | 'The order in which attributes are defined in the class body is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1640 | 'preserved in the new class’s "__dict__". Note that this is ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 1641 | 'reliable\n' |
| 1642 | 'only right after the class is created and only for classes that ' |
| 1643 | 'were\n' |
| 1644 | 'defined using the definition syntax.\n' |
| 1645 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1646 | 'Class creation can be customized heavily using metaclasses.\n' |
| 1647 | '\n' |
| 1648 | 'Classes can also be decorated: just like when decorating ' |
| 1649 | 'functions,\n' |
| 1650 | '\n' |
| 1651 | ' @f1(arg)\n' |
| 1652 | ' @f2\n' |
| 1653 | ' class Foo: pass\n' |
| 1654 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 1655 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1656 | '\n' |
| 1657 | ' class Foo: pass\n' |
| 1658 | ' Foo = f1(arg)(f2(Foo))\n' |
| 1659 | '\n' |
| 1660 | 'The evaluation rules for the decorator expressions are the same as ' |
| 1661 | 'for\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 1662 | 'function decorators. The result is then bound to the class name.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1663 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1664 | '**Programmer’s note:** Variables defined in the class definition ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1665 | 'are\n' |
| 1666 | 'class attributes; they are shared by instances. Instance ' |
| 1667 | 'attributes\n' |
| 1668 | 'can be set in a method with "self.name = value". Both class and\n' |
| 1669 | 'instance attributes are accessible through the notation ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1670 | '“"self.name"”,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1671 | 'and an instance attribute hides a class attribute with the same ' |
| 1672 | 'name\n' |
| 1673 | 'when accessed in this way. Class attributes can be used as ' |
| 1674 | 'defaults\n' |
| 1675 | 'for instance attributes, but using mutable values there can lead ' |
| 1676 | 'to\n' |
| 1677 | 'unexpected results. Descriptors can be used to create instance\n' |
| 1678 | 'variables with different implementation details.\n' |
| 1679 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1680 | 'See also:\n' |
| 1681 | '\n' |
| 1682 | ' **PEP 3115** - Metaclasses in Python 3000\n' |
| 1683 | ' The proposal that changed the declaration of metaclasses to ' |
| 1684 | 'the\n' |
| 1685 | ' current syntax, and the semantics for how classes with\n' |
| 1686 | ' metaclasses are constructed.\n' |
| 1687 | '\n' |
| 1688 | ' **PEP 3129** - Class Decorators\n' |
| 1689 | ' The proposal that added class decorators. Function and ' |
| 1690 | 'method\n' |
| 1691 | ' decorators were introduced in **PEP 318**.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1692 | 'comparisons': 'Comparisons\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1693 | '***********\n' |
| 1694 | '\n' |
| 1695 | 'Unlike C, all comparison operations in Python have the same ' |
| 1696 | 'priority,\n' |
| 1697 | 'which is lower than that of any arithmetic, shifting or ' |
| 1698 | 'bitwise\n' |
| 1699 | 'operation. Also unlike C, expressions like "a < b < c" have ' |
| 1700 | 'the\n' |
| 1701 | 'interpretation that is conventional in mathematics:\n' |
| 1702 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1703 | ' comparison ::= or_expr (comp_operator or_expr)*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1704 | ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' |
| 1705 | ' | "is" ["not"] | ["not"] "in"\n' |
| 1706 | '\n' |
| 1707 | 'Comparisons yield boolean values: "True" or "False".\n' |
| 1708 | '\n' |
| 1709 | 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' |
| 1710 | 'is\n' |
| 1711 | 'equivalent to "x < y and y <= z", except that "y" is ' |
| 1712 | 'evaluated only\n' |
| 1713 | 'once (but in both cases "z" is not evaluated at all when "x < ' |
| 1714 | 'y" is\n' |
| 1715 | 'found to be false).\n' |
| 1716 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1717 | 'Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1718 | '*op1*,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1719 | '*op2*, …, *opN* are comparison operators, then "a op1 b op2 c ' |
| 1720 | '... y\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1721 | 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' |
| 1722 | 'z", except\n' |
| 1723 | 'that each expression is evaluated at most once.\n' |
| 1724 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1725 | 'Note that "a op1 b op2 c" doesn’t imply any kind of ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1726 | 'comparison between\n' |
| 1727 | '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' |
| 1728 | '(though\n' |
| 1729 | 'perhaps not pretty).\n' |
| 1730 | '\n' |
| 1731 | '\n' |
| 1732 | 'Value comparisons\n' |
| 1733 | '=================\n' |
| 1734 | '\n' |
| 1735 | 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' |
| 1736 | 'the values\n' |
| 1737 | 'of two objects. The objects do not need to have the same ' |
| 1738 | 'type.\n' |
| 1739 | '\n' |
| 1740 | 'Chapter Objects, values and types states that objects have a ' |
| 1741 | 'value (in\n' |
| 1742 | 'addition to type and identity). The value of an object is a ' |
| 1743 | 'rather\n' |
| 1744 | 'abstract notion in Python: For example, there is no canonical ' |
| 1745 | 'access\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1746 | 'method for an object’s value. Also, there is no requirement ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1747 | 'that the\n' |
| 1748 | 'value of an object should be constructed in a particular way, ' |
| 1749 | 'e.g.\n' |
| 1750 | 'comprised of all its data attributes. Comparison operators ' |
| 1751 | 'implement a\n' |
| 1752 | 'particular notion of what the value of an object is. One can ' |
| 1753 | 'think of\n' |
| 1754 | 'them as defining the value of an object indirectly, by means ' |
| 1755 | 'of their\n' |
| 1756 | 'comparison implementation.\n' |
| 1757 | '\n' |
| 1758 | 'Because all types are (direct or indirect) subtypes of ' |
| 1759 | '"object", they\n' |
| 1760 | 'inherit the default comparison behavior from "object". Types ' |
| 1761 | 'can\n' |
| 1762 | 'customize their comparison behavior by implementing *rich ' |
| 1763 | 'comparison\n' |
| 1764 | 'methods* like "__lt__()", described in Basic customization.\n' |
| 1765 | '\n' |
| 1766 | 'The default behavior for equality comparison ("==" and "!=") ' |
| 1767 | 'is based\n' |
| 1768 | 'on the identity of the objects. Hence, equality comparison ' |
| 1769 | 'of\n' |
| 1770 | 'instances with the same identity results in equality, and ' |
| 1771 | 'equality\n' |
| 1772 | 'comparison of instances with different identities results in\n' |
| 1773 | 'inequality. A motivation for this default behavior is the ' |
| 1774 | 'desire that\n' |
| 1775 | 'all objects should be reflexive (i.e. "x is y" implies "x == ' |
| 1776 | 'y").\n' |
| 1777 | '\n' |
| 1778 | 'A default order comparison ("<", ">", "<=", and ">=") is not ' |
| 1779 | 'provided;\n' |
| 1780 | 'an attempt raises "TypeError". A motivation for this default ' |
| 1781 | 'behavior\n' |
| 1782 | 'is the lack of a similar invariant as for equality.\n' |
| 1783 | '\n' |
| 1784 | 'The behavior of the default equality comparison, that ' |
| 1785 | 'instances with\n' |
| 1786 | 'different identities are always unequal, may be in contrast ' |
| 1787 | 'to what\n' |
| 1788 | 'types will need that have a sensible definition of object ' |
| 1789 | 'value and\n' |
| 1790 | 'value-based equality. Such types will need to customize ' |
| 1791 | 'their\n' |
| 1792 | 'comparison behavior, and in fact, a number of built-in types ' |
| 1793 | 'have done\n' |
| 1794 | 'that.\n' |
| 1795 | '\n' |
| 1796 | 'The following list describes the comparison behavior of the ' |
| 1797 | 'most\n' |
| 1798 | 'important built-in types.\n' |
| 1799 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1800 | '* Numbers of built-in numeric types (Numeric Types — int, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1801 | 'float,\n' |
| 1802 | ' complex) and of the standard library types ' |
| 1803 | '"fractions.Fraction" and\n' |
| 1804 | ' "decimal.Decimal" can be compared within and across their ' |
| 1805 | 'types,\n' |
| 1806 | ' with the restriction that complex numbers do not support ' |
| 1807 | 'order\n' |
| 1808 | ' comparison. Within the limits of the types involved, they ' |
| 1809 | 'compare\n' |
| 1810 | ' mathematically (algorithmically) correct without loss of ' |
| 1811 | 'precision.\n' |
| 1812 | '\n' |
| 1813 | ' The not-a-number values "float(\'NaN\')" and ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 1814 | '"decimal.Decimal(\'NaN\')"\n' |
| 1815 | ' are special. Any ordered comparison of a number to a ' |
| 1816 | 'not-a-number\n' |
| 1817 | ' value is false. A counter-intuitive implication is that ' |
| 1818 | 'not-a-number\n' |
| 1819 | ' values are not equal to themselves. For example, if "x =\n' |
| 1820 | ' float(\'NaN\')", "3 < x", "x < 3", "x == x", "x != x" are ' |
| 1821 | 'all false.\n' |
| 1822 | ' This behavior is compliant with IEEE 754.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1823 | '\n' |
| 1824 | '* Binary sequences (instances of "bytes" or "bytearray") can ' |
| 1825 | 'be\n' |
| 1826 | ' compared within and across their types. They compare\n' |
| 1827 | ' lexicographically using the numeric values of their ' |
| 1828 | 'elements.\n' |
| 1829 | '\n' |
| 1830 | '* Strings (instances of "str") compare lexicographically ' |
| 1831 | 'using the\n' |
| 1832 | ' numerical Unicode code points (the result of the built-in ' |
| 1833 | 'function\n' |
| 1834 | ' "ord()") of their characters. [3]\n' |
| 1835 | '\n' |
| 1836 | ' Strings and binary sequences cannot be directly compared.\n' |
| 1837 | '\n' |
| 1838 | '* Sequences (instances of "tuple", "list", or "range") can ' |
| 1839 | 'be\n' |
| 1840 | ' compared only within each of their types, with the ' |
| 1841 | 'restriction that\n' |
| 1842 | ' ranges do not support order comparison. Equality ' |
| 1843 | 'comparison across\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1844 | ' these types results in inequality, and ordering comparison ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1845 | 'across\n' |
| 1846 | ' these types raises "TypeError".\n' |
| 1847 | '\n' |
| 1848 | ' Sequences compare lexicographically using comparison of\n' |
| 1849 | ' corresponding elements, whereby reflexivity of the elements ' |
| 1850 | 'is\n' |
| 1851 | ' enforced.\n' |
| 1852 | '\n' |
| 1853 | ' In enforcing reflexivity of elements, the comparison of ' |
| 1854 | 'collections\n' |
| 1855 | ' assumes that for a collection element "x", "x == x" is ' |
| 1856 | 'always true.\n' |
| 1857 | ' Based on that assumption, element identity is compared ' |
| 1858 | 'first, and\n' |
| 1859 | ' element comparison is performed only for distinct ' |
| 1860 | 'elements. This\n' |
| 1861 | ' approach yields the same result as a strict element ' |
| 1862 | 'comparison\n' |
| 1863 | ' would, if the compared elements are reflexive. For ' |
| 1864 | 'non-reflexive\n' |
| 1865 | ' elements, the result is different than for strict element\n' |
| 1866 | ' comparison, and may be surprising: The non-reflexive ' |
| 1867 | 'not-a-number\n' |
| 1868 | ' values for example result in the following comparison ' |
| 1869 | 'behavior when\n' |
| 1870 | ' used in a list:\n' |
| 1871 | '\n' |
| 1872 | " >>> nan = float('NaN')\n" |
| 1873 | ' >>> nan is nan\n' |
| 1874 | ' True\n' |
| 1875 | ' >>> nan == nan\n' |
| 1876 | ' False <-- the defined non-reflexive ' |
| 1877 | 'behavior of NaN\n' |
| 1878 | ' >>> [nan] == [nan]\n' |
| 1879 | ' True <-- list enforces reflexivity and ' |
| 1880 | 'tests identity first\n' |
| 1881 | '\n' |
| 1882 | ' Lexicographical comparison between built-in collections ' |
| 1883 | 'works as\n' |
| 1884 | ' follows:\n' |
| 1885 | '\n' |
| 1886 | ' * For two collections to compare equal, they must be of the ' |
| 1887 | 'same\n' |
| 1888 | ' type, have the same length, and each pair of ' |
| 1889 | 'corresponding\n' |
| 1890 | ' elements must compare equal (for example, "[1,2] == ' |
| 1891 | '(1,2)" is\n' |
| 1892 | ' false because the type is not the same).\n' |
| 1893 | '\n' |
| 1894 | ' * Collections that support order comparison are ordered the ' |
| 1895 | 'same\n' |
| 1896 | ' as their first unequal elements (for example, "[1,2,x] <= ' |
| 1897 | '[1,2,y]"\n' |
| 1898 | ' has the same value as "x <= y"). If a corresponding ' |
| 1899 | 'element does\n' |
| 1900 | ' not exist, the shorter collection is ordered first (for ' |
| 1901 | 'example,\n' |
| 1902 | ' "[1,2] < [1,2,3]" is true).\n' |
| 1903 | '\n' |
| 1904 | '* Mappings (instances of "dict") compare equal if and only if ' |
| 1905 | 'they\n' |
| 1906 | ' have equal *(key, value)* pairs. Equality comparison of the ' |
| 1907 | 'keys and\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1908 | ' values enforces reflexivity.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1909 | '\n' |
| 1910 | ' Order comparisons ("<", ">", "<=", and ">=") raise ' |
| 1911 | '"TypeError".\n' |
| 1912 | '\n' |
| 1913 | '* Sets (instances of "set" or "frozenset") can be compared ' |
| 1914 | 'within\n' |
| 1915 | ' and across their types.\n' |
| 1916 | '\n' |
| 1917 | ' They define order comparison operators to mean subset and ' |
| 1918 | 'superset\n' |
| 1919 | ' tests. Those relations do not define total orderings (for ' |
| 1920 | 'example,\n' |
| 1921 | ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets ' |
| 1922 | 'of one\n' |
| 1923 | ' another, nor supersets of one another). Accordingly, sets ' |
| 1924 | 'are not\n' |
| 1925 | ' appropriate arguments for functions which depend on total ' |
| 1926 | 'ordering\n' |
| 1927 | ' (for example, "min()", "max()", and "sorted()" produce ' |
| 1928 | 'undefined\n' |
| 1929 | ' results given a list of sets as inputs).\n' |
| 1930 | '\n' |
| 1931 | ' Comparison of sets enforces reflexivity of its elements.\n' |
| 1932 | '\n' |
| 1933 | '* Most other built-in types have no comparison methods ' |
| 1934 | 'implemented,\n' |
| 1935 | ' so they inherit the default comparison behavior.\n' |
| 1936 | '\n' |
| 1937 | 'User-defined classes that customize their comparison behavior ' |
| 1938 | 'should\n' |
| 1939 | 'follow some consistency rules, if possible:\n' |
| 1940 | '\n' |
| 1941 | '* Equality comparison should be reflexive. In other words, ' |
| 1942 | 'identical\n' |
| 1943 | ' objects should compare equal:\n' |
| 1944 | '\n' |
| 1945 | ' "x is y" implies "x == y"\n' |
| 1946 | '\n' |
| 1947 | '* Comparison should be symmetric. In other words, the ' |
| 1948 | 'following\n' |
| 1949 | ' expressions should have the same result:\n' |
| 1950 | '\n' |
| 1951 | ' "x == y" and "y == x"\n' |
| 1952 | '\n' |
| 1953 | ' "x != y" and "y != x"\n' |
| 1954 | '\n' |
| 1955 | ' "x < y" and "y > x"\n' |
| 1956 | '\n' |
| 1957 | ' "x <= y" and "y >= x"\n' |
| 1958 | '\n' |
| 1959 | '* Comparison should be transitive. The following ' |
| 1960 | '(non-exhaustive)\n' |
| 1961 | ' examples illustrate that:\n' |
| 1962 | '\n' |
| 1963 | ' "x > y and y > z" implies "x > z"\n' |
| 1964 | '\n' |
| 1965 | ' "x < y and y <= z" implies "x < z"\n' |
| 1966 | '\n' |
| 1967 | '* Inverse comparison should result in the boolean negation. ' |
| 1968 | 'In other\n' |
| 1969 | ' words, the following expressions should have the same ' |
| 1970 | 'result:\n' |
| 1971 | '\n' |
| 1972 | ' "x == y" and "not x != y"\n' |
| 1973 | '\n' |
| 1974 | ' "x < y" and "not x >= y" (for total ordering)\n' |
| 1975 | '\n' |
| 1976 | ' "x > y" and "not x <= y" (for total ordering)\n' |
| 1977 | '\n' |
| 1978 | ' The last two expressions apply to totally ordered ' |
| 1979 | 'collections (e.g.\n' |
| 1980 | ' to sequences, but not to sets or mappings). See also the\n' |
| 1981 | ' "total_ordering()" decorator.\n' |
| 1982 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1983 | '* The "hash()" result should be consistent with equality. ' |
| 1984 | 'Objects\n' |
| 1985 | ' that are equal should either have the same hash value, or ' |
| 1986 | 'be marked\n' |
| 1987 | ' as unhashable.\n' |
| 1988 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1989 | 'Python does not enforce these consistency rules. In fact, ' |
| 1990 | 'the\n' |
| 1991 | 'not-a-number values are an example for not following these ' |
| 1992 | 'rules.\n' |
| 1993 | '\n' |
| 1994 | '\n' |
| 1995 | 'Membership test operations\n' |
| 1996 | '==========================\n' |
| 1997 | '\n' |
| 1998 | 'The operators "in" and "not in" test for membership. "x in ' |
| 1999 | 's"\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2000 | 'evaluates to "True" if *x* is a member of *s*, and "False" ' |
| 2001 | 'otherwise.\n' |
| 2002 | '"x not in s" returns the negation of "x in s". All built-in ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2003 | 'sequences\n' |
| 2004 | 'and set types support this as well as dictionary, for which ' |
| 2005 | '"in" tests\n' |
| 2006 | 'whether the dictionary has a given key. For container types ' |
| 2007 | 'such as\n' |
| 2008 | 'list, tuple, set, frozenset, dict, or collections.deque, the\n' |
| 2009 | 'expression "x in y" is equivalent to "any(x is e or x == e ' |
| 2010 | 'for e in\n' |
| 2011 | 'y)".\n' |
| 2012 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2013 | 'For the string and bytes types, "x in y" is "True" if and ' |
| 2014 | 'only if *x*\n' |
| 2015 | 'is a substring of *y*. An equivalent test is "y.find(x) != ' |
| 2016 | '-1".\n' |
| 2017 | 'Empty strings are always considered to be a substring of any ' |
| 2018 | 'other\n' |
| 2019 | 'string, so """ in "abc"" will return "True".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2020 | '\n' |
| 2021 | 'For user-defined classes which define the "__contains__()" ' |
| 2022 | 'method, "x\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2023 | 'in y" returns "True" if "y.__contains__(x)" returns a true ' |
| 2024 | 'value, and\n' |
| 2025 | '"False" otherwise.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2026 | '\n' |
| 2027 | 'For user-defined classes which do not define "__contains__()" ' |
| 2028 | 'but do\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2029 | 'define "__iter__()", "x in y" is "True" if some value "z" ' |
| 2030 | 'with "x ==\n' |
| 2031 | 'z" is produced while iterating over "y". If an exception is ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2032 | 'raised\n' |
| 2033 | 'during the iteration, it is as if "in" raised that ' |
| 2034 | 'exception.\n' |
| 2035 | '\n' |
| 2036 | 'Lastly, the old-style iteration protocol is tried: if a class ' |
| 2037 | 'defines\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2038 | '"__getitem__()", "x in y" is "True" if and only if there is a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2039 | 'non-\n' |
| 2040 | 'negative integer index *i* such that "x == y[i]", and all ' |
| 2041 | 'lower\n' |
| 2042 | 'integer indices do not raise "IndexError" exception. (If any ' |
| 2043 | 'other\n' |
| 2044 | 'exception is raised, it is as if "in" raised that ' |
| 2045 | 'exception).\n' |
| 2046 | '\n' |
| 2047 | 'The operator "not in" is defined to have the inverse true ' |
| 2048 | 'value of\n' |
| 2049 | '"in".\n' |
| 2050 | '\n' |
| 2051 | '\n' |
| 2052 | 'Identity comparisons\n' |
| 2053 | '====================\n' |
| 2054 | '\n' |
| 2055 | 'The operators "is" and "is not" test for object identity: "x ' |
| 2056 | 'is y" is\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2057 | 'true if and only if *x* and *y* are the same object. Object ' |
| 2058 | 'identity\n' |
| 2059 | 'is determined using the "id()" function. "x is not y" yields ' |
| 2060 | 'the\n' |
| 2061 | 'inverse truth value. [4]\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2062 | 'compound': 'Compound statements\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2063 | '*******************\n' |
| 2064 | '\n' |
| 2065 | 'Compound statements contain (groups of) other statements; they ' |
| 2066 | 'affect\n' |
| 2067 | 'or control the execution of those other statements in some way. ' |
| 2068 | 'In\n' |
| 2069 | 'general, compound statements span multiple lines, although in ' |
| 2070 | 'simple\n' |
| 2071 | 'incarnations a whole compound statement may be contained in one ' |
| 2072 | 'line.\n' |
| 2073 | '\n' |
| 2074 | 'The "if", "while" and "for" statements implement traditional ' |
| 2075 | 'control\n' |
| 2076 | 'flow constructs. "try" specifies exception handlers and/or ' |
| 2077 | 'cleanup\n' |
| 2078 | 'code for a group of statements, while the "with" statement ' |
| 2079 | 'allows the\n' |
| 2080 | 'execution of initialization and finalization code around a block ' |
| 2081 | 'of\n' |
| 2082 | 'code. Function and class definitions are also syntactically ' |
| 2083 | 'compound\n' |
| 2084 | 'statements.\n' |
| 2085 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2086 | 'A compound statement consists of one or more ‘clauses.’ A ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2087 | 'clause\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2088 | 'consists of a header and a ‘suite.’ The clause headers of a\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2089 | 'particular compound statement are all at the same indentation ' |
| 2090 | 'level.\n' |
| 2091 | 'Each clause header begins with a uniquely identifying keyword ' |
| 2092 | 'and ends\n' |
| 2093 | 'with a colon. A suite is a group of statements controlled by a\n' |
| 2094 | 'clause. A suite can be one or more semicolon-separated simple\n' |
| 2095 | 'statements on the same line as the header, following the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2096 | 'header’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2097 | 'colon, or it can be one or more indented statements on ' |
| 2098 | 'subsequent\n' |
| 2099 | 'lines. Only the latter form of a suite can contain nested ' |
| 2100 | 'compound\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2101 | 'statements; the following is illegal, mostly because it wouldn’t ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2102 | 'be\n' |
| 2103 | 'clear to which "if" clause a following "else" clause would ' |
| 2104 | 'belong:\n' |
| 2105 | '\n' |
| 2106 | ' if test1: if test2: print(x)\n' |
| 2107 | '\n' |
| 2108 | 'Also note that the semicolon binds tighter than the colon in ' |
| 2109 | 'this\n' |
| 2110 | 'context, so that in the following example, either all or none of ' |
| 2111 | 'the\n' |
| 2112 | '"print()" calls are executed:\n' |
| 2113 | '\n' |
| 2114 | ' if x < y < z: print(x); print(y); print(z)\n' |
| 2115 | '\n' |
| 2116 | 'Summarizing:\n' |
| 2117 | '\n' |
| 2118 | ' compound_stmt ::= if_stmt\n' |
| 2119 | ' | while_stmt\n' |
| 2120 | ' | for_stmt\n' |
| 2121 | ' | try_stmt\n' |
| 2122 | ' | with_stmt\n' |
| 2123 | ' | funcdef\n' |
| 2124 | ' | classdef\n' |
| 2125 | ' | async_with_stmt\n' |
| 2126 | ' | async_for_stmt\n' |
| 2127 | ' | async_funcdef\n' |
| 2128 | ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' |
| 2129 | 'statement+ DEDENT\n' |
| 2130 | ' statement ::= stmt_list NEWLINE | compound_stmt\n' |
| 2131 | ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' |
| 2132 | '\n' |
| 2133 | 'Note that statements always end in a "NEWLINE" possibly followed ' |
| 2134 | 'by a\n' |
| 2135 | '"DEDENT". Also note that optional continuation clauses always ' |
| 2136 | 'begin\n' |
| 2137 | 'with a keyword that cannot start a statement, thus there are no\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2138 | 'ambiguities (the ‘dangling "else"’ problem is solved in Python ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2139 | 'by\n' |
| 2140 | 'requiring nested "if" statements to be indented).\n' |
| 2141 | '\n' |
| 2142 | 'The formatting of the grammar rules in the following sections ' |
| 2143 | 'places\n' |
| 2144 | 'each clause on a separate line for clarity.\n' |
| 2145 | '\n' |
| 2146 | '\n' |
| 2147 | 'The "if" statement\n' |
| 2148 | '==================\n' |
| 2149 | '\n' |
| 2150 | 'The "if" statement is used for conditional execution:\n' |
| 2151 | '\n' |
| 2152 | ' if_stmt ::= "if" expression ":" suite\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2153 | ' ("elif" expression ":" suite)*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2154 | ' ["else" ":" suite]\n' |
| 2155 | '\n' |
| 2156 | 'It selects exactly one of the suites by evaluating the ' |
| 2157 | 'expressions one\n' |
| 2158 | 'by one until one is found to be true (see section Boolean ' |
| 2159 | 'operations\n' |
| 2160 | 'for the definition of true and false); then that suite is ' |
| 2161 | 'executed\n' |
| 2162 | '(and no other part of the "if" statement is executed or ' |
| 2163 | 'evaluated).\n' |
| 2164 | 'If all expressions are false, the suite of the "else" clause, ' |
| 2165 | 'if\n' |
| 2166 | 'present, is executed.\n' |
| 2167 | '\n' |
| 2168 | '\n' |
| 2169 | 'The "while" statement\n' |
| 2170 | '=====================\n' |
| 2171 | '\n' |
| 2172 | 'The "while" statement is used for repeated execution as long as ' |
| 2173 | 'an\n' |
| 2174 | 'expression is true:\n' |
| 2175 | '\n' |
| 2176 | ' while_stmt ::= "while" expression ":" suite\n' |
| 2177 | ' ["else" ":" suite]\n' |
| 2178 | '\n' |
| 2179 | 'This repeatedly tests the expression and, if it is true, ' |
| 2180 | 'executes the\n' |
| 2181 | 'first suite; if the expression is false (which may be the first ' |
| 2182 | 'time\n' |
| 2183 | 'it is tested) the suite of the "else" clause, if present, is ' |
| 2184 | 'executed\n' |
| 2185 | 'and the loop terminates.\n' |
| 2186 | '\n' |
| 2187 | 'A "break" statement executed in the first suite terminates the ' |
| 2188 | 'loop\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2189 | 'without executing the "else" clause’s suite. A "continue" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2190 | 'statement\n' |
| 2191 | 'executed in the first suite skips the rest of the suite and goes ' |
| 2192 | 'back\n' |
| 2193 | 'to testing the expression.\n' |
| 2194 | '\n' |
| 2195 | '\n' |
| 2196 | 'The "for" statement\n' |
| 2197 | '===================\n' |
| 2198 | '\n' |
| 2199 | 'The "for" statement is used to iterate over the elements of a ' |
| 2200 | 'sequence\n' |
| 2201 | '(such as a string, tuple or list) or other iterable object:\n' |
| 2202 | '\n' |
| 2203 | ' for_stmt ::= "for" target_list "in" expression_list ":" ' |
| 2204 | 'suite\n' |
| 2205 | ' ["else" ":" suite]\n' |
| 2206 | '\n' |
| 2207 | 'The expression list is evaluated once; it should yield an ' |
| 2208 | 'iterable\n' |
| 2209 | 'object. An iterator is created for the result of the\n' |
| 2210 | '"expression_list". The suite is then executed once for each ' |
| 2211 | 'item\n' |
| 2212 | 'provided by the iterator, in the order returned by the ' |
| 2213 | 'iterator. Each\n' |
| 2214 | 'item in turn is assigned to the target list using the standard ' |
| 2215 | 'rules\n' |
| 2216 | 'for assignments (see Assignment statements), and then the suite ' |
| 2217 | 'is\n' |
| 2218 | 'executed. When the items are exhausted (which is immediately ' |
| 2219 | 'when the\n' |
| 2220 | 'sequence is empty or an iterator raises a "StopIteration" ' |
| 2221 | 'exception),\n' |
| 2222 | 'the suite in the "else" clause, if present, is executed, and the ' |
| 2223 | 'loop\n' |
| 2224 | 'terminates.\n' |
| 2225 | '\n' |
| 2226 | 'A "break" statement executed in the first suite terminates the ' |
| 2227 | 'loop\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2228 | 'without executing the "else" clause’s suite. A "continue" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2229 | 'statement\n' |
| 2230 | 'executed in the first suite skips the rest of the suite and ' |
| 2231 | 'continues\n' |
| 2232 | 'with the next item, or with the "else" clause if there is no ' |
| 2233 | 'next\n' |
| 2234 | 'item.\n' |
| 2235 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2236 | 'The for-loop makes assignments to the variables in the target ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2237 | 'list.\n' |
| 2238 | 'This overwrites all previous assignments to those variables ' |
| 2239 | 'including\n' |
| 2240 | 'those made in the suite of the for-loop:\n' |
| 2241 | '\n' |
| 2242 | ' for i in range(10):\n' |
| 2243 | ' print(i)\n' |
| 2244 | ' i = 5 # this will not affect the for-loop\n' |
| 2245 | ' # because i will be overwritten with ' |
| 2246 | 'the next\n' |
| 2247 | ' # index in the range\n' |
| 2248 | '\n' |
| 2249 | 'Names in the target list are not deleted when the loop is ' |
| 2250 | 'finished,\n' |
| 2251 | 'but if the sequence is empty, they will not have been assigned ' |
| 2252 | 'to at\n' |
| 2253 | 'all by the loop. Hint: the built-in function "range()" returns ' |
| 2254 | 'an\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2255 | 'iterator of integers suitable to emulate the effect of Pascal’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2256 | '"for i\n' |
| 2257 | ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' |
| 2258 | '2]".\n' |
| 2259 | '\n' |
| 2260 | 'Note: There is a subtlety when the sequence is being modified by ' |
| 2261 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2262 | ' loop (this can only occur for mutable sequences, e.g. lists). ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2263 | 'An\n' |
| 2264 | ' internal counter is used to keep track of which item is used ' |
| 2265 | 'next,\n' |
| 2266 | ' and this is incremented on each iteration. When this counter ' |
| 2267 | 'has\n' |
| 2268 | ' reached the length of the sequence the loop terminates. This ' |
| 2269 | 'means\n' |
| 2270 | ' that if the suite deletes the current (or a previous) item ' |
| 2271 | 'from the\n' |
| 2272 | ' sequence, the next item will be skipped (since it gets the ' |
| 2273 | 'index of\n' |
| 2274 | ' the current item which has already been treated). Likewise, ' |
| 2275 | 'if the\n' |
| 2276 | ' suite inserts an item in the sequence before the current item, ' |
| 2277 | 'the\n' |
| 2278 | ' current item will be treated again the next time through the ' |
| 2279 | 'loop.\n' |
| 2280 | ' This can lead to nasty bugs that can be avoided by making a\n' |
| 2281 | ' temporary copy using a slice of the whole sequence, e.g.,\n' |
| 2282 | '\n' |
| 2283 | ' for x in a[:]:\n' |
| 2284 | ' if x < 0: a.remove(x)\n' |
| 2285 | '\n' |
| 2286 | '\n' |
| 2287 | 'The "try" statement\n' |
| 2288 | '===================\n' |
| 2289 | '\n' |
| 2290 | 'The "try" statement specifies exception handlers and/or cleanup ' |
| 2291 | 'code\n' |
| 2292 | 'for a group of statements:\n' |
| 2293 | '\n' |
| 2294 | ' try_stmt ::= try1_stmt | try2_stmt\n' |
| 2295 | ' try1_stmt ::= "try" ":" suite\n' |
| 2296 | ' ("except" [expression ["as" identifier]] ":" ' |
| 2297 | 'suite)+\n' |
| 2298 | ' ["else" ":" suite]\n' |
| 2299 | ' ["finally" ":" suite]\n' |
| 2300 | ' try2_stmt ::= "try" ":" suite\n' |
| 2301 | ' "finally" ":" suite\n' |
| 2302 | '\n' |
| 2303 | 'The "except" clause(s) specify one or more exception handlers. ' |
| 2304 | 'When no\n' |
| 2305 | 'exception occurs in the "try" clause, no exception handler is\n' |
| 2306 | 'executed. When an exception occurs in the "try" suite, a search ' |
| 2307 | 'for an\n' |
| 2308 | 'exception handler is started. This search inspects the except ' |
| 2309 | 'clauses\n' |
| 2310 | 'in turn until one is found that matches the exception. An ' |
| 2311 | 'expression-\n' |
| 2312 | 'less except clause, if present, must be last; it matches any\n' |
| 2313 | 'exception. For an except clause with an expression, that ' |
| 2314 | 'expression\n' |
| 2315 | 'is evaluated, and the clause matches the exception if the ' |
| 2316 | 'resulting\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2317 | 'object is “compatible” with the exception. An object is ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2318 | 'compatible\n' |
| 2319 | 'with an exception if it is the class or a base class of the ' |
| 2320 | 'exception\n' |
| 2321 | 'object or a tuple containing an item compatible with the ' |
| 2322 | 'exception.\n' |
| 2323 | '\n' |
| 2324 | 'If no except clause matches the exception, the search for an ' |
| 2325 | 'exception\n' |
| 2326 | 'handler continues in the surrounding code and on the invocation ' |
| 2327 | 'stack.\n' |
| 2328 | '[1]\n' |
| 2329 | '\n' |
| 2330 | 'If the evaluation of an expression in the header of an except ' |
| 2331 | 'clause\n' |
| 2332 | 'raises an exception, the original search for a handler is ' |
| 2333 | 'canceled and\n' |
| 2334 | 'a search starts for the new exception in the surrounding code ' |
| 2335 | 'and on\n' |
| 2336 | 'the call stack (it is treated as if the entire "try" statement ' |
| 2337 | 'raised\n' |
| 2338 | 'the exception).\n' |
| 2339 | '\n' |
| 2340 | 'When a matching except clause is found, the exception is ' |
| 2341 | 'assigned to\n' |
| 2342 | 'the target specified after the "as" keyword in that except ' |
| 2343 | 'clause, if\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2344 | 'present, and the except clause’s suite is executed. All except\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2345 | 'clauses must have an executable block. When the end of this ' |
| 2346 | 'block is\n' |
| 2347 | 'reached, execution continues normally after the entire try ' |
| 2348 | 'statement.\n' |
| 2349 | '(This means that if two nested handlers exist for the same ' |
| 2350 | 'exception,\n' |
| 2351 | 'and the exception occurs in the try clause of the inner handler, ' |
| 2352 | 'the\n' |
| 2353 | 'outer handler will not handle the exception.)\n' |
| 2354 | '\n' |
| 2355 | 'When an exception has been assigned using "as target", it is ' |
| 2356 | 'cleared\n' |
| 2357 | 'at the end of the except clause. This is as if\n' |
| 2358 | '\n' |
| 2359 | ' except E as N:\n' |
| 2360 | ' foo\n' |
| 2361 | '\n' |
| 2362 | 'was translated to\n' |
| 2363 | '\n' |
| 2364 | ' except E as N:\n' |
| 2365 | ' try:\n' |
| 2366 | ' foo\n' |
| 2367 | ' finally:\n' |
| 2368 | ' del N\n' |
| 2369 | '\n' |
| 2370 | 'This means the exception must be assigned to a different name to ' |
| 2371 | 'be\n' |
| 2372 | 'able to refer to it after the except clause. Exceptions are ' |
| 2373 | 'cleared\n' |
| 2374 | 'because with the traceback attached to them, they form a ' |
| 2375 | 'reference\n' |
| 2376 | 'cycle with the stack frame, keeping all locals in that frame ' |
| 2377 | 'alive\n' |
| 2378 | 'until the next garbage collection occurs.\n' |
| 2379 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2380 | 'Before an except clause’s suite is executed, details about the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2381 | 'exception are stored in the "sys" module and can be accessed ' |
| 2382 | 'via\n' |
| 2383 | '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' |
| 2384 | 'of the\n' |
| 2385 | 'exception class, the exception instance and a traceback object ' |
| 2386 | '(see\n' |
| 2387 | 'section The standard type hierarchy) identifying the point in ' |
| 2388 | 'the\n' |
| 2389 | 'program where the exception occurred. "sys.exc_info()" values ' |
| 2390 | 'are\n' |
| 2391 | 'restored to their previous values (before the call) when ' |
| 2392 | 'returning\n' |
| 2393 | 'from a function that handled an exception.\n' |
| 2394 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2395 | 'The optional "else" clause is executed if the control flow ' |
| 2396 | 'leaves the\n' |
| 2397 | '"try" suite, no exception was raised, and no "return", ' |
| 2398 | '"continue", or\n' |
| 2399 | '"break" statement was executed. Exceptions in the "else" clause ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2400 | 'are\n' |
| 2401 | 'not handled by the preceding "except" clauses.\n' |
| 2402 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2403 | 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' |
| 2404 | '"try"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2405 | 'clause is executed, including any "except" and "else" clauses. ' |
| 2406 | 'If an\n' |
| 2407 | 'exception occurs in any of the clauses and is not handled, the\n' |
| 2408 | 'exception is temporarily saved. The "finally" clause is ' |
| 2409 | 'executed. If\n' |
| 2410 | 'there is a saved exception it is re-raised at the end of the ' |
| 2411 | '"finally"\n' |
| 2412 | 'clause. If the "finally" clause raises another exception, the ' |
| 2413 | 'saved\n' |
| 2414 | 'exception is set as the context of the new exception. If the ' |
| 2415 | '"finally"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2416 | 'clause executes a "return", "break" or "continue" statement, the ' |
| 2417 | 'saved\n' |
| 2418 | 'exception is discarded:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2419 | '\n' |
| 2420 | ' >>> def f():\n' |
| 2421 | ' ... try:\n' |
| 2422 | ' ... 1/0\n' |
| 2423 | ' ... finally:\n' |
| 2424 | ' ... return 42\n' |
| 2425 | ' ...\n' |
| 2426 | ' >>> f()\n' |
| 2427 | ' 42\n' |
| 2428 | '\n' |
| 2429 | 'The exception information is not available to the program ' |
| 2430 | 'during\n' |
| 2431 | 'execution of the "finally" clause.\n' |
| 2432 | '\n' |
| 2433 | 'When a "return", "break" or "continue" statement is executed in ' |
| 2434 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2435 | '"try" suite of a "try"…"finally" statement, the "finally" clause ' |
| 2436 | 'is\n' |
| 2437 | 'also executed ‘on the way out.’\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2438 | '\n' |
| 2439 | 'The return value of a function is determined by the last ' |
| 2440 | '"return"\n' |
| 2441 | 'statement executed. Since the "finally" clause always executes, ' |
| 2442 | 'a\n' |
| 2443 | '"return" statement executed in the "finally" clause will always ' |
| 2444 | 'be the\n' |
| 2445 | 'last one executed:\n' |
| 2446 | '\n' |
| 2447 | ' >>> def foo():\n' |
| 2448 | ' ... try:\n' |
| 2449 | " ... return 'try'\n" |
| 2450 | ' ... finally:\n' |
| 2451 | " ... return 'finally'\n" |
| 2452 | ' ...\n' |
| 2453 | ' >>> foo()\n' |
| 2454 | " 'finally'\n" |
| 2455 | '\n' |
| 2456 | 'Additional information on exceptions can be found in section\n' |
| 2457 | 'Exceptions, and information on using the "raise" statement to ' |
| 2458 | 'generate\n' |
| 2459 | 'exceptions may be found in section The raise statement.\n' |
| 2460 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2461 | 'Changed in version 3.8: Prior to Python 3.8, a "continue" ' |
| 2462 | 'statement\n' |
| 2463 | 'was illegal in the "finally" clause due to a problem with the\n' |
| 2464 | 'implementation.\n' |
| 2465 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2466 | '\n' |
| 2467 | 'The "with" statement\n' |
| 2468 | '====================\n' |
| 2469 | '\n' |
| 2470 | 'The "with" statement is used to wrap the execution of a block ' |
| 2471 | 'with\n' |
| 2472 | 'methods defined by a context manager (see section With ' |
| 2473 | 'Statement\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2474 | 'Context Managers). This allows common "try"…"except"…"finally" ' |
| 2475 | 'usage\n' |
| 2476 | 'patterns to be encapsulated for convenient reuse.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2477 | '\n' |
| 2478 | ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' |
| 2479 | ' with_item ::= expression ["as" target]\n' |
| 2480 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2481 | 'The execution of the "with" statement with one “item” proceeds ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2482 | 'as\n' |
| 2483 | 'follows:\n' |
| 2484 | '\n' |
| 2485 | '1. The context expression (the expression given in the ' |
| 2486 | '"with_item")\n' |
| 2487 | ' is evaluated to obtain a context manager.\n' |
| 2488 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2489 | '2. The context manager’s "__exit__()" is loaded for later use.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2490 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2491 | '3. The context manager’s "__enter__()" method is invoked.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2492 | '\n' |
| 2493 | '4. If a target was included in the "with" statement, the return\n' |
| 2494 | ' value from "__enter__()" is assigned to it.\n' |
| 2495 | '\n' |
| 2496 | ' Note: The "with" statement guarantees that if the ' |
| 2497 | '"__enter__()"\n' |
| 2498 | ' method returns without an error, then "__exit__()" will ' |
| 2499 | 'always be\n' |
| 2500 | ' called. Thus, if an error occurs during the assignment to ' |
| 2501 | 'the\n' |
| 2502 | ' target list, it will be treated the same as an error ' |
| 2503 | 'occurring\n' |
| 2504 | ' within the suite would be. See step 6 below.\n' |
| 2505 | '\n' |
| 2506 | '5. The suite is executed.\n' |
| 2507 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2508 | '6. The context manager’s "__exit__()" method is invoked. If an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2509 | ' exception caused the suite to be exited, its type, value, ' |
| 2510 | 'and\n' |
| 2511 | ' traceback are passed as arguments to "__exit__()". Otherwise, ' |
| 2512 | 'three\n' |
| 2513 | ' "None" arguments are supplied.\n' |
| 2514 | '\n' |
| 2515 | ' If the suite was exited due to an exception, and the return ' |
| 2516 | 'value\n' |
| 2517 | ' from the "__exit__()" method was false, the exception is ' |
| 2518 | 'reraised.\n' |
| 2519 | ' If the return value was true, the exception is suppressed, ' |
| 2520 | 'and\n' |
| 2521 | ' execution continues with the statement following the "with"\n' |
| 2522 | ' statement.\n' |
| 2523 | '\n' |
| 2524 | ' If the suite was exited for any reason other than an ' |
| 2525 | 'exception, the\n' |
| 2526 | ' return value from "__exit__()" is ignored, and execution ' |
| 2527 | 'proceeds\n' |
| 2528 | ' at the normal location for the kind of exit that was taken.\n' |
| 2529 | '\n' |
| 2530 | 'With more than one item, the context managers are processed as ' |
| 2531 | 'if\n' |
| 2532 | 'multiple "with" statements were nested:\n' |
| 2533 | '\n' |
| 2534 | ' with A() as a, B() as b:\n' |
| 2535 | ' suite\n' |
| 2536 | '\n' |
| 2537 | 'is equivalent to\n' |
| 2538 | '\n' |
| 2539 | ' with A() as a:\n' |
| 2540 | ' with B() as b:\n' |
| 2541 | ' suite\n' |
| 2542 | '\n' |
| 2543 | 'Changed in version 3.1: Support for multiple context ' |
| 2544 | 'expressions.\n' |
| 2545 | '\n' |
| 2546 | 'See also:\n' |
| 2547 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2548 | ' **PEP 343** - The “with” statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2549 | ' The specification, background, and examples for the Python ' |
| 2550 | '"with"\n' |
| 2551 | ' statement.\n' |
| 2552 | '\n' |
| 2553 | '\n' |
| 2554 | 'Function definitions\n' |
| 2555 | '====================\n' |
| 2556 | '\n' |
| 2557 | 'A function definition defines a user-defined function object ' |
| 2558 | '(see\n' |
| 2559 | 'section The standard type hierarchy):\n' |
| 2560 | '\n' |
| 2561 | ' funcdef ::= [decorators] "def" funcname "(" ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2562 | '[parameter_list] ")"\n' |
| 2563 | ' ["->" expression] ":" suite\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2564 | ' decorators ::= decorator+\n' |
| 2565 | ' decorator ::= "@" dotted_name ["(" ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 2566 | '[argument_list [","]] ")"] NEWLINE\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2567 | ' dotted_name ::= identifier ("." identifier)*\n' |
| 2568 | ' parameter_list ::= defparameter ("," defparameter)* ' |
| 2569 | '["," [parameter_list_starargs]]\n' |
| 2570 | ' | parameter_list_starargs\n' |
| 2571 | ' parameter_list_starargs ::= "*" [parameter] ("," ' |
| 2572 | 'defparameter)* ["," ["**" parameter [","]]]\n' |
| 2573 | ' | "**" parameter [","]\n' |
| 2574 | ' parameter ::= identifier [":" expression]\n' |
| 2575 | ' defparameter ::= parameter ["=" expression]\n' |
| 2576 | ' funcname ::= identifier\n' |
| 2577 | '\n' |
| 2578 | 'A function definition is an executable statement. Its execution ' |
| 2579 | 'binds\n' |
| 2580 | 'the function name in the current local namespace to a function ' |
| 2581 | 'object\n' |
| 2582 | '(a wrapper around the executable code for the function). This\n' |
| 2583 | 'function object contains a reference to the current global ' |
| 2584 | 'namespace\n' |
| 2585 | 'as the global namespace to be used when the function is called.\n' |
| 2586 | '\n' |
| 2587 | 'The function definition does not execute the function body; this ' |
| 2588 | 'gets\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2589 | 'executed only when the function is called. [2]\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2590 | '\n' |
| 2591 | 'A function definition may be wrapped by one or more *decorator*\n' |
| 2592 | 'expressions. Decorator expressions are evaluated when the ' |
| 2593 | 'function is\n' |
| 2594 | 'defined, in the scope that contains the function definition. ' |
| 2595 | 'The\n' |
| 2596 | 'result must be a callable, which is invoked with the function ' |
| 2597 | 'object\n' |
| 2598 | 'as the only argument. The returned value is bound to the ' |
| 2599 | 'function name\n' |
| 2600 | 'instead of the function object. Multiple decorators are applied ' |
| 2601 | 'in\n' |
| 2602 | 'nested fashion. For example, the following code\n' |
| 2603 | '\n' |
| 2604 | ' @f1(arg)\n' |
| 2605 | ' @f2\n' |
| 2606 | ' def func(): pass\n' |
| 2607 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2608 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2609 | '\n' |
| 2610 | ' def func(): pass\n' |
| 2611 | ' func = f1(arg)(f2(func))\n' |
| 2612 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2613 | 'except that the original function is not temporarily bound to ' |
| 2614 | 'the name\n' |
| 2615 | '"func".\n' |
| 2616 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2617 | 'When one or more *parameters* have the form *parameter* "="\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2618 | '*expression*, the function is said to have “default parameter ' |
| 2619 | 'values.”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2620 | 'For a parameter with a default value, the corresponding ' |
| 2621 | '*argument* may\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2622 | 'be omitted from a call, in which case the parameter’s default ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2623 | 'value is\n' |
| 2624 | 'substituted. If a parameter has a default value, all following\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2625 | 'parameters up until the “"*"” must also have a default value — ' |
| 2626 | 'this is\n' |
| 2627 | 'a syntactic restriction that is not expressed by the grammar.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2628 | '\n' |
| 2629 | '**Default parameter values are evaluated from left to right when ' |
| 2630 | 'the\n' |
| 2631 | 'function definition is executed.** This means that the ' |
| 2632 | 'expression is\n' |
| 2633 | 'evaluated once, when the function is defined, and that the same ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2634 | '“pre-\n' |
| 2635 | 'computed” value is used for each call. This is especially ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2636 | 'important\n' |
| 2637 | 'to understand when a default parameter is a mutable object, such ' |
| 2638 | 'as a\n' |
| 2639 | 'list or a dictionary: if the function modifies the object (e.g. ' |
| 2640 | 'by\n' |
| 2641 | 'appending an item to a list), the default value is in effect ' |
| 2642 | 'modified.\n' |
| 2643 | 'This is generally not what was intended. A way around this is ' |
| 2644 | 'to use\n' |
| 2645 | '"None" as the default, and explicitly test for it in the body of ' |
| 2646 | 'the\n' |
| 2647 | 'function, e.g.:\n' |
| 2648 | '\n' |
| 2649 | ' def whats_on_the_telly(penguin=None):\n' |
| 2650 | ' if penguin is None:\n' |
| 2651 | ' penguin = []\n' |
| 2652 | ' penguin.append("property of the zoo")\n' |
| 2653 | ' return penguin\n' |
| 2654 | '\n' |
| 2655 | 'Function call semantics are described in more detail in section ' |
| 2656 | 'Calls.\n' |
| 2657 | 'A function call always assigns values to all parameters ' |
| 2658 | 'mentioned in\n' |
| 2659 | 'the parameter list, either from position arguments, from ' |
| 2660 | 'keyword\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2661 | 'arguments, or from default values. If the form “"*identifier"” ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2662 | 'is\n' |
| 2663 | 'present, it is initialized to a tuple receiving any excess ' |
| 2664 | 'positional\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2665 | 'parameters, defaulting to the empty tuple. If the form\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2666 | '“"**identifier"” is present, it is initialized to a new ordered\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2667 | 'mapping receiving any excess keyword arguments, defaulting to a ' |
| 2668 | 'new\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2669 | 'empty mapping of the same type. Parameters after “"*"” or\n' |
| 2670 | '“"*identifier"” are keyword-only parameters and may only be ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2671 | 'passed\n' |
| 2672 | 'used keyword arguments.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2673 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2674 | 'Parameters may have an *annotation* of the form “": ' |
| 2675 | 'expression"”\n' |
| 2676 | 'following the parameter name. Any parameter may have an ' |
| 2677 | 'annotation,\n' |
| 2678 | 'even those of the form "*identifier" or "**identifier". ' |
| 2679 | 'Functions may\n' |
| 2680 | 'have “return” annotation of the form “"-> expression"” after ' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 2681 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2682 | 'parameter list. These annotations can be any valid Python ' |
| 2683 | 'expression.\n' |
| 2684 | 'The presence of annotations does not change the semantics of a\n' |
| 2685 | 'function. The annotation values are available as values of a\n' |
| 2686 | 'dictionary keyed by the parameters’ names in the ' |
| 2687 | '"__annotations__"\n' |
| 2688 | 'attribute of the function object. If the "annotations" import ' |
| 2689 | 'from\n' |
| 2690 | '"__future__" is used, annotations are preserved as strings at ' |
| 2691 | 'runtime\n' |
| 2692 | 'which enables postponed evaluation. Otherwise, they are ' |
| 2693 | 'evaluated\n' |
| 2694 | 'when the function definition is executed. In this case ' |
| 2695 | 'annotations\n' |
| 2696 | 'may be evaluated in a different order than they appear in the ' |
| 2697 | 'source\n' |
| 2698 | 'code.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2699 | '\n' |
| 2700 | 'It is also possible to create anonymous functions (functions not ' |
| 2701 | 'bound\n' |
| 2702 | 'to a name), for immediate use in expressions. This uses lambda\n' |
| 2703 | 'expressions, described in section Lambdas. Note that the ' |
| 2704 | 'lambda\n' |
| 2705 | 'expression is merely a shorthand for a simplified function ' |
| 2706 | 'definition;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2707 | 'a function defined in a “"def"” statement can be passed around ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2708 | 'or\n' |
| 2709 | 'assigned to another name just like a function defined by a ' |
| 2710 | 'lambda\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2711 | 'expression. The “"def"” form is actually more powerful since ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2712 | 'it\n' |
| 2713 | 'allows the execution of multiple statements and annotations.\n' |
| 2714 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2715 | '**Programmer’s note:** Functions are first-class objects. A ' |
| 2716 | '“"def"”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2717 | 'statement executed inside a function definition defines a local\n' |
| 2718 | 'function that can be returned or passed around. Free variables ' |
| 2719 | 'used\n' |
| 2720 | 'in the nested function can access the local variables of the ' |
| 2721 | 'function\n' |
| 2722 | 'containing the def. See section Naming and binding for ' |
| 2723 | 'details.\n' |
| 2724 | '\n' |
| 2725 | 'See also:\n' |
| 2726 | '\n' |
| 2727 | ' **PEP 3107** - Function Annotations\n' |
| 2728 | ' The original specification for function annotations.\n' |
| 2729 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 2730 | ' **PEP 484** - Type Hints\n' |
| 2731 | ' Definition of a standard meaning for annotations: type ' |
| 2732 | 'hints.\n' |
| 2733 | '\n' |
| 2734 | ' **PEP 526** - Syntax for Variable Annotations\n' |
| 2735 | ' Ability to type hint variable declarations, including ' |
| 2736 | 'class\n' |
| 2737 | ' variables and instance variables\n' |
| 2738 | '\n' |
| 2739 | ' **PEP 563** - Postponed Evaluation of Annotations\n' |
| 2740 | ' Support for forward references within annotations by ' |
| 2741 | 'preserving\n' |
| 2742 | ' annotations in a string form at runtime instead of eager\n' |
| 2743 | ' evaluation.\n' |
| 2744 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2745 | '\n' |
| 2746 | 'Class definitions\n' |
| 2747 | '=================\n' |
| 2748 | '\n' |
| 2749 | 'A class definition defines a class object (see section The ' |
| 2750 | 'standard\n' |
| 2751 | 'type hierarchy):\n' |
| 2752 | '\n' |
| 2753 | ' classdef ::= [decorators] "class" classname [inheritance] ' |
| 2754 | '":" suite\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 2755 | ' inheritance ::= "(" [argument_list] ")"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2756 | ' classname ::= identifier\n' |
| 2757 | '\n' |
| 2758 | 'A class definition is an executable statement. The inheritance ' |
| 2759 | 'list\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2760 | 'usually gives a list of base classes (see Metaclasses for more\n' |
| 2761 | 'advanced uses), so each item in the list should evaluate to a ' |
| 2762 | 'class\n' |
| 2763 | 'object which allows subclassing. Classes without an inheritance ' |
| 2764 | 'list\n' |
| 2765 | 'inherit, by default, from the base class "object"; hence,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2766 | '\n' |
| 2767 | ' class Foo:\n' |
| 2768 | ' pass\n' |
| 2769 | '\n' |
| 2770 | 'is equivalent to\n' |
| 2771 | '\n' |
| 2772 | ' class Foo(object):\n' |
| 2773 | ' pass\n' |
| 2774 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2775 | 'The class’s suite is then executed in a new execution frame ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2776 | '(see\n' |
| 2777 | 'Naming and binding), using a newly created local namespace and ' |
| 2778 | 'the\n' |
| 2779 | 'original global namespace. (Usually, the suite contains mostly\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2780 | 'function definitions.) When the class’s suite finishes ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2781 | 'execution, its\n' |
| 2782 | 'execution frame is discarded but its local namespace is saved. ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2783 | '[3] A\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2784 | 'class object is then created using the inheritance list for the ' |
| 2785 | 'base\n' |
| 2786 | 'classes and the saved local namespace for the attribute ' |
| 2787 | 'dictionary.\n' |
| 2788 | 'The class name is bound to this class object in the original ' |
| 2789 | 'local\n' |
| 2790 | 'namespace.\n' |
| 2791 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2792 | 'The order in which attributes are defined in the class body is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2793 | 'preserved in the new class’s "__dict__". Note that this is ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2794 | 'reliable\n' |
| 2795 | 'only right after the class is created and only for classes that ' |
| 2796 | 'were\n' |
| 2797 | 'defined using the definition syntax.\n' |
| 2798 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2799 | 'Class creation can be customized heavily using metaclasses.\n' |
| 2800 | '\n' |
| 2801 | 'Classes can also be decorated: just like when decorating ' |
| 2802 | 'functions,\n' |
| 2803 | '\n' |
| 2804 | ' @f1(arg)\n' |
| 2805 | ' @f2\n' |
| 2806 | ' class Foo: pass\n' |
| 2807 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2808 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2809 | '\n' |
| 2810 | ' class Foo: pass\n' |
| 2811 | ' Foo = f1(arg)(f2(Foo))\n' |
| 2812 | '\n' |
| 2813 | 'The evaluation rules for the decorator expressions are the same ' |
| 2814 | 'as for\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2815 | 'function decorators. The result is then bound to the class ' |
| 2816 | 'name.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2817 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2818 | '**Programmer’s note:** Variables defined in the class definition ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2819 | 'are\n' |
| 2820 | 'class attributes; they are shared by instances. Instance ' |
| 2821 | 'attributes\n' |
| 2822 | 'can be set in a method with "self.name = value". Both class ' |
| 2823 | 'and\n' |
| 2824 | 'instance attributes are accessible through the notation ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2825 | '“"self.name"”,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2826 | 'and an instance attribute hides a class attribute with the same ' |
| 2827 | 'name\n' |
| 2828 | 'when accessed in this way. Class attributes can be used as ' |
| 2829 | 'defaults\n' |
| 2830 | 'for instance attributes, but using mutable values there can lead ' |
| 2831 | 'to\n' |
| 2832 | 'unexpected results. Descriptors can be used to create instance\n' |
| 2833 | 'variables with different implementation details.\n' |
| 2834 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2835 | 'See also:\n' |
| 2836 | '\n' |
| 2837 | ' **PEP 3115** - Metaclasses in Python 3000\n' |
| 2838 | ' The proposal that changed the declaration of metaclasses to ' |
| 2839 | 'the\n' |
| 2840 | ' current syntax, and the semantics for how classes with\n' |
| 2841 | ' metaclasses are constructed.\n' |
| 2842 | '\n' |
| 2843 | ' **PEP 3129** - Class Decorators\n' |
| 2844 | ' The proposal that added class decorators. Function and ' |
| 2845 | 'method\n' |
| 2846 | ' decorators were introduced in **PEP 318**.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2847 | '\n' |
| 2848 | '\n' |
| 2849 | 'Coroutines\n' |
| 2850 | '==========\n' |
| 2851 | '\n' |
| 2852 | 'New in version 3.5.\n' |
| 2853 | '\n' |
| 2854 | '\n' |
| 2855 | 'Coroutine function definition\n' |
| 2856 | '-----------------------------\n' |
| 2857 | '\n' |
| 2858 | ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2859 | '[parameter_list] ")"\n' |
| 2860 | ' ["->" expression] ":" suite\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2861 | '\n' |
| 2862 | 'Execution of Python coroutines can be suspended and resumed at ' |
| 2863 | 'many\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2864 | 'points (see *coroutine*). Inside the body of a coroutine ' |
| 2865 | 'function,\n' |
| 2866 | '"await" and "async" identifiers become reserved keywords; ' |
| 2867 | '"await"\n' |
| 2868 | 'expressions, "async for" and "async with" can only be used in\n' |
| 2869 | 'coroutine function bodies.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2870 | '\n' |
| 2871 | 'Functions defined with "async def" syntax are always coroutine\n' |
| 2872 | 'functions, even if they do not contain "await" or "async" ' |
| 2873 | 'keywords.\n' |
| 2874 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2875 | 'It is a "SyntaxError" to use a "yield from" expression inside ' |
| 2876 | 'the body\n' |
| 2877 | 'of a coroutine function.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2878 | '\n' |
| 2879 | 'An example of a coroutine function:\n' |
| 2880 | '\n' |
| 2881 | ' async def func(param1, param2):\n' |
| 2882 | ' do_stuff()\n' |
| 2883 | ' await some_coroutine()\n' |
| 2884 | '\n' |
| 2885 | '\n' |
| 2886 | 'The "async for" statement\n' |
| 2887 | '-------------------------\n' |
| 2888 | '\n' |
| 2889 | ' async_for_stmt ::= "async" for_stmt\n' |
| 2890 | '\n' |
| 2891 | 'An *asynchronous iterable* is able to call asynchronous code in ' |
| 2892 | 'its\n' |
| 2893 | '*iter* implementation, and *asynchronous iterator* can call\n' |
| 2894 | 'asynchronous code in its *next* method.\n' |
| 2895 | '\n' |
| 2896 | 'The "async for" statement allows convenient iteration over\n' |
| 2897 | 'asynchronous iterators.\n' |
| 2898 | '\n' |
| 2899 | 'The following code:\n' |
| 2900 | '\n' |
| 2901 | ' async for TARGET in ITER:\n' |
| 2902 | ' BLOCK\n' |
| 2903 | ' else:\n' |
| 2904 | ' BLOCK2\n' |
| 2905 | '\n' |
| 2906 | 'Is semantically equivalent to:\n' |
| 2907 | '\n' |
| 2908 | ' iter = (ITER)\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 2909 | ' iter = type(iter).__aiter__(iter)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2910 | ' running = True\n' |
| 2911 | ' while running:\n' |
| 2912 | ' try:\n' |
| 2913 | ' TARGET = await type(iter).__anext__(iter)\n' |
| 2914 | ' except StopAsyncIteration:\n' |
| 2915 | ' running = False\n' |
| 2916 | ' else:\n' |
| 2917 | ' BLOCK\n' |
| 2918 | ' else:\n' |
| 2919 | ' BLOCK2\n' |
| 2920 | '\n' |
| 2921 | 'See also "__aiter__()" and "__anext__()" for details.\n' |
| 2922 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2923 | 'It is a "SyntaxError" to use an "async for" statement outside ' |
| 2924 | 'the body\n' |
| 2925 | 'of a coroutine function.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2926 | '\n' |
| 2927 | '\n' |
| 2928 | 'The "async with" statement\n' |
| 2929 | '--------------------------\n' |
| 2930 | '\n' |
| 2931 | ' async_with_stmt ::= "async" with_stmt\n' |
| 2932 | '\n' |
| 2933 | 'An *asynchronous context manager* is a *context manager* that is ' |
| 2934 | 'able\n' |
| 2935 | 'to suspend execution in its *enter* and *exit* methods.\n' |
| 2936 | '\n' |
| 2937 | 'The following code:\n' |
| 2938 | '\n' |
| 2939 | ' async with EXPR as VAR:\n' |
| 2940 | ' BLOCK\n' |
| 2941 | '\n' |
| 2942 | 'Is semantically equivalent to:\n' |
| 2943 | '\n' |
| 2944 | ' mgr = (EXPR)\n' |
| 2945 | ' aexit = type(mgr).__aexit__\n' |
| 2946 | ' aenter = type(mgr).__aenter__(mgr)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2947 | '\n' |
| 2948 | ' VAR = await aenter\n' |
| 2949 | ' try:\n' |
| 2950 | ' BLOCK\n' |
| 2951 | ' except:\n' |
| 2952 | ' if not await aexit(mgr, *sys.exc_info()):\n' |
| 2953 | ' raise\n' |
| 2954 | ' else:\n' |
| 2955 | ' await aexit(mgr, None, None, None)\n' |
| 2956 | '\n' |
| 2957 | 'See also "__aenter__()" and "__aexit__()" for details.\n' |
| 2958 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2959 | 'It is a "SyntaxError" to use an "async with" statement outside ' |
| 2960 | 'the\n' |
| 2961 | 'body of a coroutine function.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2962 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2963 | 'See also:\n' |
| 2964 | '\n' |
| 2965 | ' **PEP 492** - Coroutines with async and await syntax\n' |
| 2966 | ' The proposal that made coroutines a proper standalone ' |
| 2967 | 'concept in\n' |
| 2968 | ' Python, and added supporting syntax.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2969 | '\n' |
| 2970 | '-[ Footnotes ]-\n' |
| 2971 | '\n' |
| 2972 | '[1] The exception is propagated to the invocation stack unless\n' |
| 2973 | ' there is a "finally" clause which happens to raise another\n' |
| 2974 | ' exception. That new exception causes the old one to be ' |
| 2975 | 'lost.\n' |
| 2976 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2977 | '[2] A string literal appearing as the first statement in the\n' |
| 2978 | ' function body is transformed into the function’s "__doc__"\n' |
| 2979 | ' attribute and therefore the function’s *docstring*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2980 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2981 | '[3] A string literal appearing as the first statement in the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2982 | 'class\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 2983 | ' body is transformed into the namespace’s "__doc__" item and\n' |
| 2984 | ' therefore the class’s *docstring*.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2985 | 'context-managers': 'With Statement Context Managers\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2986 | '*******************************\n' |
| 2987 | '\n' |
| 2988 | 'A *context manager* is an object that defines the ' |
| 2989 | 'runtime context to\n' |
| 2990 | 'be established when executing a "with" statement. The ' |
| 2991 | 'context manager\n' |
| 2992 | 'handles the entry into, and the exit from, the desired ' |
| 2993 | 'runtime context\n' |
| 2994 | 'for the execution of the block of code. Context ' |
| 2995 | 'managers are normally\n' |
| 2996 | 'invoked using the "with" statement (described in section ' |
| 2997 | 'The with\n' |
| 2998 | 'statement), but can also be used by directly invoking ' |
| 2999 | 'their methods.\n' |
| 3000 | '\n' |
| 3001 | 'Typical uses of context managers include saving and ' |
| 3002 | 'restoring various\n' |
| 3003 | 'kinds of global state, locking and unlocking resources, ' |
| 3004 | 'closing opened\n' |
| 3005 | 'files, etc.\n' |
| 3006 | '\n' |
| 3007 | 'For more information on context managers, see Context ' |
| 3008 | 'Manager Types.\n' |
| 3009 | '\n' |
| 3010 | 'object.__enter__(self)\n' |
| 3011 | '\n' |
| 3012 | ' Enter the runtime context related to this object. The ' |
| 3013 | '"with"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3014 | ' statement will bind this method’s return value to the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3015 | 'target(s)\n' |
| 3016 | ' specified in the "as" clause of the statement, if ' |
| 3017 | 'any.\n' |
| 3018 | '\n' |
| 3019 | 'object.__exit__(self, exc_type, exc_value, traceback)\n' |
| 3020 | '\n' |
| 3021 | ' Exit the runtime context related to this object. The ' |
| 3022 | 'parameters\n' |
| 3023 | ' describe the exception that caused the context to be ' |
| 3024 | 'exited. If the\n' |
| 3025 | ' context was exited without an exception, all three ' |
| 3026 | 'arguments will\n' |
| 3027 | ' be "None".\n' |
| 3028 | '\n' |
| 3029 | ' If an exception is supplied, and the method wishes to ' |
| 3030 | 'suppress the\n' |
| 3031 | ' exception (i.e., prevent it from being propagated), ' |
| 3032 | 'it should\n' |
| 3033 | ' return a true value. Otherwise, the exception will be ' |
| 3034 | 'processed\n' |
| 3035 | ' normally upon exit from this method.\n' |
| 3036 | '\n' |
| 3037 | ' Note that "__exit__()" methods should not reraise the ' |
| 3038 | 'passed-in\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3039 | ' exception; this is the caller’s responsibility.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3040 | '\n' |
| 3041 | 'See also:\n' |
| 3042 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3043 | ' **PEP 343** - The “with” statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3044 | ' The specification, background, and examples for the ' |
| 3045 | 'Python "with"\n' |
| 3046 | ' statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3047 | 'continue': 'The "continue" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3048 | '************************\n' |
| 3049 | '\n' |
| 3050 | ' continue_stmt ::= "continue"\n' |
| 3051 | '\n' |
| 3052 | '"continue" may only occur syntactically nested in a "for" or ' |
| 3053 | '"while"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3054 | 'loop, but not nested in a function or class definition within ' |
| 3055 | 'that\n' |
| 3056 | 'loop. It continues with the next cycle of the nearest enclosing ' |
| 3057 | 'loop.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3058 | '\n' |
| 3059 | 'When "continue" passes control out of a "try" statement with a\n' |
| 3060 | '"finally" clause, that "finally" clause is executed before ' |
| 3061 | 'really\n' |
| 3062 | 'starting the next loop cycle.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3063 | 'conversions': 'Arithmetic conversions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3064 | '**********************\n' |
| 3065 | '\n' |
| 3066 | 'When a description of an arithmetic operator below uses the ' |
| 3067 | 'phrase\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3068 | '“the numeric arguments are converted to a common type,” this ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3069 | 'means\n' |
| 3070 | 'that the operator implementation for built-in types works as ' |
| 3071 | 'follows:\n' |
| 3072 | '\n' |
| 3073 | '* If either argument is a complex number, the other is ' |
| 3074 | 'converted to\n' |
| 3075 | ' complex;\n' |
| 3076 | '\n' |
| 3077 | '* otherwise, if either argument is a floating point number, ' |
| 3078 | 'the\n' |
| 3079 | ' other is converted to floating point;\n' |
| 3080 | '\n' |
| 3081 | '* otherwise, both must be integers and no conversion is ' |
| 3082 | 'necessary.\n' |
| 3083 | '\n' |
| 3084 | 'Some additional rules apply for certain operators (e.g., a ' |
| 3085 | 'string as a\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3086 | 'left argument to the ‘%’ operator). Extensions must define ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3087 | 'their own\n' |
| 3088 | 'conversion behavior.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3089 | 'customization': 'Basic customization\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3090 | '*******************\n' |
| 3091 | '\n' |
| 3092 | 'object.__new__(cls[, ...])\n' |
| 3093 | '\n' |
| 3094 | ' Called to create a new instance of class *cls*. ' |
| 3095 | '"__new__()" is a\n' |
| 3096 | ' static method (special-cased so you need not declare it ' |
| 3097 | 'as such)\n' |
| 3098 | ' that takes the class of which an instance was requested ' |
| 3099 | 'as its\n' |
| 3100 | ' first argument. The remaining arguments are those ' |
| 3101 | 'passed to the\n' |
| 3102 | ' object constructor expression (the call to the class). ' |
| 3103 | 'The return\n' |
| 3104 | ' value of "__new__()" should be the new object instance ' |
| 3105 | '(usually an\n' |
| 3106 | ' instance of *cls*).\n' |
| 3107 | '\n' |
| 3108 | ' Typical implementations create a new instance of the ' |
| 3109 | 'class by\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3110 | ' invoking the superclass’s "__new__()" method using\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3111 | ' "super().__new__(cls[, ...])" with appropriate arguments ' |
| 3112 | 'and then\n' |
| 3113 | ' modifying the newly-created instance as necessary before ' |
| 3114 | 'returning\n' |
| 3115 | ' it.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3116 | '\n' |
| 3117 | ' If "__new__()" returns an instance of *cls*, then the ' |
| 3118 | 'new\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3119 | ' instance’s "__init__()" method will be invoked like\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3120 | ' "__init__(self[, ...])", where *self* is the new ' |
| 3121 | 'instance and the\n' |
| 3122 | ' remaining arguments are the same as were passed to ' |
| 3123 | '"__new__()".\n' |
| 3124 | '\n' |
| 3125 | ' If "__new__()" does not return an instance of *cls*, ' |
| 3126 | 'then the new\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3127 | ' instance’s "__init__()" method will not be invoked.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3128 | '\n' |
| 3129 | ' "__new__()" is intended mainly to allow subclasses of ' |
| 3130 | 'immutable\n' |
| 3131 | ' types (like int, str, or tuple) to customize instance ' |
| 3132 | 'creation. It\n' |
| 3133 | ' is also commonly overridden in custom metaclasses in ' |
| 3134 | 'order to\n' |
| 3135 | ' customize class creation.\n' |
| 3136 | '\n' |
| 3137 | 'object.__init__(self[, ...])\n' |
| 3138 | '\n' |
| 3139 | ' Called after the instance has been created (by ' |
| 3140 | '"__new__()"), but\n' |
| 3141 | ' before it is returned to the caller. The arguments are ' |
| 3142 | 'those\n' |
| 3143 | ' passed to the class constructor expression. If a base ' |
| 3144 | 'class has an\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3145 | ' "__init__()" method, the derived class’s "__init__()" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3146 | 'method, if\n' |
| 3147 | ' any, must explicitly call it to ensure proper ' |
| 3148 | 'initialization of the\n' |
| 3149 | ' base class part of the instance; for example:\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3150 | ' "super().__init__([args...])".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3151 | '\n' |
| 3152 | ' Because "__new__()" and "__init__()" work together in ' |
| 3153 | 'constructing\n' |
| 3154 | ' objects ("__new__()" to create it, and "__init__()" to ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3155 | 'customize\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3156 | ' it), no non-"None" value may be returned by ' |
| 3157 | '"__init__()"; doing so\n' |
| 3158 | ' will cause a "TypeError" to be raised at runtime.\n' |
| 3159 | '\n' |
| 3160 | 'object.__del__(self)\n' |
| 3161 | '\n' |
| 3162 | ' Called when the instance is about to be destroyed. This ' |
| 3163 | 'is also\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3164 | ' called a finalizer or (improperly) a destructor. If a ' |
| 3165 | 'base class\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3166 | ' has a "__del__()" method, the derived class’s ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3167 | '"__del__()" method,\n' |
| 3168 | ' if any, must explicitly call it to ensure proper ' |
| 3169 | 'deletion of the\n' |
| 3170 | ' base class part of the instance.\n' |
| 3171 | '\n' |
| 3172 | ' It is possible (though not recommended!) for the ' |
| 3173 | '"__del__()" method\n' |
| 3174 | ' to postpone destruction of the instance by creating a ' |
| 3175 | 'new reference\n' |
| 3176 | ' to it. This is called object *resurrection*. It is\n' |
| 3177 | ' implementation-dependent whether "__del__()" is called a ' |
| 3178 | 'second\n' |
| 3179 | ' time when a resurrected object is about to be destroyed; ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3180 | 'the\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3181 | ' current *CPython* implementation only calls it once.\n' |
| 3182 | '\n' |
| 3183 | ' It is not guaranteed that "__del__()" methods are called ' |
| 3184 | 'for\n' |
| 3185 | ' objects that still exist when the interpreter exits.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3186 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3187 | ' Note: "del x" doesn’t directly call "x.__del__()" — the ' |
| 3188 | 'former\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3189 | ' decrements the reference count for "x" by one, and the ' |
| 3190 | 'latter is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3191 | ' only called when "x"’s reference count reaches zero.\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3192 | '\n' |
| 3193 | ' **CPython implementation detail:** It is possible for a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3194 | 'reference\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3195 | ' cycle to prevent the reference count of an object from ' |
| 3196 | 'going to\n' |
| 3197 | ' zero. In this case, the cycle will be later detected ' |
| 3198 | 'and deleted\n' |
| 3199 | ' by the *cyclic garbage collector*. A common cause of ' |
| 3200 | 'reference\n' |
| 3201 | ' cycles is when an exception has been caught in a local ' |
| 3202 | 'variable.\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3203 | ' The frame’s locals then reference the exception, which ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3204 | 'references\n' |
| 3205 | ' its own traceback, which references the locals of all ' |
| 3206 | 'frames caught\n' |
| 3207 | ' in the traceback.\n' |
| 3208 | '\n' |
| 3209 | ' See also: Documentation for the "gc" module.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3210 | '\n' |
| 3211 | ' Warning: Due to the precarious circumstances under ' |
| 3212 | 'which\n' |
| 3213 | ' "__del__()" methods are invoked, exceptions that occur ' |
| 3214 | 'during\n' |
| 3215 | ' their execution are ignored, and a warning is printed ' |
| 3216 | 'to\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3217 | ' "sys.stderr" instead. In particular:\n' |
| 3218 | '\n' |
| 3219 | ' * "__del__()" can be invoked when arbitrary code is ' |
| 3220 | 'being\n' |
| 3221 | ' executed, including from any arbitrary thread. If ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3222 | '"__del__()"\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3223 | ' needs to take a lock or invoke any other blocking ' |
| 3224 | 'resource, it\n' |
| 3225 | ' may deadlock as the resource may already be taken by ' |
| 3226 | 'the code\n' |
| 3227 | ' that gets interrupted to execute "__del__()".\n' |
| 3228 | '\n' |
| 3229 | ' * "__del__()" can be executed during interpreter ' |
| 3230 | 'shutdown. As\n' |
| 3231 | ' a consequence, the global variables it needs to ' |
| 3232 | 'access\n' |
| 3233 | ' (including other modules) may already have been ' |
| 3234 | 'deleted or set\n' |
| 3235 | ' to "None". Python guarantees that globals whose name ' |
| 3236 | 'begins\n' |
| 3237 | ' with a single underscore are deleted from their ' |
| 3238 | 'module before\n' |
| 3239 | ' other globals are deleted; if no other references to ' |
| 3240 | 'such\n' |
| 3241 | ' globals exist, this may help in assuring that ' |
| 3242 | 'imported modules\n' |
| 3243 | ' are still available at the time when the "__del__()" ' |
| 3244 | 'method is\n' |
| 3245 | ' called.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3246 | '\n' |
| 3247 | 'object.__repr__(self)\n' |
| 3248 | '\n' |
| 3249 | ' Called by the "repr()" built-in function to compute the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3250 | '“official”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3251 | ' string representation of an object. If at all possible, ' |
| 3252 | 'this\n' |
| 3253 | ' should look like a valid Python expression that could be ' |
| 3254 | 'used to\n' |
| 3255 | ' recreate an object with the same value (given an ' |
| 3256 | 'appropriate\n' |
| 3257 | ' environment). If this is not possible, a string of the ' |
| 3258 | 'form\n' |
| 3259 | ' "<...some useful description...>" should be returned. ' |
| 3260 | 'The return\n' |
| 3261 | ' value must be a string object. If a class defines ' |
| 3262 | '"__repr__()" but\n' |
| 3263 | ' not "__str__()", then "__repr__()" is also used when an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3264 | '“informal”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3265 | ' string representation of instances of that class is ' |
| 3266 | 'required.\n' |
| 3267 | '\n' |
| 3268 | ' This is typically used for debugging, so it is important ' |
| 3269 | 'that the\n' |
| 3270 | ' representation is information-rich and unambiguous.\n' |
| 3271 | '\n' |
| 3272 | 'object.__str__(self)\n' |
| 3273 | '\n' |
| 3274 | ' Called by "str(object)" and the built-in functions ' |
| 3275 | '"format()" and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3276 | ' "print()" to compute the “informal” or nicely printable ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3277 | 'string\n' |
| 3278 | ' representation of an object. The return value must be a ' |
| 3279 | 'string\n' |
| 3280 | ' object.\n' |
| 3281 | '\n' |
| 3282 | ' This method differs from "object.__repr__()" in that ' |
| 3283 | 'there is no\n' |
| 3284 | ' expectation that "__str__()" return a valid Python ' |
| 3285 | 'expression: a\n' |
| 3286 | ' more convenient or concise representation can be used.\n' |
| 3287 | '\n' |
| 3288 | ' The default implementation defined by the built-in type ' |
| 3289 | '"object"\n' |
| 3290 | ' calls "object.__repr__()".\n' |
| 3291 | '\n' |
| 3292 | 'object.__bytes__(self)\n' |
| 3293 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3294 | ' Called by bytes to compute a byte-string representation ' |
| 3295 | 'of an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3296 | ' object. This should return a "bytes" object.\n' |
| 3297 | '\n' |
| 3298 | 'object.__format__(self, format_spec)\n' |
| 3299 | '\n' |
| 3300 | ' Called by the "format()" built-in function, and by ' |
| 3301 | 'extension,\n' |
| 3302 | ' evaluation of formatted string literals and the ' |
| 3303 | '"str.format()"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3304 | ' method, to produce a “formatted” string representation ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3305 | 'of an\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 3306 | ' object. The *format_spec* argument is a string that ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3307 | 'contains a\n' |
| 3308 | ' description of the formatting options desired. The ' |
| 3309 | 'interpretation\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 3310 | ' of the *format_spec* argument is up to the type ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3311 | 'implementing\n' |
| 3312 | ' "__format__()", however most classes will either ' |
| 3313 | 'delegate\n' |
| 3314 | ' formatting to one of the built-in types, or use a ' |
| 3315 | 'similar\n' |
| 3316 | ' formatting option syntax.\n' |
| 3317 | '\n' |
| 3318 | ' See Format Specification Mini-Language for a description ' |
| 3319 | 'of the\n' |
| 3320 | ' standard formatting syntax.\n' |
| 3321 | '\n' |
| 3322 | ' The return value must be a string object.\n' |
| 3323 | '\n' |
| 3324 | ' Changed in version 3.4: The __format__ method of ' |
| 3325 | '"object" itself\n' |
| 3326 | ' raises a "TypeError" if passed any non-empty string.\n' |
| 3327 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3328 | ' Changed in version 3.7: "object.__format__(x, \'\')" is ' |
| 3329 | 'now\n' |
| 3330 | ' equivalent to "str(x)" rather than "format(str(self), ' |
| 3331 | '\'\')".\n' |
| 3332 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3333 | 'object.__lt__(self, other)\n' |
| 3334 | 'object.__le__(self, other)\n' |
| 3335 | 'object.__eq__(self, other)\n' |
| 3336 | 'object.__ne__(self, other)\n' |
| 3337 | 'object.__gt__(self, other)\n' |
| 3338 | 'object.__ge__(self, other)\n' |
| 3339 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3340 | ' These are the so-called “rich comparison” methods. The\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3341 | ' correspondence between operator symbols and method names ' |
| 3342 | 'is as\n' |
| 3343 | ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' |
| 3344 | '"x.__le__(y)",\n' |
| 3345 | ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' |
| 3346 | '"x>y" calls\n' |
| 3347 | ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' |
| 3348 | '\n' |
| 3349 | ' A rich comparison method may return the singleton ' |
| 3350 | '"NotImplemented"\n' |
| 3351 | ' if it does not implement the operation for a given pair ' |
| 3352 | 'of\n' |
| 3353 | ' arguments. By convention, "False" and "True" are ' |
| 3354 | 'returned for a\n' |
| 3355 | ' successful comparison. However, these methods can return ' |
| 3356 | 'any value,\n' |
| 3357 | ' so if the comparison operator is used in a Boolean ' |
| 3358 | 'context (e.g.,\n' |
| 3359 | ' in the condition of an "if" statement), Python will call ' |
| 3360 | '"bool()"\n' |
| 3361 | ' on the value to determine if the result is true or ' |
| 3362 | 'false.\n' |
| 3363 | '\n' |
| 3364 | ' By default, "__ne__()" delegates to "__eq__()" and ' |
| 3365 | 'inverts the\n' |
| 3366 | ' result unless it is "NotImplemented". There are no ' |
| 3367 | 'other implied\n' |
| 3368 | ' relationships among the comparison operators, for ' |
| 3369 | 'example, the\n' |
| 3370 | ' truth of "(x<y or x==y)" does not imply "x<=y". To ' |
| 3371 | 'automatically\n' |
| 3372 | ' generate ordering operations from a single root ' |
| 3373 | 'operation, see\n' |
| 3374 | ' "functools.total_ordering()".\n' |
| 3375 | '\n' |
| 3376 | ' See the paragraph on "__hash__()" for some important ' |
| 3377 | 'notes on\n' |
| 3378 | ' creating *hashable* objects which support custom ' |
| 3379 | 'comparison\n' |
| 3380 | ' operations and are usable as dictionary keys.\n' |
| 3381 | '\n' |
| 3382 | ' There are no swapped-argument versions of these methods ' |
| 3383 | '(to be used\n' |
| 3384 | ' when the left argument does not support the operation ' |
| 3385 | 'but the right\n' |
| 3386 | ' argument does); rather, "__lt__()" and "__gt__()" are ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3387 | 'each other’s\n' |
| 3388 | ' reflection, "__le__()" and "__ge__()" are each other’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3389 | 'reflection,\n' |
| 3390 | ' and "__eq__()" and "__ne__()" are their own reflection. ' |
| 3391 | 'If the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3392 | ' operands are of different types, and right operand’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3393 | 'type is a\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3394 | ' direct or indirect subclass of the left operand’s type, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3395 | 'the\n' |
| 3396 | ' reflected method of the right operand has priority, ' |
| 3397 | 'otherwise the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3398 | ' left operand’s method has priority. Virtual subclassing ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3399 | 'is not\n' |
| 3400 | ' considered.\n' |
| 3401 | '\n' |
| 3402 | 'object.__hash__(self)\n' |
| 3403 | '\n' |
| 3404 | ' Called by built-in function "hash()" and for operations ' |
| 3405 | 'on members\n' |
| 3406 | ' of hashed collections including "set", "frozenset", and ' |
| 3407 | '"dict".\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3408 | ' "__hash__()" should return an integer. The only required ' |
| 3409 | 'property\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3410 | ' is that objects which compare equal have the same hash ' |
| 3411 | 'value; it is\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3412 | ' advised to mix together the hash values of the ' |
| 3413 | 'components of the\n' |
| 3414 | ' object that also play a part in comparison of objects by ' |
| 3415 | 'packing\n' |
| 3416 | ' them into a tuple and hashing the tuple. Example:\n' |
| 3417 | '\n' |
| 3418 | ' def __hash__(self):\n' |
| 3419 | ' return hash((self.name, self.nick, self.color))\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3420 | '\n' |
| 3421 | ' Note: "hash()" truncates the value returned from an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3422 | 'object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3423 | ' custom "__hash__()" method to the size of a ' |
| 3424 | '"Py_ssize_t". This\n' |
| 3425 | ' is typically 8 bytes on 64-bit builds and 4 bytes on ' |
| 3426 | '32-bit\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3427 | ' builds. If an object’s "__hash__()" must ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3428 | 'interoperate on builds\n' |
| 3429 | ' of different bit sizes, be sure to check the width on ' |
| 3430 | 'all\n' |
| 3431 | ' supported builds. An easy way to do this is with ' |
| 3432 | '"python -c\n' |
| 3433 | ' "import sys; print(sys.hash_info.width)"".\n' |
| 3434 | '\n' |
| 3435 | ' If a class does not define an "__eq__()" method it ' |
| 3436 | 'should not\n' |
| 3437 | ' define a "__hash__()" operation either; if it defines ' |
| 3438 | '"__eq__()"\n' |
| 3439 | ' but not "__hash__()", its instances will not be usable ' |
| 3440 | 'as items in\n' |
| 3441 | ' hashable collections. If a class defines mutable ' |
| 3442 | 'objects and\n' |
| 3443 | ' implements an "__eq__()" method, it should not ' |
| 3444 | 'implement\n' |
| 3445 | ' "__hash__()", since the implementation of hashable ' |
| 3446 | 'collections\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3447 | ' requires that a key’s hash value is immutable (if the ' |
| 3448 | 'object’s hash\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3449 | ' value changes, it will be in the wrong hash bucket).\n' |
| 3450 | '\n' |
| 3451 | ' User-defined classes have "__eq__()" and "__hash__()" ' |
| 3452 | 'methods by\n' |
| 3453 | ' default; with them, all objects compare unequal (except ' |
| 3454 | 'with\n' |
| 3455 | ' themselves) and "x.__hash__()" returns an appropriate ' |
| 3456 | 'value such\n' |
| 3457 | ' that "x == y" implies both that "x is y" and "hash(x) == ' |
| 3458 | 'hash(y)".\n' |
| 3459 | '\n' |
| 3460 | ' A class that overrides "__eq__()" and does not define ' |
| 3461 | '"__hash__()"\n' |
| 3462 | ' will have its "__hash__()" implicitly set to "None". ' |
| 3463 | 'When the\n' |
| 3464 | ' "__hash__()" method of a class is "None", instances of ' |
| 3465 | 'the class\n' |
| 3466 | ' will raise an appropriate "TypeError" when a program ' |
| 3467 | 'attempts to\n' |
| 3468 | ' retrieve their hash value, and will also be correctly ' |
| 3469 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3470 | ' unhashable when checking "isinstance(obj,\n' |
| 3471 | ' collections.abc.Hashable)".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3472 | '\n' |
| 3473 | ' If a class that overrides "__eq__()" needs to retain ' |
| 3474 | 'the\n' |
| 3475 | ' implementation of "__hash__()" from a parent class, the ' |
| 3476 | 'interpreter\n' |
| 3477 | ' must be told this explicitly by setting "__hash__ =\n' |
| 3478 | ' <ParentClass>.__hash__".\n' |
| 3479 | '\n' |
| 3480 | ' If a class that does not override "__eq__()" wishes to ' |
| 3481 | 'suppress\n' |
| 3482 | ' hash support, it should include "__hash__ = None" in the ' |
| 3483 | 'class\n' |
| 3484 | ' definition. A class which defines its own "__hash__()" ' |
| 3485 | 'that\n' |
| 3486 | ' explicitly raises a "TypeError" would be incorrectly ' |
| 3487 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3488 | ' hashable by an "isinstance(obj, ' |
| 3489 | 'collections.abc.Hashable)" call.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3490 | '\n' |
| 3491 | ' Note: By default, the "__hash__()" values of str, bytes ' |
| 3492 | 'and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3493 | ' datetime objects are “salted” with an unpredictable ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3494 | 'random value.\n' |
| 3495 | ' Although they remain constant within an individual ' |
| 3496 | 'Python\n' |
| 3497 | ' process, they are not predictable between repeated ' |
| 3498 | 'invocations of\n' |
| 3499 | ' Python.This is intended to provide protection against ' |
| 3500 | 'a denial-\n' |
| 3501 | ' of-service caused by carefully-chosen inputs that ' |
| 3502 | 'exploit the\n' |
| 3503 | ' worst case performance of a dict insertion, O(n^2) ' |
| 3504 | 'complexity.\n' |
| 3505 | ' See ' |
| 3506 | 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' |
| 3507 | ' details.Changing hash values affects the iteration ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3508 | 'order of sets.\n' |
| 3509 | ' Python has never made guarantees about this ordering ' |
| 3510 | '(and it\n' |
| 3511 | ' typically varies between 32-bit and 64-bit builds).See ' |
| 3512 | 'also\n' |
| 3513 | ' "PYTHONHASHSEED".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3514 | '\n' |
| 3515 | ' Changed in version 3.3: Hash randomization is enabled by ' |
| 3516 | 'default.\n' |
| 3517 | '\n' |
| 3518 | 'object.__bool__(self)\n' |
| 3519 | '\n' |
| 3520 | ' Called to implement truth value testing and the built-in ' |
| 3521 | 'operation\n' |
| 3522 | ' "bool()"; should return "False" or "True". When this ' |
| 3523 | 'method is not\n' |
| 3524 | ' defined, "__len__()" is called, if it is defined, and ' |
| 3525 | 'the object is\n' |
| 3526 | ' considered true if its result is nonzero. If a class ' |
| 3527 | 'defines\n' |
| 3528 | ' neither "__len__()" nor "__bool__()", all its instances ' |
| 3529 | 'are\n' |
| 3530 | ' considered true.\n', |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3531 | 'debugger': '"pdb" — The Python Debugger\n' |
| 3532 | '***************************\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3533 | '\n' |
| 3534 | '**Source code:** Lib/pdb.py\n' |
| 3535 | '\n' |
| 3536 | '======================================================================\n' |
| 3537 | '\n' |
| 3538 | 'The module "pdb" defines an interactive source code debugger ' |
| 3539 | 'for\n' |
| 3540 | 'Python programs. It supports setting (conditional) breakpoints ' |
| 3541 | 'and\n' |
| 3542 | 'single stepping at the source line level, inspection of stack ' |
| 3543 | 'frames,\n' |
| 3544 | 'source code listing, and evaluation of arbitrary Python code in ' |
| 3545 | 'the\n' |
| 3546 | 'context of any stack frame. It also supports post-mortem ' |
| 3547 | 'debugging\n' |
| 3548 | 'and can be called under program control.\n' |
| 3549 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3550 | 'The debugger is extensible – it is actually defined as the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3551 | 'class\n' |
| 3552 | '"Pdb". This is currently undocumented but easily understood by ' |
| 3553 | 'reading\n' |
| 3554 | 'the source. The extension interface uses the modules "bdb" and ' |
| 3555 | '"cmd".\n' |
| 3556 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3557 | 'The debugger’s prompt is "(Pdb)". Typical usage to run a program ' |
| 3558 | 'under\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3559 | 'control of the debugger is:\n' |
| 3560 | '\n' |
| 3561 | ' >>> import pdb\n' |
| 3562 | ' >>> import mymodule\n' |
| 3563 | " >>> pdb.run('mymodule.test()')\n" |
| 3564 | ' > <string>(0)?()\n' |
| 3565 | ' (Pdb) continue\n' |
| 3566 | ' > <string>(1)?()\n' |
| 3567 | ' (Pdb) continue\n' |
| 3568 | " NameError: 'spam'\n" |
| 3569 | ' > <string>(1)?()\n' |
| 3570 | ' (Pdb)\n' |
| 3571 | '\n' |
| 3572 | 'Changed in version 3.3: Tab-completion via the "readline" module ' |
| 3573 | 'is\n' |
| 3574 | 'available for commands and command arguments, e.g. the current ' |
| 3575 | 'global\n' |
| 3576 | 'and local names are offered as arguments of the "p" command.\n' |
| 3577 | '\n' |
| 3578 | '"pdb.py" can also be invoked as a script to debug other ' |
| 3579 | 'scripts. For\n' |
| 3580 | 'example:\n' |
| 3581 | '\n' |
| 3582 | ' python3 -m pdb myscript.py\n' |
| 3583 | '\n' |
| 3584 | 'When invoked as a script, pdb will automatically enter ' |
| 3585 | 'post-mortem\n' |
| 3586 | 'debugging if the program being debugged exits abnormally. After ' |
| 3587 | 'post-\n' |
| 3588 | 'mortem debugging (or after normal exit of the program), pdb ' |
| 3589 | 'will\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3590 | 'restart the program. Automatic restarting preserves pdb’s state ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3591 | '(such\n' |
| 3592 | 'as breakpoints) and in most cases is more useful than quitting ' |
| 3593 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3594 | 'debugger upon program’s exit.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3595 | '\n' |
| 3596 | 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' |
| 3597 | 'executes\n' |
| 3598 | 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n' |
| 3599 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3600 | 'New in version 3.7: "pdb.py" now accepts a "-m" option that ' |
| 3601 | 'execute\n' |
| 3602 | 'modules similar to the way "python3 -m" does. As with a script, ' |
| 3603 | 'the\n' |
| 3604 | 'debugger will pause execution just before the first line of the\n' |
| 3605 | 'module.\n' |
| 3606 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3607 | 'The typical usage to break into the debugger from a running ' |
| 3608 | 'program is\n' |
| 3609 | 'to insert\n' |
| 3610 | '\n' |
| 3611 | ' import pdb; pdb.set_trace()\n' |
| 3612 | '\n' |
| 3613 | 'at the location you want to break into the debugger. You can ' |
| 3614 | 'then\n' |
| 3615 | 'step through the code following this statement, and continue ' |
| 3616 | 'running\n' |
| 3617 | 'without the debugger using the "continue" command.\n' |
| 3618 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3619 | 'New in version 3.7: The built-in "breakpoint()", when called ' |
| 3620 | 'with\n' |
| 3621 | 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n' |
| 3622 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3623 | 'The typical usage to inspect a crashed program is:\n' |
| 3624 | '\n' |
| 3625 | ' >>> import pdb\n' |
| 3626 | ' >>> import mymodule\n' |
| 3627 | ' >>> mymodule.test()\n' |
| 3628 | ' Traceback (most recent call last):\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3629 | ' File "<stdin>", line 1, in <module>\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3630 | ' File "./mymodule.py", line 4, in test\n' |
| 3631 | ' test2()\n' |
| 3632 | ' File "./mymodule.py", line 3, in test2\n' |
| 3633 | ' print(spam)\n' |
| 3634 | ' NameError: spam\n' |
| 3635 | ' >>> pdb.pm()\n' |
| 3636 | ' > ./mymodule.py(3)test2()\n' |
| 3637 | ' -> print(spam)\n' |
| 3638 | ' (Pdb)\n' |
| 3639 | '\n' |
| 3640 | 'The module defines the following functions; each enters the ' |
| 3641 | 'debugger\n' |
| 3642 | 'in a slightly different way:\n' |
| 3643 | '\n' |
| 3644 | 'pdb.run(statement, globals=None, locals=None)\n' |
| 3645 | '\n' |
| 3646 | ' Execute the *statement* (given as a string or a code object) ' |
| 3647 | 'under\n' |
| 3648 | ' debugger control. The debugger prompt appears before any ' |
| 3649 | 'code is\n' |
| 3650 | ' executed; you can set breakpoints and type "continue", or you ' |
| 3651 | 'can\n' |
| 3652 | ' step through the statement using "step" or "next" (all these\n' |
| 3653 | ' commands are explained below). The optional *globals* and ' |
| 3654 | '*locals*\n' |
| 3655 | ' arguments specify the environment in which the code is ' |
| 3656 | 'executed; by\n' |
| 3657 | ' default the dictionary of the module "__main__" is used. ' |
| 3658 | '(See the\n' |
| 3659 | ' explanation of the built-in "exec()" or "eval()" functions.)\n' |
| 3660 | '\n' |
| 3661 | 'pdb.runeval(expression, globals=None, locals=None)\n' |
| 3662 | '\n' |
| 3663 | ' Evaluate the *expression* (given as a string or a code ' |
| 3664 | 'object)\n' |
| 3665 | ' under debugger control. When "runeval()" returns, it returns ' |
| 3666 | 'the\n' |
| 3667 | ' value of the expression. Otherwise this function is similar ' |
| 3668 | 'to\n' |
| 3669 | ' "run()".\n' |
| 3670 | '\n' |
| 3671 | 'pdb.runcall(function, *args, **kwds)\n' |
| 3672 | '\n' |
| 3673 | ' Call the *function* (a function or method object, not a ' |
| 3674 | 'string)\n' |
| 3675 | ' with the given arguments. When "runcall()" returns, it ' |
| 3676 | 'returns\n' |
| 3677 | ' whatever the function call returned. The debugger prompt ' |
| 3678 | 'appears\n' |
| 3679 | ' as soon as the function is entered.\n' |
| 3680 | '\n' |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 3681 | 'pdb.set_trace(*, header=None)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3682 | '\n' |
| 3683 | ' Enter the debugger at the calling stack frame. This is ' |
| 3684 | 'useful to\n' |
| 3685 | ' hard-code a breakpoint at a given point in a program, even if ' |
| 3686 | 'the\n' |
| 3687 | ' code is not otherwise being debugged (e.g. when an assertion\n' |
Ned Deily | 3f9a728 | 2017-12-05 03:17:33 -0500 | [diff] [blame] | 3688 | ' fails). If given, *header* is printed to the console just ' |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 3689 | 'before\n' |
| 3690 | ' debugging begins.\n' |
| 3691 | '\n' |
Ned Deily | 3f9a728 | 2017-12-05 03:17:33 -0500 | [diff] [blame] | 3692 | ' Changed in version 3.7: The keyword-only argument *header*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3693 | '\n' |
| 3694 | 'pdb.post_mortem(traceback=None)\n' |
| 3695 | '\n' |
| 3696 | ' Enter post-mortem debugging of the given *traceback* object. ' |
| 3697 | 'If no\n' |
| 3698 | ' *traceback* is given, it uses the one of the exception that ' |
| 3699 | 'is\n' |
| 3700 | ' currently being handled (an exception must be being handled ' |
| 3701 | 'if the\n' |
| 3702 | ' default is to be used).\n' |
| 3703 | '\n' |
| 3704 | 'pdb.pm()\n' |
| 3705 | '\n' |
| 3706 | ' Enter post-mortem debugging of the traceback found in\n' |
| 3707 | ' "sys.last_traceback".\n' |
| 3708 | '\n' |
| 3709 | 'The "run*" functions and "set_trace()" are aliases for ' |
| 3710 | 'instantiating\n' |
| 3711 | 'the "Pdb" class and calling the method of the same name. If you ' |
| 3712 | 'want\n' |
| 3713 | 'to access further features, you have to do this yourself:\n' |
| 3714 | '\n' |
| 3715 | "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, " |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3716 | 'skip=None, nosigint=False, readrc=True)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3717 | '\n' |
| 3718 | ' "Pdb" is the debugger class.\n' |
| 3719 | '\n' |
| 3720 | ' The *completekey*, *stdin* and *stdout* arguments are passed ' |
| 3721 | 'to the\n' |
| 3722 | ' underlying "cmd.Cmd" class; see the description there.\n' |
| 3723 | '\n' |
| 3724 | ' The *skip* argument, if given, must be an iterable of ' |
| 3725 | 'glob-style\n' |
| 3726 | ' module name patterns. The debugger will not step into frames ' |
| 3727 | 'that\n' |
| 3728 | ' originate in a module that matches one of these patterns. ' |
| 3729 | '[1]\n' |
| 3730 | '\n' |
| 3731 | ' By default, Pdb sets a handler for the SIGINT signal (which ' |
| 3732 | 'is sent\n' |
| 3733 | ' when the user presses "Ctrl-C" on the console) when you give ' |
| 3734 | 'a\n' |
| 3735 | ' "continue" command. This allows you to break into the ' |
| 3736 | 'debugger\n' |
| 3737 | ' again by pressing "Ctrl-C". If you want Pdb not to touch ' |
| 3738 | 'the\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3739 | ' SIGINT handler, set *nosigint* to true.\n' |
| 3740 | '\n' |
| 3741 | ' The *readrc* argument defaults to true and controls whether ' |
| 3742 | 'Pdb\n' |
| 3743 | ' will load .pdbrc files from the filesystem.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3744 | '\n' |
| 3745 | ' Example call to enable tracing with *skip*:\n' |
| 3746 | '\n' |
| 3747 | " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" |
| 3748 | '\n' |
| 3749 | ' New in version 3.1: The *skip* argument.\n' |
| 3750 | '\n' |
| 3751 | ' New in version 3.2: The *nosigint* argument. Previously, a ' |
| 3752 | 'SIGINT\n' |
| 3753 | ' handler was never set by Pdb.\n' |
| 3754 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3755 | ' Changed in version 3.6: The *readrc* argument.\n' |
| 3756 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3757 | ' run(statement, globals=None, locals=None)\n' |
| 3758 | ' runeval(expression, globals=None, locals=None)\n' |
| 3759 | ' runcall(function, *args, **kwds)\n' |
| 3760 | ' set_trace()\n' |
| 3761 | '\n' |
| 3762 | ' See the documentation for the functions explained above.\n' |
| 3763 | '\n' |
| 3764 | '\n' |
| 3765 | 'Debugger Commands\n' |
| 3766 | '=================\n' |
| 3767 | '\n' |
| 3768 | 'The commands recognized by the debugger are listed below. Most\n' |
| 3769 | 'commands can be abbreviated to one or two letters as indicated; ' |
| 3770 | 'e.g.\n' |
| 3771 | '"h(elp)" means that either "h" or "help" can be used to enter ' |
| 3772 | 'the help\n' |
| 3773 | 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' |
| 3774 | 'Arguments to commands must be separated by whitespace (spaces ' |
| 3775 | 'or\n' |
| 3776 | 'tabs). Optional arguments are enclosed in square brackets ' |
| 3777 | '("[]") in\n' |
| 3778 | 'the command syntax; the square brackets must not be typed.\n' |
| 3779 | 'Alternatives in the command syntax are separated by a vertical ' |
| 3780 | 'bar\n' |
| 3781 | '("|").\n' |
| 3782 | '\n' |
| 3783 | 'Entering a blank line repeats the last command entered. ' |
| 3784 | 'Exception: if\n' |
| 3785 | 'the last command was a "list" command, the next 11 lines are ' |
| 3786 | 'listed.\n' |
| 3787 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3788 | 'Commands that the debugger doesn’t recognize are assumed to be ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3789 | 'Python\n' |
| 3790 | 'statements and are executed in the context of the program being\n' |
| 3791 | 'debugged. Python statements can also be prefixed with an ' |
| 3792 | 'exclamation\n' |
| 3793 | 'point ("!"). This is a powerful way to inspect the program ' |
| 3794 | 'being\n' |
| 3795 | 'debugged; it is even possible to change a variable or call a ' |
| 3796 | 'function.\n' |
| 3797 | 'When an exception occurs in such a statement, the exception name ' |
| 3798 | 'is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3799 | 'printed but the debugger’s state is not changed.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3800 | '\n' |
| 3801 | 'The debugger supports aliases. Aliases can have parameters ' |
| 3802 | 'which\n' |
| 3803 | 'allows one a certain level of adaptability to the context under\n' |
| 3804 | 'examination.\n' |
| 3805 | '\n' |
| 3806 | 'Multiple commands may be entered on a single line, separated by ' |
| 3807 | '";;".\n' |
| 3808 | '(A single ";" is not used as it is the separator for multiple ' |
| 3809 | 'commands\n' |
| 3810 | 'in a line that is passed to the Python parser.) No intelligence ' |
| 3811 | 'is\n' |
| 3812 | 'applied to separating the commands; the input is split at the ' |
| 3813 | 'first\n' |
| 3814 | '";;" pair, even if it is in the middle of a quoted string.\n' |
| 3815 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3816 | 'If a file ".pdbrc" exists in the user’s home directory or in ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3817 | 'the\n' |
| 3818 | 'current directory, it is read in and executed as if it had been ' |
| 3819 | 'typed\n' |
| 3820 | 'at the debugger prompt. This is particularly useful for ' |
| 3821 | 'aliases. If\n' |
| 3822 | 'both files exist, the one in the home directory is read first ' |
| 3823 | 'and\n' |
| 3824 | 'aliases defined there can be overridden by the local file.\n' |
| 3825 | '\n' |
| 3826 | 'Changed in version 3.2: ".pdbrc" can now contain commands that\n' |
| 3827 | 'continue debugging, such as "continue" or "next". Previously, ' |
| 3828 | 'these\n' |
| 3829 | 'commands had no effect.\n' |
| 3830 | '\n' |
| 3831 | 'h(elp) [command]\n' |
| 3832 | '\n' |
| 3833 | ' Without argument, print the list of available commands. With ' |
| 3834 | 'a\n' |
| 3835 | ' *command* as argument, print help about that command. "help ' |
| 3836 | 'pdb"\n' |
| 3837 | ' displays the full documentation (the docstring of the "pdb"\n' |
| 3838 | ' module). Since the *command* argument must be an identifier, ' |
| 3839 | '"help\n' |
| 3840 | ' exec" must be entered to get help on the "!" command.\n' |
| 3841 | '\n' |
| 3842 | 'w(here)\n' |
| 3843 | '\n' |
| 3844 | ' Print a stack trace, with the most recent frame at the ' |
| 3845 | 'bottom. An\n' |
| 3846 | ' arrow indicates the current frame, which determines the ' |
| 3847 | 'context of\n' |
| 3848 | ' most commands.\n' |
| 3849 | '\n' |
| 3850 | 'd(own) [count]\n' |
| 3851 | '\n' |
| 3852 | ' Move the current frame *count* (default one) levels down in ' |
| 3853 | 'the\n' |
| 3854 | ' stack trace (to a newer frame).\n' |
| 3855 | '\n' |
| 3856 | 'u(p) [count]\n' |
| 3857 | '\n' |
| 3858 | ' Move the current frame *count* (default one) levels up in the ' |
| 3859 | 'stack\n' |
| 3860 | ' trace (to an older frame).\n' |
| 3861 | '\n' |
| 3862 | 'b(reak) [([filename:]lineno | function) [, condition]]\n' |
| 3863 | '\n' |
| 3864 | ' With a *lineno* argument, set a break there in the current ' |
| 3865 | 'file.\n' |
| 3866 | ' With a *function* argument, set a break at the first ' |
| 3867 | 'executable\n' |
| 3868 | ' statement within that function. The line number may be ' |
| 3869 | 'prefixed\n' |
| 3870 | ' with a filename and a colon, to specify a breakpoint in ' |
| 3871 | 'another\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3872 | ' file (probably one that hasn’t been loaded yet). The file ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3873 | 'is\n' |
| 3874 | ' searched on "sys.path". Note that each breakpoint is ' |
| 3875 | 'assigned a\n' |
| 3876 | ' number to which all the other breakpoint commands refer.\n' |
| 3877 | '\n' |
| 3878 | ' If a second argument is present, it is an expression which ' |
| 3879 | 'must\n' |
| 3880 | ' evaluate to true before the breakpoint is honored.\n' |
| 3881 | '\n' |
| 3882 | ' Without argument, list all breaks, including for each ' |
| 3883 | 'breakpoint,\n' |
| 3884 | ' the number of times that breakpoint has been hit, the ' |
| 3885 | 'current\n' |
| 3886 | ' ignore count, and the associated condition if any.\n' |
| 3887 | '\n' |
| 3888 | 'tbreak [([filename:]lineno | function) [, condition]]\n' |
| 3889 | '\n' |
| 3890 | ' Temporary breakpoint, which is removed automatically when it ' |
| 3891 | 'is\n' |
| 3892 | ' first hit. The arguments are the same as for "break".\n' |
| 3893 | '\n' |
| 3894 | 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' |
| 3895 | '\n' |
| 3896 | ' With a *filename:lineno* argument, clear all the breakpoints ' |
| 3897 | 'at\n' |
| 3898 | ' this line. With a space separated list of breakpoint numbers, ' |
| 3899 | 'clear\n' |
| 3900 | ' those breakpoints. Without argument, clear all breaks (but ' |
| 3901 | 'first\n' |
| 3902 | ' ask confirmation).\n' |
| 3903 | '\n' |
| 3904 | 'disable [bpnumber [bpnumber ...]]\n' |
| 3905 | '\n' |
| 3906 | ' Disable the breakpoints given as a space separated list of\n' |
| 3907 | ' breakpoint numbers. Disabling a breakpoint means it cannot ' |
| 3908 | 'cause\n' |
| 3909 | ' the program to stop execution, but unlike clearing a ' |
| 3910 | 'breakpoint, it\n' |
| 3911 | ' remains in the list of breakpoints and can be (re-)enabled.\n' |
| 3912 | '\n' |
| 3913 | 'enable [bpnumber [bpnumber ...]]\n' |
| 3914 | '\n' |
| 3915 | ' Enable the breakpoints specified.\n' |
| 3916 | '\n' |
| 3917 | 'ignore bpnumber [count]\n' |
| 3918 | '\n' |
| 3919 | ' Set the ignore count for the given breakpoint number. If ' |
| 3920 | 'count is\n' |
| 3921 | ' omitted, the ignore count is set to 0. A breakpoint becomes ' |
| 3922 | 'active\n' |
| 3923 | ' when the ignore count is zero. When non-zero, the count is\n' |
| 3924 | ' decremented each time the breakpoint is reached and the ' |
| 3925 | 'breakpoint\n' |
| 3926 | ' is not disabled and any associated condition evaluates to ' |
| 3927 | 'true.\n' |
| 3928 | '\n' |
| 3929 | 'condition bpnumber [condition]\n' |
| 3930 | '\n' |
| 3931 | ' Set a new *condition* for the breakpoint, an expression which ' |
| 3932 | 'must\n' |
| 3933 | ' evaluate to true before the breakpoint is honored. If ' |
| 3934 | '*condition*\n' |
| 3935 | ' is absent, any existing condition is removed; i.e., the ' |
| 3936 | 'breakpoint\n' |
| 3937 | ' is made unconditional.\n' |
| 3938 | '\n' |
| 3939 | 'commands [bpnumber]\n' |
| 3940 | '\n' |
| 3941 | ' Specify a list of commands for breakpoint number *bpnumber*. ' |
| 3942 | 'The\n' |
| 3943 | ' commands themselves appear on the following lines. Type a ' |
| 3944 | 'line\n' |
| 3945 | ' containing just "end" to terminate the commands. An example:\n' |
| 3946 | '\n' |
| 3947 | ' (Pdb) commands 1\n' |
| 3948 | ' (com) p some_variable\n' |
| 3949 | ' (com) end\n' |
| 3950 | ' (Pdb)\n' |
| 3951 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3952 | ' To remove all commands from a breakpoint, type "commands" ' |
| 3953 | 'and\n' |
| 3954 | ' follow it immediately with "end"; that is, give no commands.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3955 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3956 | ' With no *bpnumber* argument, "commands" refers to the last\n' |
| 3957 | ' breakpoint set.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3958 | '\n' |
| 3959 | ' You can use breakpoint commands to start your program up ' |
| 3960 | 'again.\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3961 | ' Simply use the "continue" command, or "step", or any other ' |
| 3962 | 'command\n' |
| 3963 | ' that resumes execution.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3964 | '\n' |
| 3965 | ' Specifying any command resuming execution (currently ' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3966 | '"continue",\n' |
| 3967 | ' "step", "next", "return", "jump", "quit" and their ' |
| 3968 | 'abbreviations)\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3969 | ' terminates the command list (as if that command was ' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3970 | 'immediately\n' |
| 3971 | ' followed by end). This is because any time you resume ' |
| 3972 | 'execution\n' |
| 3973 | ' (even with a simple next or step), you may encounter another\n' |
| 3974 | ' breakpoint—which could have its own command list, leading to\n' |
| 3975 | ' ambiguities about which list to execute.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3976 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 3977 | ' If you use the ‘silent’ command in the command list, the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3978 | 'usual\n' |
| 3979 | ' message about stopping at a breakpoint is not printed. This ' |
| 3980 | 'may be\n' |
| 3981 | ' desirable for breakpoints that are to print a specific ' |
| 3982 | 'message and\n' |
| 3983 | ' then continue. If none of the other commands print anything, ' |
| 3984 | 'you\n' |
| 3985 | ' see no sign that the breakpoint was reached.\n' |
| 3986 | '\n' |
| 3987 | 's(tep)\n' |
| 3988 | '\n' |
| 3989 | ' Execute the current line, stop at the first possible ' |
| 3990 | 'occasion\n' |
| 3991 | ' (either in a function that is called or on the next line in ' |
| 3992 | 'the\n' |
| 3993 | ' current function).\n' |
| 3994 | '\n' |
| 3995 | 'n(ext)\n' |
| 3996 | '\n' |
| 3997 | ' Continue execution until the next line in the current ' |
| 3998 | 'function is\n' |
| 3999 | ' reached or it returns. (The difference between "next" and ' |
| 4000 | '"step"\n' |
| 4001 | ' is that "step" stops inside a called function, while "next"\n' |
| 4002 | ' executes called functions at (nearly) full speed, only ' |
| 4003 | 'stopping at\n' |
| 4004 | ' the next line in the current function.)\n' |
| 4005 | '\n' |
| 4006 | 'unt(il) [lineno]\n' |
| 4007 | '\n' |
| 4008 | ' Without argument, continue execution until the line with a ' |
| 4009 | 'number\n' |
| 4010 | ' greater than the current one is reached.\n' |
| 4011 | '\n' |
| 4012 | ' With a line number, continue execution until a line with a ' |
| 4013 | 'number\n' |
| 4014 | ' greater or equal to that is reached. In both cases, also ' |
| 4015 | 'stop when\n' |
| 4016 | ' the current frame returns.\n' |
| 4017 | '\n' |
| 4018 | ' Changed in version 3.2: Allow giving an explicit line ' |
| 4019 | 'number.\n' |
| 4020 | '\n' |
| 4021 | 'r(eturn)\n' |
| 4022 | '\n' |
| 4023 | ' Continue execution until the current function returns.\n' |
| 4024 | '\n' |
| 4025 | 'c(ont(inue))\n' |
| 4026 | '\n' |
| 4027 | ' Continue execution, only stop when a breakpoint is ' |
| 4028 | 'encountered.\n' |
| 4029 | '\n' |
| 4030 | 'j(ump) lineno\n' |
| 4031 | '\n' |
| 4032 | ' Set the next line that will be executed. Only available in ' |
| 4033 | 'the\n' |
| 4034 | ' bottom-most frame. This lets you jump back and execute code ' |
| 4035 | 'again,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4036 | ' or jump forward to skip code that you don’t want to run.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4037 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4038 | ' It should be noted that not all jumps are allowed – for ' |
| 4039 | 'instance it\n' |
| 4040 | ' is not possible to jump into the middle of a "for" loop or ' |
| 4041 | 'out of a\n' |
| 4042 | ' "finally" clause.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4043 | '\n' |
| 4044 | 'l(ist) [first[, last]]\n' |
| 4045 | '\n' |
| 4046 | ' List source code for the current file. Without arguments, ' |
| 4047 | 'list 11\n' |
| 4048 | ' lines around the current line or continue the previous ' |
| 4049 | 'listing.\n' |
| 4050 | ' With "." as argument, list 11 lines around the current line. ' |
| 4051 | 'With\n' |
| 4052 | ' one argument, list 11 lines around at that line. With two\n' |
| 4053 | ' arguments, list the given range; if the second argument is ' |
| 4054 | 'less\n' |
| 4055 | ' than the first, it is interpreted as a count.\n' |
| 4056 | '\n' |
| 4057 | ' The current line in the current frame is indicated by "->". ' |
| 4058 | 'If an\n' |
| 4059 | ' exception is being debugged, the line where the exception ' |
| 4060 | 'was\n' |
| 4061 | ' originally raised or propagated is indicated by ">>", if it ' |
| 4062 | 'differs\n' |
| 4063 | ' from the current line.\n' |
| 4064 | '\n' |
| 4065 | ' New in version 3.2: The ">>" marker.\n' |
| 4066 | '\n' |
| 4067 | 'll | longlist\n' |
| 4068 | '\n' |
| 4069 | ' List all source code for the current function or frame.\n' |
| 4070 | ' Interesting lines are marked as for "list".\n' |
| 4071 | '\n' |
| 4072 | ' New in version 3.2.\n' |
| 4073 | '\n' |
| 4074 | 'a(rgs)\n' |
| 4075 | '\n' |
| 4076 | ' Print the argument list of the current function.\n' |
| 4077 | '\n' |
| 4078 | 'p expression\n' |
| 4079 | '\n' |
| 4080 | ' Evaluate the *expression* in the current context and print ' |
| 4081 | 'its\n' |
| 4082 | ' value.\n' |
| 4083 | '\n' |
| 4084 | ' Note: "print()" can also be used, but is not a debugger ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4085 | 'command —\n' |
| 4086 | ' this executes the Python "print()" function.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4087 | '\n' |
| 4088 | 'pp expression\n' |
| 4089 | '\n' |
| 4090 | ' Like the "p" command, except the value of the expression is ' |
| 4091 | 'pretty-\n' |
| 4092 | ' printed using the "pprint" module.\n' |
| 4093 | '\n' |
| 4094 | 'whatis expression\n' |
| 4095 | '\n' |
| 4096 | ' Print the type of the *expression*.\n' |
| 4097 | '\n' |
| 4098 | 'source expression\n' |
| 4099 | '\n' |
| 4100 | ' Try to get source code for the given object and display it.\n' |
| 4101 | '\n' |
| 4102 | ' New in version 3.2.\n' |
| 4103 | '\n' |
| 4104 | 'display [expression]\n' |
| 4105 | '\n' |
| 4106 | ' Display the value of the expression if it changed, each time\n' |
| 4107 | ' execution stops in the current frame.\n' |
| 4108 | '\n' |
| 4109 | ' Without expression, list all display expressions for the ' |
| 4110 | 'current\n' |
| 4111 | ' frame.\n' |
| 4112 | '\n' |
| 4113 | ' New in version 3.2.\n' |
| 4114 | '\n' |
| 4115 | 'undisplay [expression]\n' |
| 4116 | '\n' |
| 4117 | ' Do not display the expression any more in the current frame.\n' |
| 4118 | ' Without expression, clear all display expressions for the ' |
| 4119 | 'current\n' |
| 4120 | ' frame.\n' |
| 4121 | '\n' |
| 4122 | ' New in version 3.2.\n' |
| 4123 | '\n' |
| 4124 | 'interact\n' |
| 4125 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 4126 | ' Start an interactive interpreter (using the "code" module) ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4127 | 'whose\n' |
| 4128 | ' global namespace contains all the (global and local) names ' |
| 4129 | 'found in\n' |
| 4130 | ' the current scope.\n' |
| 4131 | '\n' |
| 4132 | ' New in version 3.2.\n' |
| 4133 | '\n' |
| 4134 | 'alias [name [command]]\n' |
| 4135 | '\n' |
| 4136 | ' Create an alias called *name* that executes *command*. The ' |
| 4137 | 'command\n' |
| 4138 | ' must *not* be enclosed in quotes. Replaceable parameters can ' |
| 4139 | 'be\n' |
| 4140 | ' indicated by "%1", "%2", and so on, while "%*" is replaced by ' |
| 4141 | 'all\n' |
| 4142 | ' the parameters. If no command is given, the current alias ' |
| 4143 | 'for\n' |
| 4144 | ' *name* is shown. If no arguments are given, all aliases are ' |
| 4145 | 'listed.\n' |
| 4146 | '\n' |
| 4147 | ' Aliases may be nested and can contain anything that can be ' |
| 4148 | 'legally\n' |
| 4149 | ' typed at the pdb prompt. Note that internal pdb commands ' |
| 4150 | '*can* be\n' |
| 4151 | ' overridden by aliases. Such a command is then hidden until ' |
| 4152 | 'the\n' |
| 4153 | ' alias is removed. Aliasing is recursively applied to the ' |
| 4154 | 'first\n' |
| 4155 | ' word of the command line; all other words in the line are ' |
| 4156 | 'left\n' |
| 4157 | ' alone.\n' |
| 4158 | '\n' |
| 4159 | ' As an example, here are two useful aliases (especially when ' |
| 4160 | 'placed\n' |
| 4161 | ' in the ".pdbrc" file):\n' |
| 4162 | '\n' |
| 4163 | ' # Print instance variables (usage "pi classInst")\n' |
| 4164 | ' alias pi for k in %1.__dict__.keys(): ' |
| 4165 | 'print("%1.",k,"=",%1.__dict__[k])\n' |
| 4166 | ' # Print instance variables in self\n' |
| 4167 | ' alias ps pi self\n' |
| 4168 | '\n' |
| 4169 | 'unalias name\n' |
| 4170 | '\n' |
| 4171 | ' Delete the specified alias.\n' |
| 4172 | '\n' |
| 4173 | '! statement\n' |
| 4174 | '\n' |
| 4175 | ' Execute the (one-line) *statement* in the context of the ' |
| 4176 | 'current\n' |
| 4177 | ' stack frame. The exclamation point can be omitted unless the ' |
| 4178 | 'first\n' |
| 4179 | ' word of the statement resembles a debugger command. To set ' |
| 4180 | 'a\n' |
| 4181 | ' global variable, you can prefix the assignment command with ' |
| 4182 | 'a\n' |
| 4183 | ' "global" statement on the same line, e.g.:\n' |
| 4184 | '\n' |
| 4185 | " (Pdb) global list_options; list_options = ['-l']\n" |
| 4186 | ' (Pdb)\n' |
| 4187 | '\n' |
| 4188 | 'run [args ...]\n' |
| 4189 | 'restart [args ...]\n' |
| 4190 | '\n' |
| 4191 | ' Restart the debugged Python program. If an argument is ' |
| 4192 | 'supplied,\n' |
| 4193 | ' it is split with "shlex" and the result is used as the new\n' |
| 4194 | ' "sys.argv". History, breakpoints, actions and debugger ' |
| 4195 | 'options are\n' |
| 4196 | ' preserved. "restart" is an alias for "run".\n' |
| 4197 | '\n' |
| 4198 | 'q(uit)\n' |
| 4199 | '\n' |
| 4200 | ' Quit from the debugger. The program being executed is ' |
| 4201 | 'aborted.\n' |
| 4202 | '\n' |
| 4203 | '-[ Footnotes ]-\n' |
| 4204 | '\n' |
| 4205 | '[1] Whether a frame is considered to originate in a certain ' |
| 4206 | 'module\n' |
| 4207 | ' is determined by the "__name__" in the frame globals.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4208 | 'del': 'The "del" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4209 | '*******************\n' |
| 4210 | '\n' |
| 4211 | ' del_stmt ::= "del" target_list\n' |
| 4212 | '\n' |
| 4213 | 'Deletion is recursively defined very similar to the way assignment ' |
| 4214 | 'is\n' |
| 4215 | 'defined. Rather than spelling it out in full details, here are some\n' |
| 4216 | 'hints.\n' |
| 4217 | '\n' |
| 4218 | 'Deletion of a target list recursively deletes each target, from left\n' |
| 4219 | 'to right.\n' |
| 4220 | '\n' |
| 4221 | 'Deletion of a name removes the binding of that name from the local ' |
| 4222 | 'or\n' |
| 4223 | 'global namespace, depending on whether the name occurs in a "global"\n' |
| 4224 | 'statement in the same code block. If the name is unbound, a\n' |
| 4225 | '"NameError" exception will be raised.\n' |
| 4226 | '\n' |
| 4227 | 'Deletion of attribute references, subscriptions and slicings is ' |
| 4228 | 'passed\n' |
| 4229 | 'to the primary object involved; deletion of a slicing is in general\n' |
| 4230 | 'equivalent to assignment of an empty slice of the right type (but ' |
| 4231 | 'even\n' |
| 4232 | 'this is determined by the sliced object).\n' |
| 4233 | '\n' |
| 4234 | 'Changed in version 3.2: Previously it was illegal to delete a name\n' |
| 4235 | 'from the local namespace if it occurs as a free variable in a nested\n' |
| 4236 | 'block.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4237 | 'dict': 'Dictionary displays\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4238 | '*******************\n' |
| 4239 | '\n' |
| 4240 | 'A dictionary display is a possibly empty series of key/datum pairs\n' |
| 4241 | 'enclosed in curly braces:\n' |
| 4242 | '\n' |
| 4243 | ' dict_display ::= "{" [key_datum_list | dict_comprehension] ' |
| 4244 | '"}"\n' |
| 4245 | ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4246 | ' key_datum ::= expression ":" expression | "**" or_expr\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4247 | ' dict_comprehension ::= expression ":" expression comp_for\n' |
| 4248 | '\n' |
| 4249 | 'A dictionary display yields a new dictionary object.\n' |
| 4250 | '\n' |
| 4251 | 'If a comma-separated sequence of key/datum pairs is given, they are\n' |
| 4252 | 'evaluated from left to right to define the entries of the ' |
| 4253 | 'dictionary:\n' |
| 4254 | 'each key object is used as a key into the dictionary to store the\n' |
| 4255 | 'corresponding datum. This means that you can specify the same key\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4256 | 'multiple times in the key/datum list, and the final dictionary’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4257 | 'value\n' |
| 4258 | 'for that key will be the last one given.\n' |
| 4259 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4260 | 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n' |
| 4261 | 'must be a *mapping*. Each mapping item is added to the new\n' |
| 4262 | 'dictionary. Later values replace values already set by earlier\n' |
| 4263 | 'key/datum pairs and earlier dictionary unpackings.\n' |
| 4264 | '\n' |
| 4265 | 'New in version 3.5: Unpacking into dictionary displays, originally\n' |
| 4266 | 'proposed by **PEP 448**.\n' |
| 4267 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4268 | 'A dict comprehension, in contrast to list and set comprehensions,\n' |
| 4269 | 'needs two expressions separated with a colon followed by the usual\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4270 | '“for” and “if” clauses. When the comprehension is run, the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4271 | 'resulting\n' |
| 4272 | 'key and value elements are inserted in the new dictionary in the ' |
| 4273 | 'order\n' |
| 4274 | 'they are produced.\n' |
| 4275 | '\n' |
| 4276 | 'Restrictions on the types of the key values are listed earlier in\n' |
| 4277 | 'section The standard type hierarchy. (To summarize, the key type\n' |
| 4278 | 'should be *hashable*, which excludes all mutable objects.) Clashes\n' |
| 4279 | 'between duplicate keys are not detected; the last datum (textually\n' |
| 4280 | 'rightmost in the display) stored for a given key value prevails.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4281 | 'dynamic-features': 'Interaction with dynamic features\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4282 | '*********************************\n' |
| 4283 | '\n' |
| 4284 | 'Name resolution of free variables occurs at runtime, not ' |
| 4285 | 'at compile\n' |
| 4286 | 'time. This means that the following code will print 42:\n' |
| 4287 | '\n' |
| 4288 | ' i = 10\n' |
| 4289 | ' def f():\n' |
| 4290 | ' print(i)\n' |
| 4291 | ' i = 42\n' |
| 4292 | ' f()\n' |
| 4293 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4294 | 'The "eval()" and "exec()" functions do not have access ' |
| 4295 | 'to the full\n' |
| 4296 | 'environment for resolving names. Names may be resolved ' |
| 4297 | 'in the local\n' |
| 4298 | 'and global namespaces of the caller. Free variables are ' |
| 4299 | 'not resolved\n' |
| 4300 | 'in the nearest enclosing namespace, but in the global ' |
| 4301 | 'namespace. [1]\n' |
| 4302 | 'The "exec()" and "eval()" functions have optional ' |
| 4303 | 'arguments to\n' |
| 4304 | 'override the global and local namespace. If only one ' |
| 4305 | 'namespace is\n' |
| 4306 | 'specified, it is used for both.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4307 | 'else': 'The "if" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4308 | '******************\n' |
| 4309 | '\n' |
| 4310 | 'The "if" statement is used for conditional execution:\n' |
| 4311 | '\n' |
| 4312 | ' if_stmt ::= "if" expression ":" suite\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4313 | ' ("elif" expression ":" suite)*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4314 | ' ["else" ":" suite]\n' |
| 4315 | '\n' |
| 4316 | 'It selects exactly one of the suites by evaluating the expressions ' |
| 4317 | 'one\n' |
| 4318 | 'by one until one is found to be true (see section Boolean ' |
| 4319 | 'operations\n' |
| 4320 | 'for the definition of true and false); then that suite is executed\n' |
| 4321 | '(and no other part of the "if" statement is executed or evaluated).\n' |
| 4322 | 'If all expressions are false, the suite of the "else" clause, if\n' |
| 4323 | 'present, is executed.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4324 | 'exceptions': 'Exceptions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4325 | '**********\n' |
| 4326 | '\n' |
| 4327 | 'Exceptions are a means of breaking out of the normal flow of ' |
| 4328 | 'control\n' |
| 4329 | 'of a code block in order to handle errors or other ' |
| 4330 | 'exceptional\n' |
| 4331 | 'conditions. An exception is *raised* at the point where the ' |
| 4332 | 'error is\n' |
| 4333 | 'detected; it may be *handled* by the surrounding code block or ' |
| 4334 | 'by any\n' |
| 4335 | 'code block that directly or indirectly invoked the code block ' |
| 4336 | 'where\n' |
| 4337 | 'the error occurred.\n' |
| 4338 | '\n' |
| 4339 | 'The Python interpreter raises an exception when it detects a ' |
| 4340 | 'run-time\n' |
| 4341 | 'error (such as division by zero). A Python program can also\n' |
| 4342 | 'explicitly raise an exception with the "raise" statement. ' |
| 4343 | 'Exception\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4344 | 'handlers are specified with the "try" … "except" statement. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4345 | 'The\n' |
| 4346 | '"finally" clause of such a statement can be used to specify ' |
| 4347 | 'cleanup\n' |
| 4348 | 'code which does not handle the exception, but is executed ' |
| 4349 | 'whether an\n' |
| 4350 | 'exception occurred or not in the preceding code.\n' |
| 4351 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4352 | 'Python uses the “termination” model of error handling: an ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4353 | 'exception\n' |
| 4354 | 'handler can find out what happened and continue execution at ' |
| 4355 | 'an outer\n' |
| 4356 | 'level, but it cannot repair the cause of the error and retry ' |
| 4357 | 'the\n' |
| 4358 | 'failing operation (except by re-entering the offending piece ' |
| 4359 | 'of code\n' |
| 4360 | 'from the top).\n' |
| 4361 | '\n' |
| 4362 | 'When an exception is not handled at all, the interpreter ' |
| 4363 | 'terminates\n' |
| 4364 | 'execution of the program, or returns to its interactive main ' |
| 4365 | 'loop. In\n' |
| 4366 | 'either case, it prints a stack backtrace, except when the ' |
| 4367 | 'exception is\n' |
| 4368 | '"SystemExit".\n' |
| 4369 | '\n' |
| 4370 | 'Exceptions are identified by class instances. The "except" ' |
| 4371 | 'clause is\n' |
| 4372 | 'selected depending on the class of the instance: it must ' |
| 4373 | 'reference the\n' |
| 4374 | 'class of the instance or a base class thereof. The instance ' |
| 4375 | 'can be\n' |
| 4376 | 'received by the handler and can carry additional information ' |
| 4377 | 'about the\n' |
| 4378 | 'exceptional condition.\n' |
| 4379 | '\n' |
| 4380 | 'Note: Exception messages are not part of the Python API. ' |
| 4381 | 'Their\n' |
| 4382 | ' contents may change from one version of Python to the next ' |
| 4383 | 'without\n' |
| 4384 | ' warning and should not be relied on by code which will run ' |
| 4385 | 'under\n' |
| 4386 | ' multiple versions of the interpreter.\n' |
| 4387 | '\n' |
| 4388 | 'See also the description of the "try" statement in section The ' |
| 4389 | 'try\n' |
| 4390 | 'statement and "raise" statement in section The raise ' |
| 4391 | 'statement.\n' |
| 4392 | '\n' |
| 4393 | '-[ Footnotes ]-\n' |
| 4394 | '\n' |
| 4395 | '[1] This limitation occurs because the code that is executed ' |
| 4396 | 'by\n' |
| 4397 | ' these operations is not available at the time the module ' |
| 4398 | 'is\n' |
| 4399 | ' compiled.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4400 | 'execmodel': 'Execution model\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4401 | '***************\n' |
| 4402 | '\n' |
| 4403 | '\n' |
| 4404 | 'Structure of a program\n' |
| 4405 | '======================\n' |
| 4406 | '\n' |
| 4407 | 'A Python program is constructed from code blocks. A *block* is ' |
| 4408 | 'a piece\n' |
| 4409 | 'of Python program text that is executed as a unit. The ' |
| 4410 | 'following are\n' |
| 4411 | 'blocks: a module, a function body, and a class definition. ' |
| 4412 | 'Each\n' |
| 4413 | 'command typed interactively is a block. A script file (a file ' |
| 4414 | 'given\n' |
| 4415 | 'as standard input to the interpreter or specified as a command ' |
| 4416 | 'line\n' |
| 4417 | 'argument to the interpreter) is a code block. A script command ' |
| 4418 | '(a\n' |
| 4419 | 'command specified on the interpreter command line with the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4420 | '"-c"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4421 | 'option) is a code block. The string argument passed to the ' |
| 4422 | 'built-in\n' |
| 4423 | 'functions "eval()" and "exec()" is a code block.\n' |
| 4424 | '\n' |
| 4425 | 'A code block is executed in an *execution frame*. A frame ' |
| 4426 | 'contains\n' |
| 4427 | 'some administrative information (used for debugging) and ' |
| 4428 | 'determines\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4429 | 'where and how execution continues after the code block’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4430 | 'execution has\n' |
| 4431 | 'completed.\n' |
| 4432 | '\n' |
| 4433 | '\n' |
| 4434 | 'Naming and binding\n' |
| 4435 | '==================\n' |
| 4436 | '\n' |
| 4437 | '\n' |
| 4438 | 'Binding of names\n' |
| 4439 | '----------------\n' |
| 4440 | '\n' |
| 4441 | '*Names* refer to objects. Names are introduced by name ' |
| 4442 | 'binding\n' |
| 4443 | 'operations.\n' |
| 4444 | '\n' |
| 4445 | 'The following constructs bind names: formal parameters to ' |
| 4446 | 'functions,\n' |
| 4447 | '"import" statements, class and function definitions (these bind ' |
| 4448 | 'the\n' |
| 4449 | 'class or function name in the defining block), and targets that ' |
| 4450 | 'are\n' |
| 4451 | 'identifiers if occurring in an assignment, "for" loop header, ' |
| 4452 | 'or after\n' |
| 4453 | '"as" in a "with" statement or "except" clause. The "import" ' |
| 4454 | 'statement\n' |
| 4455 | 'of the form "from ... import *" binds all names defined in the\n' |
| 4456 | 'imported module, except those beginning with an underscore. ' |
| 4457 | 'This form\n' |
| 4458 | 'may only be used at the module level.\n' |
| 4459 | '\n' |
| 4460 | 'A target occurring in a "del" statement is also considered ' |
| 4461 | 'bound for\n' |
| 4462 | 'this purpose (though the actual semantics are to unbind the ' |
| 4463 | 'name).\n' |
| 4464 | '\n' |
| 4465 | 'Each assignment or import statement occurs within a block ' |
| 4466 | 'defined by a\n' |
| 4467 | 'class or function definition or at the module level (the ' |
| 4468 | 'top-level\n' |
| 4469 | 'code block).\n' |
| 4470 | '\n' |
| 4471 | 'If a name is bound in a block, it is a local variable of that ' |
| 4472 | 'block,\n' |
| 4473 | 'unless declared as "nonlocal" or "global". If a name is bound ' |
| 4474 | 'at the\n' |
| 4475 | 'module level, it is a global variable. (The variables of the ' |
| 4476 | 'module\n' |
| 4477 | 'code block are local and global.) If a variable is used in a ' |
| 4478 | 'code\n' |
| 4479 | 'block but not defined there, it is a *free variable*.\n' |
| 4480 | '\n' |
| 4481 | 'Each occurrence of a name in the program text refers to the ' |
| 4482 | '*binding*\n' |
| 4483 | 'of that name established by the following name resolution ' |
| 4484 | 'rules.\n' |
| 4485 | '\n' |
| 4486 | '\n' |
| 4487 | 'Resolution of names\n' |
| 4488 | '-------------------\n' |
| 4489 | '\n' |
| 4490 | 'A *scope* defines the visibility of a name within a block. If ' |
| 4491 | 'a local\n' |
| 4492 | 'variable is defined in a block, its scope includes that block. ' |
| 4493 | 'If the\n' |
| 4494 | 'definition occurs in a function block, the scope extends to any ' |
| 4495 | 'blocks\n' |
| 4496 | 'contained within the defining one, unless a contained block ' |
| 4497 | 'introduces\n' |
| 4498 | 'a different binding for the name.\n' |
| 4499 | '\n' |
| 4500 | 'When a name is used in a code block, it is resolved using the ' |
| 4501 | 'nearest\n' |
| 4502 | 'enclosing scope. The set of all such scopes visible to a code ' |
| 4503 | 'block\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4504 | 'is called the block’s *environment*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4505 | '\n' |
| 4506 | 'When a name is not found at all, a "NameError" exception is ' |
| 4507 | 'raised. If\n' |
| 4508 | 'the current scope is a function scope, and the name refers to a ' |
| 4509 | 'local\n' |
| 4510 | 'variable that has not yet been bound to a value at the point ' |
| 4511 | 'where the\n' |
| 4512 | 'name is used, an "UnboundLocalError" exception is raised.\n' |
| 4513 | '"UnboundLocalError" is a subclass of "NameError".\n' |
| 4514 | '\n' |
| 4515 | 'If a name binding operation occurs anywhere within a code ' |
| 4516 | 'block, all\n' |
| 4517 | 'uses of the name within the block are treated as references to ' |
| 4518 | 'the\n' |
| 4519 | 'current block. This can lead to errors when a name is used ' |
| 4520 | 'within a\n' |
| 4521 | 'block before it is bound. This rule is subtle. Python lacks\n' |
| 4522 | 'declarations and allows name binding operations to occur ' |
| 4523 | 'anywhere\n' |
| 4524 | 'within a code block. The local variables of a code block can ' |
| 4525 | 'be\n' |
| 4526 | 'determined by scanning the entire text of the block for name ' |
| 4527 | 'binding\n' |
| 4528 | 'operations.\n' |
| 4529 | '\n' |
| 4530 | 'If the "global" statement occurs within a block, all uses of ' |
| 4531 | 'the name\n' |
| 4532 | 'specified in the statement refer to the binding of that name in ' |
| 4533 | 'the\n' |
| 4534 | 'top-level namespace. Names are resolved in the top-level ' |
| 4535 | 'namespace by\n' |
| 4536 | 'searching the global namespace, i.e. the namespace of the ' |
| 4537 | 'module\n' |
| 4538 | 'containing the code block, and the builtins namespace, the ' |
| 4539 | 'namespace\n' |
| 4540 | 'of the module "builtins". The global namespace is searched ' |
| 4541 | 'first. If\n' |
| 4542 | 'the name is not found there, the builtins namespace is ' |
| 4543 | 'searched. The\n' |
| 4544 | '"global" statement must precede all uses of the name.\n' |
| 4545 | '\n' |
| 4546 | 'The "global" statement has the same scope as a name binding ' |
| 4547 | 'operation\n' |
| 4548 | 'in the same block. If the nearest enclosing scope for a free ' |
| 4549 | 'variable\n' |
| 4550 | 'contains a global statement, the free variable is treated as a ' |
| 4551 | 'global.\n' |
| 4552 | '\n' |
| 4553 | 'The "nonlocal" statement causes corresponding names to refer ' |
| 4554 | 'to\n' |
| 4555 | 'previously bound variables in the nearest enclosing function ' |
| 4556 | 'scope.\n' |
| 4557 | '"SyntaxError" is raised at compile time if the given name does ' |
| 4558 | 'not\n' |
| 4559 | 'exist in any enclosing function scope.\n' |
| 4560 | '\n' |
| 4561 | 'The namespace for a module is automatically created the first ' |
| 4562 | 'time a\n' |
| 4563 | 'module is imported. The main module for a script is always ' |
| 4564 | 'called\n' |
| 4565 | '"__main__".\n' |
| 4566 | '\n' |
| 4567 | 'Class definition blocks and arguments to "exec()" and "eval()" ' |
| 4568 | 'are\n' |
| 4569 | 'special in the context of name resolution. A class definition ' |
| 4570 | 'is an\n' |
| 4571 | 'executable statement that may use and define names. These ' |
| 4572 | 'references\n' |
| 4573 | 'follow the normal rules for name resolution with an exception ' |
| 4574 | 'that\n' |
| 4575 | 'unbound local variables are looked up in the global namespace. ' |
| 4576 | 'The\n' |
| 4577 | 'namespace of the class definition becomes the attribute ' |
| 4578 | 'dictionary of\n' |
| 4579 | 'the class. The scope of names defined in a class block is ' |
| 4580 | 'limited to\n' |
| 4581 | 'the class block; it does not extend to the code blocks of ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4582 | 'methods –\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4583 | 'this includes comprehensions and generator expressions since ' |
| 4584 | 'they are\n' |
| 4585 | 'implemented using a function scope. This means that the ' |
| 4586 | 'following\n' |
| 4587 | 'will fail:\n' |
| 4588 | '\n' |
| 4589 | ' class A:\n' |
| 4590 | ' a = 42\n' |
| 4591 | ' b = list(a + i for i in range(10))\n' |
| 4592 | '\n' |
| 4593 | '\n' |
| 4594 | 'Builtins and restricted execution\n' |
| 4595 | '---------------------------------\n' |
| 4596 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4597 | '**CPython implementation detail:** Users should not touch\n' |
| 4598 | '"__builtins__"; it is strictly an implementation detail. ' |
| 4599 | 'Users\n' |
| 4600 | 'wanting to override values in the builtins namespace should ' |
| 4601 | '"import"\n' |
| 4602 | 'the "builtins" module and modify its attributes appropriately.\n' |
| 4603 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4604 | 'The builtins namespace associated with the execution of a code ' |
| 4605 | 'block\n' |
| 4606 | 'is actually found by looking up the name "__builtins__" in its ' |
| 4607 | 'global\n' |
| 4608 | 'namespace; this should be a dictionary or a module (in the ' |
| 4609 | 'latter case\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4610 | 'the module’s dictionary is used). By default, when in the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4611 | '"__main__"\n' |
| 4612 | 'module, "__builtins__" is the built-in module "builtins"; when ' |
| 4613 | 'in any\n' |
| 4614 | 'other module, "__builtins__" is an alias for the dictionary of ' |
| 4615 | 'the\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4616 | '"builtins" module itself.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4617 | '\n' |
| 4618 | '\n' |
| 4619 | 'Interaction with dynamic features\n' |
| 4620 | '---------------------------------\n' |
| 4621 | '\n' |
| 4622 | 'Name resolution of free variables occurs at runtime, not at ' |
| 4623 | 'compile\n' |
| 4624 | 'time. This means that the following code will print 42:\n' |
| 4625 | '\n' |
| 4626 | ' i = 10\n' |
| 4627 | ' def f():\n' |
| 4628 | ' print(i)\n' |
| 4629 | ' i = 42\n' |
| 4630 | ' f()\n' |
| 4631 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4632 | 'The "eval()" and "exec()" functions do not have access to the ' |
| 4633 | 'full\n' |
| 4634 | 'environment for resolving names. Names may be resolved in the ' |
| 4635 | 'local\n' |
| 4636 | 'and global namespaces of the caller. Free variables are not ' |
| 4637 | 'resolved\n' |
| 4638 | 'in the nearest enclosing namespace, but in the global ' |
| 4639 | 'namespace. [1]\n' |
| 4640 | 'The "exec()" and "eval()" functions have optional arguments to\n' |
| 4641 | 'override the global and local namespace. If only one namespace ' |
| 4642 | 'is\n' |
| 4643 | 'specified, it is used for both.\n' |
| 4644 | '\n' |
| 4645 | '\n' |
| 4646 | 'Exceptions\n' |
| 4647 | '==========\n' |
| 4648 | '\n' |
| 4649 | 'Exceptions are a means of breaking out of the normal flow of ' |
| 4650 | 'control\n' |
| 4651 | 'of a code block in order to handle errors or other exceptional\n' |
| 4652 | 'conditions. An exception is *raised* at the point where the ' |
| 4653 | 'error is\n' |
| 4654 | 'detected; it may be *handled* by the surrounding code block or ' |
| 4655 | 'by any\n' |
| 4656 | 'code block that directly or indirectly invoked the code block ' |
| 4657 | 'where\n' |
| 4658 | 'the error occurred.\n' |
| 4659 | '\n' |
| 4660 | 'The Python interpreter raises an exception when it detects a ' |
| 4661 | 'run-time\n' |
| 4662 | 'error (such as division by zero). A Python program can also\n' |
| 4663 | 'explicitly raise an exception with the "raise" statement. ' |
| 4664 | 'Exception\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4665 | 'handlers are specified with the "try" … "except" statement. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4666 | 'The\n' |
| 4667 | '"finally" clause of such a statement can be used to specify ' |
| 4668 | 'cleanup\n' |
| 4669 | 'code which does not handle the exception, but is executed ' |
| 4670 | 'whether an\n' |
| 4671 | 'exception occurred or not in the preceding code.\n' |
| 4672 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4673 | 'Python uses the “termination” model of error handling: an ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4674 | 'exception\n' |
| 4675 | 'handler can find out what happened and continue execution at an ' |
| 4676 | 'outer\n' |
| 4677 | 'level, but it cannot repair the cause of the error and retry ' |
| 4678 | 'the\n' |
| 4679 | 'failing operation (except by re-entering the offending piece of ' |
| 4680 | 'code\n' |
| 4681 | 'from the top).\n' |
| 4682 | '\n' |
| 4683 | 'When an exception is not handled at all, the interpreter ' |
| 4684 | 'terminates\n' |
| 4685 | 'execution of the program, or returns to its interactive main ' |
| 4686 | 'loop. In\n' |
| 4687 | 'either case, it prints a stack backtrace, except when the ' |
| 4688 | 'exception is\n' |
| 4689 | '"SystemExit".\n' |
| 4690 | '\n' |
| 4691 | 'Exceptions are identified by class instances. The "except" ' |
| 4692 | 'clause is\n' |
| 4693 | 'selected depending on the class of the instance: it must ' |
| 4694 | 'reference the\n' |
| 4695 | 'class of the instance or a base class thereof. The instance ' |
| 4696 | 'can be\n' |
| 4697 | 'received by the handler and can carry additional information ' |
| 4698 | 'about the\n' |
| 4699 | 'exceptional condition.\n' |
| 4700 | '\n' |
| 4701 | 'Note: Exception messages are not part of the Python API. ' |
| 4702 | 'Their\n' |
| 4703 | ' contents may change from one version of Python to the next ' |
| 4704 | 'without\n' |
| 4705 | ' warning and should not be relied on by code which will run ' |
| 4706 | 'under\n' |
| 4707 | ' multiple versions of the interpreter.\n' |
| 4708 | '\n' |
| 4709 | 'See also the description of the "try" statement in section The ' |
| 4710 | 'try\n' |
| 4711 | 'statement and "raise" statement in section The raise ' |
| 4712 | 'statement.\n' |
| 4713 | '\n' |
| 4714 | '-[ Footnotes ]-\n' |
| 4715 | '\n' |
| 4716 | '[1] This limitation occurs because the code that is executed ' |
| 4717 | 'by\n' |
| 4718 | ' these operations is not available at the time the module ' |
| 4719 | 'is\n' |
| 4720 | ' compiled.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4721 | 'exprlists': 'Expression lists\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4722 | '****************\n' |
| 4723 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4724 | ' expression_list ::= expression ("," expression)* [","]\n' |
| 4725 | ' starred_list ::= starred_item ("," starred_item)* ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4726 | '[","]\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4727 | ' starred_expression ::= expression | (starred_item ",")* ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4728 | '[starred_item]\n' |
| 4729 | ' starred_item ::= expression | "*" or_expr\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4730 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4731 | 'Except when part of a list or set display, an expression list\n' |
| 4732 | 'containing at least one comma yields a tuple. The length of ' |
| 4733 | 'the tuple\n' |
| 4734 | 'is the number of expressions in the list. The expressions are\n' |
| 4735 | 'evaluated from left to right.\n' |
| 4736 | '\n' |
| 4737 | 'An asterisk "*" denotes *iterable unpacking*. Its operand must ' |
| 4738 | 'be an\n' |
| 4739 | '*iterable*. The iterable is expanded into a sequence of items, ' |
| 4740 | 'which\n' |
| 4741 | 'are included in the new tuple, list, or set, at the site of ' |
| 4742 | 'the\n' |
| 4743 | 'unpacking.\n' |
| 4744 | '\n' |
| 4745 | 'New in version 3.5: Iterable unpacking in expression lists, ' |
| 4746 | 'originally\n' |
| 4747 | 'proposed by **PEP 448**.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4748 | '\n' |
| 4749 | 'The trailing comma is required only to create a single tuple ' |
| 4750 | '(a.k.a. a\n' |
| 4751 | '*singleton*); it is optional in all other cases. A single ' |
| 4752 | 'expression\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4753 | 'without a trailing comma doesn’t create a tuple, but rather ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4754 | 'yields the\n' |
| 4755 | 'value of that expression. (To create an empty tuple, use an ' |
| 4756 | 'empty pair\n' |
| 4757 | 'of parentheses: "()".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4758 | 'floating': 'Floating point literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4759 | '***********************\n' |
| 4760 | '\n' |
| 4761 | 'Floating point literals are described by the following lexical\n' |
| 4762 | 'definitions:\n' |
| 4763 | '\n' |
| 4764 | ' floatnumber ::= pointfloat | exponentfloat\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4765 | ' pointfloat ::= [digitpart] fraction | digitpart "."\n' |
| 4766 | ' exponentfloat ::= (digitpart | pointfloat) exponent\n' |
| 4767 | ' digitpart ::= digit (["_"] digit)*\n' |
| 4768 | ' fraction ::= "." digitpart\n' |
| 4769 | ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4770 | '\n' |
| 4771 | 'Note that the integer and exponent parts are always interpreted ' |
| 4772 | 'using\n' |
| 4773 | 'radix 10. For example, "077e010" is legal, and denotes the same ' |
| 4774 | 'number\n' |
| 4775 | 'as "77e10". The allowed range of floating point literals is\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4776 | 'implementation-dependent. As in integer literals, underscores ' |
| 4777 | 'are\n' |
| 4778 | 'supported for digit grouping.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4779 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4780 | 'Some examples of floating point literals:\n' |
| 4781 | '\n' |
| 4782 | ' 3.14 10. .001 1e100 3.14e-10 0e0 ' |
| 4783 | '3.14_15_93\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4784 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4785 | 'Changed in version 3.6: Underscores are now allowed for ' |
| 4786 | 'grouping\n' |
| 4787 | 'purposes in literals.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4788 | 'for': 'The "for" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4789 | '*******************\n' |
| 4790 | '\n' |
| 4791 | 'The "for" statement is used to iterate over the elements of a ' |
| 4792 | 'sequence\n' |
| 4793 | '(such as a string, tuple or list) or other iterable object:\n' |
| 4794 | '\n' |
| 4795 | ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' |
| 4796 | ' ["else" ":" suite]\n' |
| 4797 | '\n' |
| 4798 | 'The expression list is evaluated once; it should yield an iterable\n' |
| 4799 | 'object. An iterator is created for the result of the\n' |
| 4800 | '"expression_list". The suite is then executed once for each item\n' |
| 4801 | 'provided by the iterator, in the order returned by the iterator. ' |
| 4802 | 'Each\n' |
| 4803 | 'item in turn is assigned to the target list using the standard rules\n' |
| 4804 | 'for assignments (see Assignment statements), and then the suite is\n' |
| 4805 | 'executed. When the items are exhausted (which is immediately when ' |
| 4806 | 'the\n' |
| 4807 | 'sequence is empty or an iterator raises a "StopIteration" ' |
| 4808 | 'exception),\n' |
| 4809 | 'the suite in the "else" clause, if present, is executed, and the ' |
| 4810 | 'loop\n' |
| 4811 | 'terminates.\n' |
| 4812 | '\n' |
| 4813 | 'A "break" statement executed in the first suite terminates the loop\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4814 | 'without executing the "else" clause’s suite. A "continue" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4815 | 'executed in the first suite skips the rest of the suite and ' |
| 4816 | 'continues\n' |
| 4817 | 'with the next item, or with the "else" clause if there is no next\n' |
| 4818 | 'item.\n' |
| 4819 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4820 | 'The for-loop makes assignments to the variables in the target list.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4821 | 'This overwrites all previous assignments to those variables ' |
| 4822 | 'including\n' |
| 4823 | 'those made in the suite of the for-loop:\n' |
| 4824 | '\n' |
| 4825 | ' for i in range(10):\n' |
| 4826 | ' print(i)\n' |
| 4827 | ' i = 5 # this will not affect the for-loop\n' |
| 4828 | ' # because i will be overwritten with the ' |
| 4829 | 'next\n' |
| 4830 | ' # index in the range\n' |
| 4831 | '\n' |
| 4832 | 'Names in the target list are not deleted when the loop is finished,\n' |
| 4833 | 'but if the sequence is empty, they will not have been assigned to at\n' |
| 4834 | 'all by the loop. Hint: the built-in function "range()" returns an\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4835 | 'iterator of integers suitable to emulate the effect of Pascal’s "for ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4836 | 'i\n' |
| 4837 | ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n' |
| 4838 | '\n' |
| 4839 | 'Note: There is a subtlety when the sequence is being modified by the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4840 | ' loop (this can only occur for mutable sequences, e.g. lists). An\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4841 | ' internal counter is used to keep track of which item is used next,\n' |
| 4842 | ' and this is incremented on each iteration. When this counter has\n' |
| 4843 | ' reached the length of the sequence the loop terminates. This ' |
| 4844 | 'means\n' |
| 4845 | ' that if the suite deletes the current (or a previous) item from ' |
| 4846 | 'the\n' |
| 4847 | ' sequence, the next item will be skipped (since it gets the index ' |
| 4848 | 'of\n' |
| 4849 | ' the current item which has already been treated). Likewise, if ' |
| 4850 | 'the\n' |
| 4851 | ' suite inserts an item in the sequence before the current item, the\n' |
| 4852 | ' current item will be treated again the next time through the loop.\n' |
| 4853 | ' This can lead to nasty bugs that can be avoided by making a\n' |
| 4854 | ' temporary copy using a slice of the whole sequence, e.g.,\n' |
| 4855 | '\n' |
| 4856 | ' for x in a[:]:\n' |
| 4857 | ' if x < 0: a.remove(x)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4858 | 'formatstrings': 'Format String Syntax\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4859 | '********************\n' |
| 4860 | '\n' |
| 4861 | 'The "str.format()" method and the "Formatter" class share ' |
| 4862 | 'the same\n' |
| 4863 | 'syntax for format strings (although in the case of ' |
| 4864 | '"Formatter",\n' |
| 4865 | 'subclasses can define their own format string syntax). The ' |
| 4866 | 'syntax is\n' |
| 4867 | 'related to that of formatted string literals, but there ' |
| 4868 | 'are\n' |
| 4869 | 'differences.\n' |
| 4870 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4871 | 'Format strings contain “replacement fields” surrounded by ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4872 | 'curly braces\n' |
| 4873 | '"{}". Anything that is not contained in braces is ' |
| 4874 | 'considered literal\n' |
| 4875 | 'text, which is copied unchanged to the output. If you need ' |
| 4876 | 'to include\n' |
| 4877 | 'a brace character in the literal text, it can be escaped by ' |
| 4878 | 'doubling:\n' |
| 4879 | '"{{" and "}}".\n' |
| 4880 | '\n' |
| 4881 | 'The grammar for a replacement field is as follows:\n' |
| 4882 | '\n' |
| 4883 | ' replacement_field ::= "{" [field_name] ["!" ' |
| 4884 | 'conversion] [":" format_spec] "}"\n' |
| 4885 | ' field_name ::= arg_name ("." attribute_name | ' |
| 4886 | '"[" element_index "]")*\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4887 | ' arg_name ::= [identifier | digit+]\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4888 | ' attribute_name ::= identifier\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4889 | ' element_index ::= digit+ | index_string\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4890 | ' index_string ::= <any source character except ' |
| 4891 | '"]"> +\n' |
| 4892 | ' conversion ::= "r" | "s" | "a"\n' |
| 4893 | ' format_spec ::= <described in the next ' |
| 4894 | 'section>\n' |
| 4895 | '\n' |
| 4896 | 'In less formal terms, the replacement field can start with ' |
| 4897 | 'a\n' |
| 4898 | '*field_name* that specifies the object whose value is to be ' |
| 4899 | 'formatted\n' |
| 4900 | 'and inserted into the output instead of the replacement ' |
| 4901 | 'field. The\n' |
| 4902 | '*field_name* is optionally followed by a *conversion* ' |
| 4903 | 'field, which is\n' |
| 4904 | 'preceded by an exclamation point "\'!\'", and a ' |
| 4905 | '*format_spec*, which is\n' |
| 4906 | 'preceded by a colon "\':\'". These specify a non-default ' |
| 4907 | 'format for the\n' |
| 4908 | 'replacement value.\n' |
| 4909 | '\n' |
| 4910 | 'See also the Format Specification Mini-Language section.\n' |
| 4911 | '\n' |
| 4912 | 'The *field_name* itself begins with an *arg_name* that is ' |
| 4913 | 'either a\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4914 | 'number or a keyword. If it’s a number, it refers to a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4915 | 'positional\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4916 | 'argument, and if it’s a keyword, it refers to a named ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4917 | 'keyword\n' |
| 4918 | 'argument. If the numerical arg_names in a format string ' |
| 4919 | 'are 0, 1, 2,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4920 | '… in sequence, they can all be omitted (not just some) and ' |
| 4921 | 'the numbers\n' |
| 4922 | '0, 1, 2, … will be automatically inserted in that order. ' |
| 4923 | 'Because\n' |
| 4924 | '*arg_name* is not quote-delimited, it is not possible to ' |
| 4925 | 'specify\n' |
| 4926 | 'arbitrary dictionary keys (e.g., the strings "\'10\'" or ' |
| 4927 | '"\':-]\'") within\n' |
| 4928 | 'a format string. The *arg_name* can be followed by any ' |
| 4929 | 'number of index\n' |
| 4930 | 'or attribute expressions. An expression of the form ' |
| 4931 | '"\'.name\'" selects\n' |
| 4932 | 'the named attribute using "getattr()", while an expression ' |
| 4933 | 'of the form\n' |
| 4934 | '"\'[index]\'" does an index lookup using "__getitem__()".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4935 | '\n' |
| 4936 | 'Changed in version 3.1: The positional argument specifiers ' |
| 4937 | 'can be\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4938 | 'omitted for "str.format()", so "\'{} {}\'.format(a, b)" is ' |
| 4939 | 'equivalent to\n' |
| 4940 | '"\'{0} {1}\'.format(a, b)".\n' |
| 4941 | '\n' |
| 4942 | 'Changed in version 3.4: The positional argument specifiers ' |
| 4943 | 'can be\n' |
| 4944 | 'omitted for "Formatter".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4945 | '\n' |
| 4946 | 'Some simple format string examples:\n' |
| 4947 | '\n' |
| 4948 | ' "First, thou shalt count to {0}" # References first ' |
| 4949 | 'positional argument\n' |
| 4950 | ' "Bring me a {}" # Implicitly ' |
| 4951 | 'references the first positional argument\n' |
| 4952 | ' "From {} to {}" # Same as "From {0} to ' |
| 4953 | '{1}"\n' |
| 4954 | ' "My quest is {name}" # References keyword ' |
| 4955 | "argument 'name'\n" |
| 4956 | ' "Weight in tons {0.weight}" # \'weight\' attribute ' |
| 4957 | 'of first positional arg\n' |
| 4958 | ' "Units destroyed: {players[0]}" # First element of ' |
| 4959 | "keyword argument 'players'.\n" |
| 4960 | '\n' |
| 4961 | 'The *conversion* field causes a type coercion before ' |
| 4962 | 'formatting.\n' |
| 4963 | 'Normally, the job of formatting a value is done by the ' |
| 4964 | '"__format__()"\n' |
| 4965 | 'method of the value itself. However, in some cases it is ' |
| 4966 | 'desirable to\n' |
| 4967 | 'force a type to be formatted as a string, overriding its ' |
| 4968 | 'own\n' |
| 4969 | 'definition of formatting. By converting the value to a ' |
| 4970 | 'string before\n' |
| 4971 | 'calling "__format__()", the normal formatting logic is ' |
| 4972 | 'bypassed.\n' |
| 4973 | '\n' |
| 4974 | 'Three conversion flags are currently supported: "\'!s\'" ' |
| 4975 | 'which calls\n' |
| 4976 | '"str()" on the value, "\'!r\'" which calls "repr()" and ' |
| 4977 | '"\'!a\'" which\n' |
| 4978 | 'calls "ascii()".\n' |
| 4979 | '\n' |
| 4980 | 'Some examples:\n' |
| 4981 | '\n' |
| 4982 | ' "Harold\'s a clever {0!s}" # Calls str() on the ' |
| 4983 | 'argument first\n' |
| 4984 | ' "Bring out the holy {name!r}" # Calls repr() on the ' |
| 4985 | 'argument first\n' |
| 4986 | ' "More {!a}" # Calls ascii() on the ' |
| 4987 | 'argument first\n' |
| 4988 | '\n' |
| 4989 | 'The *format_spec* field contains a specification of how the ' |
| 4990 | 'value\n' |
| 4991 | 'should be presented, including such details as field width, ' |
| 4992 | 'alignment,\n' |
| 4993 | 'padding, decimal precision and so on. Each value type can ' |
| 4994 | 'define its\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 4995 | 'own “formatting mini-language” or interpretation of the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4996 | '*format_spec*.\n' |
| 4997 | '\n' |
| 4998 | 'Most built-in types support a common formatting ' |
| 4999 | 'mini-language, which\n' |
| 5000 | 'is described in the next section.\n' |
| 5001 | '\n' |
| 5002 | 'A *format_spec* field can also include nested replacement ' |
| 5003 | 'fields\n' |
| 5004 | 'within it. These nested replacement fields may contain a ' |
| 5005 | 'field name,\n' |
| 5006 | 'conversion flag and format specification, but deeper ' |
| 5007 | 'nesting is not\n' |
| 5008 | 'allowed. The replacement fields within the format_spec ' |
| 5009 | 'are\n' |
| 5010 | 'substituted before the *format_spec* string is interpreted. ' |
| 5011 | 'This\n' |
| 5012 | 'allows the formatting of a value to be dynamically ' |
| 5013 | 'specified.\n' |
| 5014 | '\n' |
| 5015 | 'See the Format examples section for some examples.\n' |
| 5016 | '\n' |
| 5017 | '\n' |
| 5018 | 'Format Specification Mini-Language\n' |
| 5019 | '==================================\n' |
| 5020 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5021 | '“Format specifications” are used within replacement fields ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5022 | 'contained\n' |
| 5023 | 'within a format string to define how individual values are ' |
| 5024 | 'presented\n' |
| 5025 | '(see Format String Syntax and Formatted string literals). ' |
| 5026 | 'They can\n' |
| 5027 | 'also be passed directly to the built-in "format()" ' |
| 5028 | 'function. Each\n' |
| 5029 | 'formattable type may define how the format specification is ' |
| 5030 | 'to be\n' |
| 5031 | 'interpreted.\n' |
| 5032 | '\n' |
| 5033 | 'Most built-in types implement the following options for ' |
| 5034 | 'format\n' |
| 5035 | 'specifications, although some of the formatting options are ' |
| 5036 | 'only\n' |
| 5037 | 'supported by the numeric types.\n' |
| 5038 | '\n' |
| 5039 | 'A general convention is that an empty format string ("""") ' |
| 5040 | 'produces\n' |
| 5041 | 'the same result as if you had called "str()" on the value. ' |
| 5042 | 'A non-empty\n' |
| 5043 | 'format string typically modifies the result.\n' |
| 5044 | '\n' |
| 5045 | 'The general form of a *standard format specifier* is:\n' |
| 5046 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5047 | ' format_spec ::= ' |
| 5048 | '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n' |
| 5049 | ' fill ::= <any character>\n' |
| 5050 | ' align ::= "<" | ">" | "=" | "^"\n' |
| 5051 | ' sign ::= "+" | "-" | " "\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5052 | ' width ::= digit+\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5053 | ' grouping_option ::= "_" | ","\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5054 | ' precision ::= digit+\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5055 | ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' |
| 5056 | '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5057 | '\n' |
| 5058 | 'If a valid *align* value is specified, it can be preceded ' |
| 5059 | 'by a *fill*\n' |
| 5060 | 'character that can be any character and defaults to a space ' |
| 5061 | 'if\n' |
| 5062 | 'omitted. It is not possible to use a literal curly brace ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5063 | '(“"{"” or\n' |
| 5064 | '“"}"”) as the *fill* character in a formatted string ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5065 | 'literal or when\n' |
| 5066 | 'using the "str.format()" method. However, it is possible ' |
| 5067 | 'to insert a\n' |
| 5068 | 'curly brace with a nested replacement field. This ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5069 | 'limitation doesn’t\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5070 | 'affect the "format()" function.\n' |
| 5071 | '\n' |
| 5072 | 'The meaning of the various alignment options is as ' |
| 5073 | 'follows:\n' |
| 5074 | '\n' |
| 5075 | ' ' |
| 5076 | '+-----------+------------------------------------------------------------+\n' |
| 5077 | ' | Option | ' |
| 5078 | 'Meaning ' |
| 5079 | '|\n' |
| 5080 | ' ' |
| 5081 | '+===========+============================================================+\n' |
| 5082 | ' | "\'<\'" | Forces the field to be left-aligned ' |
| 5083 | 'within the available |\n' |
| 5084 | ' | | space (this is the default for most ' |
| 5085 | 'objects). |\n' |
| 5086 | ' ' |
| 5087 | '+-----------+------------------------------------------------------------+\n' |
| 5088 | ' | "\'>\'" | Forces the field to be right-aligned ' |
| 5089 | 'within the available |\n' |
| 5090 | ' | | space (this is the default for ' |
| 5091 | 'numbers). |\n' |
| 5092 | ' ' |
| 5093 | '+-----------+------------------------------------------------------------+\n' |
| 5094 | ' | "\'=\'" | Forces the padding to be placed after ' |
| 5095 | 'the sign (if any) |\n' |
| 5096 | ' | | but before the digits. This is used for ' |
| 5097 | 'printing fields |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5098 | ' | | in the form ‘+000000120’. This alignment ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5099 | 'option is only |\n' |
| 5100 | ' | | valid for numeric types. It becomes the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5101 | 'default when ‘0’ |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5102 | ' | | immediately precedes the field ' |
| 5103 | 'width. |\n' |
| 5104 | ' ' |
| 5105 | '+-----------+------------------------------------------------------------+\n' |
| 5106 | ' | "\'^\'" | Forces the field to be centered within ' |
| 5107 | 'the available |\n' |
| 5108 | ' | | ' |
| 5109 | 'space. ' |
| 5110 | '|\n' |
| 5111 | ' ' |
| 5112 | '+-----------+------------------------------------------------------------+\n' |
| 5113 | '\n' |
| 5114 | 'Note that unless a minimum field width is defined, the ' |
| 5115 | 'field width\n' |
| 5116 | 'will always be the same size as the data to fill it, so ' |
| 5117 | 'that the\n' |
| 5118 | 'alignment option has no meaning in this case.\n' |
| 5119 | '\n' |
| 5120 | 'The *sign* option is only valid for number types, and can ' |
| 5121 | 'be one of\n' |
| 5122 | 'the following:\n' |
| 5123 | '\n' |
| 5124 | ' ' |
| 5125 | '+-----------+------------------------------------------------------------+\n' |
| 5126 | ' | Option | ' |
| 5127 | 'Meaning ' |
| 5128 | '|\n' |
| 5129 | ' ' |
| 5130 | '+===========+============================================================+\n' |
| 5131 | ' | "\'+\'" | indicates that a sign should be used for ' |
| 5132 | 'both positive as |\n' |
| 5133 | ' | | well as negative ' |
| 5134 | 'numbers. |\n' |
| 5135 | ' ' |
| 5136 | '+-----------+------------------------------------------------------------+\n' |
| 5137 | ' | "\'-\'" | indicates that a sign should be used ' |
| 5138 | 'only for negative |\n' |
| 5139 | ' | | numbers (this is the default ' |
| 5140 | 'behavior). |\n' |
| 5141 | ' ' |
| 5142 | '+-----------+------------------------------------------------------------+\n' |
| 5143 | ' | space | indicates that a leading space should be ' |
| 5144 | 'used on positive |\n' |
| 5145 | ' | | numbers, and a minus sign on negative ' |
| 5146 | 'numbers. |\n' |
| 5147 | ' ' |
| 5148 | '+-----------+------------------------------------------------------------+\n' |
| 5149 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5150 | 'The "\'#\'" option causes the “alternate form” to be used ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5151 | 'for the\n' |
| 5152 | 'conversion. The alternate form is defined differently for ' |
| 5153 | 'different\n' |
| 5154 | 'types. This option is only valid for integer, float, ' |
| 5155 | 'complex and\n' |
| 5156 | 'Decimal types. For integers, when binary, octal, or ' |
| 5157 | 'hexadecimal output\n' |
| 5158 | 'is used, this option adds the prefix respective "\'0b\'", ' |
| 5159 | '"\'0o\'", or\n' |
| 5160 | '"\'0x\'" to the output value. For floats, complex and ' |
| 5161 | 'Decimal the\n' |
| 5162 | 'alternate form causes the result of the conversion to ' |
| 5163 | 'always contain a\n' |
| 5164 | 'decimal-point character, even if no digits follow it. ' |
| 5165 | 'Normally, a\n' |
| 5166 | 'decimal-point character appears in the result of these ' |
| 5167 | 'conversions\n' |
| 5168 | 'only if a digit follows it. In addition, for "\'g\'" and ' |
| 5169 | '"\'G\'"\n' |
| 5170 | 'conversions, trailing zeros are not removed from the ' |
| 5171 | 'result.\n' |
| 5172 | '\n' |
| 5173 | 'The "\',\'" option signals the use of a comma for a ' |
| 5174 | 'thousands separator.\n' |
| 5175 | 'For a locale aware separator, use the "\'n\'" integer ' |
| 5176 | 'presentation type\n' |
| 5177 | 'instead.\n' |
| 5178 | '\n' |
| 5179 | 'Changed in version 3.1: Added the "\',\'" option (see also ' |
| 5180 | '**PEP 378**).\n' |
| 5181 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5182 | 'The "\'_\'" option signals the use of an underscore for a ' |
| 5183 | 'thousands\n' |
| 5184 | 'separator for floating point presentation types and for ' |
| 5185 | 'integer\n' |
| 5186 | 'presentation type "\'d\'". For integer presentation types ' |
| 5187 | '"\'b\'", "\'o\'",\n' |
| 5188 | '"\'x\'", and "\'X\'", underscores will be inserted every 4 ' |
| 5189 | 'digits. For\n' |
| 5190 | 'other presentation types, specifying this option is an ' |
| 5191 | 'error.\n' |
| 5192 | '\n' |
| 5193 | 'Changed in version 3.6: Added the "\'_\'" option (see also ' |
| 5194 | '**PEP 515**).\n' |
| 5195 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5196 | '*width* is a decimal integer defining the minimum field ' |
| 5197 | 'width. If not\n' |
| 5198 | 'specified, then the field width will be determined by the ' |
| 5199 | 'content.\n' |
| 5200 | '\n' |
| 5201 | 'When no explicit alignment is given, preceding the *width* ' |
| 5202 | 'field by a\n' |
| 5203 | 'zero ("\'0\'") character enables sign-aware zero-padding ' |
| 5204 | 'for numeric\n' |
| 5205 | 'types. This is equivalent to a *fill* character of "\'0\'" ' |
| 5206 | 'with an\n' |
| 5207 | '*alignment* type of "\'=\'".\n' |
| 5208 | '\n' |
| 5209 | 'The *precision* is a decimal number indicating how many ' |
| 5210 | 'digits should\n' |
| 5211 | 'be displayed after the decimal point for a floating point ' |
| 5212 | 'value\n' |
| 5213 | 'formatted with "\'f\'" and "\'F\'", or before and after the ' |
| 5214 | 'decimal point\n' |
| 5215 | 'for a floating point value formatted with "\'g\'" or ' |
| 5216 | '"\'G\'". For non-\n' |
| 5217 | 'number types the field indicates the maximum field size - ' |
| 5218 | 'in other\n' |
| 5219 | 'words, how many characters will be used from the field ' |
| 5220 | 'content. The\n' |
| 5221 | '*precision* is not allowed for integer values.\n' |
| 5222 | '\n' |
| 5223 | 'Finally, the *type* determines how the data should be ' |
| 5224 | 'presented.\n' |
| 5225 | '\n' |
| 5226 | 'The available string presentation types are:\n' |
| 5227 | '\n' |
| 5228 | ' ' |
| 5229 | '+-----------+------------------------------------------------------------+\n' |
| 5230 | ' | Type | ' |
| 5231 | 'Meaning ' |
| 5232 | '|\n' |
| 5233 | ' ' |
| 5234 | '+===========+============================================================+\n' |
| 5235 | ' | "\'s\'" | String format. This is the default type ' |
| 5236 | 'for strings and |\n' |
| 5237 | ' | | may be ' |
| 5238 | 'omitted. |\n' |
| 5239 | ' ' |
| 5240 | '+-----------+------------------------------------------------------------+\n' |
| 5241 | ' | None | The same as ' |
| 5242 | '"\'s\'". |\n' |
| 5243 | ' ' |
| 5244 | '+-----------+------------------------------------------------------------+\n' |
| 5245 | '\n' |
| 5246 | 'The available integer presentation types are:\n' |
| 5247 | '\n' |
| 5248 | ' ' |
| 5249 | '+-----------+------------------------------------------------------------+\n' |
| 5250 | ' | Type | ' |
| 5251 | 'Meaning ' |
| 5252 | '|\n' |
| 5253 | ' ' |
| 5254 | '+===========+============================================================+\n' |
| 5255 | ' | "\'b\'" | Binary format. Outputs the number in ' |
| 5256 | 'base 2. |\n' |
| 5257 | ' ' |
| 5258 | '+-----------+------------------------------------------------------------+\n' |
| 5259 | ' | "\'c\'" | Character. Converts the integer to the ' |
| 5260 | 'corresponding |\n' |
| 5261 | ' | | unicode character before ' |
| 5262 | 'printing. |\n' |
| 5263 | ' ' |
| 5264 | '+-----------+------------------------------------------------------------+\n' |
| 5265 | ' | "\'d\'" | Decimal Integer. Outputs the number in ' |
| 5266 | 'base 10. |\n' |
| 5267 | ' ' |
| 5268 | '+-----------+------------------------------------------------------------+\n' |
| 5269 | ' | "\'o\'" | Octal format. Outputs the number in base ' |
| 5270 | '8. |\n' |
| 5271 | ' ' |
| 5272 | '+-----------+------------------------------------------------------------+\n' |
| 5273 | ' | "\'x\'" | Hex format. Outputs the number in base ' |
| 5274 | '16, using lower- |\n' |
| 5275 | ' | | case letters for the digits above ' |
| 5276 | '9. |\n' |
| 5277 | ' ' |
| 5278 | '+-----------+------------------------------------------------------------+\n' |
| 5279 | ' | "\'X\'" | Hex format. Outputs the number in base ' |
| 5280 | '16, using upper- |\n' |
| 5281 | ' | | case letters for the digits above ' |
| 5282 | '9. |\n' |
| 5283 | ' ' |
| 5284 | '+-----------+------------------------------------------------------------+\n' |
| 5285 | ' | "\'n\'" | Number. This is the same as "\'d\'", ' |
| 5286 | 'except that it uses the |\n' |
| 5287 | ' | | current locale setting to insert the ' |
| 5288 | 'appropriate number |\n' |
| 5289 | ' | | separator ' |
| 5290 | 'characters. |\n' |
| 5291 | ' ' |
| 5292 | '+-----------+------------------------------------------------------------+\n' |
| 5293 | ' | None | The same as ' |
| 5294 | '"\'d\'". |\n' |
| 5295 | ' ' |
| 5296 | '+-----------+------------------------------------------------------------+\n' |
| 5297 | '\n' |
| 5298 | 'In addition to the above presentation types, integers can ' |
| 5299 | 'be formatted\n' |
| 5300 | 'with the floating point presentation types listed below ' |
| 5301 | '(except "\'n\'"\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5302 | 'and "None"). When doing so, "float()" is used to convert ' |
| 5303 | 'the integer\n' |
| 5304 | 'to a floating point number before formatting.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5305 | '\n' |
| 5306 | 'The available presentation types for floating point and ' |
| 5307 | 'decimal values\n' |
| 5308 | 'are:\n' |
| 5309 | '\n' |
| 5310 | ' ' |
| 5311 | '+-----------+------------------------------------------------------------+\n' |
| 5312 | ' | Type | ' |
| 5313 | 'Meaning ' |
| 5314 | '|\n' |
| 5315 | ' ' |
| 5316 | '+===========+============================================================+\n' |
| 5317 | ' | "\'e\'" | Exponent notation. Prints the number in ' |
| 5318 | 'scientific |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5319 | ' | | notation using the letter ‘e’ to indicate ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5320 | 'the exponent. |\n' |
| 5321 | ' | | The default precision is ' |
| 5322 | '"6". |\n' |
| 5323 | ' ' |
| 5324 | '+-----------+------------------------------------------------------------+\n' |
| 5325 | ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' |
| 5326 | 'except it uses an upper |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5327 | ' | | case ‘E’ as the separator ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5328 | 'character. |\n' |
| 5329 | ' ' |
| 5330 | '+-----------+------------------------------------------------------------+\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5331 | ' | "\'f\'" | Fixed-point notation. Displays the ' |
| 5332 | 'number as a fixed-point |\n' |
| 5333 | ' | | number. The default precision is ' |
| 5334 | '"6". |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5335 | ' ' |
| 5336 | '+-----------+------------------------------------------------------------+\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5337 | ' | "\'F\'" | Fixed-point notation. Same as "\'f\'", ' |
| 5338 | 'but converts "nan" to |\n' |
| 5339 | ' | | "NAN" and "inf" to ' |
| 5340 | '"INF". |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5341 | ' ' |
| 5342 | '+-----------+------------------------------------------------------------+\n' |
| 5343 | ' | "\'g\'" | General format. For a given precision ' |
| 5344 | '"p >= 1", this |\n' |
| 5345 | ' | | rounds the number to "p" significant ' |
| 5346 | 'digits and then |\n' |
| 5347 | ' | | formats the result in either fixed-point ' |
| 5348 | 'format or in |\n' |
| 5349 | ' | | scientific notation, depending on its ' |
| 5350 | 'magnitude. The |\n' |
| 5351 | ' | | precise rules are as follows: suppose that ' |
| 5352 | 'the result |\n' |
| 5353 | ' | | formatted with presentation type "\'e\'" ' |
| 5354 | 'and precision "p-1" |\n' |
| 5355 | ' | | would have exponent "exp". Then if "-4 <= ' |
| 5356 | 'exp < p", the |\n' |
| 5357 | ' | | number is formatted with presentation type ' |
| 5358 | '"\'f\'" and |\n' |
| 5359 | ' | | precision "p-1-exp". Otherwise, the ' |
| 5360 | 'number is formatted |\n' |
| 5361 | ' | | with presentation type "\'e\'" and ' |
| 5362 | 'precision "p-1". In both |\n' |
| 5363 | ' | | cases insignificant trailing zeros are ' |
| 5364 | 'removed from the |\n' |
| 5365 | ' | | significand, and the decimal point is also ' |
| 5366 | 'removed if |\n' |
| 5367 | ' | | there are no remaining digits following ' |
| 5368 | 'it. Positive and |\n' |
| 5369 | ' | | negative infinity, positive and negative ' |
| 5370 | 'zero, and nans, |\n' |
| 5371 | ' | | are formatted as "inf", "-inf", "0", "-0" ' |
| 5372 | 'and "nan" |\n' |
| 5373 | ' | | respectively, regardless of the ' |
| 5374 | 'precision. A precision of |\n' |
| 5375 | ' | | "0" is treated as equivalent to a ' |
| 5376 | 'precision of "1". The |\n' |
| 5377 | ' | | default precision is ' |
| 5378 | '"6". |\n' |
| 5379 | ' ' |
| 5380 | '+-----------+------------------------------------------------------------+\n' |
| 5381 | ' | "\'G\'" | General format. Same as "\'g\'" except ' |
| 5382 | 'switches to "\'E\'" if |\n' |
| 5383 | ' | | the number gets too large. The ' |
| 5384 | 'representations of infinity |\n' |
| 5385 | ' | | and NaN are uppercased, ' |
| 5386 | 'too. |\n' |
| 5387 | ' ' |
| 5388 | '+-----------+------------------------------------------------------------+\n' |
| 5389 | ' | "\'n\'" | Number. This is the same as "\'g\'", ' |
| 5390 | 'except that it uses the |\n' |
| 5391 | ' | | current locale setting to insert the ' |
| 5392 | 'appropriate number |\n' |
| 5393 | ' | | separator ' |
| 5394 | 'characters. |\n' |
| 5395 | ' ' |
| 5396 | '+-----------+------------------------------------------------------------+\n' |
| 5397 | ' | "\'%\'" | Percentage. Multiplies the number by 100 ' |
| 5398 | 'and displays in |\n' |
| 5399 | ' | | fixed ("\'f\'") format, followed by a ' |
| 5400 | 'percent sign. |\n' |
| 5401 | ' ' |
| 5402 | '+-----------+------------------------------------------------------------+\n' |
| 5403 | ' | None | Similar to "\'g\'", except that ' |
| 5404 | 'fixed-point notation, when |\n' |
| 5405 | ' | | used, has at least one digit past the ' |
| 5406 | 'decimal point. The |\n' |
| 5407 | ' | | default precision is as high as needed to ' |
| 5408 | 'represent the |\n' |
| 5409 | ' | | particular value. The overall effect is to ' |
| 5410 | 'match the |\n' |
| 5411 | ' | | output of "str()" as altered by the other ' |
| 5412 | 'format |\n' |
| 5413 | ' | | ' |
| 5414 | 'modifiers. ' |
| 5415 | '|\n' |
| 5416 | ' ' |
| 5417 | '+-----------+------------------------------------------------------------+\n' |
| 5418 | '\n' |
| 5419 | '\n' |
| 5420 | 'Format examples\n' |
| 5421 | '===============\n' |
| 5422 | '\n' |
| 5423 | 'This section contains examples of the "str.format()" syntax ' |
| 5424 | 'and\n' |
| 5425 | 'comparison with the old "%"-formatting.\n' |
| 5426 | '\n' |
| 5427 | 'In most of the cases the syntax is similar to the old ' |
| 5428 | '"%"-formatting,\n' |
| 5429 | 'with the addition of the "{}" and with ":" used instead of ' |
| 5430 | '"%". For\n' |
| 5431 | 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n' |
| 5432 | '\n' |
| 5433 | 'The new format syntax also supports new and different ' |
| 5434 | 'options, shown\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5435 | 'in the following examples.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5436 | '\n' |
| 5437 | 'Accessing arguments by position:\n' |
| 5438 | '\n' |
| 5439 | " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" |
| 5440 | " 'a, b, c'\n" |
| 5441 | " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" |
| 5442 | " 'a, b, c'\n" |
| 5443 | " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" |
| 5444 | " 'c, b, a'\n" |
| 5445 | " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " |
| 5446 | 'argument sequence\n' |
| 5447 | " 'c, b, a'\n" |
| 5448 | " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " |
| 5449 | 'indices can be repeated\n' |
| 5450 | " 'abracadabra'\n" |
| 5451 | '\n' |
| 5452 | 'Accessing arguments by name:\n' |
| 5453 | '\n' |
| 5454 | " >>> 'Coordinates: {latitude}, " |
| 5455 | "{longitude}'.format(latitude='37.24N', " |
| 5456 | "longitude='-115.81W')\n" |
| 5457 | " 'Coordinates: 37.24N, -115.81W'\n" |
| 5458 | " >>> coord = {'latitude': '37.24N', 'longitude': " |
| 5459 | "'-115.81W'}\n" |
| 5460 | " >>> 'Coordinates: {latitude}, " |
| 5461 | "{longitude}'.format(**coord)\n" |
| 5462 | " 'Coordinates: 37.24N, -115.81W'\n" |
| 5463 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5464 | 'Accessing arguments’ attributes:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5465 | '\n' |
| 5466 | ' >>> c = 3-5j\n' |
| 5467 | " >>> ('The complex number {0} is formed from the real " |
| 5468 | "part {0.real} '\n" |
| 5469 | " ... 'and the imaginary part {0.imag}.').format(c)\n" |
| 5470 | " 'The complex number (3-5j) is formed from the real part " |
| 5471 | "3.0 and the imaginary part -5.0.'\n" |
| 5472 | ' >>> class Point:\n' |
| 5473 | ' ... def __init__(self, x, y):\n' |
| 5474 | ' ... self.x, self.y = x, y\n' |
| 5475 | ' ... def __str__(self):\n' |
| 5476 | " ... return 'Point({self.x}, " |
| 5477 | "{self.y})'.format(self=self)\n" |
| 5478 | ' ...\n' |
| 5479 | ' >>> str(Point(4, 2))\n' |
| 5480 | " 'Point(4, 2)'\n" |
| 5481 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5482 | 'Accessing arguments’ items:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5483 | '\n' |
| 5484 | ' >>> coord = (3, 5)\n' |
| 5485 | " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" |
| 5486 | " 'X: 3; Y: 5'\n" |
| 5487 | '\n' |
| 5488 | 'Replacing "%s" and "%r":\n' |
| 5489 | '\n' |
| 5490 | ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' |
| 5491 | '{!s}".format(\'test1\', \'test2\')\n' |
| 5492 | ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n' |
| 5493 | '\n' |
| 5494 | 'Aligning the text and specifying a width:\n' |
| 5495 | '\n' |
| 5496 | " >>> '{:<30}'.format('left aligned')\n" |
| 5497 | " 'left aligned '\n" |
| 5498 | " >>> '{:>30}'.format('right aligned')\n" |
| 5499 | " ' right aligned'\n" |
| 5500 | " >>> '{:^30}'.format('centered')\n" |
| 5501 | " ' centered '\n" |
| 5502 | " >>> '{:*^30}'.format('centered') # use '*' as a fill " |
| 5503 | 'char\n' |
| 5504 | " '***********centered***********'\n" |
| 5505 | '\n' |
| 5506 | 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' |
| 5507 | '\n' |
| 5508 | " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " |
| 5509 | 'always\n' |
| 5510 | " '+3.140000; -3.140000'\n" |
| 5511 | " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " |
| 5512 | 'for positive numbers\n' |
| 5513 | " ' 3.140000; -3.140000'\n" |
| 5514 | " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the " |
| 5515 | "minus -- same as '{:f}; {:f}'\n" |
| 5516 | " '3.140000; -3.140000'\n" |
| 5517 | '\n' |
| 5518 | 'Replacing "%x" and "%o" and converting the value to ' |
| 5519 | 'different bases:\n' |
| 5520 | '\n' |
| 5521 | ' >>> # format also supports binary numbers\n' |
| 5522 | ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' |
| 5523 | '{0:b}".format(42)\n' |
| 5524 | " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" |
| 5525 | ' >>> # with 0x, 0o, or 0b as prefix:\n' |
| 5526 | ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' |
| 5527 | '{0:#b}".format(42)\n' |
| 5528 | " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" |
| 5529 | '\n' |
| 5530 | 'Using the comma as a thousands separator:\n' |
| 5531 | '\n' |
| 5532 | " >>> '{:,}'.format(1234567890)\n" |
| 5533 | " '1,234,567,890'\n" |
| 5534 | '\n' |
| 5535 | 'Expressing a percentage:\n' |
| 5536 | '\n' |
| 5537 | ' >>> points = 19\n' |
| 5538 | ' >>> total = 22\n' |
| 5539 | " >>> 'Correct answers: {:.2%}'.format(points/total)\n" |
| 5540 | " 'Correct answers: 86.36%'\n" |
| 5541 | '\n' |
| 5542 | 'Using type-specific formatting:\n' |
| 5543 | '\n' |
| 5544 | ' >>> import datetime\n' |
| 5545 | ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' |
| 5546 | " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" |
| 5547 | " '2010-07-04 12:15:58'\n" |
| 5548 | '\n' |
| 5549 | 'Nesting arguments and more complex examples:\n' |
| 5550 | '\n' |
| 5551 | " >>> for align, text in zip('<^>', ['left', 'center', " |
| 5552 | "'right']):\n" |
| 5553 | " ... '{0:{fill}{align}16}'.format(text, fill=align, " |
| 5554 | 'align=align)\n' |
| 5555 | ' ...\n' |
| 5556 | " 'left<<<<<<<<<<<<'\n" |
| 5557 | " '^^^^^center^^^^^'\n" |
| 5558 | " '>>>>>>>>>>>right'\n" |
| 5559 | ' >>>\n' |
| 5560 | ' >>> octets = [192, 168, 0, 1]\n' |
| 5561 | " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" |
| 5562 | " 'C0A80001'\n" |
| 5563 | ' >>> int(_, 16)\n' |
| 5564 | ' 3232235521\n' |
| 5565 | ' >>>\n' |
| 5566 | ' >>> width = 5\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5567 | ' >>> for num in range(5,12): \n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5568 | " ... for base in 'dXob':\n" |
| 5569 | " ... print('{0:{width}{base}}'.format(num, " |
| 5570 | "base=base, width=width), end=' ')\n" |
| 5571 | ' ... print()\n' |
| 5572 | ' ...\n' |
| 5573 | ' 5 5 5 101\n' |
| 5574 | ' 6 6 6 110\n' |
| 5575 | ' 7 7 7 111\n' |
| 5576 | ' 8 8 10 1000\n' |
| 5577 | ' 9 9 11 1001\n' |
| 5578 | ' 10 A 12 1010\n' |
| 5579 | ' 11 B 13 1011\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5580 | 'function': 'Function definitions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5581 | '********************\n' |
| 5582 | '\n' |
| 5583 | 'A function definition defines a user-defined function object ' |
| 5584 | '(see\n' |
| 5585 | 'section The standard type hierarchy):\n' |
| 5586 | '\n' |
| 5587 | ' funcdef ::= [decorators] "def" funcname "(" ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5588 | '[parameter_list] ")"\n' |
| 5589 | ' ["->" expression] ":" suite\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5590 | ' decorators ::= decorator+\n' |
| 5591 | ' decorator ::= "@" dotted_name ["(" ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 5592 | '[argument_list [","]] ")"] NEWLINE\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5593 | ' dotted_name ::= identifier ("." identifier)*\n' |
| 5594 | ' parameter_list ::= defparameter ("," defparameter)* ' |
| 5595 | '["," [parameter_list_starargs]]\n' |
| 5596 | ' | parameter_list_starargs\n' |
| 5597 | ' parameter_list_starargs ::= "*" [parameter] ("," ' |
| 5598 | 'defparameter)* ["," ["**" parameter [","]]]\n' |
| 5599 | ' | "**" parameter [","]\n' |
| 5600 | ' parameter ::= identifier [":" expression]\n' |
| 5601 | ' defparameter ::= parameter ["=" expression]\n' |
| 5602 | ' funcname ::= identifier\n' |
| 5603 | '\n' |
| 5604 | 'A function definition is an executable statement. Its execution ' |
| 5605 | 'binds\n' |
| 5606 | 'the function name in the current local namespace to a function ' |
| 5607 | 'object\n' |
| 5608 | '(a wrapper around the executable code for the function). This\n' |
| 5609 | 'function object contains a reference to the current global ' |
| 5610 | 'namespace\n' |
| 5611 | 'as the global namespace to be used when the function is called.\n' |
| 5612 | '\n' |
| 5613 | 'The function definition does not execute the function body; this ' |
| 5614 | 'gets\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5615 | 'executed only when the function is called. [2]\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5616 | '\n' |
| 5617 | 'A function definition may be wrapped by one or more *decorator*\n' |
| 5618 | 'expressions. Decorator expressions are evaluated when the ' |
| 5619 | 'function is\n' |
| 5620 | 'defined, in the scope that contains the function definition. ' |
| 5621 | 'The\n' |
| 5622 | 'result must be a callable, which is invoked with the function ' |
| 5623 | 'object\n' |
| 5624 | 'as the only argument. The returned value is bound to the ' |
| 5625 | 'function name\n' |
| 5626 | 'instead of the function object. Multiple decorators are applied ' |
| 5627 | 'in\n' |
| 5628 | 'nested fashion. For example, the following code\n' |
| 5629 | '\n' |
| 5630 | ' @f1(arg)\n' |
| 5631 | ' @f2\n' |
| 5632 | ' def func(): pass\n' |
| 5633 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 5634 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5635 | '\n' |
| 5636 | ' def func(): pass\n' |
| 5637 | ' func = f1(arg)(f2(func))\n' |
| 5638 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 5639 | 'except that the original function is not temporarily bound to ' |
| 5640 | 'the name\n' |
| 5641 | '"func".\n' |
| 5642 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5643 | 'When one or more *parameters* have the form *parameter* "="\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5644 | '*expression*, the function is said to have “default parameter ' |
| 5645 | 'values.”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5646 | 'For a parameter with a default value, the corresponding ' |
| 5647 | '*argument* may\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5648 | 'be omitted from a call, in which case the parameter’s default ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5649 | 'value is\n' |
| 5650 | 'substituted. If a parameter has a default value, all following\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5651 | 'parameters up until the “"*"” must also have a default value — ' |
| 5652 | 'this is\n' |
| 5653 | 'a syntactic restriction that is not expressed by the grammar.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5654 | '\n' |
| 5655 | '**Default parameter values are evaluated from left to right when ' |
| 5656 | 'the\n' |
| 5657 | 'function definition is executed.** This means that the ' |
| 5658 | 'expression is\n' |
| 5659 | 'evaluated once, when the function is defined, and that the same ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5660 | '“pre-\n' |
| 5661 | 'computed” value is used for each call. This is especially ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5662 | 'important\n' |
| 5663 | 'to understand when a default parameter is a mutable object, such ' |
| 5664 | 'as a\n' |
| 5665 | 'list or a dictionary: if the function modifies the object (e.g. ' |
| 5666 | 'by\n' |
| 5667 | 'appending an item to a list), the default value is in effect ' |
| 5668 | 'modified.\n' |
| 5669 | 'This is generally not what was intended. A way around this is ' |
| 5670 | 'to use\n' |
| 5671 | '"None" as the default, and explicitly test for it in the body of ' |
| 5672 | 'the\n' |
| 5673 | 'function, e.g.:\n' |
| 5674 | '\n' |
| 5675 | ' def whats_on_the_telly(penguin=None):\n' |
| 5676 | ' if penguin is None:\n' |
| 5677 | ' penguin = []\n' |
| 5678 | ' penguin.append("property of the zoo")\n' |
| 5679 | ' return penguin\n' |
| 5680 | '\n' |
| 5681 | 'Function call semantics are described in more detail in section ' |
| 5682 | 'Calls.\n' |
| 5683 | 'A function call always assigns values to all parameters ' |
| 5684 | 'mentioned in\n' |
| 5685 | 'the parameter list, either from position arguments, from ' |
| 5686 | 'keyword\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5687 | 'arguments, or from default values. If the form “"*identifier"” ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5688 | 'is\n' |
| 5689 | 'present, it is initialized to a tuple receiving any excess ' |
| 5690 | 'positional\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5691 | 'parameters, defaulting to the empty tuple. If the form\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5692 | '“"**identifier"” is present, it is initialized to a new ordered\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5693 | 'mapping receiving any excess keyword arguments, defaulting to a ' |
| 5694 | 'new\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5695 | 'empty mapping of the same type. Parameters after “"*"” or\n' |
| 5696 | '“"*identifier"” are keyword-only parameters and may only be ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5697 | 'passed\n' |
| 5698 | 'used keyword arguments.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5699 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5700 | 'Parameters may have an *annotation* of the form “": ' |
| 5701 | 'expression"”\n' |
| 5702 | 'following the parameter name. Any parameter may have an ' |
| 5703 | 'annotation,\n' |
| 5704 | 'even those of the form "*identifier" or "**identifier". ' |
| 5705 | 'Functions may\n' |
| 5706 | 'have “return” annotation of the form “"-> expression"” after ' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 5707 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5708 | 'parameter list. These annotations can be any valid Python ' |
| 5709 | 'expression.\n' |
| 5710 | 'The presence of annotations does not change the semantics of a\n' |
| 5711 | 'function. The annotation values are available as values of a\n' |
| 5712 | 'dictionary keyed by the parameters’ names in the ' |
| 5713 | '"__annotations__"\n' |
| 5714 | 'attribute of the function object. If the "annotations" import ' |
| 5715 | 'from\n' |
| 5716 | '"__future__" is used, annotations are preserved as strings at ' |
| 5717 | 'runtime\n' |
| 5718 | 'which enables postponed evaluation. Otherwise, they are ' |
| 5719 | 'evaluated\n' |
| 5720 | 'when the function definition is executed. In this case ' |
| 5721 | 'annotations\n' |
| 5722 | 'may be evaluated in a different order than they appear in the ' |
| 5723 | 'source\n' |
| 5724 | 'code.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5725 | '\n' |
| 5726 | 'It is also possible to create anonymous functions (functions not ' |
| 5727 | 'bound\n' |
| 5728 | 'to a name), for immediate use in expressions. This uses lambda\n' |
| 5729 | 'expressions, described in section Lambdas. Note that the ' |
| 5730 | 'lambda\n' |
| 5731 | 'expression is merely a shorthand for a simplified function ' |
| 5732 | 'definition;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5733 | 'a function defined in a “"def"” statement can be passed around ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5734 | 'or\n' |
| 5735 | 'assigned to another name just like a function defined by a ' |
| 5736 | 'lambda\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5737 | 'expression. The “"def"” form is actually more powerful since ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5738 | 'it\n' |
| 5739 | 'allows the execution of multiple statements and annotations.\n' |
| 5740 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5741 | '**Programmer’s note:** Functions are first-class objects. A ' |
| 5742 | '“"def"”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5743 | 'statement executed inside a function definition defines a local\n' |
| 5744 | 'function that can be returned or passed around. Free variables ' |
| 5745 | 'used\n' |
| 5746 | 'in the nested function can access the local variables of the ' |
| 5747 | 'function\n' |
| 5748 | 'containing the def. See section Naming and binding for ' |
| 5749 | 'details.\n' |
| 5750 | '\n' |
| 5751 | 'See also:\n' |
| 5752 | '\n' |
| 5753 | ' **PEP 3107** - Function Annotations\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 5754 | ' The original specification for function annotations.\n' |
| 5755 | '\n' |
| 5756 | ' **PEP 484** - Type Hints\n' |
| 5757 | ' Definition of a standard meaning for annotations: type ' |
| 5758 | 'hints.\n' |
| 5759 | '\n' |
| 5760 | ' **PEP 526** - Syntax for Variable Annotations\n' |
| 5761 | ' Ability to type hint variable declarations, including ' |
| 5762 | 'class\n' |
| 5763 | ' variables and instance variables\n' |
| 5764 | '\n' |
| 5765 | ' **PEP 563** - Postponed Evaluation of Annotations\n' |
| 5766 | ' Support for forward references within annotations by ' |
| 5767 | 'preserving\n' |
| 5768 | ' annotations in a string form at runtime instead of eager\n' |
| 5769 | ' evaluation.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5770 | 'global': 'The "global" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5771 | '**********************\n' |
| 5772 | '\n' |
| 5773 | ' global_stmt ::= "global" identifier ("," identifier)*\n' |
| 5774 | '\n' |
| 5775 | 'The "global" statement is a declaration which holds for the ' |
| 5776 | 'entire\n' |
| 5777 | 'current code block. It means that the listed identifiers are to ' |
| 5778 | 'be\n' |
| 5779 | 'interpreted as globals. It would be impossible to assign to a ' |
| 5780 | 'global\n' |
| 5781 | 'variable without "global", although free variables may refer to\n' |
| 5782 | 'globals without being declared global.\n' |
| 5783 | '\n' |
| 5784 | 'Names listed in a "global" statement must not be used in the same ' |
| 5785 | 'code\n' |
| 5786 | 'block textually preceding that "global" statement.\n' |
| 5787 | '\n' |
| 5788 | 'Names listed in a "global" statement must not be defined as ' |
| 5789 | 'formal\n' |
| 5790 | 'parameters or in a "for" loop control target, "class" definition,\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5791 | 'function definition, "import" statement, or variable annotation.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5792 | '\n' |
| 5793 | '**CPython implementation detail:** The current implementation does ' |
| 5794 | 'not\n' |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 5795 | 'enforce some of these restrictions, but programs should not abuse ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5796 | 'this\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5797 | 'freedom, as future implementations may enforce them or silently ' |
| 5798 | 'change\n' |
| 5799 | 'the meaning of the program.\n' |
| 5800 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5801 | '**Programmer’s note:** "global" is a directive to the parser. It\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5802 | 'applies only to code parsed at the same time as the "global"\n' |
| 5803 | 'statement. In particular, a "global" statement contained in a ' |
| 5804 | 'string\n' |
| 5805 | 'or code object supplied to the built-in "exec()" function does ' |
| 5806 | 'not\n' |
| 5807 | 'affect the code block *containing* the function call, and code\n' |
| 5808 | 'contained in such a string is unaffected by "global" statements in ' |
| 5809 | 'the\n' |
| 5810 | 'code containing the function call. The same applies to the ' |
| 5811 | '"eval()"\n' |
| 5812 | 'and "compile()" functions.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5813 | 'id-classes': 'Reserved classes of identifiers\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5814 | '*******************************\n' |
| 5815 | '\n' |
| 5816 | 'Certain classes of identifiers (besides keywords) have ' |
| 5817 | 'special\n' |
| 5818 | 'meanings. These classes are identified by the patterns of ' |
| 5819 | 'leading and\n' |
| 5820 | 'trailing underscore characters:\n' |
| 5821 | '\n' |
| 5822 | '"_*"\n' |
| 5823 | ' Not imported by "from module import *". The special ' |
| 5824 | 'identifier "_"\n' |
| 5825 | ' is used in the interactive interpreter to store the result ' |
| 5826 | 'of the\n' |
| 5827 | ' last evaluation; it is stored in the "builtins" module. ' |
| 5828 | 'When not\n' |
| 5829 | ' in interactive mode, "_" has no special meaning and is not ' |
| 5830 | 'defined.\n' |
| 5831 | ' See section The import statement.\n' |
| 5832 | '\n' |
| 5833 | ' Note: The name "_" is often used in conjunction with\n' |
| 5834 | ' internationalization; refer to the documentation for the\n' |
| 5835 | ' "gettext" module for more information on this ' |
| 5836 | 'convention.\n' |
| 5837 | '\n' |
| 5838 | '"__*__"\n' |
| 5839 | ' System-defined names. These names are defined by the ' |
| 5840 | 'interpreter\n' |
| 5841 | ' and its implementation (including the standard library). ' |
| 5842 | 'Current\n' |
| 5843 | ' system names are discussed in the Special method names ' |
| 5844 | 'section and\n' |
| 5845 | ' elsewhere. More will likely be defined in future versions ' |
| 5846 | 'of\n' |
| 5847 | ' Python. *Any* use of "__*__" names, in any context, that ' |
| 5848 | 'does not\n' |
| 5849 | ' follow explicitly documented use, is subject to breakage ' |
| 5850 | 'without\n' |
| 5851 | ' warning.\n' |
| 5852 | '\n' |
| 5853 | '"__*"\n' |
| 5854 | ' Class-private names. Names in this category, when used ' |
| 5855 | 'within the\n' |
| 5856 | ' context of a class definition, are re-written to use a ' |
| 5857 | 'mangled form\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 5858 | ' to help avoid name clashes between “private” attributes of ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5859 | 'base and\n' |
| 5860 | ' derived classes. See section Identifiers (Names).\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5861 | 'identifiers': 'Identifiers and keywords\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5862 | '************************\n' |
| 5863 | '\n' |
| 5864 | 'Identifiers (also referred to as *names*) are described by ' |
| 5865 | 'the\n' |
| 5866 | 'following lexical definitions.\n' |
| 5867 | '\n' |
| 5868 | 'The syntax of identifiers in Python is based on the Unicode ' |
| 5869 | 'standard\n' |
| 5870 | 'annex UAX-31, with elaboration and changes as defined below; ' |
| 5871 | 'see also\n' |
| 5872 | '**PEP 3131** for further details.\n' |
| 5873 | '\n' |
| 5874 | 'Within the ASCII range (U+0001..U+007F), the valid characters ' |
| 5875 | 'for\n' |
| 5876 | 'identifiers are the same as in Python 2.x: the uppercase and ' |
| 5877 | 'lowercase\n' |
| 5878 | 'letters "A" through "Z", the underscore "_" and, except for ' |
| 5879 | 'the first\n' |
| 5880 | 'character, the digits "0" through "9".\n' |
| 5881 | '\n' |
| 5882 | 'Python 3.0 introduces additional characters from outside the ' |
| 5883 | 'ASCII\n' |
| 5884 | 'range (see **PEP 3131**). For these characters, the ' |
| 5885 | 'classification\n' |
| 5886 | 'uses the version of the Unicode Character Database as ' |
| 5887 | 'included in the\n' |
| 5888 | '"unicodedata" module.\n' |
| 5889 | '\n' |
| 5890 | 'Identifiers are unlimited in length. Case is significant.\n' |
| 5891 | '\n' |
| 5892 | ' identifier ::= xid_start xid_continue*\n' |
| 5893 | ' id_start ::= <all characters in general categories Lu, ' |
| 5894 | 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the ' |
| 5895 | 'Other_ID_Start property>\n' |
| 5896 | ' id_continue ::= <all characters in id_start, plus ' |
| 5897 | 'characters in the categories Mn, Mc, Nd, Pc and others with ' |
| 5898 | 'the Other_ID_Continue property>\n' |
| 5899 | ' xid_start ::= <all characters in id_start whose NFKC ' |
| 5900 | 'normalization is in "id_start xid_continue*">\n' |
| 5901 | ' xid_continue ::= <all characters in id_continue whose NFKC ' |
| 5902 | 'normalization is in "id_continue*">\n' |
| 5903 | '\n' |
| 5904 | 'The Unicode category codes mentioned above stand for:\n' |
| 5905 | '\n' |
| 5906 | '* *Lu* - uppercase letters\n' |
| 5907 | '\n' |
| 5908 | '* *Ll* - lowercase letters\n' |
| 5909 | '\n' |
| 5910 | '* *Lt* - titlecase letters\n' |
| 5911 | '\n' |
| 5912 | '* *Lm* - modifier letters\n' |
| 5913 | '\n' |
| 5914 | '* *Lo* - other letters\n' |
| 5915 | '\n' |
| 5916 | '* *Nl* - letter numbers\n' |
| 5917 | '\n' |
| 5918 | '* *Mn* - nonspacing marks\n' |
| 5919 | '\n' |
| 5920 | '* *Mc* - spacing combining marks\n' |
| 5921 | '\n' |
| 5922 | '* *Nd* - decimal numbers\n' |
| 5923 | '\n' |
| 5924 | '* *Pc* - connector punctuations\n' |
| 5925 | '\n' |
| 5926 | '* *Other_ID_Start* - explicit list of characters in ' |
| 5927 | 'PropList.txt to\n' |
| 5928 | ' support backwards compatibility\n' |
| 5929 | '\n' |
| 5930 | '* *Other_ID_Continue* - likewise\n' |
| 5931 | '\n' |
| 5932 | 'All identifiers are converted into the normal form NFKC while ' |
| 5933 | 'parsing;\n' |
| 5934 | 'comparison of identifiers is based on NFKC.\n' |
| 5935 | '\n' |
| 5936 | 'A non-normative HTML file listing all valid identifier ' |
| 5937 | 'characters for\n' |
| 5938 | 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n' |
| 5939 | 'potsdam.de/home/loewis/table-3131.html.\n' |
| 5940 | '\n' |
| 5941 | '\n' |
| 5942 | 'Keywords\n' |
| 5943 | '========\n' |
| 5944 | '\n' |
| 5945 | 'The following identifiers are used as reserved words, or ' |
| 5946 | '*keywords* of\n' |
| 5947 | 'the language, and cannot be used as ordinary identifiers. ' |
| 5948 | 'They must\n' |
| 5949 | 'be spelled exactly as written here:\n' |
| 5950 | '\n' |
Ned Deily | 3f9a728 | 2017-12-05 03:17:33 -0500 | [diff] [blame] | 5951 | ' False await else import pass\n' |
| 5952 | ' None break except in raise\n' |
| 5953 | ' True class finally is return\n' |
| 5954 | ' and continue for lambda try\n' |
| 5955 | ' as def from nonlocal while\n' |
| 5956 | ' assert del global not with\n' |
| 5957 | ' async elif if or yield\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5958 | '\n' |
| 5959 | '\n' |
| 5960 | 'Reserved classes of identifiers\n' |
| 5961 | '===============================\n' |
| 5962 | '\n' |
| 5963 | 'Certain classes of identifiers (besides keywords) have ' |
| 5964 | 'special\n' |
| 5965 | 'meanings. These classes are identified by the patterns of ' |
| 5966 | 'leading and\n' |
| 5967 | 'trailing underscore characters:\n' |
| 5968 | '\n' |
| 5969 | '"_*"\n' |
| 5970 | ' Not imported by "from module import *". The special ' |
| 5971 | 'identifier "_"\n' |
| 5972 | ' is used in the interactive interpreter to store the result ' |
| 5973 | 'of the\n' |
| 5974 | ' last evaluation; it is stored in the "builtins" module. ' |
| 5975 | 'When not\n' |
| 5976 | ' in interactive mode, "_" has no special meaning and is not ' |
| 5977 | 'defined.\n' |
| 5978 | ' See section The import statement.\n' |
| 5979 | '\n' |
| 5980 | ' Note: The name "_" is often used in conjunction with\n' |
| 5981 | ' internationalization; refer to the documentation for ' |
| 5982 | 'the\n' |
| 5983 | ' "gettext" module for more information on this ' |
| 5984 | 'convention.\n' |
| 5985 | '\n' |
| 5986 | '"__*__"\n' |
| 5987 | ' System-defined names. These names are defined by the ' |
| 5988 | 'interpreter\n' |
| 5989 | ' and its implementation (including the standard library). ' |
| 5990 | 'Current\n' |
| 5991 | ' system names are discussed in the Special method names ' |
| 5992 | 'section and\n' |
| 5993 | ' elsewhere. More will likely be defined in future versions ' |
| 5994 | 'of\n' |
| 5995 | ' Python. *Any* use of "__*__" names, in any context, that ' |
| 5996 | 'does not\n' |
| 5997 | ' follow explicitly documented use, is subject to breakage ' |
| 5998 | 'without\n' |
| 5999 | ' warning.\n' |
| 6000 | '\n' |
| 6001 | '"__*"\n' |
| 6002 | ' Class-private names. Names in this category, when used ' |
| 6003 | 'within the\n' |
| 6004 | ' context of a class definition, are re-written to use a ' |
| 6005 | 'mangled form\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6006 | ' to help avoid name clashes between “private” attributes of ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6007 | 'base and\n' |
| 6008 | ' derived classes. See section Identifiers (Names).\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6009 | 'if': 'The "if" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6010 | '******************\n' |
| 6011 | '\n' |
| 6012 | 'The "if" statement is used for conditional execution:\n' |
| 6013 | '\n' |
| 6014 | ' if_stmt ::= "if" expression ":" suite\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6015 | ' ("elif" expression ":" suite)*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6016 | ' ["else" ":" suite]\n' |
| 6017 | '\n' |
| 6018 | 'It selects exactly one of the suites by evaluating the expressions ' |
| 6019 | 'one\n' |
| 6020 | 'by one until one is found to be true (see section Boolean operations\n' |
| 6021 | 'for the definition of true and false); then that suite is executed\n' |
| 6022 | '(and no other part of the "if" statement is executed or evaluated).\n' |
| 6023 | 'If all expressions are false, the suite of the "else" clause, if\n' |
| 6024 | 'present, is executed.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6025 | 'imaginary': 'Imaginary literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6026 | '******************\n' |
| 6027 | '\n' |
| 6028 | 'Imaginary literals are described by the following lexical ' |
| 6029 | 'definitions:\n' |
| 6030 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6031 | ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6032 | '\n' |
| 6033 | 'An imaginary literal yields a complex number with a real part ' |
| 6034 | 'of 0.0.\n' |
| 6035 | 'Complex numbers are represented as a pair of floating point ' |
| 6036 | 'numbers\n' |
| 6037 | 'and have the same restrictions on their range. To create a ' |
| 6038 | 'complex\n' |
| 6039 | 'number with a nonzero real part, add a floating point number to ' |
| 6040 | 'it,\n' |
| 6041 | 'e.g., "(3+4j)". Some examples of imaginary literals:\n' |
| 6042 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6043 | ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j ' |
| 6044 | '3.14_15_93j\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6045 | 'import': 'The "import" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6046 | '**********************\n' |
| 6047 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6048 | ' import_stmt ::= "import" module ["as" identifier] ("," ' |
| 6049 | 'module ["as" identifier])*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6050 | ' | "from" relative_module "import" identifier ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6051 | '["as" identifier]\n' |
| 6052 | ' ("," identifier ["as" identifier])*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6053 | ' | "from" relative_module "import" "(" ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6054 | 'identifier ["as" identifier]\n' |
| 6055 | ' ("," identifier ["as" identifier])* [","] ")"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6056 | ' | "from" module "import" "*"\n' |
| 6057 | ' module ::= (identifier ".")* identifier\n' |
| 6058 | ' relative_module ::= "."* module | "."+\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6059 | '\n' |
| 6060 | 'The basic import statement (no "from" clause) is executed in two\n' |
| 6061 | 'steps:\n' |
| 6062 | '\n' |
| 6063 | '1. find a module, loading and initializing it if necessary\n' |
| 6064 | '\n' |
| 6065 | '2. define a name or names in the local namespace for the scope\n' |
| 6066 | ' where the "import" statement occurs.\n' |
| 6067 | '\n' |
| 6068 | 'When the statement contains multiple clauses (separated by commas) ' |
| 6069 | 'the\n' |
| 6070 | 'two steps are carried out separately for each clause, just as ' |
| 6071 | 'though\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 6072 | 'the clauses had been separated out into individual import ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6073 | 'statements.\n' |
| 6074 | '\n' |
| 6075 | 'The details of the first step, finding and loading modules are\n' |
| 6076 | 'described in greater detail in the section on the import system, ' |
| 6077 | 'which\n' |
| 6078 | 'also describes the various types of packages and modules that can ' |
| 6079 | 'be\n' |
| 6080 | 'imported, as well as all the hooks that can be used to customize ' |
| 6081 | 'the\n' |
| 6082 | 'import system. Note that failures in this step may indicate ' |
| 6083 | 'either\n' |
| 6084 | 'that the module could not be located, *or* that an error occurred\n' |
| 6085 | 'while initializing the module, which includes execution of the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6086 | 'module’s code.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6087 | '\n' |
| 6088 | 'If the requested module is retrieved successfully, it will be ' |
| 6089 | 'made\n' |
| 6090 | 'available in the local namespace in one of three ways:\n' |
| 6091 | '\n' |
| 6092 | '* If the module name is followed by "as", then the name following\n' |
| 6093 | ' "as" is bound directly to the imported module.\n' |
| 6094 | '\n' |
| 6095 | '* If no other name is specified, and the module being imported is ' |
| 6096 | 'a\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6097 | ' top level module, the module’s name is bound in the local ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6098 | 'namespace\n' |
| 6099 | ' as a reference to the imported module\n' |
| 6100 | '\n' |
| 6101 | '* If the module being imported is *not* a top level module, then ' |
| 6102 | 'the\n' |
| 6103 | ' name of the top level package that contains the module is bound ' |
| 6104 | 'in\n' |
| 6105 | ' the local namespace as a reference to the top level package. ' |
| 6106 | 'The\n' |
| 6107 | ' imported module must be accessed using its full qualified name\n' |
| 6108 | ' rather than directly\n' |
| 6109 | '\n' |
| 6110 | 'The "from" form uses a slightly more complex process:\n' |
| 6111 | '\n' |
| 6112 | '1. find the module specified in the "from" clause, loading and\n' |
| 6113 | ' initializing it if necessary;\n' |
| 6114 | '\n' |
| 6115 | '2. for each of the identifiers specified in the "import" clauses:\n' |
| 6116 | '\n' |
| 6117 | ' 1. check if the imported module has an attribute by that name\n' |
| 6118 | '\n' |
| 6119 | ' 2. if not, attempt to import a submodule with that name and ' |
| 6120 | 'then\n' |
| 6121 | ' check the imported module again for that attribute\n' |
| 6122 | '\n' |
| 6123 | ' 3. if the attribute is not found, "ImportError" is raised.\n' |
| 6124 | '\n' |
| 6125 | ' 4. otherwise, a reference to that value is stored in the local\n' |
| 6126 | ' namespace, using the name in the "as" clause if it is ' |
| 6127 | 'present,\n' |
| 6128 | ' otherwise using the attribute name\n' |
| 6129 | '\n' |
| 6130 | 'Examples:\n' |
| 6131 | '\n' |
| 6132 | ' import foo # foo imported and bound locally\n' |
| 6133 | ' import foo.bar.baz # foo.bar.baz imported, foo bound ' |
| 6134 | 'locally\n' |
| 6135 | ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' |
| 6136 | 'fbb\n' |
| 6137 | ' from foo.bar import baz # foo.bar.baz imported and bound as ' |
| 6138 | 'baz\n' |
| 6139 | ' from foo import attr # foo imported and foo.attr bound as ' |
| 6140 | 'attr\n' |
| 6141 | '\n' |
| 6142 | 'If the list of identifiers is replaced by a star ("\'*\'"), all ' |
| 6143 | 'public\n' |
| 6144 | 'names defined in the module are bound in the local namespace for ' |
| 6145 | 'the\n' |
| 6146 | 'scope where the "import" statement occurs.\n' |
| 6147 | '\n' |
| 6148 | 'The *public names* defined by a module are determined by checking ' |
| 6149 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6150 | 'module’s namespace for a variable named "__all__"; if defined, it ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6151 | 'must\n' |
| 6152 | 'be a sequence of strings which are names defined or imported by ' |
| 6153 | 'that\n' |
| 6154 | 'module. The names given in "__all__" are all considered public ' |
| 6155 | 'and\n' |
| 6156 | 'are required to exist. If "__all__" is not defined, the set of ' |
| 6157 | 'public\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6158 | 'names includes all names found in the module’s namespace which do ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6159 | 'not\n' |
| 6160 | 'begin with an underscore character ("\'_\'"). "__all__" should ' |
| 6161 | 'contain\n' |
| 6162 | 'the entire public API. It is intended to avoid accidentally ' |
| 6163 | 'exporting\n' |
| 6164 | 'items that are not part of the API (such as library modules which ' |
| 6165 | 'were\n' |
| 6166 | 'imported and used within the module).\n' |
| 6167 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6168 | 'The wild card form of import — "from module import *" — is only\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6169 | 'allowed at the module level. Attempting to use it in class or\n' |
| 6170 | 'function definitions will raise a "SyntaxError".\n' |
| 6171 | '\n' |
| 6172 | 'When specifying what module to import you do not have to specify ' |
| 6173 | 'the\n' |
| 6174 | 'absolute name of the module. When a module or package is ' |
| 6175 | 'contained\n' |
| 6176 | 'within another package it is possible to make a relative import ' |
| 6177 | 'within\n' |
| 6178 | 'the same top package without having to mention the package name. ' |
| 6179 | 'By\n' |
| 6180 | 'using leading dots in the specified module or package after "from" ' |
| 6181 | 'you\n' |
| 6182 | 'can specify how high to traverse up the current package hierarchy\n' |
| 6183 | 'without specifying exact names. One leading dot means the current\n' |
| 6184 | 'package where the module making the import exists. Two dots means ' |
| 6185 | 'up\n' |
| 6186 | 'one package level. Three dots is up two levels, etc. So if you ' |
| 6187 | 'execute\n' |
| 6188 | '"from . import mod" from a module in the "pkg" package then you ' |
| 6189 | 'will\n' |
| 6190 | 'end up importing "pkg.mod". If you execute "from ..subpkg2 import ' |
| 6191 | 'mod"\n' |
| 6192 | 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 6193 | 'specification for relative imports is contained in the Package\n' |
| 6194 | 'Relative Imports section.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6195 | '\n' |
| 6196 | '"importlib.import_module()" is provided to support applications ' |
| 6197 | 'that\n' |
| 6198 | 'determine dynamically the modules to be loaded.\n' |
| 6199 | '\n' |
| 6200 | '\n' |
| 6201 | 'Future statements\n' |
| 6202 | '=================\n' |
| 6203 | '\n' |
| 6204 | 'A *future statement* is a directive to the compiler that a ' |
| 6205 | 'particular\n' |
| 6206 | 'module should be compiled using syntax or semantics that will be\n' |
| 6207 | 'available in a specified future release of Python where the ' |
| 6208 | 'feature\n' |
| 6209 | 'becomes standard.\n' |
| 6210 | '\n' |
| 6211 | 'The future statement is intended to ease migration to future ' |
| 6212 | 'versions\n' |
| 6213 | 'of Python that introduce incompatible changes to the language. ' |
| 6214 | 'It\n' |
| 6215 | 'allows use of the new features on a per-module basis before the\n' |
| 6216 | 'release in which the feature becomes standard.\n' |
| 6217 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6218 | ' future_stmt ::= "from" "__future__" "import" feature ["as" ' |
| 6219 | 'identifier]\n' |
| 6220 | ' ("," feature ["as" identifier])*\n' |
| 6221 | ' | "from" "__future__" "import" "(" feature ' |
| 6222 | '["as" identifier]\n' |
| 6223 | ' ("," feature ["as" identifier])* [","] ")"\n' |
| 6224 | ' feature ::= identifier\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6225 | '\n' |
| 6226 | 'A future statement must appear near the top of the module. The ' |
| 6227 | 'only\n' |
| 6228 | 'lines that can appear before a future statement are:\n' |
| 6229 | '\n' |
| 6230 | '* the module docstring (if any),\n' |
| 6231 | '\n' |
| 6232 | '* comments,\n' |
| 6233 | '\n' |
| 6234 | '* blank lines, and\n' |
| 6235 | '\n' |
| 6236 | '* other future statements.\n' |
| 6237 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 6238 | 'The only feature in Python 3.7 that requires using the future\n' |
| 6239 | 'statement is "annotations".\n' |
| 6240 | '\n' |
| 6241 | 'All historical features enabled by the future statement are still\n' |
| 6242 | 'recognized by Python 3. The list includes "absolute_import",\n' |
| 6243 | '"division", "generators", "generator_stop", "unicode_literals",\n' |
| 6244 | '"print_function", "nested_scopes" and "with_statement". They are ' |
| 6245 | 'all\n' |
| 6246 | 'redundant because they are always enabled, and only kept for ' |
| 6247 | 'backwards\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6248 | 'compatibility.\n' |
| 6249 | '\n' |
| 6250 | 'A future statement is recognized and treated specially at compile\n' |
| 6251 | 'time: Changes to the semantics of core constructs are often\n' |
| 6252 | 'implemented by generating different code. It may even be the ' |
| 6253 | 'case\n' |
| 6254 | 'that a new feature introduces new incompatible syntax (such as a ' |
| 6255 | 'new\n' |
| 6256 | 'reserved word), in which case the compiler may need to parse the\n' |
| 6257 | 'module differently. Such decisions cannot be pushed off until\n' |
| 6258 | 'runtime.\n' |
| 6259 | '\n' |
| 6260 | 'For any given release, the compiler knows which feature names ' |
| 6261 | 'have\n' |
| 6262 | 'been defined, and raises a compile-time error if a future ' |
| 6263 | 'statement\n' |
| 6264 | 'contains a feature not known to it.\n' |
| 6265 | '\n' |
| 6266 | 'The direct runtime semantics are the same as for any import ' |
| 6267 | 'statement:\n' |
| 6268 | 'there is a standard module "__future__", described later, and it ' |
| 6269 | 'will\n' |
| 6270 | 'be imported in the usual way at the time the future statement is\n' |
| 6271 | 'executed.\n' |
| 6272 | '\n' |
| 6273 | 'The interesting runtime semantics depend on the specific feature\n' |
| 6274 | 'enabled by the future statement.\n' |
| 6275 | '\n' |
| 6276 | 'Note that there is nothing special about the statement:\n' |
| 6277 | '\n' |
| 6278 | ' import __future__ [as name]\n' |
| 6279 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6280 | 'That is not a future statement; it’s an ordinary import statement ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6281 | 'with\n' |
| 6282 | 'no special semantics or syntax restrictions.\n' |
| 6283 | '\n' |
| 6284 | 'Code compiled by calls to the built-in functions "exec()" and\n' |
| 6285 | '"compile()" that occur in a module "M" containing a future ' |
| 6286 | 'statement\n' |
| 6287 | 'will, by default, use the new syntax or semantics associated with ' |
| 6288 | 'the\n' |
| 6289 | 'future statement. This can be controlled by optional arguments ' |
| 6290 | 'to\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6291 | '"compile()" — see the documentation of that function for details.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6292 | '\n' |
| 6293 | 'A future statement typed at an interactive interpreter prompt ' |
| 6294 | 'will\n' |
| 6295 | 'take effect for the rest of the interpreter session. If an\n' |
| 6296 | 'interpreter is started with the "-i" option, is passed a script ' |
| 6297 | 'name\n' |
| 6298 | 'to execute, and the script includes a future statement, it will be ' |
| 6299 | 'in\n' |
| 6300 | 'effect in the interactive session started after the script is\n' |
| 6301 | 'executed.\n' |
| 6302 | '\n' |
| 6303 | 'See also:\n' |
| 6304 | '\n' |
| 6305 | ' **PEP 236** - Back to the __future__\n' |
| 6306 | ' The original proposal for the __future__ mechanism.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6307 | 'in': 'Membership test operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6308 | '**************************\n' |
| 6309 | '\n' |
| 6310 | 'The operators "in" and "not in" test for membership. "x in s"\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6311 | 'evaluates to "True" if *x* is a member of *s*, and "False" otherwise.\n' |
| 6312 | '"x not in s" returns the negation of "x in s". All built-in ' |
| 6313 | 'sequences\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6314 | 'and set types support this as well as dictionary, for which "in" ' |
| 6315 | 'tests\n' |
| 6316 | 'whether the dictionary has a given key. For container types such as\n' |
| 6317 | 'list, tuple, set, frozenset, dict, or collections.deque, the\n' |
| 6318 | 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' |
| 6319 | 'y)".\n' |
| 6320 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6321 | 'For the string and bytes types, "x in y" is "True" if and only if *x*\n' |
| 6322 | 'is a substring of *y*. An equivalent test is "y.find(x) != -1".\n' |
| 6323 | 'Empty strings are always considered to be a substring of any other\n' |
| 6324 | 'string, so """ in "abc"" will return "True".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6325 | '\n' |
| 6326 | 'For user-defined classes which define the "__contains__()" method, "x\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6327 | 'in y" returns "True" if "y.__contains__(x)" returns a true value, and\n' |
| 6328 | '"False" otherwise.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6329 | '\n' |
| 6330 | 'For user-defined classes which do not define "__contains__()" but do\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6331 | 'define "__iter__()", "x in y" is "True" if some value "z" with "x ==\n' |
| 6332 | 'z" is produced while iterating over "y". If an exception is raised\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6333 | 'during the iteration, it is as if "in" raised that exception.\n' |
| 6334 | '\n' |
| 6335 | 'Lastly, the old-style iteration protocol is tried: if a class defines\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6336 | '"__getitem__()", "x in y" is "True" if and only if there is a non-\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6337 | 'negative integer index *i* such that "x == y[i]", and all lower\n' |
| 6338 | 'integer indices do not raise "IndexError" exception. (If any other\n' |
| 6339 | 'exception is raised, it is as if "in" raised that exception).\n' |
| 6340 | '\n' |
| 6341 | 'The operator "not in" is defined to have the inverse true value of\n' |
| 6342 | '"in".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6343 | 'integers': 'Integer literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6344 | '****************\n' |
| 6345 | '\n' |
| 6346 | 'Integer literals are described by the following lexical ' |
| 6347 | 'definitions:\n' |
| 6348 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6349 | ' integer ::= decinteger | bininteger | octinteger | ' |
| 6350 | 'hexinteger\n' |
| 6351 | ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] ' |
| 6352 | '"0")*\n' |
| 6353 | ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n' |
| 6354 | ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n' |
| 6355 | ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n' |
| 6356 | ' nonzerodigit ::= "1"..."9"\n' |
| 6357 | ' digit ::= "0"..."9"\n' |
| 6358 | ' bindigit ::= "0" | "1"\n' |
| 6359 | ' octdigit ::= "0"..."7"\n' |
| 6360 | ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6361 | '\n' |
| 6362 | 'There is no limit for the length of integer literals apart from ' |
| 6363 | 'what\n' |
| 6364 | 'can be stored in available memory.\n' |
| 6365 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6366 | 'Underscores are ignored for determining the numeric value of ' |
| 6367 | 'the\n' |
| 6368 | 'literal. They can be used to group digits for enhanced ' |
| 6369 | 'readability.\n' |
| 6370 | 'One underscore can occur between digits, and after base ' |
| 6371 | 'specifiers\n' |
| 6372 | 'like "0x".\n' |
| 6373 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6374 | 'Note that leading zeros in a non-zero decimal number are not ' |
| 6375 | 'allowed.\n' |
| 6376 | 'This is for disambiguation with C-style octal literals, which ' |
| 6377 | 'Python\n' |
| 6378 | 'used before version 3.0.\n' |
| 6379 | '\n' |
| 6380 | 'Some examples of integer literals:\n' |
| 6381 | '\n' |
| 6382 | ' 7 2147483647 0o177 0b100110111\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6383 | ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n' |
| 6384 | ' 100_000_000_000 0b_1110_0101\n' |
| 6385 | '\n' |
| 6386 | 'Changed in version 3.6: Underscores are now allowed for ' |
| 6387 | 'grouping\n' |
| 6388 | 'purposes in literals.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6389 | 'lambda': 'Lambdas\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6390 | '*******\n' |
| 6391 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6392 | ' lambda_expr ::= "lambda" [parameter_list] ":" ' |
| 6393 | 'expression\n' |
| 6394 | ' lambda_expr_nocond ::= "lambda" [parameter_list] ":" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6395 | 'expression_nocond\n' |
| 6396 | '\n' |
| 6397 | 'Lambda expressions (sometimes called lambda forms) are used to ' |
| 6398 | 'create\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6399 | 'anonymous functions. The expression "lambda parameters: ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6400 | 'expression"\n' |
| 6401 | 'yields a function object. The unnamed object behaves like a ' |
| 6402 | 'function\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 6403 | 'object defined with:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6404 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6405 | ' def <lambda>(parameters):\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6406 | ' return expression\n' |
| 6407 | '\n' |
| 6408 | 'See section Function definitions for the syntax of parameter ' |
| 6409 | 'lists.\n' |
| 6410 | 'Note that functions created with lambda expressions cannot ' |
| 6411 | 'contain\n' |
| 6412 | 'statements or annotations.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6413 | 'lists': 'List displays\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6414 | '*************\n' |
| 6415 | '\n' |
| 6416 | 'A list display is a possibly empty series of expressions enclosed ' |
| 6417 | 'in\n' |
| 6418 | 'square brackets:\n' |
| 6419 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 6420 | ' list_display ::= "[" [starred_list | comprehension] "]"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6421 | '\n' |
| 6422 | 'A list display yields a new list object, the contents being ' |
| 6423 | 'specified\n' |
| 6424 | 'by either a list of expressions or a comprehension. When a comma-\n' |
| 6425 | 'separated list of expressions is supplied, its elements are ' |
| 6426 | 'evaluated\n' |
| 6427 | 'from left to right and placed into the list object in that order.\n' |
| 6428 | 'When a comprehension is supplied, the list is constructed from the\n' |
| 6429 | 'elements resulting from the comprehension.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6430 | 'naming': 'Naming and binding\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6431 | '******************\n' |
| 6432 | '\n' |
| 6433 | '\n' |
| 6434 | 'Binding of names\n' |
| 6435 | '================\n' |
| 6436 | '\n' |
| 6437 | '*Names* refer to objects. Names are introduced by name binding\n' |
| 6438 | 'operations.\n' |
| 6439 | '\n' |
| 6440 | 'The following constructs bind names: formal parameters to ' |
| 6441 | 'functions,\n' |
| 6442 | '"import" statements, class and function definitions (these bind ' |
| 6443 | 'the\n' |
| 6444 | 'class or function name in the defining block), and targets that ' |
| 6445 | 'are\n' |
| 6446 | 'identifiers if occurring in an assignment, "for" loop header, or ' |
| 6447 | 'after\n' |
| 6448 | '"as" in a "with" statement or "except" clause. The "import" ' |
| 6449 | 'statement\n' |
| 6450 | 'of the form "from ... import *" binds all names defined in the\n' |
| 6451 | 'imported module, except those beginning with an underscore. This ' |
| 6452 | 'form\n' |
| 6453 | 'may only be used at the module level.\n' |
| 6454 | '\n' |
| 6455 | 'A target occurring in a "del" statement is also considered bound ' |
| 6456 | 'for\n' |
| 6457 | 'this purpose (though the actual semantics are to unbind the ' |
| 6458 | 'name).\n' |
| 6459 | '\n' |
| 6460 | 'Each assignment or import statement occurs within a block defined ' |
| 6461 | 'by a\n' |
| 6462 | 'class or function definition or at the module level (the ' |
| 6463 | 'top-level\n' |
| 6464 | 'code block).\n' |
| 6465 | '\n' |
| 6466 | 'If a name is bound in a block, it is a local variable of that ' |
| 6467 | 'block,\n' |
| 6468 | 'unless declared as "nonlocal" or "global". If a name is bound at ' |
| 6469 | 'the\n' |
| 6470 | 'module level, it is a global variable. (The variables of the ' |
| 6471 | 'module\n' |
| 6472 | 'code block are local and global.) If a variable is used in a ' |
| 6473 | 'code\n' |
| 6474 | 'block but not defined there, it is a *free variable*.\n' |
| 6475 | '\n' |
| 6476 | 'Each occurrence of a name in the program text refers to the ' |
| 6477 | '*binding*\n' |
| 6478 | 'of that name established by the following name resolution rules.\n' |
| 6479 | '\n' |
| 6480 | '\n' |
| 6481 | 'Resolution of names\n' |
| 6482 | '===================\n' |
| 6483 | '\n' |
| 6484 | 'A *scope* defines the visibility of a name within a block. If a ' |
| 6485 | 'local\n' |
| 6486 | 'variable is defined in a block, its scope includes that block. If ' |
| 6487 | 'the\n' |
| 6488 | 'definition occurs in a function block, the scope extends to any ' |
| 6489 | 'blocks\n' |
| 6490 | 'contained within the defining one, unless a contained block ' |
| 6491 | 'introduces\n' |
| 6492 | 'a different binding for the name.\n' |
| 6493 | '\n' |
| 6494 | 'When a name is used in a code block, it is resolved using the ' |
| 6495 | 'nearest\n' |
| 6496 | 'enclosing scope. The set of all such scopes visible to a code ' |
| 6497 | 'block\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6498 | 'is called the block’s *environment*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6499 | '\n' |
| 6500 | 'When a name is not found at all, a "NameError" exception is ' |
| 6501 | 'raised. If\n' |
| 6502 | 'the current scope is a function scope, and the name refers to a ' |
| 6503 | 'local\n' |
| 6504 | 'variable that has not yet been bound to a value at the point where ' |
| 6505 | 'the\n' |
| 6506 | 'name is used, an "UnboundLocalError" exception is raised.\n' |
| 6507 | '"UnboundLocalError" is a subclass of "NameError".\n' |
| 6508 | '\n' |
| 6509 | 'If a name binding operation occurs anywhere within a code block, ' |
| 6510 | 'all\n' |
| 6511 | 'uses of the name within the block are treated as references to ' |
| 6512 | 'the\n' |
| 6513 | 'current block. This can lead to errors when a name is used within ' |
| 6514 | 'a\n' |
| 6515 | 'block before it is bound. This rule is subtle. Python lacks\n' |
| 6516 | 'declarations and allows name binding operations to occur anywhere\n' |
| 6517 | 'within a code block. The local variables of a code block can be\n' |
| 6518 | 'determined by scanning the entire text of the block for name ' |
| 6519 | 'binding\n' |
| 6520 | 'operations.\n' |
| 6521 | '\n' |
| 6522 | 'If the "global" statement occurs within a block, all uses of the ' |
| 6523 | 'name\n' |
| 6524 | 'specified in the statement refer to the binding of that name in ' |
| 6525 | 'the\n' |
| 6526 | 'top-level namespace. Names are resolved in the top-level ' |
| 6527 | 'namespace by\n' |
| 6528 | 'searching the global namespace, i.e. the namespace of the module\n' |
| 6529 | 'containing the code block, and the builtins namespace, the ' |
| 6530 | 'namespace\n' |
| 6531 | 'of the module "builtins". The global namespace is searched ' |
| 6532 | 'first. If\n' |
| 6533 | 'the name is not found there, the builtins namespace is searched. ' |
| 6534 | 'The\n' |
| 6535 | '"global" statement must precede all uses of the name.\n' |
| 6536 | '\n' |
| 6537 | 'The "global" statement has the same scope as a name binding ' |
| 6538 | 'operation\n' |
| 6539 | 'in the same block. If the nearest enclosing scope for a free ' |
| 6540 | 'variable\n' |
| 6541 | 'contains a global statement, the free variable is treated as a ' |
| 6542 | 'global.\n' |
| 6543 | '\n' |
| 6544 | 'The "nonlocal" statement causes corresponding names to refer to\n' |
| 6545 | 'previously bound variables in the nearest enclosing function ' |
| 6546 | 'scope.\n' |
| 6547 | '"SyntaxError" is raised at compile time if the given name does ' |
| 6548 | 'not\n' |
| 6549 | 'exist in any enclosing function scope.\n' |
| 6550 | '\n' |
| 6551 | 'The namespace for a module is automatically created the first time ' |
| 6552 | 'a\n' |
| 6553 | 'module is imported. The main module for a script is always ' |
| 6554 | 'called\n' |
| 6555 | '"__main__".\n' |
| 6556 | '\n' |
| 6557 | 'Class definition blocks and arguments to "exec()" and "eval()" ' |
| 6558 | 'are\n' |
| 6559 | 'special in the context of name resolution. A class definition is ' |
| 6560 | 'an\n' |
| 6561 | 'executable statement that may use and define names. These ' |
| 6562 | 'references\n' |
| 6563 | 'follow the normal rules for name resolution with an exception ' |
| 6564 | 'that\n' |
| 6565 | 'unbound local variables are looked up in the global namespace. ' |
| 6566 | 'The\n' |
| 6567 | 'namespace of the class definition becomes the attribute dictionary ' |
| 6568 | 'of\n' |
| 6569 | 'the class. The scope of names defined in a class block is limited ' |
| 6570 | 'to\n' |
| 6571 | 'the class block; it does not extend to the code blocks of methods ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6572 | '–\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6573 | 'this includes comprehensions and generator expressions since they ' |
| 6574 | 'are\n' |
| 6575 | 'implemented using a function scope. This means that the ' |
| 6576 | 'following\n' |
| 6577 | 'will fail:\n' |
| 6578 | '\n' |
| 6579 | ' class A:\n' |
| 6580 | ' a = 42\n' |
| 6581 | ' b = list(a + i for i in range(10))\n' |
| 6582 | '\n' |
| 6583 | '\n' |
| 6584 | 'Builtins and restricted execution\n' |
| 6585 | '=================================\n' |
| 6586 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6587 | '**CPython implementation detail:** Users should not touch\n' |
| 6588 | '"__builtins__"; it is strictly an implementation detail. Users\n' |
| 6589 | 'wanting to override values in the builtins namespace should ' |
| 6590 | '"import"\n' |
| 6591 | 'the "builtins" module and modify its attributes appropriately.\n' |
| 6592 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6593 | 'The builtins namespace associated with the execution of a code ' |
| 6594 | 'block\n' |
| 6595 | 'is actually found by looking up the name "__builtins__" in its ' |
| 6596 | 'global\n' |
| 6597 | 'namespace; this should be a dictionary or a module (in the latter ' |
| 6598 | 'case\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6599 | 'the module’s dictionary is used). By default, when in the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6600 | '"__main__"\n' |
| 6601 | 'module, "__builtins__" is the built-in module "builtins"; when in ' |
| 6602 | 'any\n' |
| 6603 | 'other module, "__builtins__" is an alias for the dictionary of ' |
| 6604 | 'the\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6605 | '"builtins" module itself.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6606 | '\n' |
| 6607 | '\n' |
| 6608 | 'Interaction with dynamic features\n' |
| 6609 | '=================================\n' |
| 6610 | '\n' |
| 6611 | 'Name resolution of free variables occurs at runtime, not at ' |
| 6612 | 'compile\n' |
| 6613 | 'time. This means that the following code will print 42:\n' |
| 6614 | '\n' |
| 6615 | ' i = 10\n' |
| 6616 | ' def f():\n' |
| 6617 | ' print(i)\n' |
| 6618 | ' i = 42\n' |
| 6619 | ' f()\n' |
| 6620 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6621 | 'The "eval()" and "exec()" functions do not have access to the ' |
| 6622 | 'full\n' |
| 6623 | 'environment for resolving names. Names may be resolved in the ' |
| 6624 | 'local\n' |
| 6625 | 'and global namespaces of the caller. Free variables are not ' |
| 6626 | 'resolved\n' |
| 6627 | 'in the nearest enclosing namespace, but in the global namespace. ' |
| 6628 | '[1]\n' |
| 6629 | 'The "exec()" and "eval()" functions have optional arguments to\n' |
| 6630 | 'override the global and local namespace. If only one namespace ' |
| 6631 | 'is\n' |
| 6632 | 'specified, it is used for both.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6633 | 'nonlocal': 'The "nonlocal" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6634 | '************************\n' |
| 6635 | '\n' |
| 6636 | ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' |
| 6637 | '\n' |
| 6638 | 'The "nonlocal" statement causes the listed identifiers to refer ' |
| 6639 | 'to\n' |
| 6640 | 'previously bound variables in the nearest enclosing scope ' |
| 6641 | 'excluding\n' |
| 6642 | 'globals. This is important because the default behavior for ' |
| 6643 | 'binding is\n' |
| 6644 | 'to search the local namespace first. The statement allows\n' |
| 6645 | 'encapsulated code to rebind variables outside of the local ' |
| 6646 | 'scope\n' |
| 6647 | 'besides the global (module) scope.\n' |
| 6648 | '\n' |
| 6649 | 'Names listed in a "nonlocal" statement, unlike those listed in ' |
| 6650 | 'a\n' |
| 6651 | '"global" statement, must refer to pre-existing bindings in an\n' |
| 6652 | 'enclosing scope (the scope in which a new binding should be ' |
| 6653 | 'created\n' |
| 6654 | 'cannot be determined unambiguously).\n' |
| 6655 | '\n' |
| 6656 | 'Names listed in a "nonlocal" statement must not collide with ' |
| 6657 | 'pre-\n' |
| 6658 | 'existing bindings in the local scope.\n' |
| 6659 | '\n' |
| 6660 | 'See also:\n' |
| 6661 | '\n' |
| 6662 | ' **PEP 3104** - Access to Names in Outer Scopes\n' |
| 6663 | ' The specification for the "nonlocal" statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6664 | 'numbers': 'Numeric literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6665 | '****************\n' |
| 6666 | '\n' |
| 6667 | 'There are three types of numeric literals: integers, floating ' |
| 6668 | 'point\n' |
| 6669 | 'numbers, and imaginary numbers. There are no complex literals\n' |
| 6670 | '(complex numbers can be formed by adding a real number and an\n' |
| 6671 | 'imaginary number).\n' |
| 6672 | '\n' |
| 6673 | 'Note that numeric literals do not include a sign; a phrase like ' |
| 6674 | '"-1"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6675 | 'is actually an expression composed of the unary operator ‘"-"‘ ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6676 | 'and the\n' |
| 6677 | 'literal "1".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6678 | 'numeric-types': 'Emulating numeric types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6679 | '***********************\n' |
| 6680 | '\n' |
| 6681 | 'The following methods can be defined to emulate numeric ' |
| 6682 | 'objects.\n' |
| 6683 | 'Methods corresponding to operations that are not supported ' |
| 6684 | 'by the\n' |
| 6685 | 'particular kind of number implemented (e.g., bitwise ' |
| 6686 | 'operations for\n' |
| 6687 | 'non-integral numbers) should be left undefined.\n' |
| 6688 | '\n' |
| 6689 | 'object.__add__(self, other)\n' |
| 6690 | 'object.__sub__(self, other)\n' |
| 6691 | 'object.__mul__(self, other)\n' |
| 6692 | 'object.__matmul__(self, other)\n' |
| 6693 | 'object.__truediv__(self, other)\n' |
| 6694 | 'object.__floordiv__(self, other)\n' |
| 6695 | 'object.__mod__(self, other)\n' |
| 6696 | 'object.__divmod__(self, other)\n' |
| 6697 | 'object.__pow__(self, other[, modulo])\n' |
| 6698 | 'object.__lshift__(self, other)\n' |
| 6699 | 'object.__rshift__(self, other)\n' |
| 6700 | 'object.__and__(self, other)\n' |
| 6701 | 'object.__xor__(self, other)\n' |
| 6702 | 'object.__or__(self, other)\n' |
| 6703 | '\n' |
| 6704 | ' These methods are called to implement the binary ' |
| 6705 | 'arithmetic\n' |
| 6706 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 6707 | '"divmod()",\n' |
| 6708 | ' "pow()", "**", "<<", ">>", "&", "^", "|"). For ' |
| 6709 | 'instance, to\n' |
| 6710 | ' evaluate the expression "x + y", where *x* is an ' |
| 6711 | 'instance of a\n' |
| 6712 | ' class that has an "__add__()" method, "x.__add__(y)" is ' |
| 6713 | 'called.\n' |
| 6714 | ' The "__divmod__()" method should be the equivalent to ' |
| 6715 | 'using\n' |
| 6716 | ' "__floordiv__()" and "__mod__()"; it should not be ' |
| 6717 | 'related to\n' |
| 6718 | ' "__truediv__()". Note that "__pow__()" should be ' |
| 6719 | 'defined to accept\n' |
| 6720 | ' an optional third argument if the ternary version of the ' |
| 6721 | 'built-in\n' |
| 6722 | ' "pow()" function is to be supported.\n' |
| 6723 | '\n' |
| 6724 | ' If one of those methods does not support the operation ' |
| 6725 | 'with the\n' |
| 6726 | ' supplied arguments, it should return "NotImplemented".\n' |
| 6727 | '\n' |
| 6728 | 'object.__radd__(self, other)\n' |
| 6729 | 'object.__rsub__(self, other)\n' |
| 6730 | 'object.__rmul__(self, other)\n' |
| 6731 | 'object.__rmatmul__(self, other)\n' |
| 6732 | 'object.__rtruediv__(self, other)\n' |
| 6733 | 'object.__rfloordiv__(self, other)\n' |
| 6734 | 'object.__rmod__(self, other)\n' |
| 6735 | 'object.__rdivmod__(self, other)\n' |
| 6736 | 'object.__rpow__(self, other)\n' |
| 6737 | 'object.__rlshift__(self, other)\n' |
| 6738 | 'object.__rrshift__(self, other)\n' |
| 6739 | 'object.__rand__(self, other)\n' |
| 6740 | 'object.__rxor__(self, other)\n' |
| 6741 | 'object.__ror__(self, other)\n' |
| 6742 | '\n' |
| 6743 | ' These methods are called to implement the binary ' |
| 6744 | 'arithmetic\n' |
| 6745 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 6746 | '"divmod()",\n' |
| 6747 | ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' |
| 6748 | '(swapped)\n' |
| 6749 | ' operands. These functions are only called if the left ' |
| 6750 | 'operand does\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6751 | ' not support the corresponding operation [3] and the ' |
| 6752 | 'operands are of\n' |
| 6753 | ' different types. [4] For instance, to evaluate the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6754 | 'expression "x -\n' |
| 6755 | ' y", where *y* is an instance of a class that has an ' |
| 6756 | '"__rsub__()"\n' |
| 6757 | ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' |
| 6758 | 'returns\n' |
| 6759 | ' *NotImplemented*.\n' |
| 6760 | '\n' |
| 6761 | ' Note that ternary "pow()" will not try calling ' |
| 6762 | '"__rpow__()" (the\n' |
| 6763 | ' coercion rules would become too complicated).\n' |
| 6764 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6765 | ' Note: If the right operand’s type is a subclass of the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6766 | 'left\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6767 | ' operand’s type and that subclass provides the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6768 | 'reflected method\n' |
| 6769 | ' for the operation, this method will be called before ' |
| 6770 | 'the left\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6771 | ' operand’s non-reflected method. This behavior allows ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6772 | 'subclasses\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6773 | ' to override their ancestors’ operations.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6774 | '\n' |
| 6775 | 'object.__iadd__(self, other)\n' |
| 6776 | 'object.__isub__(self, other)\n' |
| 6777 | 'object.__imul__(self, other)\n' |
| 6778 | 'object.__imatmul__(self, other)\n' |
| 6779 | 'object.__itruediv__(self, other)\n' |
| 6780 | 'object.__ifloordiv__(self, other)\n' |
| 6781 | 'object.__imod__(self, other)\n' |
| 6782 | 'object.__ipow__(self, other[, modulo])\n' |
| 6783 | 'object.__ilshift__(self, other)\n' |
| 6784 | 'object.__irshift__(self, other)\n' |
| 6785 | 'object.__iand__(self, other)\n' |
| 6786 | 'object.__ixor__(self, other)\n' |
| 6787 | 'object.__ior__(self, other)\n' |
| 6788 | '\n' |
| 6789 | ' These methods are called to implement the augmented ' |
| 6790 | 'arithmetic\n' |
| 6791 | ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' |
| 6792 | '"**=",\n' |
| 6793 | ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' |
| 6794 | 'attempt to\n' |
| 6795 | ' do the operation in-place (modifying *self*) and return ' |
| 6796 | 'the result\n' |
| 6797 | ' (which could be, but does not have to be, *self*). If a ' |
| 6798 | 'specific\n' |
| 6799 | ' method is not defined, the augmented assignment falls ' |
| 6800 | 'back to the\n' |
| 6801 | ' normal methods. For instance, if *x* is an instance of ' |
| 6802 | 'a class\n' |
| 6803 | ' with an "__iadd__()" method, "x += y" is equivalent to ' |
| 6804 | '"x =\n' |
| 6805 | ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' |
| 6806 | '"y.__radd__(x)" are\n' |
| 6807 | ' considered, as with the evaluation of "x + y". In ' |
| 6808 | 'certain\n' |
| 6809 | ' situations, augmented assignment can result in ' |
| 6810 | 'unexpected errors\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6811 | ' (see Why does a_tuple[i] += [‘item’] raise an exception ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6812 | 'when the\n' |
| 6813 | ' addition works?), but this behavior is in fact part of ' |
| 6814 | 'the data\n' |
| 6815 | ' model.\n' |
| 6816 | '\n' |
| 6817 | 'object.__neg__(self)\n' |
| 6818 | 'object.__pos__(self)\n' |
| 6819 | 'object.__abs__(self)\n' |
| 6820 | 'object.__invert__(self)\n' |
| 6821 | '\n' |
| 6822 | ' Called to implement the unary arithmetic operations ' |
| 6823 | '("-", "+",\n' |
| 6824 | ' "abs()" and "~").\n' |
| 6825 | '\n' |
| 6826 | 'object.__complex__(self)\n' |
| 6827 | 'object.__int__(self)\n' |
| 6828 | 'object.__float__(self)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6829 | '\n' |
| 6830 | ' Called to implement the built-in functions "complex()", ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6831 | '"int()" and\n' |
| 6832 | ' "float()". Should return a value of the appropriate ' |
| 6833 | 'type.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6834 | '\n' |
| 6835 | 'object.__index__(self)\n' |
| 6836 | '\n' |
| 6837 | ' Called to implement "operator.index()", and whenever ' |
| 6838 | 'Python needs\n' |
| 6839 | ' to losslessly convert the numeric object to an integer ' |
| 6840 | 'object (such\n' |
| 6841 | ' as in slicing, or in the built-in "bin()", "hex()" and ' |
| 6842 | '"oct()"\n' |
| 6843 | ' functions). Presence of this method indicates that the ' |
| 6844 | 'numeric\n' |
| 6845 | ' object is an integer type. Must return an integer.\n' |
| 6846 | '\n' |
| 6847 | ' Note: In order to have a coherent integer type class, ' |
| 6848 | 'when\n' |
| 6849 | ' "__index__()" is defined "__int__()" should also be ' |
| 6850 | 'defined, and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6851 | ' both should return the same value.\n' |
| 6852 | '\n' |
| 6853 | 'object.__round__(self[, ndigits])\n' |
| 6854 | 'object.__trunc__(self)\n' |
| 6855 | 'object.__floor__(self)\n' |
| 6856 | 'object.__ceil__(self)\n' |
| 6857 | '\n' |
| 6858 | ' Called to implement the built-in function "round()" and ' |
| 6859 | '"math"\n' |
| 6860 | ' functions "trunc()", "floor()" and "ceil()". Unless ' |
| 6861 | '*ndigits* is\n' |
| 6862 | ' passed to "__round__()" all these methods should return ' |
| 6863 | 'the value\n' |
| 6864 | ' of the object truncated to an "Integral" (typically an ' |
| 6865 | '"int").\n' |
| 6866 | '\n' |
| 6867 | ' If "__int__()" is not defined then the built-in function ' |
| 6868 | '"int()"\n' |
| 6869 | ' falls back to "__trunc__()".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6870 | 'objects': 'Objects, values and types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6871 | '*************************\n' |
| 6872 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6873 | '*Objects* are Python’s abstraction for data. All data in a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6874 | 'Python\n' |
| 6875 | 'program is represented by objects or by relations between ' |
| 6876 | 'objects. (In\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6877 | 'a sense, and in conformance to Von Neumann’s model of a “stored\n' |
| 6878 | 'program computer,” code is also represented by objects.)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6879 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6880 | 'Every object has an identity, a type and a value. An object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6881 | '*identity* never changes once it has been created; you may think ' |
| 6882 | 'of it\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6883 | 'as the object’s address in memory. The ‘"is"’ operator compares ' |
| 6884 | 'the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6885 | 'identity of two objects; the "id()" function returns an integer\n' |
| 6886 | 'representing its identity.\n' |
| 6887 | '\n' |
| 6888 | '**CPython implementation detail:** For CPython, "id(x)" is the ' |
| 6889 | 'memory\n' |
| 6890 | 'address where "x" is stored.\n' |
| 6891 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6892 | 'An object’s type determines the operations that the object ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6893 | 'supports\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6894 | '(e.g., “does it have a length?”) and also defines the possible ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6895 | 'values\n' |
| 6896 | 'for objects of that type. The "type()" function returns an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6897 | 'object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6898 | 'type (which is an object itself). Like its identity, an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6899 | 'object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6900 | '*type* is also unchangeable. [1]\n' |
| 6901 | '\n' |
| 6902 | 'The *value* of some objects can change. Objects whose value can\n' |
| 6903 | 'change are said to be *mutable*; objects whose value is ' |
| 6904 | 'unchangeable\n' |
| 6905 | 'once they are created are called *immutable*. (The value of an\n' |
| 6906 | 'immutable container object that contains a reference to a ' |
| 6907 | 'mutable\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6908 | 'object can change when the latter’s value is changed; however ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6909 | 'the\n' |
| 6910 | 'container is still considered immutable, because the collection ' |
| 6911 | 'of\n' |
| 6912 | 'objects it contains cannot be changed. So, immutability is not\n' |
| 6913 | 'strictly the same as having an unchangeable value, it is more ' |
| 6914 | 'subtle.)\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6915 | 'An object’s mutability is determined by its type; for instance,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6916 | 'numbers, strings and tuples are immutable, while dictionaries ' |
| 6917 | 'and\n' |
| 6918 | 'lists are mutable.\n' |
| 6919 | '\n' |
| 6920 | 'Objects are never explicitly destroyed; however, when they ' |
| 6921 | 'become\n' |
| 6922 | 'unreachable they may be garbage-collected. An implementation is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6923 | 'allowed to postpone garbage collection or omit it altogether — it ' |
| 6924 | 'is a\n' |
| 6925 | 'matter of implementation quality how garbage collection is\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6926 | 'implemented, as long as no objects are collected that are still\n' |
| 6927 | 'reachable.\n' |
| 6928 | '\n' |
| 6929 | '**CPython implementation detail:** CPython currently uses a ' |
| 6930 | 'reference-\n' |
| 6931 | 'counting scheme with (optional) delayed detection of cyclically ' |
| 6932 | 'linked\n' |
| 6933 | 'garbage, which collects most objects as soon as they become\n' |
| 6934 | 'unreachable, but is not guaranteed to collect garbage containing\n' |
| 6935 | 'circular references. See the documentation of the "gc" module ' |
| 6936 | 'for\n' |
| 6937 | 'information on controlling the collection of cyclic garbage. ' |
| 6938 | 'Other\n' |
| 6939 | 'implementations act differently and CPython may change. Do not ' |
| 6940 | 'depend\n' |
| 6941 | 'on immediate finalization of objects when they become unreachable ' |
| 6942 | '(so\n' |
| 6943 | 'you should always close files explicitly).\n' |
| 6944 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6945 | 'Note that the use of the implementation’s tracing or debugging\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6946 | 'facilities may keep objects alive that would normally be ' |
| 6947 | 'collectable.\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6948 | 'Also note that catching an exception with a ‘"try"…"except"’ ' |
| 6949 | 'statement\n' |
| 6950 | 'may keep objects alive.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6951 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6952 | 'Some objects contain references to “external” resources such as ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6953 | 'open\n' |
| 6954 | 'files or windows. It is understood that these resources are ' |
| 6955 | 'freed\n' |
| 6956 | 'when the object is garbage-collected, but since garbage ' |
| 6957 | 'collection is\n' |
| 6958 | 'not guaranteed to happen, such objects also provide an explicit ' |
| 6959 | 'way to\n' |
| 6960 | 'release the external resource, usually a "close()" method. ' |
| 6961 | 'Programs\n' |
| 6962 | 'are strongly recommended to explicitly close such objects. The\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6963 | '‘"try"…"finally"’ statement and the ‘"with"’ statement provide\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6964 | 'convenient ways to do this.\n' |
| 6965 | '\n' |
| 6966 | 'Some objects contain references to other objects; these are ' |
| 6967 | 'called\n' |
| 6968 | '*containers*. Examples of containers are tuples, lists and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 6969 | 'dictionaries. The references are part of a container’s value. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6970 | 'In\n' |
| 6971 | 'most cases, when we talk about the value of a container, we imply ' |
| 6972 | 'the\n' |
| 6973 | 'values, not the identities of the contained objects; however, ' |
| 6974 | 'when we\n' |
| 6975 | 'talk about the mutability of a container, only the identities of ' |
| 6976 | 'the\n' |
| 6977 | 'immediately contained objects are implied. So, if an immutable\n' |
| 6978 | 'container (like a tuple) contains a reference to a mutable ' |
| 6979 | 'object, its\n' |
| 6980 | 'value changes if that mutable object is changed.\n' |
| 6981 | '\n' |
| 6982 | 'Types affect almost all aspects of object behavior. Even the\n' |
| 6983 | 'importance of object identity is affected in some sense: for ' |
| 6984 | 'immutable\n' |
| 6985 | 'types, operations that compute new values may actually return a\n' |
| 6986 | 'reference to any existing object with the same type and value, ' |
| 6987 | 'while\n' |
| 6988 | 'for mutable objects this is not allowed. E.g., after "a = 1; b = ' |
| 6989 | '1",\n' |
| 6990 | '"a" and "b" may or may not refer to the same object with the ' |
| 6991 | 'value\n' |
| 6992 | 'one, depending on the implementation, but after "c = []; d = []", ' |
| 6993 | '"c"\n' |
| 6994 | 'and "d" are guaranteed to refer to two different, unique, newly\n' |
| 6995 | 'created empty lists. (Note that "c = d = []" assigns the same ' |
| 6996 | 'object\n' |
| 6997 | 'to both "c" and "d".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6998 | 'operator-summary': 'Operator precedence\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6999 | '*******************\n' |
| 7000 | '\n' |
| 7001 | 'The following table summarizes the operator precedence ' |
| 7002 | 'in Python, from\n' |
| 7003 | 'lowest precedence (least binding) to highest precedence ' |
| 7004 | '(most\n' |
| 7005 | 'binding). Operators in the same box have the same ' |
| 7006 | 'precedence. Unless\n' |
| 7007 | 'the syntax is explicitly given, operators are binary. ' |
| 7008 | 'Operators in\n' |
| 7009 | 'the same box group left to right (except for ' |
| 7010 | 'exponentiation, which\n' |
| 7011 | 'groups from right to left).\n' |
| 7012 | '\n' |
| 7013 | 'Note that comparisons, membership tests, and identity ' |
| 7014 | 'tests, all have\n' |
| 7015 | 'the same precedence and have a left-to-right chaining ' |
| 7016 | 'feature as\n' |
| 7017 | 'described in the Comparisons section.\n' |
| 7018 | '\n' |
| 7019 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7020 | '| Operator | ' |
| 7021 | 'Description |\n' |
| 7022 | '+=================================================+=======================================+\n' |
| 7023 | '| "lambda" | ' |
| 7024 | 'Lambda expression |\n' |
| 7025 | '+-------------------------------------------------+---------------------------------------+\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7026 | '| "if" – "else" | ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7027 | 'Conditional expression |\n' |
| 7028 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7029 | '| "or" | ' |
| 7030 | 'Boolean OR |\n' |
| 7031 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7032 | '| "and" | ' |
| 7033 | 'Boolean AND |\n' |
| 7034 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7035 | '| "not" "x" | ' |
| 7036 | 'Boolean NOT |\n' |
| 7037 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7038 | '| "in", "not in", "is", "is not", "<", "<=", ">", | ' |
| 7039 | 'Comparisons, including membership |\n' |
| 7040 | '| ">=", "!=", "==" | ' |
| 7041 | 'tests and identity tests |\n' |
| 7042 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7043 | '| "|" | ' |
| 7044 | 'Bitwise OR |\n' |
| 7045 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7046 | '| "^" | ' |
| 7047 | 'Bitwise XOR |\n' |
| 7048 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7049 | '| "&" | ' |
| 7050 | 'Bitwise AND |\n' |
| 7051 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7052 | '| "<<", ">>" | ' |
| 7053 | 'Shifts |\n' |
| 7054 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7055 | '| "+", "-" | ' |
| 7056 | 'Addition and subtraction |\n' |
| 7057 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7058 | '| "*", "@", "/", "//", "%" | ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7059 | 'Multiplication, matrix |\n' |
| 7060 | '| | ' |
| 7061 | 'multiplication, division, floor |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7062 | '| | ' |
| 7063 | 'division, remainder [5] |\n' |
| 7064 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7065 | '| "+x", "-x", "~x" | ' |
| 7066 | 'Positive, negative, bitwise NOT |\n' |
| 7067 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7068 | '| "**" | ' |
| 7069 | 'Exponentiation [6] |\n' |
| 7070 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7071 | '| "await" "x" | ' |
| 7072 | 'Await expression |\n' |
| 7073 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7074 | '| "x[index]", "x[index:index]", | ' |
| 7075 | 'Subscription, slicing, call, |\n' |
| 7076 | '| "x(arguments...)", "x.attribute" | ' |
| 7077 | 'attribute reference |\n' |
| 7078 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7079 | '| "(expressions...)", "[expressions...]", "{key: | ' |
| 7080 | 'Binding or tuple display, list |\n' |
| 7081 | '| value...}", "{expressions...}" | ' |
| 7082 | 'display, dictionary display, set |\n' |
| 7083 | '| | ' |
| 7084 | 'display |\n' |
| 7085 | '+-------------------------------------------------+---------------------------------------+\n' |
| 7086 | '\n' |
| 7087 | '-[ Footnotes ]-\n' |
| 7088 | '\n' |
| 7089 | '[1] While "abs(x%y) < abs(y)" is true mathematically, ' |
| 7090 | 'for floats\n' |
| 7091 | ' it may not be true numerically due to roundoff. For ' |
| 7092 | 'example, and\n' |
| 7093 | ' assuming a platform on which a Python float is an ' |
| 7094 | 'IEEE 754 double-\n' |
| 7095 | ' precision number, in order that "-1e-100 % 1e100" ' |
| 7096 | 'have the same\n' |
| 7097 | ' sign as "1e100", the computed result is "-1e-100 + ' |
| 7098 | '1e100", which\n' |
| 7099 | ' is numerically exactly equal to "1e100". The ' |
| 7100 | 'function\n' |
| 7101 | ' "math.fmod()" returns a result whose sign matches ' |
| 7102 | 'the sign of the\n' |
| 7103 | ' first argument instead, and so returns "-1e-100" in ' |
| 7104 | 'this case.\n' |
| 7105 | ' Which approach is more appropriate depends on the ' |
| 7106 | 'application.\n' |
| 7107 | '\n' |
| 7108 | '[2] If x is very close to an exact integer multiple of ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7109 | 'y, it’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7110 | ' possible for "x//y" to be one larger than ' |
| 7111 | '"(x-x%y)//y" due to\n' |
| 7112 | ' rounding. In such cases, Python returns the latter ' |
| 7113 | 'result, in\n' |
| 7114 | ' order to preserve that "divmod(x,y)[0] * y + x % y" ' |
| 7115 | 'be very close\n' |
| 7116 | ' to "x".\n' |
| 7117 | '\n' |
| 7118 | '[3] The Unicode standard distinguishes between *code ' |
| 7119 | 'points* (e.g.\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7120 | ' U+0041) and *abstract characters* (e.g. “LATIN ' |
| 7121 | 'CAPITAL LETTER A”).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7122 | ' While most abstract characters in Unicode are only ' |
| 7123 | 'represented\n' |
| 7124 | ' using one code point, there is a number of abstract ' |
| 7125 | 'characters\n' |
| 7126 | ' that can in addition be represented using a sequence ' |
| 7127 | 'of more than\n' |
| 7128 | ' one code point. For example, the abstract character ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7129 | '“LATIN\n' |
| 7130 | ' CAPITAL LETTER C WITH CEDILLA” can be represented as ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7131 | 'a single\n' |
| 7132 | ' *precomposed character* at code position U+00C7, or ' |
| 7133 | 'as a sequence\n' |
| 7134 | ' of a *base character* at code position U+0043 (LATIN ' |
| 7135 | 'CAPITAL\n' |
| 7136 | ' LETTER C), followed by a *combining character* at ' |
| 7137 | 'code position\n' |
| 7138 | ' U+0327 (COMBINING CEDILLA).\n' |
| 7139 | '\n' |
| 7140 | ' The comparison operators on strings compare at the ' |
| 7141 | 'level of\n' |
| 7142 | ' Unicode code points. This may be counter-intuitive ' |
| 7143 | 'to humans. For\n' |
| 7144 | ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", ' |
| 7145 | 'even though both\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7146 | ' strings represent the same abstract character “LATIN ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7147 | 'CAPITAL\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7148 | ' LETTER C WITH CEDILLA”.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7149 | '\n' |
| 7150 | ' To compare strings at the level of abstract ' |
| 7151 | 'characters (that is,\n' |
| 7152 | ' in a way intuitive to humans), use ' |
| 7153 | '"unicodedata.normalize()".\n' |
| 7154 | '\n' |
| 7155 | '[4] Due to automatic garbage-collection, free lists, and ' |
| 7156 | 'the\n' |
| 7157 | ' dynamic nature of descriptors, you may notice ' |
| 7158 | 'seemingly unusual\n' |
| 7159 | ' behaviour in certain uses of the "is" operator, like ' |
| 7160 | 'those\n' |
| 7161 | ' involving comparisons between instance methods, or ' |
| 7162 | 'constants.\n' |
| 7163 | ' Check their documentation for more info.\n' |
| 7164 | '\n' |
| 7165 | '[5] The "%" operator is also used for string formatting; ' |
| 7166 | 'the same\n' |
| 7167 | ' precedence applies.\n' |
| 7168 | '\n' |
| 7169 | '[6] The power operator "**" binds less tightly than an ' |
| 7170 | 'arithmetic\n' |
| 7171 | ' or bitwise unary operator on its right, that is, ' |
| 7172 | '"2**-1" is "0.5".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7173 | 'pass': 'The "pass" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7174 | '********************\n' |
| 7175 | '\n' |
| 7176 | ' pass_stmt ::= "pass"\n' |
| 7177 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7178 | '"pass" is a null operation — when it is executed, nothing happens. ' |
| 7179 | 'It\n' |
| 7180 | 'is useful as a placeholder when a statement is required ' |
| 7181 | 'syntactically,\n' |
| 7182 | 'but no code needs to be executed, for example:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7183 | '\n' |
| 7184 | ' def f(arg): pass # a function that does nothing (yet)\n' |
| 7185 | '\n' |
| 7186 | ' class C: pass # a class with no methods (yet)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7187 | 'power': 'The power operator\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7188 | '******************\n' |
| 7189 | '\n' |
| 7190 | 'The power operator binds more tightly than unary operators on its\n' |
| 7191 | 'left; it binds less tightly than unary operators on its right. ' |
| 7192 | 'The\n' |
| 7193 | 'syntax is:\n' |
| 7194 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7195 | ' power ::= (await_expr | primary) ["**" u_expr]\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7196 | '\n' |
| 7197 | 'Thus, in an unparenthesized sequence of power and unary operators, ' |
| 7198 | 'the\n' |
| 7199 | 'operators are evaluated from right to left (this does not ' |
| 7200 | 'constrain\n' |
| 7201 | 'the evaluation order for the operands): "-1**2" results in "-1".\n' |
| 7202 | '\n' |
| 7203 | 'The power operator has the same semantics as the built-in "pow()"\n' |
| 7204 | 'function, when called with two arguments: it yields its left ' |
| 7205 | 'argument\n' |
| 7206 | 'raised to the power of its right argument. The numeric arguments ' |
| 7207 | 'are\n' |
| 7208 | 'first converted to a common type, and the result is of that type.\n' |
| 7209 | '\n' |
| 7210 | 'For int operands, the result has the same type as the operands ' |
| 7211 | 'unless\n' |
| 7212 | 'the second argument is negative; in that case, all arguments are\n' |
| 7213 | 'converted to float and a float result is delivered. For example,\n' |
| 7214 | '"10**2" returns "100", but "10**-2" returns "0.01".\n' |
| 7215 | '\n' |
| 7216 | 'Raising "0.0" to a negative power results in a ' |
| 7217 | '"ZeroDivisionError".\n' |
| 7218 | 'Raising a negative number to a fractional power results in a ' |
| 7219 | '"complex"\n' |
| 7220 | 'number. (In earlier versions it raised a "ValueError".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7221 | 'raise': 'The "raise" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7222 | '*********************\n' |
| 7223 | '\n' |
| 7224 | ' raise_stmt ::= "raise" [expression ["from" expression]]\n' |
| 7225 | '\n' |
| 7226 | 'If no expressions are present, "raise" re-raises the last ' |
| 7227 | 'exception\n' |
| 7228 | 'that was active in the current scope. If no exception is active ' |
| 7229 | 'in\n' |
| 7230 | 'the current scope, a "RuntimeError" exception is raised indicating\n' |
| 7231 | 'that this is an error.\n' |
| 7232 | '\n' |
| 7233 | 'Otherwise, "raise" evaluates the first expression as the exception\n' |
| 7234 | 'object. It must be either a subclass or an instance of\n' |
| 7235 | '"BaseException". If it is a class, the exception instance will be\n' |
| 7236 | 'obtained when needed by instantiating the class with no arguments.\n' |
| 7237 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7238 | 'The *type* of the exception is the exception instance’s class, the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7239 | '*value* is the instance itself.\n' |
| 7240 | '\n' |
| 7241 | 'A traceback object is normally created automatically when an ' |
| 7242 | 'exception\n' |
| 7243 | 'is raised and attached to it as the "__traceback__" attribute, ' |
| 7244 | 'which\n' |
| 7245 | 'is writable. You can create an exception and set your own traceback ' |
| 7246 | 'in\n' |
| 7247 | 'one step using the "with_traceback()" exception method (which ' |
| 7248 | 'returns\n' |
| 7249 | 'the same exception instance, with its traceback set to its ' |
| 7250 | 'argument),\n' |
| 7251 | 'like so:\n' |
| 7252 | '\n' |
| 7253 | ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' |
| 7254 | '\n' |
| 7255 | 'The "from" clause is used for exception chaining: if given, the ' |
| 7256 | 'second\n' |
| 7257 | '*expression* must be another exception class or instance, which ' |
| 7258 | 'will\n' |
| 7259 | 'then be attached to the raised exception as the "__cause__" ' |
| 7260 | 'attribute\n' |
| 7261 | '(which is writable). If the raised exception is not handled, both\n' |
| 7262 | 'exceptions will be printed:\n' |
| 7263 | '\n' |
| 7264 | ' >>> try:\n' |
| 7265 | ' ... print(1 / 0)\n' |
| 7266 | ' ... except Exception as exc:\n' |
| 7267 | ' ... raise RuntimeError("Something bad happened") from exc\n' |
| 7268 | ' ...\n' |
| 7269 | ' Traceback (most recent call last):\n' |
| 7270 | ' File "<stdin>", line 2, in <module>\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7271 | ' ZeroDivisionError: division by zero\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7272 | '\n' |
| 7273 | ' The above exception was the direct cause of the following ' |
| 7274 | 'exception:\n' |
| 7275 | '\n' |
| 7276 | ' Traceback (most recent call last):\n' |
| 7277 | ' File "<stdin>", line 4, in <module>\n' |
| 7278 | ' RuntimeError: Something bad happened\n' |
| 7279 | '\n' |
| 7280 | 'A similar mechanism works implicitly if an exception is raised ' |
| 7281 | 'inside\n' |
| 7282 | 'an exception handler or a "finally" clause: the previous exception ' |
| 7283 | 'is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7284 | 'then attached as the new exception’s "__context__" attribute:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7285 | '\n' |
| 7286 | ' >>> try:\n' |
| 7287 | ' ... print(1 / 0)\n' |
| 7288 | ' ... except:\n' |
| 7289 | ' ... raise RuntimeError("Something bad happened")\n' |
| 7290 | ' ...\n' |
| 7291 | ' Traceback (most recent call last):\n' |
| 7292 | ' File "<stdin>", line 2, in <module>\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7293 | ' ZeroDivisionError: division by zero\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7294 | '\n' |
| 7295 | ' During handling of the above exception, another exception ' |
| 7296 | 'occurred:\n' |
| 7297 | '\n' |
| 7298 | ' Traceback (most recent call last):\n' |
| 7299 | ' File "<stdin>", line 4, in <module>\n' |
| 7300 | ' RuntimeError: Something bad happened\n' |
| 7301 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7302 | 'Exception chaining can be explicitly suppressed by specifying ' |
| 7303 | '"None"\n' |
| 7304 | 'in the "from" clause:\n' |
| 7305 | '\n' |
| 7306 | ' >>> try:\n' |
| 7307 | ' ... print(1 / 0)\n' |
| 7308 | ' ... except:\n' |
| 7309 | ' ... raise RuntimeError("Something bad happened") from None\n' |
| 7310 | ' ...\n' |
| 7311 | ' Traceback (most recent call last):\n' |
| 7312 | ' File "<stdin>", line 4, in <module>\n' |
| 7313 | ' RuntimeError: Something bad happened\n' |
| 7314 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7315 | 'Additional information on exceptions can be found in section\n' |
| 7316 | 'Exceptions, and information about handling exceptions is in ' |
| 7317 | 'section\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7318 | 'The try statement.\n' |
| 7319 | '\n' |
| 7320 | 'Changed in version 3.3: "None" is now permitted as "Y" in "raise X\n' |
| 7321 | 'from Y".\n' |
| 7322 | '\n' |
| 7323 | 'New in version 3.3: The "__suppress_context__" attribute to ' |
| 7324 | 'suppress\n' |
| 7325 | 'automatic display of the exception context.\n', |
| 7326 | 'return': 'The "return" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7327 | '**********************\n' |
| 7328 | '\n' |
| 7329 | ' return_stmt ::= "return" [expression_list]\n' |
| 7330 | '\n' |
| 7331 | '"return" may only occur syntactically nested in a function ' |
| 7332 | 'definition,\n' |
| 7333 | 'not within a nested class definition.\n' |
| 7334 | '\n' |
| 7335 | 'If an expression list is present, it is evaluated, else "None" is\n' |
| 7336 | 'substituted.\n' |
| 7337 | '\n' |
| 7338 | '"return" leaves the current function call with the expression list ' |
| 7339 | '(or\n' |
| 7340 | '"None") as return value.\n' |
| 7341 | '\n' |
| 7342 | 'When "return" passes control out of a "try" statement with a ' |
| 7343 | '"finally"\n' |
| 7344 | 'clause, that "finally" clause is executed before really leaving ' |
| 7345 | 'the\n' |
| 7346 | 'function.\n' |
| 7347 | '\n' |
| 7348 | 'In a generator function, the "return" statement indicates that ' |
| 7349 | 'the\n' |
| 7350 | 'generator is done and will cause "StopIteration" to be raised. ' |
| 7351 | 'The\n' |
| 7352 | 'returned value (if any) is used as an argument to construct\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7353 | '"StopIteration" and becomes the "StopIteration.value" attribute.\n' |
| 7354 | '\n' |
| 7355 | 'In an asynchronous generator function, an empty "return" ' |
| 7356 | 'statement\n' |
| 7357 | 'indicates that the asynchronous generator is done and will cause\n' |
| 7358 | '"StopAsyncIteration" to be raised. A non-empty "return" statement ' |
| 7359 | 'is\n' |
| 7360 | 'a syntax error in an asynchronous generator function.\n', |
| 7361 | 'sequence-types': 'Emulating container types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7362 | '*************************\n' |
| 7363 | '\n' |
| 7364 | 'The following methods can be defined to implement ' |
| 7365 | 'container objects.\n' |
| 7366 | 'Containers usually are sequences (such as lists or tuples) ' |
| 7367 | 'or mappings\n' |
| 7368 | '(like dictionaries), but can represent other containers as ' |
| 7369 | 'well. The\n' |
| 7370 | 'first set of methods is used either to emulate a sequence ' |
| 7371 | 'or to\n' |
| 7372 | 'emulate a mapping; the difference is that for a sequence, ' |
| 7373 | 'the\n' |
| 7374 | 'allowable keys should be the integers *k* for which "0 <= ' |
| 7375 | 'k < N" where\n' |
| 7376 | '*N* is the length of the sequence, or slice objects, which ' |
| 7377 | 'define a\n' |
| 7378 | 'range of items. It is also recommended that mappings ' |
| 7379 | 'provide the\n' |
| 7380 | 'methods "keys()", "values()", "items()", "get()", ' |
| 7381 | '"clear()",\n' |
| 7382 | '"setdefault()", "pop()", "popitem()", "copy()", and ' |
| 7383 | '"update()"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7384 | 'behaving similar to those for Python’s standard dictionary ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7385 | 'objects.\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7386 | 'The "collections.abc" module provides a "MutableMapping" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7387 | 'abstract base\n' |
| 7388 | 'class to help create those methods from a base set of ' |
| 7389 | '"__getitem__()",\n' |
| 7390 | '"__setitem__()", "__delitem__()", and "keys()". Mutable ' |
| 7391 | 'sequences\n' |
| 7392 | 'should provide methods "append()", "count()", "index()", ' |
| 7393 | '"extend()",\n' |
| 7394 | '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' |
| 7395 | 'like Python\n' |
| 7396 | 'standard list objects. Finally, sequence types should ' |
| 7397 | 'implement\n' |
| 7398 | 'addition (meaning concatenation) and multiplication ' |
| 7399 | '(meaning\n' |
| 7400 | 'repetition) by defining the methods "__add__()", ' |
| 7401 | '"__radd__()",\n' |
| 7402 | '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' |
| 7403 | 'described\n' |
| 7404 | 'below; they should not define other numerical operators. ' |
| 7405 | 'It is\n' |
| 7406 | 'recommended that both mappings and sequences implement ' |
| 7407 | 'the\n' |
| 7408 | '"__contains__()" method to allow efficient use of the "in" ' |
| 7409 | 'operator;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7410 | 'for mappings, "in" should search the mapping’s keys; for ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7411 | 'sequences, it\n' |
| 7412 | 'should search through the values. It is further ' |
| 7413 | 'recommended that both\n' |
| 7414 | 'mappings and sequences implement the "__iter__()" method ' |
| 7415 | 'to allow\n' |
| 7416 | 'efficient iteration through the container; for mappings, ' |
| 7417 | '"__iter__()"\n' |
| 7418 | 'should be the same as "keys()"; for sequences, it should ' |
| 7419 | 'iterate\n' |
| 7420 | 'through the values.\n' |
| 7421 | '\n' |
| 7422 | 'object.__len__(self)\n' |
| 7423 | '\n' |
| 7424 | ' Called to implement the built-in function "len()". ' |
| 7425 | 'Should return\n' |
| 7426 | ' the length of the object, an integer ">=" 0. Also, an ' |
| 7427 | 'object that\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7428 | ' doesn’t define a "__bool__()" method and whose ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7429 | '"__len__()" method\n' |
| 7430 | ' returns zero is considered to be false in a Boolean ' |
| 7431 | 'context.\n' |
| 7432 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7433 | ' **CPython implementation detail:** In CPython, the ' |
| 7434 | 'length is\n' |
| 7435 | ' required to be at most "sys.maxsize". If the length is ' |
| 7436 | 'larger than\n' |
| 7437 | ' "sys.maxsize" some features (such as "len()") may ' |
| 7438 | 'raise\n' |
| 7439 | ' "OverflowError". To prevent raising "OverflowError" by ' |
| 7440 | 'truth value\n' |
| 7441 | ' testing, an object must define a "__bool__()" method.\n' |
| 7442 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7443 | 'object.__length_hint__(self)\n' |
| 7444 | '\n' |
| 7445 | ' Called to implement "operator.length_hint()". Should ' |
| 7446 | 'return an\n' |
| 7447 | ' estimated length for the object (which may be greater ' |
| 7448 | 'or less than\n' |
| 7449 | ' the actual length). The length must be an integer ">=" ' |
| 7450 | '0. This\n' |
| 7451 | ' method is purely an optimization and is never required ' |
| 7452 | 'for\n' |
| 7453 | ' correctness.\n' |
| 7454 | '\n' |
| 7455 | ' New in version 3.4.\n' |
| 7456 | '\n' |
| 7457 | 'Note: Slicing is done exclusively with the following three ' |
| 7458 | 'methods.\n' |
| 7459 | ' A call like\n' |
| 7460 | '\n' |
| 7461 | ' a[1:2] = b\n' |
| 7462 | '\n' |
| 7463 | ' is translated to\n' |
| 7464 | '\n' |
| 7465 | ' a[slice(1, 2, None)] = b\n' |
| 7466 | '\n' |
| 7467 | ' and so forth. Missing slice items are always filled in ' |
| 7468 | 'with "None".\n' |
| 7469 | '\n' |
| 7470 | 'object.__getitem__(self, key)\n' |
| 7471 | '\n' |
| 7472 | ' Called to implement evaluation of "self[key]". For ' |
| 7473 | 'sequence types,\n' |
| 7474 | ' the accepted keys should be integers and slice ' |
| 7475 | 'objects. Note that\n' |
| 7476 | ' the special interpretation of negative indexes (if the ' |
| 7477 | 'class wishes\n' |
| 7478 | ' to emulate a sequence type) is up to the ' |
| 7479 | '"__getitem__()" method. If\n' |
| 7480 | ' *key* is of an inappropriate type, "TypeError" may be ' |
| 7481 | 'raised; if of\n' |
| 7482 | ' a value outside the set of indexes for the sequence ' |
| 7483 | '(after any\n' |
| 7484 | ' special interpretation of negative values), ' |
| 7485 | '"IndexError" should be\n' |
| 7486 | ' raised. For mapping types, if *key* is missing (not in ' |
| 7487 | 'the\n' |
| 7488 | ' container), "KeyError" should be raised.\n' |
| 7489 | '\n' |
| 7490 | ' Note: "for" loops expect that an "IndexError" will be ' |
| 7491 | 'raised for\n' |
| 7492 | ' illegal indexes to allow proper detection of the end ' |
| 7493 | 'of the\n' |
| 7494 | ' sequence.\n' |
| 7495 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7496 | 'object.__setitem__(self, key, value)\n' |
| 7497 | '\n' |
| 7498 | ' Called to implement assignment to "self[key]". Same ' |
| 7499 | 'note as for\n' |
| 7500 | ' "__getitem__()". This should only be implemented for ' |
| 7501 | 'mappings if\n' |
| 7502 | ' the objects support changes to the values for keys, or ' |
| 7503 | 'if new keys\n' |
| 7504 | ' can be added, or for sequences if elements can be ' |
| 7505 | 'replaced. The\n' |
| 7506 | ' same exceptions should be raised for improper *key* ' |
| 7507 | 'values as for\n' |
| 7508 | ' the "__getitem__()" method.\n' |
| 7509 | '\n' |
| 7510 | 'object.__delitem__(self, key)\n' |
| 7511 | '\n' |
| 7512 | ' Called to implement deletion of "self[key]". Same note ' |
| 7513 | 'as for\n' |
| 7514 | ' "__getitem__()". This should only be implemented for ' |
| 7515 | 'mappings if\n' |
| 7516 | ' the objects support removal of keys, or for sequences ' |
| 7517 | 'if elements\n' |
| 7518 | ' can be removed from the sequence. The same exceptions ' |
| 7519 | 'should be\n' |
| 7520 | ' raised for improper *key* values as for the ' |
| 7521 | '"__getitem__()" method.\n' |
| 7522 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7523 | 'object.__missing__(self, key)\n' |
| 7524 | '\n' |
| 7525 | ' Called by "dict"."__getitem__()" to implement ' |
| 7526 | '"self[key]" for dict\n' |
| 7527 | ' subclasses when key is not in the dictionary.\n' |
| 7528 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7529 | 'object.__iter__(self)\n' |
| 7530 | '\n' |
| 7531 | ' This method is called when an iterator is required for ' |
| 7532 | 'a container.\n' |
| 7533 | ' This method should return a new iterator object that ' |
| 7534 | 'can iterate\n' |
| 7535 | ' over all the objects in the container. For mappings, ' |
| 7536 | 'it should\n' |
| 7537 | ' iterate over the keys of the container.\n' |
| 7538 | '\n' |
| 7539 | ' Iterator objects also need to implement this method; ' |
| 7540 | 'they are\n' |
| 7541 | ' required to return themselves. For more information on ' |
| 7542 | 'iterator\n' |
| 7543 | ' objects, see Iterator Types.\n' |
| 7544 | '\n' |
| 7545 | 'object.__reversed__(self)\n' |
| 7546 | '\n' |
| 7547 | ' Called (if present) by the "reversed()" built-in to ' |
| 7548 | 'implement\n' |
| 7549 | ' reverse iteration. It should return a new iterator ' |
| 7550 | 'object that\n' |
| 7551 | ' iterates over all the objects in the container in ' |
| 7552 | 'reverse order.\n' |
| 7553 | '\n' |
| 7554 | ' If the "__reversed__()" method is not provided, the ' |
| 7555 | '"reversed()"\n' |
| 7556 | ' built-in will fall back to using the sequence protocol ' |
| 7557 | '("__len__()"\n' |
| 7558 | ' and "__getitem__()"). Objects that support the ' |
| 7559 | 'sequence protocol\n' |
| 7560 | ' should only provide "__reversed__()" if they can ' |
| 7561 | 'provide an\n' |
| 7562 | ' implementation that is more efficient than the one ' |
| 7563 | 'provided by\n' |
| 7564 | ' "reversed()".\n' |
| 7565 | '\n' |
| 7566 | 'The membership test operators ("in" and "not in") are ' |
| 7567 | 'normally\n' |
| 7568 | 'implemented as an iteration through a sequence. However, ' |
| 7569 | 'container\n' |
| 7570 | 'objects can supply the following special method with a ' |
| 7571 | 'more efficient\n' |
| 7572 | 'implementation, which also does not require the object be ' |
| 7573 | 'a sequence.\n' |
| 7574 | '\n' |
| 7575 | 'object.__contains__(self, item)\n' |
| 7576 | '\n' |
| 7577 | ' Called to implement membership test operators. Should ' |
| 7578 | 'return true\n' |
| 7579 | ' if *item* is in *self*, false otherwise. For mapping ' |
| 7580 | 'objects, this\n' |
| 7581 | ' should consider the keys of the mapping rather than the ' |
| 7582 | 'values or\n' |
| 7583 | ' the key-item pairs.\n' |
| 7584 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7585 | ' For objects that don’t define "__contains__()", the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7586 | 'membership test\n' |
| 7587 | ' first tries iteration via "__iter__()", then the old ' |
| 7588 | 'sequence\n' |
| 7589 | ' iteration protocol via "__getitem__()", see this ' |
| 7590 | 'section in the\n' |
| 7591 | ' language reference.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7592 | 'shifting': 'Shifting operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7593 | '*******************\n' |
| 7594 | '\n' |
| 7595 | 'The shifting operations have lower priority than the arithmetic\n' |
| 7596 | 'operations:\n' |
| 7597 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7598 | ' shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7599 | '\n' |
| 7600 | 'These operators accept integers as arguments. They shift the ' |
| 7601 | 'first\n' |
| 7602 | 'argument to the left or right by the number of bits given by ' |
| 7603 | 'the\n' |
| 7604 | 'second argument.\n' |
| 7605 | '\n' |
| 7606 | 'A right shift by *n* bits is defined as floor division by ' |
| 7607 | '"pow(2,n)".\n' |
| 7608 | 'A left shift by *n* bits is defined as multiplication with ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7609 | '"pow(2,n)".\n', |
| 7610 | 'slicings': 'Slicings\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7611 | '********\n' |
| 7612 | '\n' |
| 7613 | 'A slicing selects a range of items in a sequence object (e.g., ' |
| 7614 | 'a\n' |
| 7615 | 'string, tuple or list). Slicings may be used as expressions or ' |
| 7616 | 'as\n' |
| 7617 | 'targets in assignment or "del" statements. The syntax for a ' |
| 7618 | 'slicing:\n' |
| 7619 | '\n' |
| 7620 | ' slicing ::= primary "[" slice_list "]"\n' |
| 7621 | ' slice_list ::= slice_item ("," slice_item)* [","]\n' |
| 7622 | ' slice_item ::= expression | proper_slice\n' |
| 7623 | ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' |
| 7624 | '[stride] ]\n' |
| 7625 | ' lower_bound ::= expression\n' |
| 7626 | ' upper_bound ::= expression\n' |
| 7627 | ' stride ::= expression\n' |
| 7628 | '\n' |
| 7629 | 'There is ambiguity in the formal syntax here: anything that ' |
| 7630 | 'looks like\n' |
| 7631 | 'an expression list also looks like a slice list, so any ' |
| 7632 | 'subscription\n' |
| 7633 | 'can be interpreted as a slicing. Rather than further ' |
| 7634 | 'complicating the\n' |
| 7635 | 'syntax, this is disambiguated by defining that in this case the\n' |
| 7636 | 'interpretation as a subscription takes priority over the\n' |
| 7637 | 'interpretation as a slicing (this is the case if the slice list\n' |
| 7638 | 'contains no proper slice).\n' |
| 7639 | '\n' |
| 7640 | 'The semantics for a slicing are as follows. The primary is ' |
| 7641 | 'indexed\n' |
| 7642 | '(using the same "__getitem__()" method as normal subscription) ' |
| 7643 | 'with a\n' |
| 7644 | 'key that is constructed from the slice list, as follows. If the ' |
| 7645 | 'slice\n' |
| 7646 | 'list contains at least one comma, the key is a tuple containing ' |
| 7647 | 'the\n' |
| 7648 | 'conversion of the slice items; otherwise, the conversion of the ' |
| 7649 | 'lone\n' |
| 7650 | 'slice item is the key. The conversion of a slice item that is ' |
| 7651 | 'an\n' |
| 7652 | 'expression is that expression. The conversion of a proper slice ' |
| 7653 | 'is a\n' |
| 7654 | 'slice object (see section The standard type hierarchy) whose ' |
| 7655 | '"start",\n' |
| 7656 | '"stop" and "step" attributes are the values of the expressions ' |
| 7657 | 'given\n' |
| 7658 | 'as lower bound, upper bound and stride, respectively, ' |
| 7659 | 'substituting\n' |
| 7660 | '"None" for missing expressions.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7661 | 'specialattrs': 'Special Attributes\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7662 | '******************\n' |
| 7663 | '\n' |
| 7664 | 'The implementation adds a few special read-only attributes ' |
| 7665 | 'to several\n' |
| 7666 | 'object types, where they are relevant. Some of these are ' |
| 7667 | 'not reported\n' |
| 7668 | 'by the "dir()" built-in function.\n' |
| 7669 | '\n' |
| 7670 | 'object.__dict__\n' |
| 7671 | '\n' |
| 7672 | ' A dictionary or other mapping object used to store an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7673 | 'object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7674 | ' (writable) attributes.\n' |
| 7675 | '\n' |
| 7676 | 'instance.__class__\n' |
| 7677 | '\n' |
| 7678 | ' The class to which a class instance belongs.\n' |
| 7679 | '\n' |
| 7680 | 'class.__bases__\n' |
| 7681 | '\n' |
| 7682 | ' The tuple of base classes of a class object.\n' |
| 7683 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7684 | 'definition.__name__\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7685 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7686 | ' The name of the class, function, method, descriptor, or ' |
| 7687 | 'generator\n' |
| 7688 | ' instance.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7689 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7690 | 'definition.__qualname__\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7691 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7692 | ' The *qualified name* of the class, function, method, ' |
| 7693 | 'descriptor, or\n' |
| 7694 | ' generator instance.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7695 | '\n' |
| 7696 | ' New in version 3.3.\n' |
| 7697 | '\n' |
| 7698 | 'class.__mro__\n' |
| 7699 | '\n' |
| 7700 | ' This attribute is a tuple of classes that are considered ' |
| 7701 | 'when\n' |
| 7702 | ' looking for base classes during method resolution.\n' |
| 7703 | '\n' |
| 7704 | 'class.mro()\n' |
| 7705 | '\n' |
| 7706 | ' This method can be overridden by a metaclass to customize ' |
| 7707 | 'the\n' |
| 7708 | ' method resolution order for its instances. It is called ' |
| 7709 | 'at class\n' |
| 7710 | ' instantiation, and its result is stored in "__mro__".\n' |
| 7711 | '\n' |
| 7712 | 'class.__subclasses__()\n' |
| 7713 | '\n' |
| 7714 | ' Each class keeps a list of weak references to its ' |
| 7715 | 'immediate\n' |
| 7716 | ' subclasses. This method returns a list of all those ' |
| 7717 | 'references\n' |
| 7718 | ' still alive. Example:\n' |
| 7719 | '\n' |
| 7720 | ' >>> int.__subclasses__()\n' |
| 7721 | " [<class 'bool'>]\n" |
| 7722 | '\n' |
| 7723 | '-[ Footnotes ]-\n' |
| 7724 | '\n' |
| 7725 | '[1] Additional information on these special methods may be ' |
| 7726 | 'found\n' |
| 7727 | ' in the Python Reference Manual (Basic customization).\n' |
| 7728 | '\n' |
| 7729 | '[2] As a consequence, the list "[1, 2]" is considered equal ' |
| 7730 | 'to\n' |
| 7731 | ' "[1.0, 2.0]", and similarly for tuples.\n' |
| 7732 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7733 | '[3] They must have since the parser can’t tell the type of ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7734 | 'the\n' |
| 7735 | ' operands.\n' |
| 7736 | '\n' |
| 7737 | '[4] Cased characters are those with general category ' |
| 7738 | 'property\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7739 | ' being one of “Lu” (Letter, uppercase), “Ll” (Letter, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7740 | 'lowercase),\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7741 | ' or “Lt” (Letter, titlecase).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7742 | '\n' |
| 7743 | '[5] To format only a tuple you should therefore provide a\n' |
| 7744 | ' singleton tuple whose only element is the tuple to be ' |
| 7745 | 'formatted.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7746 | 'specialnames': 'Special method names\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7747 | '********************\n' |
| 7748 | '\n' |
| 7749 | 'A class can implement certain operations that are invoked by ' |
| 7750 | 'special\n' |
| 7751 | 'syntax (such as arithmetic operations or subscripting and ' |
| 7752 | 'slicing) by\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7753 | 'defining methods with special names. This is Python’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7754 | 'approach to\n' |
| 7755 | '*operator overloading*, allowing classes to define their own ' |
| 7756 | 'behavior\n' |
| 7757 | 'with respect to language operators. For instance, if a ' |
| 7758 | 'class defines\n' |
| 7759 | 'a method named "__getitem__()", and "x" is an instance of ' |
| 7760 | 'this class,\n' |
| 7761 | 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, ' |
| 7762 | 'i)".\n' |
| 7763 | 'Except where mentioned, attempts to execute an operation ' |
| 7764 | 'raise an\n' |
| 7765 | 'exception when no appropriate method is defined (typically\n' |
| 7766 | '"AttributeError" or "TypeError").\n' |
| 7767 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 7768 | 'Setting a special method to "None" indicates that the ' |
| 7769 | 'corresponding\n' |
| 7770 | 'operation is not available. For example, if a class sets ' |
| 7771 | '"__iter__()"\n' |
| 7772 | 'to "None", the class is not iterable, so calling "iter()" on ' |
| 7773 | 'its\n' |
| 7774 | 'instances will raise a "TypeError" (without falling back to\n' |
| 7775 | '"__getitem__()"). [2]\n' |
| 7776 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7777 | 'When implementing a class that emulates any built-in type, ' |
| 7778 | 'it is\n' |
| 7779 | 'important that the emulation only be implemented to the ' |
| 7780 | 'degree that it\n' |
| 7781 | 'makes sense for the object being modelled. For example, ' |
| 7782 | 'some\n' |
| 7783 | 'sequences may work well with retrieval of individual ' |
| 7784 | 'elements, but\n' |
| 7785 | 'extracting a slice may not make sense. (One example of this ' |
| 7786 | 'is the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7787 | '"NodeList" interface in the W3C’s Document Object Model.)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7788 | '\n' |
| 7789 | '\n' |
| 7790 | 'Basic customization\n' |
| 7791 | '===================\n' |
| 7792 | '\n' |
| 7793 | 'object.__new__(cls[, ...])\n' |
| 7794 | '\n' |
| 7795 | ' Called to create a new instance of class *cls*. ' |
| 7796 | '"__new__()" is a\n' |
| 7797 | ' static method (special-cased so you need not declare it ' |
| 7798 | 'as such)\n' |
| 7799 | ' that takes the class of which an instance was requested ' |
| 7800 | 'as its\n' |
| 7801 | ' first argument. The remaining arguments are those passed ' |
| 7802 | 'to the\n' |
| 7803 | ' object constructor expression (the call to the class). ' |
| 7804 | 'The return\n' |
| 7805 | ' value of "__new__()" should be the new object instance ' |
| 7806 | '(usually an\n' |
| 7807 | ' instance of *cls*).\n' |
| 7808 | '\n' |
| 7809 | ' Typical implementations create a new instance of the ' |
| 7810 | 'class by\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7811 | ' invoking the superclass’s "__new__()" method using\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7812 | ' "super().__new__(cls[, ...])" with appropriate arguments ' |
| 7813 | 'and then\n' |
| 7814 | ' modifying the newly-created instance as necessary before ' |
| 7815 | 'returning\n' |
| 7816 | ' it.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7817 | '\n' |
| 7818 | ' If "__new__()" returns an instance of *cls*, then the ' |
| 7819 | 'new\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7820 | ' instance’s "__init__()" method will be invoked like\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7821 | ' "__init__(self[, ...])", where *self* is the new instance ' |
| 7822 | 'and the\n' |
| 7823 | ' remaining arguments are the same as were passed to ' |
| 7824 | '"__new__()".\n' |
| 7825 | '\n' |
| 7826 | ' If "__new__()" does not return an instance of *cls*, then ' |
| 7827 | 'the new\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7828 | ' instance’s "__init__()" method will not be invoked.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7829 | '\n' |
| 7830 | ' "__new__()" is intended mainly to allow subclasses of ' |
| 7831 | 'immutable\n' |
| 7832 | ' types (like int, str, or tuple) to customize instance ' |
| 7833 | 'creation. It\n' |
| 7834 | ' is also commonly overridden in custom metaclasses in ' |
| 7835 | 'order to\n' |
| 7836 | ' customize class creation.\n' |
| 7837 | '\n' |
| 7838 | 'object.__init__(self[, ...])\n' |
| 7839 | '\n' |
| 7840 | ' Called after the instance has been created (by ' |
| 7841 | '"__new__()"), but\n' |
| 7842 | ' before it is returned to the caller. The arguments are ' |
| 7843 | 'those\n' |
| 7844 | ' passed to the class constructor expression. If a base ' |
| 7845 | 'class has an\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7846 | ' "__init__()" method, the derived class’s "__init__()" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7847 | 'method, if\n' |
| 7848 | ' any, must explicitly call it to ensure proper ' |
| 7849 | 'initialization of the\n' |
| 7850 | ' base class part of the instance; for example:\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7851 | ' "super().__init__([args...])".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7852 | '\n' |
| 7853 | ' Because "__new__()" and "__init__()" work together in ' |
| 7854 | 'constructing\n' |
| 7855 | ' objects ("__new__()" to create it, and "__init__()" to ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 7856 | 'customize\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7857 | ' it), no non-"None" value may be returned by "__init__()"; ' |
| 7858 | 'doing so\n' |
| 7859 | ' will cause a "TypeError" to be raised at runtime.\n' |
| 7860 | '\n' |
| 7861 | 'object.__del__(self)\n' |
| 7862 | '\n' |
| 7863 | ' Called when the instance is about to be destroyed. This ' |
| 7864 | 'is also\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7865 | ' called a finalizer or (improperly) a destructor. If a ' |
| 7866 | 'base class\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7867 | ' has a "__del__()" method, the derived class’s "__del__()" ' |
| 7868 | 'method,\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7869 | ' if any, must explicitly call it to ensure proper deletion ' |
| 7870 | 'of the\n' |
| 7871 | ' base class part of the instance.\n' |
| 7872 | '\n' |
| 7873 | ' It is possible (though not recommended!) for the ' |
| 7874 | '"__del__()" method\n' |
| 7875 | ' to postpone destruction of the instance by creating a new ' |
| 7876 | 'reference\n' |
| 7877 | ' to it. This is called object *resurrection*. It is\n' |
| 7878 | ' implementation-dependent whether "__del__()" is called a ' |
| 7879 | 'second\n' |
| 7880 | ' time when a resurrected object is about to be destroyed; ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7881 | 'the\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7882 | ' current *CPython* implementation only calls it once.\n' |
| 7883 | '\n' |
| 7884 | ' It is not guaranteed that "__del__()" methods are called ' |
| 7885 | 'for\n' |
| 7886 | ' objects that still exist when the interpreter exits.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7887 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7888 | ' Note: "del x" doesn’t directly call "x.__del__()" — the ' |
| 7889 | 'former\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7890 | ' decrements the reference count for "x" by one, and the ' |
| 7891 | 'latter is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7892 | ' only called when "x"’s reference count reaches zero.\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7893 | '\n' |
| 7894 | ' **CPython implementation detail:** It is possible for a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7895 | 'reference\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7896 | ' cycle to prevent the reference count of an object from ' |
| 7897 | 'going to\n' |
| 7898 | ' zero. In this case, the cycle will be later detected and ' |
| 7899 | 'deleted\n' |
| 7900 | ' by the *cyclic garbage collector*. A common cause of ' |
| 7901 | 'reference\n' |
| 7902 | ' cycles is when an exception has been caught in a local ' |
| 7903 | 'variable.\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7904 | ' The frame’s locals then reference the exception, which ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7905 | 'references\n' |
| 7906 | ' its own traceback, which references the locals of all ' |
| 7907 | 'frames caught\n' |
| 7908 | ' in the traceback.\n' |
| 7909 | '\n' |
| 7910 | ' See also: Documentation for the "gc" module.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7911 | '\n' |
| 7912 | ' Warning: Due to the precarious circumstances under which\n' |
| 7913 | ' "__del__()" methods are invoked, exceptions that occur ' |
| 7914 | 'during\n' |
| 7915 | ' their execution are ignored, and a warning is printed ' |
| 7916 | 'to\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7917 | ' "sys.stderr" instead. In particular:\n' |
| 7918 | '\n' |
| 7919 | ' * "__del__()" can be invoked when arbitrary code is ' |
| 7920 | 'being\n' |
| 7921 | ' executed, including from any arbitrary thread. If ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7922 | '"__del__()"\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7923 | ' needs to take a lock or invoke any other blocking ' |
| 7924 | 'resource, it\n' |
| 7925 | ' may deadlock as the resource may already be taken by ' |
| 7926 | 'the code\n' |
| 7927 | ' that gets interrupted to execute "__del__()".\n' |
| 7928 | '\n' |
| 7929 | ' * "__del__()" can be executed during interpreter ' |
| 7930 | 'shutdown. As\n' |
| 7931 | ' a consequence, the global variables it needs to ' |
| 7932 | 'access\n' |
| 7933 | ' (including other modules) may already have been ' |
| 7934 | 'deleted or set\n' |
| 7935 | ' to "None". Python guarantees that globals whose name ' |
| 7936 | 'begins\n' |
| 7937 | ' with a single underscore are deleted from their ' |
| 7938 | 'module before\n' |
| 7939 | ' other globals are deleted; if no other references to ' |
| 7940 | 'such\n' |
| 7941 | ' globals exist, this may help in assuring that ' |
| 7942 | 'imported modules\n' |
| 7943 | ' are still available at the time when the "__del__()" ' |
| 7944 | 'method is\n' |
| 7945 | ' called.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7946 | '\n' |
| 7947 | 'object.__repr__(self)\n' |
| 7948 | '\n' |
| 7949 | ' Called by the "repr()" built-in function to compute the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7950 | '“official”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7951 | ' string representation of an object. If at all possible, ' |
| 7952 | 'this\n' |
| 7953 | ' should look like a valid Python expression that could be ' |
| 7954 | 'used to\n' |
| 7955 | ' recreate an object with the same value (given an ' |
| 7956 | 'appropriate\n' |
| 7957 | ' environment). If this is not possible, a string of the ' |
| 7958 | 'form\n' |
| 7959 | ' "<...some useful description...>" should be returned. The ' |
| 7960 | 'return\n' |
| 7961 | ' value must be a string object. If a class defines ' |
| 7962 | '"__repr__()" but\n' |
| 7963 | ' not "__str__()", then "__repr__()" is also used when an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7964 | '“informal”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7965 | ' string representation of instances of that class is ' |
| 7966 | 'required.\n' |
| 7967 | '\n' |
| 7968 | ' This is typically used for debugging, so it is important ' |
| 7969 | 'that the\n' |
| 7970 | ' representation is information-rich and unambiguous.\n' |
| 7971 | '\n' |
| 7972 | 'object.__str__(self)\n' |
| 7973 | '\n' |
| 7974 | ' Called by "str(object)" and the built-in functions ' |
| 7975 | '"format()" and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 7976 | ' "print()" to compute the “informal” or nicely printable ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7977 | 'string\n' |
| 7978 | ' representation of an object. The return value must be a ' |
| 7979 | 'string\n' |
| 7980 | ' object.\n' |
| 7981 | '\n' |
| 7982 | ' This method differs from "object.__repr__()" in that ' |
| 7983 | 'there is no\n' |
| 7984 | ' expectation that "__str__()" return a valid Python ' |
| 7985 | 'expression: a\n' |
| 7986 | ' more convenient or concise representation can be used.\n' |
| 7987 | '\n' |
| 7988 | ' The default implementation defined by the built-in type ' |
| 7989 | '"object"\n' |
| 7990 | ' calls "object.__repr__()".\n' |
| 7991 | '\n' |
| 7992 | 'object.__bytes__(self)\n' |
| 7993 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7994 | ' Called by bytes to compute a byte-string representation ' |
| 7995 | 'of an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7996 | ' object. This should return a "bytes" object.\n' |
| 7997 | '\n' |
| 7998 | 'object.__format__(self, format_spec)\n' |
| 7999 | '\n' |
| 8000 | ' Called by the "format()" built-in function, and by ' |
| 8001 | 'extension,\n' |
| 8002 | ' evaluation of formatted string literals and the ' |
| 8003 | '"str.format()"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8004 | ' method, to produce a “formatted” string representation of ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8005 | 'an\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8006 | ' object. The *format_spec* argument is a string that ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8007 | 'contains a\n' |
| 8008 | ' description of the formatting options desired. The ' |
| 8009 | 'interpretation\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8010 | ' of the *format_spec* argument is up to the type ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8011 | 'implementing\n' |
| 8012 | ' "__format__()", however most classes will either ' |
| 8013 | 'delegate\n' |
| 8014 | ' formatting to one of the built-in types, or use a ' |
| 8015 | 'similar\n' |
| 8016 | ' formatting option syntax.\n' |
| 8017 | '\n' |
| 8018 | ' See Format Specification Mini-Language for a description ' |
| 8019 | 'of the\n' |
| 8020 | ' standard formatting syntax.\n' |
| 8021 | '\n' |
| 8022 | ' The return value must be a string object.\n' |
| 8023 | '\n' |
| 8024 | ' Changed in version 3.4: The __format__ method of "object" ' |
| 8025 | 'itself\n' |
| 8026 | ' raises a "TypeError" if passed any non-empty string.\n' |
| 8027 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8028 | ' Changed in version 3.7: "object.__format__(x, \'\')" is ' |
| 8029 | 'now\n' |
| 8030 | ' equivalent to "str(x)" rather than "format(str(self), ' |
| 8031 | '\'\')".\n' |
| 8032 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8033 | 'object.__lt__(self, other)\n' |
| 8034 | 'object.__le__(self, other)\n' |
| 8035 | 'object.__eq__(self, other)\n' |
| 8036 | 'object.__ne__(self, other)\n' |
| 8037 | 'object.__gt__(self, other)\n' |
| 8038 | 'object.__ge__(self, other)\n' |
| 8039 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8040 | ' These are the so-called “rich comparison” methods. The\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8041 | ' correspondence between operator symbols and method names ' |
| 8042 | 'is as\n' |
| 8043 | ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' |
| 8044 | '"x.__le__(y)",\n' |
| 8045 | ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' |
| 8046 | '"x>y" calls\n' |
| 8047 | ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' |
| 8048 | '\n' |
| 8049 | ' A rich comparison method may return the singleton ' |
| 8050 | '"NotImplemented"\n' |
| 8051 | ' if it does not implement the operation for a given pair ' |
| 8052 | 'of\n' |
| 8053 | ' arguments. By convention, "False" and "True" are returned ' |
| 8054 | 'for a\n' |
| 8055 | ' successful comparison. However, these methods can return ' |
| 8056 | 'any value,\n' |
| 8057 | ' so if the comparison operator is used in a Boolean ' |
| 8058 | 'context (e.g.,\n' |
| 8059 | ' in the condition of an "if" statement), Python will call ' |
| 8060 | '"bool()"\n' |
| 8061 | ' on the value to determine if the result is true or ' |
| 8062 | 'false.\n' |
| 8063 | '\n' |
| 8064 | ' By default, "__ne__()" delegates to "__eq__()" and ' |
| 8065 | 'inverts the\n' |
| 8066 | ' result unless it is "NotImplemented". There are no other ' |
| 8067 | 'implied\n' |
| 8068 | ' relationships among the comparison operators, for ' |
| 8069 | 'example, the\n' |
| 8070 | ' truth of "(x<y or x==y)" does not imply "x<=y". To ' |
| 8071 | 'automatically\n' |
| 8072 | ' generate ordering operations from a single root ' |
| 8073 | 'operation, see\n' |
| 8074 | ' "functools.total_ordering()".\n' |
| 8075 | '\n' |
| 8076 | ' See the paragraph on "__hash__()" for some important ' |
| 8077 | 'notes on\n' |
| 8078 | ' creating *hashable* objects which support custom ' |
| 8079 | 'comparison\n' |
| 8080 | ' operations and are usable as dictionary keys.\n' |
| 8081 | '\n' |
| 8082 | ' There are no swapped-argument versions of these methods ' |
| 8083 | '(to be used\n' |
| 8084 | ' when the left argument does not support the operation but ' |
| 8085 | 'the right\n' |
| 8086 | ' argument does); rather, "__lt__()" and "__gt__()" are ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8087 | 'each other’s\n' |
| 8088 | ' reflection, "__le__()" and "__ge__()" are each other’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8089 | 'reflection,\n' |
| 8090 | ' and "__eq__()" and "__ne__()" are their own reflection. ' |
| 8091 | 'If the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8092 | ' operands are of different types, and right operand’s type ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8093 | 'is a\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8094 | ' direct or indirect subclass of the left operand’s type, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8095 | 'the\n' |
| 8096 | ' reflected method of the right operand has priority, ' |
| 8097 | 'otherwise the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8098 | ' left operand’s method has priority. Virtual subclassing ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8099 | 'is not\n' |
| 8100 | ' considered.\n' |
| 8101 | '\n' |
| 8102 | 'object.__hash__(self)\n' |
| 8103 | '\n' |
| 8104 | ' Called by built-in function "hash()" and for operations ' |
| 8105 | 'on members\n' |
| 8106 | ' of hashed collections including "set", "frozenset", and ' |
| 8107 | '"dict".\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8108 | ' "__hash__()" should return an integer. The only required ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8109 | 'property\n' |
| 8110 | ' is that objects which compare equal have the same hash ' |
| 8111 | 'value; it is\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8112 | ' advised to mix together the hash values of the components ' |
| 8113 | 'of the\n' |
| 8114 | ' object that also play a part in comparison of objects by ' |
| 8115 | 'packing\n' |
| 8116 | ' them into a tuple and hashing the tuple. Example:\n' |
| 8117 | '\n' |
| 8118 | ' def __hash__(self):\n' |
| 8119 | ' return hash((self.name, self.nick, self.color))\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8120 | '\n' |
| 8121 | ' Note: "hash()" truncates the value returned from an ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8122 | 'object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8123 | ' custom "__hash__()" method to the size of a ' |
| 8124 | '"Py_ssize_t". This\n' |
| 8125 | ' is typically 8 bytes on 64-bit builds and 4 bytes on ' |
| 8126 | '32-bit\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8127 | ' builds. If an object’s "__hash__()" must interoperate ' |
| 8128 | 'on builds\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8129 | ' of different bit sizes, be sure to check the width on ' |
| 8130 | 'all\n' |
| 8131 | ' supported builds. An easy way to do this is with ' |
| 8132 | '"python -c\n' |
| 8133 | ' "import sys; print(sys.hash_info.width)"".\n' |
| 8134 | '\n' |
| 8135 | ' If a class does not define an "__eq__()" method it should ' |
| 8136 | 'not\n' |
| 8137 | ' define a "__hash__()" operation either; if it defines ' |
| 8138 | '"__eq__()"\n' |
| 8139 | ' but not "__hash__()", its instances will not be usable as ' |
| 8140 | 'items in\n' |
| 8141 | ' hashable collections. If a class defines mutable objects ' |
| 8142 | 'and\n' |
| 8143 | ' implements an "__eq__()" method, it should not implement\n' |
| 8144 | ' "__hash__()", since the implementation of hashable ' |
| 8145 | 'collections\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8146 | ' requires that a key’s hash value is immutable (if the ' |
| 8147 | 'object’s hash\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8148 | ' value changes, it will be in the wrong hash bucket).\n' |
| 8149 | '\n' |
| 8150 | ' User-defined classes have "__eq__()" and "__hash__()" ' |
| 8151 | 'methods by\n' |
| 8152 | ' default; with them, all objects compare unequal (except ' |
| 8153 | 'with\n' |
| 8154 | ' themselves) and "x.__hash__()" returns an appropriate ' |
| 8155 | 'value such\n' |
| 8156 | ' that "x == y" implies both that "x is y" and "hash(x) == ' |
| 8157 | 'hash(y)".\n' |
| 8158 | '\n' |
| 8159 | ' A class that overrides "__eq__()" and does not define ' |
| 8160 | '"__hash__()"\n' |
| 8161 | ' will have its "__hash__()" implicitly set to "None". ' |
| 8162 | 'When the\n' |
| 8163 | ' "__hash__()" method of a class is "None", instances of ' |
| 8164 | 'the class\n' |
| 8165 | ' will raise an appropriate "TypeError" when a program ' |
| 8166 | 'attempts to\n' |
| 8167 | ' retrieve their hash value, and will also be correctly ' |
| 8168 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8169 | ' unhashable when checking "isinstance(obj,\n' |
| 8170 | ' collections.abc.Hashable)".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8171 | '\n' |
| 8172 | ' If a class that overrides "__eq__()" needs to retain the\n' |
| 8173 | ' implementation of "__hash__()" from a parent class, the ' |
| 8174 | 'interpreter\n' |
| 8175 | ' must be told this explicitly by setting "__hash__ =\n' |
| 8176 | ' <ParentClass>.__hash__".\n' |
| 8177 | '\n' |
| 8178 | ' If a class that does not override "__eq__()" wishes to ' |
| 8179 | 'suppress\n' |
| 8180 | ' hash support, it should include "__hash__ = None" in the ' |
| 8181 | 'class\n' |
| 8182 | ' definition. A class which defines its own "__hash__()" ' |
| 8183 | 'that\n' |
| 8184 | ' explicitly raises a "TypeError" would be incorrectly ' |
| 8185 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8186 | ' hashable by an "isinstance(obj, ' |
| 8187 | 'collections.abc.Hashable)" call.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8188 | '\n' |
| 8189 | ' Note: By default, the "__hash__()" values of str, bytes ' |
| 8190 | 'and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8191 | ' datetime objects are “salted” with an unpredictable ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8192 | 'random value.\n' |
| 8193 | ' Although they remain constant within an individual ' |
| 8194 | 'Python\n' |
| 8195 | ' process, they are not predictable between repeated ' |
| 8196 | 'invocations of\n' |
| 8197 | ' Python.This is intended to provide protection against a ' |
| 8198 | 'denial-\n' |
| 8199 | ' of-service caused by carefully-chosen inputs that ' |
| 8200 | 'exploit the\n' |
| 8201 | ' worst case performance of a dict insertion, O(n^2) ' |
| 8202 | 'complexity.\n' |
| 8203 | ' See http://www.ocert.org/advisories/ocert-2011-003.html ' |
| 8204 | 'for\n' |
| 8205 | ' details.Changing hash values affects the iteration ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8206 | 'order of sets.\n' |
| 8207 | ' Python has never made guarantees about this ordering ' |
| 8208 | '(and it\n' |
| 8209 | ' typically varies between 32-bit and 64-bit builds).See ' |
| 8210 | 'also\n' |
| 8211 | ' "PYTHONHASHSEED".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8212 | '\n' |
| 8213 | ' Changed in version 3.3: Hash randomization is enabled by ' |
| 8214 | 'default.\n' |
| 8215 | '\n' |
| 8216 | 'object.__bool__(self)\n' |
| 8217 | '\n' |
| 8218 | ' Called to implement truth value testing and the built-in ' |
| 8219 | 'operation\n' |
| 8220 | ' "bool()"; should return "False" or "True". When this ' |
| 8221 | 'method is not\n' |
| 8222 | ' defined, "__len__()" is called, if it is defined, and the ' |
| 8223 | 'object is\n' |
| 8224 | ' considered true if its result is nonzero. If a class ' |
| 8225 | 'defines\n' |
| 8226 | ' neither "__len__()" nor "__bool__()", all its instances ' |
| 8227 | 'are\n' |
| 8228 | ' considered true.\n' |
| 8229 | '\n' |
| 8230 | '\n' |
| 8231 | 'Customizing attribute access\n' |
| 8232 | '============================\n' |
| 8233 | '\n' |
| 8234 | 'The following methods can be defined to customize the ' |
| 8235 | 'meaning of\n' |
| 8236 | 'attribute access (use of, assignment to, or deletion of ' |
| 8237 | '"x.name") for\n' |
| 8238 | 'class instances.\n' |
| 8239 | '\n' |
| 8240 | 'object.__getattr__(self, name)\n' |
| 8241 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8242 | ' Called when the default attribute access fails with an\n' |
| 8243 | ' "AttributeError" (either "__getattribute__()" raises an\n' |
| 8244 | ' "AttributeError" because *name* is not an instance ' |
| 8245 | 'attribute or an\n' |
| 8246 | ' attribute in the class tree for "self"; or "__get__()" of ' |
| 8247 | 'a *name*\n' |
| 8248 | ' property raises "AttributeError"). This method should ' |
| 8249 | 'either\n' |
| 8250 | ' return the (computed) attribute value or raise an ' |
| 8251 | '"AttributeError"\n' |
| 8252 | ' exception.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8253 | '\n' |
| 8254 | ' Note that if the attribute is found through the normal ' |
| 8255 | 'mechanism,\n' |
| 8256 | ' "__getattr__()" is not called. (This is an intentional ' |
| 8257 | 'asymmetry\n' |
| 8258 | ' between "__getattr__()" and "__setattr__()".) This is ' |
| 8259 | 'done both for\n' |
| 8260 | ' efficiency reasons and because otherwise "__getattr__()" ' |
| 8261 | 'would have\n' |
| 8262 | ' no way to access other attributes of the instance. Note ' |
| 8263 | 'that at\n' |
| 8264 | ' least for instance variables, you can fake total control ' |
| 8265 | 'by not\n' |
| 8266 | ' inserting any values in the instance attribute dictionary ' |
| 8267 | '(but\n' |
| 8268 | ' instead inserting them in another object). See the\n' |
| 8269 | ' "__getattribute__()" method below for a way to actually ' |
| 8270 | 'get total\n' |
| 8271 | ' control over attribute access.\n' |
| 8272 | '\n' |
| 8273 | 'object.__getattribute__(self, name)\n' |
| 8274 | '\n' |
| 8275 | ' Called unconditionally to implement attribute accesses ' |
| 8276 | 'for\n' |
| 8277 | ' instances of the class. If the class also defines ' |
| 8278 | '"__getattr__()",\n' |
| 8279 | ' the latter will not be called unless "__getattribute__()" ' |
| 8280 | 'either\n' |
| 8281 | ' calls it explicitly or raises an "AttributeError". This ' |
| 8282 | 'method\n' |
| 8283 | ' should return the (computed) attribute value or raise an\n' |
| 8284 | ' "AttributeError" exception. In order to avoid infinite ' |
| 8285 | 'recursion in\n' |
| 8286 | ' this method, its implementation should always call the ' |
| 8287 | 'base class\n' |
| 8288 | ' method with the same name to access any attributes it ' |
| 8289 | 'needs, for\n' |
| 8290 | ' example, "object.__getattribute__(self, name)".\n' |
| 8291 | '\n' |
| 8292 | ' Note: This method may still be bypassed when looking up ' |
| 8293 | 'special\n' |
| 8294 | ' methods as the result of implicit invocation via ' |
| 8295 | 'language syntax\n' |
| 8296 | ' or built-in functions. See Special method lookup.\n' |
| 8297 | '\n' |
| 8298 | 'object.__setattr__(self, name, value)\n' |
| 8299 | '\n' |
| 8300 | ' Called when an attribute assignment is attempted. This ' |
| 8301 | 'is called\n' |
| 8302 | ' instead of the normal mechanism (i.e. store the value in ' |
| 8303 | 'the\n' |
| 8304 | ' instance dictionary). *name* is the attribute name, ' |
| 8305 | '*value* is the\n' |
| 8306 | ' value to be assigned to it.\n' |
| 8307 | '\n' |
| 8308 | ' If "__setattr__()" wants to assign to an instance ' |
| 8309 | 'attribute, it\n' |
| 8310 | ' should call the base class method with the same name, for ' |
| 8311 | 'example,\n' |
| 8312 | ' "object.__setattr__(self, name, value)".\n' |
| 8313 | '\n' |
| 8314 | 'object.__delattr__(self, name)\n' |
| 8315 | '\n' |
| 8316 | ' Like "__setattr__()" but for attribute deletion instead ' |
| 8317 | 'of\n' |
| 8318 | ' assignment. This should only be implemented if "del ' |
| 8319 | 'obj.name" is\n' |
| 8320 | ' meaningful for the object.\n' |
| 8321 | '\n' |
| 8322 | 'object.__dir__(self)\n' |
| 8323 | '\n' |
| 8324 | ' Called when "dir()" is called on the object. A sequence ' |
| 8325 | 'must be\n' |
| 8326 | ' returned. "dir()" converts the returned sequence to a ' |
| 8327 | 'list and\n' |
| 8328 | ' sorts it.\n' |
| 8329 | '\n' |
| 8330 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8331 | 'Customizing module attribute access\n' |
| 8332 | '-----------------------------------\n' |
| 8333 | '\n' |
| 8334 | 'Special names "__getattr__" and "__dir__" can be also used ' |
| 8335 | 'to\n' |
| 8336 | 'customize access to module attributes. The "__getattr__" ' |
| 8337 | 'function at\n' |
| 8338 | 'the module level should accept one argument which is the ' |
| 8339 | 'name of an\n' |
| 8340 | 'attribute and return the computed value or raise an ' |
| 8341 | '"AttributeError".\n' |
| 8342 | 'If an attribute is not found on a module object through the ' |
| 8343 | 'normal\n' |
| 8344 | 'lookup, i.e. "object.__getattribute__()", then "__getattr__" ' |
| 8345 | 'is\n' |
| 8346 | 'searched in the module "__dict__" before raising an ' |
| 8347 | '"AttributeError".\n' |
| 8348 | 'If found, it is called with the attribute name and the ' |
| 8349 | 'result is\n' |
| 8350 | 'returned.\n' |
| 8351 | '\n' |
| 8352 | 'The "__dir__" function should accept no arguments, and ' |
| 8353 | 'return a list\n' |
| 8354 | 'of strings that represents the names accessible on module. ' |
| 8355 | 'If present,\n' |
| 8356 | 'this function overrides the standard "dir()" search on a ' |
| 8357 | 'module.\n' |
| 8358 | '\n' |
| 8359 | 'For a more fine grained customization of the module behavior ' |
| 8360 | '(setting\n' |
| 8361 | 'attributes, properties, etc.), one can set the "__class__" ' |
| 8362 | 'attribute\n' |
| 8363 | 'of a module object to a subclass of "types.ModuleType". For ' |
| 8364 | 'example:\n' |
| 8365 | '\n' |
| 8366 | ' import sys\n' |
| 8367 | ' from types import ModuleType\n' |
| 8368 | '\n' |
| 8369 | ' class VerboseModule(ModuleType):\n' |
| 8370 | ' def __repr__(self):\n' |
| 8371 | " return f'Verbose {self.__name__}'\n" |
| 8372 | '\n' |
| 8373 | ' def __setattr__(self, attr, value):\n' |
| 8374 | " print(f'Setting {attr}...')\n" |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8375 | ' super().__setattr__(attr, value)\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8376 | '\n' |
| 8377 | ' sys.modules[__name__].__class__ = VerboseModule\n' |
| 8378 | '\n' |
| 8379 | 'Note: Defining module "__getattr__" and setting module ' |
| 8380 | '"__class__"\n' |
| 8381 | ' only affect lookups made using the attribute access syntax ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8382 | '–\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8383 | ' directly accessing the module globals (whether by code ' |
| 8384 | 'within the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8385 | ' module, or via a reference to the module’s globals ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8386 | 'dictionary) is\n' |
| 8387 | ' unaffected.\n' |
| 8388 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 8389 | 'Changed in version 3.5: "__class__" module attribute is now ' |
| 8390 | 'writable.\n' |
| 8391 | '\n' |
| 8392 | 'New in version 3.7: "__getattr__" and "__dir__" module ' |
| 8393 | 'attributes.\n' |
| 8394 | '\n' |
| 8395 | 'See also:\n' |
| 8396 | '\n' |
| 8397 | ' **PEP 562** - Module __getattr__ and __dir__\n' |
| 8398 | ' Describes the "__getattr__" and "__dir__" functions on ' |
| 8399 | 'modules.\n' |
| 8400 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8401 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8402 | 'Implementing Descriptors\n' |
| 8403 | '------------------------\n' |
| 8404 | '\n' |
| 8405 | 'The following methods only apply when an instance of the ' |
| 8406 | 'class\n' |
| 8407 | 'containing the method (a so-called *descriptor* class) ' |
| 8408 | 'appears in an\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8409 | '*owner* class (the descriptor must be in either the owner’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8410 | 'class\n' |
| 8411 | 'dictionary or in the class dictionary for one of its ' |
| 8412 | 'parents). In the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8413 | 'examples below, “the attribute” refers to the attribute ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8414 | 'whose name is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8415 | 'the key of the property in the owner class’ "__dict__".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8416 | '\n' |
| 8417 | 'object.__get__(self, instance, owner)\n' |
| 8418 | '\n' |
| 8419 | ' Called to get the attribute of the owner class (class ' |
| 8420 | 'attribute\n' |
| 8421 | ' access) or of an instance of that class (instance ' |
| 8422 | 'attribute\n' |
| 8423 | ' access). *owner* is always the owner class, while ' |
| 8424 | '*instance* is the\n' |
| 8425 | ' instance that the attribute was accessed through, or ' |
| 8426 | '"None" when\n' |
| 8427 | ' the attribute is accessed through the *owner*. This ' |
| 8428 | 'method should\n' |
| 8429 | ' return the (computed) attribute value or raise an ' |
| 8430 | '"AttributeError"\n' |
| 8431 | ' exception.\n' |
| 8432 | '\n' |
| 8433 | 'object.__set__(self, instance, value)\n' |
| 8434 | '\n' |
| 8435 | ' Called to set the attribute on an instance *instance* of ' |
| 8436 | 'the owner\n' |
| 8437 | ' class to a new value, *value*.\n' |
| 8438 | '\n' |
| 8439 | 'object.__delete__(self, instance)\n' |
| 8440 | '\n' |
| 8441 | ' Called to delete the attribute on an instance *instance* ' |
| 8442 | 'of the\n' |
| 8443 | ' owner class.\n' |
| 8444 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 8445 | 'object.__set_name__(self, owner, name)\n' |
| 8446 | '\n' |
| 8447 | ' Called at the time the owning class *owner* is created. ' |
| 8448 | 'The\n' |
| 8449 | ' descriptor has been assigned to *name*.\n' |
| 8450 | '\n' |
| 8451 | ' New in version 3.6.\n' |
| 8452 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8453 | 'The attribute "__objclass__" is interpreted by the "inspect" ' |
| 8454 | 'module as\n' |
| 8455 | 'specifying the class where this object was defined (setting ' |
| 8456 | 'this\n' |
| 8457 | 'appropriately can assist in runtime introspection of dynamic ' |
| 8458 | 'class\n' |
| 8459 | 'attributes). For callables, it may indicate that an instance ' |
| 8460 | 'of the\n' |
| 8461 | 'given type (or a subclass) is expected or required as the ' |
| 8462 | 'first\n' |
| 8463 | 'positional argument (for example, CPython sets this ' |
| 8464 | 'attribute for\n' |
| 8465 | 'unbound methods that are implemented in C).\n' |
| 8466 | '\n' |
| 8467 | '\n' |
| 8468 | 'Invoking Descriptors\n' |
| 8469 | '--------------------\n' |
| 8470 | '\n' |
| 8471 | 'In general, a descriptor is an object attribute with ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8472 | '“binding\n' |
| 8473 | 'behavior”, one whose attribute access has been overridden by ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8474 | 'methods\n' |
| 8475 | 'in the descriptor protocol: "__get__()", "__set__()", and\n' |
| 8476 | '"__delete__()". If any of those methods are defined for an ' |
| 8477 | 'object, it\n' |
| 8478 | 'is said to be a descriptor.\n' |
| 8479 | '\n' |
| 8480 | 'The default behavior for attribute access is to get, set, or ' |
| 8481 | 'delete\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8482 | 'the attribute from an object’s dictionary. For instance, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8483 | '"a.x" has a\n' |
| 8484 | 'lookup chain starting with "a.__dict__[\'x\']", then\n' |
| 8485 | '"type(a).__dict__[\'x\']", and continuing through the base ' |
| 8486 | 'classes of\n' |
| 8487 | '"type(a)" excluding metaclasses.\n' |
| 8488 | '\n' |
| 8489 | 'However, if the looked-up value is an object defining one of ' |
| 8490 | 'the\n' |
| 8491 | 'descriptor methods, then Python may override the default ' |
| 8492 | 'behavior and\n' |
| 8493 | 'invoke the descriptor method instead. Where this occurs in ' |
| 8494 | 'the\n' |
| 8495 | 'precedence chain depends on which descriptor methods were ' |
| 8496 | 'defined and\n' |
| 8497 | 'how they were called.\n' |
| 8498 | '\n' |
| 8499 | 'The starting point for descriptor invocation is a binding, ' |
| 8500 | '"a.x". How\n' |
| 8501 | 'the arguments are assembled depends on "a":\n' |
| 8502 | '\n' |
| 8503 | 'Direct Call\n' |
| 8504 | ' The simplest and least common call is when user code ' |
| 8505 | 'directly\n' |
| 8506 | ' invokes a descriptor method: "x.__get__(a)".\n' |
| 8507 | '\n' |
| 8508 | 'Instance Binding\n' |
| 8509 | ' If binding to an object instance, "a.x" is transformed ' |
| 8510 | 'into the\n' |
| 8511 | ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' |
| 8512 | '\n' |
| 8513 | 'Class Binding\n' |
| 8514 | ' If binding to a class, "A.x" is transformed into the ' |
| 8515 | 'call:\n' |
| 8516 | ' "A.__dict__[\'x\'].__get__(None, A)".\n' |
| 8517 | '\n' |
| 8518 | 'Super Binding\n' |
| 8519 | ' If "a" is an instance of "super", then the binding ' |
| 8520 | '"super(B,\n' |
| 8521 | ' obj).m()" searches "obj.__class__.__mro__" for the base ' |
| 8522 | 'class "A"\n' |
| 8523 | ' immediately preceding "B" and then invokes the descriptor ' |
| 8524 | 'with the\n' |
| 8525 | ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' |
| 8526 | '\n' |
| 8527 | 'For instance bindings, the precedence of descriptor ' |
| 8528 | 'invocation depends\n' |
| 8529 | 'on the which descriptor methods are defined. A descriptor ' |
| 8530 | 'can define\n' |
| 8531 | 'any combination of "__get__()", "__set__()" and ' |
| 8532 | '"__delete__()". If it\n' |
| 8533 | 'does not define "__get__()", then accessing the attribute ' |
| 8534 | 'will return\n' |
| 8535 | 'the descriptor object itself unless there is a value in the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8536 | 'object’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8537 | 'instance dictionary. If the descriptor defines "__set__()" ' |
| 8538 | 'and/or\n' |
| 8539 | '"__delete__()", it is a data descriptor; if it defines ' |
| 8540 | 'neither, it is\n' |
| 8541 | 'a non-data descriptor. Normally, data descriptors define ' |
| 8542 | 'both\n' |
| 8543 | '"__get__()" and "__set__()", while non-data descriptors have ' |
| 8544 | 'just the\n' |
| 8545 | '"__get__()" method. Data descriptors with "__set__()" and ' |
| 8546 | '"__get__()"\n' |
| 8547 | 'defined always override a redefinition in an instance ' |
| 8548 | 'dictionary. In\n' |
| 8549 | 'contrast, non-data descriptors can be overridden by ' |
| 8550 | 'instances.\n' |
| 8551 | '\n' |
| 8552 | 'Python methods (including "staticmethod()" and ' |
| 8553 | '"classmethod()") are\n' |
| 8554 | 'implemented as non-data descriptors. Accordingly, instances ' |
| 8555 | 'can\n' |
| 8556 | 'redefine and override methods. This allows individual ' |
| 8557 | 'instances to\n' |
| 8558 | 'acquire behaviors that differ from other instances of the ' |
| 8559 | 'same class.\n' |
| 8560 | '\n' |
| 8561 | 'The "property()" function is implemented as a data ' |
| 8562 | 'descriptor.\n' |
| 8563 | 'Accordingly, instances cannot override the behavior of a ' |
| 8564 | 'property.\n' |
| 8565 | '\n' |
| 8566 | '\n' |
| 8567 | '__slots__\n' |
| 8568 | '---------\n' |
| 8569 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8570 | '*__slots__* allow us to explicitly declare data members ' |
| 8571 | '(like\n' |
| 8572 | 'properties) and deny the creation of *__dict__* and ' |
| 8573 | '*__weakref__*\n' |
| 8574 | '(unless explicitly declared in *__slots__* or available in a ' |
| 8575 | 'parent.)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8576 | '\n' |
Łukasz Langa | 23f4589 | 2019-02-25 13:08:32 +0100 | [diff] [blame] | 8577 | 'The space saved over using *__dict__* can be significant. ' |
| 8578 | 'Attribute\n' |
| 8579 | 'lookup speed can be significantly improved as well.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8580 | '\n' |
| 8581 | 'object.__slots__\n' |
| 8582 | '\n' |
| 8583 | ' This class variable can be assigned a string, iterable, ' |
| 8584 | 'or sequence\n' |
| 8585 | ' of strings with variable names used by instances. ' |
| 8586 | '*__slots__*\n' |
| 8587 | ' reserves space for the declared variables and prevents ' |
| 8588 | 'the\n' |
| 8589 | ' automatic creation of *__dict__* and *__weakref__* for ' |
| 8590 | 'each\n' |
| 8591 | ' instance.\n' |
| 8592 | '\n' |
| 8593 | '\n' |
| 8594 | 'Notes on using *__slots__*\n' |
| 8595 | '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' |
| 8596 | '\n' |
| 8597 | '* When inheriting from a class without *__slots__*, the ' |
| 8598 | '*__dict__*\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8599 | ' and *__weakref__* attribute of the instances will always ' |
| 8600 | 'be\n' |
| 8601 | ' accessible.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8602 | '\n' |
| 8603 | '* Without a *__dict__* variable, instances cannot be ' |
| 8604 | 'assigned new\n' |
| 8605 | ' variables not listed in the *__slots__* definition. ' |
| 8606 | 'Attempts to\n' |
| 8607 | ' assign to an unlisted variable name raises ' |
| 8608 | '"AttributeError". If\n' |
| 8609 | ' dynamic assignment of new variables is desired, then add\n' |
| 8610 | ' "\'__dict__\'" to the sequence of strings in the ' |
| 8611 | '*__slots__*\n' |
| 8612 | ' declaration.\n' |
| 8613 | '\n' |
| 8614 | '* Without a *__weakref__* variable for each instance, ' |
| 8615 | 'classes\n' |
| 8616 | ' defining *__slots__* do not support weak references to ' |
| 8617 | 'its\n' |
| 8618 | ' instances. If weak reference support is needed, then add\n' |
| 8619 | ' "\'__weakref__\'" to the sequence of strings in the ' |
| 8620 | '*__slots__*\n' |
| 8621 | ' declaration.\n' |
| 8622 | '\n' |
| 8623 | '* *__slots__* are implemented at the class level by ' |
| 8624 | 'creating\n' |
| 8625 | ' descriptors (Implementing Descriptors) for each variable ' |
| 8626 | 'name. As a\n' |
| 8627 | ' result, class attributes cannot be used to set default ' |
| 8628 | 'values for\n' |
| 8629 | ' instance variables defined by *__slots__*; otherwise, the ' |
| 8630 | 'class\n' |
| 8631 | ' attribute would overwrite the descriptor assignment.\n' |
| 8632 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8633 | '* The action of a *__slots__* declaration is not limited to ' |
| 8634 | 'the\n' |
| 8635 | ' class where it is defined. *__slots__* declared in ' |
| 8636 | 'parents are\n' |
| 8637 | ' available in child classes. However, child subclasses will ' |
| 8638 | 'get a\n' |
| 8639 | ' *__dict__* and *__weakref__* unless they also define ' |
| 8640 | '*__slots__*\n' |
| 8641 | ' (which should only contain names of any *additional* ' |
| 8642 | 'slots).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8643 | '\n' |
| 8644 | '* If a class defines a slot also defined in a base class, ' |
| 8645 | 'the\n' |
| 8646 | ' instance variable defined by the base class slot is ' |
| 8647 | 'inaccessible\n' |
| 8648 | ' (except by retrieving its descriptor directly from the ' |
| 8649 | 'base class).\n' |
| 8650 | ' This renders the meaning of the program undefined. In the ' |
| 8651 | 'future, a\n' |
| 8652 | ' check may be added to prevent this.\n' |
| 8653 | '\n' |
| 8654 | '* Nonempty *__slots__* does not work for classes derived ' |
| 8655 | 'from\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8656 | ' “variable-length” built-in types such as "int", "bytes" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8657 | 'and "tuple".\n' |
| 8658 | '\n' |
| 8659 | '* Any non-string iterable may be assigned to *__slots__*. ' |
| 8660 | 'Mappings\n' |
| 8661 | ' may also be used; however, in the future, special meaning ' |
| 8662 | 'may be\n' |
| 8663 | ' assigned to the values corresponding to each key.\n' |
| 8664 | '\n' |
| 8665 | '* *__class__* assignment works only if both classes have the ' |
| 8666 | 'same\n' |
| 8667 | ' *__slots__*.\n' |
| 8668 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8669 | '* Multiple inheritance with multiple slotted parent classes ' |
| 8670 | 'can be\n' |
| 8671 | ' used, but only one parent is allowed to have attributes ' |
| 8672 | 'created by\n' |
| 8673 | ' slots (the other bases must have empty slot layouts) - ' |
| 8674 | 'violations\n' |
| 8675 | ' raise "TypeError".\n' |
| 8676 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8677 | '\n' |
| 8678 | 'Customizing class creation\n' |
| 8679 | '==========================\n' |
| 8680 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 8681 | 'Whenever a class inherits from another class, ' |
| 8682 | '*__init_subclass__* is\n' |
| 8683 | 'called on that class. This way, it is possible to write ' |
| 8684 | 'classes which\n' |
| 8685 | 'change the behavior of subclasses. This is closely related ' |
| 8686 | 'to class\n' |
| 8687 | 'decorators, but where class decorators only affect the ' |
| 8688 | 'specific class\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8689 | 'they’re applied to, "__init_subclass__" solely applies to ' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 8690 | 'future\n' |
| 8691 | 'subclasses of the class defining the method.\n' |
| 8692 | '\n' |
| 8693 | 'classmethod object.__init_subclass__(cls)\n' |
| 8694 | '\n' |
| 8695 | ' This method is called whenever the containing class is ' |
| 8696 | 'subclassed.\n' |
| 8697 | ' *cls* is then the new subclass. If defined as a normal ' |
| 8698 | 'instance\n' |
| 8699 | ' method, this method is implicitly converted to a class ' |
| 8700 | 'method.\n' |
| 8701 | '\n' |
| 8702 | ' Keyword arguments which are given to a new class are ' |
| 8703 | 'passed to the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8704 | ' parent’s class "__init_subclass__". For compatibility ' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 8705 | 'with other\n' |
| 8706 | ' classes using "__init_subclass__", one should take out ' |
| 8707 | 'the needed\n' |
| 8708 | ' keyword arguments and pass the others over to the base ' |
| 8709 | 'class, as\n' |
| 8710 | ' in:\n' |
| 8711 | '\n' |
| 8712 | ' class Philosopher:\n' |
| 8713 | ' def __init_subclass__(cls, default_name, ' |
| 8714 | '**kwargs):\n' |
| 8715 | ' super().__init_subclass__(**kwargs)\n' |
| 8716 | ' cls.default_name = default_name\n' |
| 8717 | '\n' |
| 8718 | ' class AustralianPhilosopher(Philosopher, ' |
| 8719 | 'default_name="Bruce"):\n' |
| 8720 | ' pass\n' |
| 8721 | '\n' |
| 8722 | ' The default implementation "object.__init_subclass__" ' |
| 8723 | 'does nothing,\n' |
| 8724 | ' but raises an error if it is called with any arguments.\n' |
| 8725 | '\n' |
| 8726 | ' Note: The metaclass hint "metaclass" is consumed by the ' |
| 8727 | 'rest of\n' |
| 8728 | ' the type machinery, and is never passed to ' |
| 8729 | '"__init_subclass__"\n' |
| 8730 | ' implementations. The actual metaclass (rather than the ' |
| 8731 | 'explicit\n' |
| 8732 | ' hint) can be accessed as "type(cls)".\n' |
| 8733 | '\n' |
| 8734 | ' New in version 3.6.\n' |
| 8735 | '\n' |
| 8736 | '\n' |
| 8737 | 'Metaclasses\n' |
| 8738 | '-----------\n' |
| 8739 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8740 | 'By default, classes are constructed using "type()". The ' |
| 8741 | 'class body is\n' |
| 8742 | 'executed in a new namespace and the class name is bound ' |
| 8743 | 'locally to the\n' |
| 8744 | 'result of "type(name, bases, namespace)".\n' |
| 8745 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 8746 | 'The class creation process can be customized by passing the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8747 | '"metaclass" keyword argument in the class definition line, ' |
| 8748 | 'or by\n' |
| 8749 | 'inheriting from an existing class that included such an ' |
| 8750 | 'argument. In\n' |
| 8751 | 'the following example, both "MyClass" and "MySubclass" are ' |
| 8752 | 'instances\n' |
| 8753 | 'of "Meta":\n' |
| 8754 | '\n' |
| 8755 | ' class Meta(type):\n' |
| 8756 | ' pass\n' |
| 8757 | '\n' |
| 8758 | ' class MyClass(metaclass=Meta):\n' |
| 8759 | ' pass\n' |
| 8760 | '\n' |
| 8761 | ' class MySubclass(MyClass):\n' |
| 8762 | ' pass\n' |
| 8763 | '\n' |
| 8764 | 'Any other keyword arguments that are specified in the class ' |
| 8765 | 'definition\n' |
| 8766 | 'are passed through to all metaclass operations described ' |
| 8767 | 'below.\n' |
| 8768 | '\n' |
| 8769 | 'When a class definition is executed, the following steps ' |
| 8770 | 'occur:\n' |
| 8771 | '\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8772 | '* MRO entries are resolved;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8773 | '\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8774 | '* the appropriate metaclass is determined;\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8775 | '\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8776 | '* the class namespace is prepared;\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8777 | '\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8778 | '* the class body is executed;\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8779 | '\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8780 | '* the class object is created.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8781 | '\n' |
| 8782 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8783 | 'Resolving MRO entries\n' |
| 8784 | '---------------------\n' |
| 8785 | '\n' |
| 8786 | 'If a base that appears in class definition is not an ' |
| 8787 | 'instance of\n' |
| 8788 | '"type", then an "__mro_entries__" method is searched on it. ' |
| 8789 | 'If found,\n' |
| 8790 | 'it is called with the original bases tuple. This method must ' |
| 8791 | 'return a\n' |
| 8792 | 'tuple of classes that will be used instead of this base. The ' |
| 8793 | 'tuple may\n' |
| 8794 | 'be empty, in such case the original base is ignored.\n' |
| 8795 | '\n' |
| 8796 | 'See also: **PEP 560** - Core support for typing module and ' |
| 8797 | 'generic\n' |
| 8798 | ' types\n' |
| 8799 | '\n' |
| 8800 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8801 | 'Determining the appropriate metaclass\n' |
| 8802 | '-------------------------------------\n' |
| 8803 | '\n' |
| 8804 | 'The appropriate metaclass for a class definition is ' |
| 8805 | 'determined as\n' |
| 8806 | 'follows:\n' |
| 8807 | '\n' |
| 8808 | '* if no bases and no explicit metaclass are given, then ' |
| 8809 | '"type()" is\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8810 | ' used;\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8811 | '\n' |
| 8812 | '* if an explicit metaclass is given and it is *not* an ' |
| 8813 | 'instance of\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8814 | ' "type()", then it is used directly as the metaclass;\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8815 | '\n' |
| 8816 | '* if an instance of "type()" is given as the explicit ' |
| 8817 | 'metaclass, or\n' |
| 8818 | ' bases are defined, then the most derived metaclass is ' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8819 | 'used.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8820 | '\n' |
| 8821 | 'The most derived metaclass is selected from the explicitly ' |
| 8822 | 'specified\n' |
| 8823 | 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of ' |
| 8824 | 'all\n' |
| 8825 | 'specified base classes. The most derived metaclass is one ' |
| 8826 | 'which is a\n' |
| 8827 | 'subtype of *all* of these candidate metaclasses. If none of ' |
| 8828 | 'the\n' |
| 8829 | 'candidate metaclasses meets that criterion, then the class ' |
| 8830 | 'definition\n' |
| 8831 | 'will fail with "TypeError".\n' |
| 8832 | '\n' |
| 8833 | '\n' |
| 8834 | 'Preparing the class namespace\n' |
| 8835 | '-----------------------------\n' |
| 8836 | '\n' |
| 8837 | 'Once the appropriate metaclass has been identified, then the ' |
| 8838 | 'class\n' |
| 8839 | 'namespace is prepared. If the metaclass has a "__prepare__" ' |
| 8840 | 'attribute,\n' |
| 8841 | 'it is called as "namespace = metaclass.__prepare__(name, ' |
| 8842 | 'bases,\n' |
| 8843 | '**kwds)" (where the additional keyword arguments, if any, ' |
| 8844 | 'come from\n' |
| 8845 | 'the class definition).\n' |
| 8846 | '\n' |
| 8847 | 'If the metaclass has no "__prepare__" attribute, then the ' |
| 8848 | 'class\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 8849 | 'namespace is initialised as an empty ordered mapping.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8850 | '\n' |
| 8851 | 'See also:\n' |
| 8852 | '\n' |
| 8853 | ' **PEP 3115** - Metaclasses in Python 3000\n' |
| 8854 | ' Introduced the "__prepare__" namespace hook\n' |
| 8855 | '\n' |
| 8856 | '\n' |
| 8857 | 'Executing the class body\n' |
| 8858 | '------------------------\n' |
| 8859 | '\n' |
| 8860 | 'The class body is executed (approximately) as "exec(body, ' |
| 8861 | 'globals(),\n' |
| 8862 | 'namespace)". The key difference from a normal call to ' |
| 8863 | '"exec()" is that\n' |
| 8864 | 'lexical scoping allows the class body (including any ' |
| 8865 | 'methods) to\n' |
| 8866 | 'reference names from the current and outer scopes when the ' |
| 8867 | 'class\n' |
| 8868 | 'definition occurs inside a function.\n' |
| 8869 | '\n' |
| 8870 | 'However, even when the class definition occurs inside the ' |
| 8871 | 'function,\n' |
| 8872 | 'methods defined inside the class still cannot see names ' |
| 8873 | 'defined at the\n' |
| 8874 | 'class scope. Class variables must be accessed through the ' |
| 8875 | 'first\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8876 | 'parameter of instance or class methods, or through the ' |
| 8877 | 'implicit\n' |
| 8878 | 'lexically scoped "__class__" reference described in the next ' |
| 8879 | 'section.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8880 | '\n' |
| 8881 | '\n' |
| 8882 | 'Creating the class object\n' |
| 8883 | '-------------------------\n' |
| 8884 | '\n' |
| 8885 | 'Once the class namespace has been populated by executing the ' |
| 8886 | 'class\n' |
| 8887 | 'body, the class object is created by calling ' |
| 8888 | '"metaclass(name, bases,\n' |
| 8889 | 'namespace, **kwds)" (the additional keywords passed here are ' |
| 8890 | 'the same\n' |
| 8891 | 'as those passed to "__prepare__").\n' |
| 8892 | '\n' |
| 8893 | 'This class object is the one that will be referenced by the ' |
| 8894 | 'zero-\n' |
| 8895 | 'argument form of "super()". "__class__" is an implicit ' |
| 8896 | 'closure\n' |
| 8897 | 'reference created by the compiler if any methods in a class ' |
| 8898 | 'body refer\n' |
| 8899 | 'to either "__class__" or "super". This allows the zero ' |
| 8900 | 'argument form\n' |
| 8901 | 'of "super()" to correctly identify the class being defined ' |
| 8902 | 'based on\n' |
| 8903 | 'lexical scoping, while the class or instance that was used ' |
| 8904 | 'to make the\n' |
| 8905 | 'current call is identified based on the first argument ' |
| 8906 | 'passed to the\n' |
| 8907 | 'method.\n' |
| 8908 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8909 | '**CPython implementation detail:** In CPython 3.6 and later, ' |
| 8910 | 'the\n' |
| 8911 | '"__class__" cell is passed to the metaclass as a ' |
| 8912 | '"__classcell__" entry\n' |
| 8913 | 'in the class namespace. If present, this must be propagated ' |
| 8914 | 'up to the\n' |
| 8915 | '"type.__new__" call in order for the class to be ' |
| 8916 | 'initialised\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8917 | 'correctly. Failing to do so will result in a "RuntimeError" ' |
| 8918 | 'in Python\n' |
| 8919 | '3.8.\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8920 | '\n' |
| 8921 | 'When using the default metaclass "type", or any metaclass ' |
| 8922 | 'that\n' |
| 8923 | 'ultimately calls "type.__new__", the following additional\n' |
| 8924 | 'customisation steps are invoked after creating the class ' |
| 8925 | 'object:\n' |
| 8926 | '\n' |
| 8927 | '* first, "type.__new__" collects all of the descriptors in ' |
| 8928 | 'the class\n' |
| 8929 | ' namespace that define a "__set_name__()" method;\n' |
| 8930 | '\n' |
| 8931 | '* second, all of these "__set_name__" methods are called ' |
| 8932 | 'with the\n' |
| 8933 | ' class being defined and the assigned name of that ' |
| 8934 | 'particular\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 8935 | ' descriptor;\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8936 | '\n' |
| 8937 | '* finally, the "__init_subclass__()" hook is called on the ' |
| 8938 | 'immediate\n' |
| 8939 | ' parent of the new class in its method resolution order.\n' |
| 8940 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8941 | 'After the class object is created, it is passed to the ' |
| 8942 | 'class\n' |
| 8943 | 'decorators included in the class definition (if any) and the ' |
| 8944 | 'resulting\n' |
| 8945 | 'object is bound in the local namespace as the defined ' |
| 8946 | 'class.\n' |
| 8947 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 8948 | 'When a new class is created by "type.__new__", the object ' |
| 8949 | 'provided as\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 8950 | 'the namespace parameter is copied to a new ordered mapping ' |
| 8951 | 'and the\n' |
| 8952 | 'original object is discarded. The new copy is wrapped in a ' |
| 8953 | 'read-only\n' |
| 8954 | 'proxy, which becomes the "__dict__" attribute of the class ' |
| 8955 | 'object.\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 8956 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8957 | 'See also:\n' |
| 8958 | '\n' |
| 8959 | ' **PEP 3135** - New super\n' |
| 8960 | ' Describes the implicit "__class__" closure reference\n' |
| 8961 | '\n' |
| 8962 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8963 | 'Uses for metaclasses\n' |
| 8964 | '--------------------\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8965 | '\n' |
| 8966 | 'The potential uses for metaclasses are boundless. Some ideas ' |
| 8967 | 'that have\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8968 | 'been explored include enum, logging, interface checking, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8969 | 'automatic\n' |
| 8970 | 'delegation, automatic property creation, proxies, ' |
| 8971 | 'frameworks, and\n' |
| 8972 | 'automatic resource locking/synchronization.\n' |
| 8973 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8974 | '\n' |
| 8975 | 'Customizing instance and subclass checks\n' |
| 8976 | '========================================\n' |
| 8977 | '\n' |
| 8978 | 'The following methods are used to override the default ' |
| 8979 | 'behavior of the\n' |
| 8980 | '"isinstance()" and "issubclass()" built-in functions.\n' |
| 8981 | '\n' |
| 8982 | 'In particular, the metaclass "abc.ABCMeta" implements these ' |
| 8983 | 'methods in\n' |
| 8984 | 'order to allow the addition of Abstract Base Classes (ABCs) ' |
| 8985 | 'as\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 8986 | '“virtual base classes” to any class or type (including ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8987 | 'built-in\n' |
| 8988 | 'types), including other ABCs.\n' |
| 8989 | '\n' |
| 8990 | 'class.__instancecheck__(self, instance)\n' |
| 8991 | '\n' |
| 8992 | ' Return true if *instance* should be considered a (direct ' |
| 8993 | 'or\n' |
| 8994 | ' indirect) instance of *class*. If defined, called to ' |
| 8995 | 'implement\n' |
| 8996 | ' "isinstance(instance, class)".\n' |
| 8997 | '\n' |
| 8998 | 'class.__subclasscheck__(self, subclass)\n' |
| 8999 | '\n' |
| 9000 | ' Return true if *subclass* should be considered a (direct ' |
| 9001 | 'or\n' |
| 9002 | ' indirect) subclass of *class*. If defined, called to ' |
| 9003 | 'implement\n' |
| 9004 | ' "issubclass(subclass, class)".\n' |
| 9005 | '\n' |
| 9006 | 'Note that these methods are looked up on the type ' |
| 9007 | '(metaclass) of a\n' |
| 9008 | 'class. They cannot be defined as class methods in the ' |
| 9009 | 'actual class.\n' |
| 9010 | 'This is consistent with the lookup of special methods that ' |
| 9011 | 'are called\n' |
| 9012 | 'on instances, only in this case the instance is itself a ' |
| 9013 | 'class.\n' |
| 9014 | '\n' |
| 9015 | 'See also:\n' |
| 9016 | '\n' |
| 9017 | ' **PEP 3119** - Introducing Abstract Base Classes\n' |
| 9018 | ' Includes the specification for customizing ' |
| 9019 | '"isinstance()" and\n' |
| 9020 | ' "issubclass()" behavior through "__instancecheck__()" ' |
| 9021 | 'and\n' |
| 9022 | ' "__subclasscheck__()", with motivation for this ' |
| 9023 | 'functionality in\n' |
| 9024 | ' the context of adding Abstract Base Classes (see the ' |
| 9025 | '"abc"\n' |
| 9026 | ' module) to the language.\n' |
| 9027 | '\n' |
| 9028 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9029 | 'Emulating generic types\n' |
| 9030 | '=======================\n' |
| 9031 | '\n' |
| 9032 | 'One can implement the generic class syntax as specified by ' |
| 9033 | '**PEP 484**\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 9034 | '(for example "List[int]") by defining a special method:\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9035 | '\n' |
| 9036 | 'classmethod object.__class_getitem__(cls, key)\n' |
| 9037 | '\n' |
| 9038 | ' Return an object representing the specialization of a ' |
| 9039 | 'generic class\n' |
| 9040 | ' by type arguments found in *key*.\n' |
| 9041 | '\n' |
| 9042 | 'This method is looked up on the class object itself, and ' |
| 9043 | 'when defined\n' |
| 9044 | 'in the class body, this method is implicitly a class ' |
| 9045 | 'method. Note,\n' |
| 9046 | 'this mechanism is primarily reserved for use with static ' |
| 9047 | 'type hints,\n' |
| 9048 | 'other usage is discouraged.\n' |
| 9049 | '\n' |
| 9050 | 'See also: **PEP 560** - Core support for typing module and ' |
| 9051 | 'generic\n' |
| 9052 | ' types\n' |
| 9053 | '\n' |
| 9054 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9055 | 'Emulating callable objects\n' |
| 9056 | '==========================\n' |
| 9057 | '\n' |
| 9058 | 'object.__call__(self[, args...])\n' |
| 9059 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9060 | ' Called when the instance is “called” as a function; if ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9061 | 'this method\n' |
| 9062 | ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' |
| 9063 | ' "x.__call__(arg1, arg2, ...)".\n' |
| 9064 | '\n' |
| 9065 | '\n' |
| 9066 | 'Emulating container types\n' |
| 9067 | '=========================\n' |
| 9068 | '\n' |
| 9069 | 'The following methods can be defined to implement container ' |
| 9070 | 'objects.\n' |
| 9071 | 'Containers usually are sequences (such as lists or tuples) ' |
| 9072 | 'or mappings\n' |
| 9073 | '(like dictionaries), but can represent other containers as ' |
| 9074 | 'well. The\n' |
| 9075 | 'first set of methods is used either to emulate a sequence or ' |
| 9076 | 'to\n' |
| 9077 | 'emulate a mapping; the difference is that for a sequence, ' |
| 9078 | 'the\n' |
| 9079 | 'allowable keys should be the integers *k* for which "0 <= k ' |
| 9080 | '< N" where\n' |
| 9081 | '*N* is the length of the sequence, or slice objects, which ' |
| 9082 | 'define a\n' |
| 9083 | 'range of items. It is also recommended that mappings ' |
| 9084 | 'provide the\n' |
| 9085 | 'methods "keys()", "values()", "items()", "get()", ' |
| 9086 | '"clear()",\n' |
| 9087 | '"setdefault()", "pop()", "popitem()", "copy()", and ' |
| 9088 | '"update()"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9089 | 'behaving similar to those for Python’s standard dictionary ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9090 | 'objects.\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9091 | 'The "collections.abc" module provides a "MutableMapping" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9092 | 'abstract base\n' |
| 9093 | 'class to help create those methods from a base set of ' |
| 9094 | '"__getitem__()",\n' |
| 9095 | '"__setitem__()", "__delitem__()", and "keys()". Mutable ' |
| 9096 | 'sequences\n' |
| 9097 | 'should provide methods "append()", "count()", "index()", ' |
| 9098 | '"extend()",\n' |
| 9099 | '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' |
| 9100 | 'like Python\n' |
| 9101 | 'standard list objects. Finally, sequence types should ' |
| 9102 | 'implement\n' |
| 9103 | 'addition (meaning concatenation) and multiplication ' |
| 9104 | '(meaning\n' |
| 9105 | 'repetition) by defining the methods "__add__()", ' |
| 9106 | '"__radd__()",\n' |
| 9107 | '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' |
| 9108 | 'described\n' |
| 9109 | 'below; they should not define other numerical operators. It ' |
| 9110 | 'is\n' |
| 9111 | 'recommended that both mappings and sequences implement the\n' |
| 9112 | '"__contains__()" method to allow efficient use of the "in" ' |
| 9113 | 'operator;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9114 | 'for mappings, "in" should search the mapping’s keys; for ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9115 | 'sequences, it\n' |
| 9116 | 'should search through the values. It is further recommended ' |
| 9117 | 'that both\n' |
| 9118 | 'mappings and sequences implement the "__iter__()" method to ' |
| 9119 | 'allow\n' |
| 9120 | 'efficient iteration through the container; for mappings, ' |
| 9121 | '"__iter__()"\n' |
| 9122 | 'should be the same as "keys()"; for sequences, it should ' |
| 9123 | 'iterate\n' |
| 9124 | 'through the values.\n' |
| 9125 | '\n' |
| 9126 | 'object.__len__(self)\n' |
| 9127 | '\n' |
| 9128 | ' Called to implement the built-in function "len()". ' |
| 9129 | 'Should return\n' |
| 9130 | ' the length of the object, an integer ">=" 0. Also, an ' |
| 9131 | 'object that\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9132 | ' doesn’t define a "__bool__()" method and whose ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9133 | '"__len__()" method\n' |
| 9134 | ' returns zero is considered to be false in a Boolean ' |
| 9135 | 'context.\n' |
| 9136 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9137 | ' **CPython implementation detail:** In CPython, the length ' |
| 9138 | 'is\n' |
| 9139 | ' required to be at most "sys.maxsize". If the length is ' |
| 9140 | 'larger than\n' |
| 9141 | ' "sys.maxsize" some features (such as "len()") may raise\n' |
| 9142 | ' "OverflowError". To prevent raising "OverflowError" by ' |
| 9143 | 'truth value\n' |
| 9144 | ' testing, an object must define a "__bool__()" method.\n' |
| 9145 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9146 | 'object.__length_hint__(self)\n' |
| 9147 | '\n' |
| 9148 | ' Called to implement "operator.length_hint()". Should ' |
| 9149 | 'return an\n' |
| 9150 | ' estimated length for the object (which may be greater or ' |
| 9151 | 'less than\n' |
| 9152 | ' the actual length). The length must be an integer ">=" 0. ' |
| 9153 | 'This\n' |
| 9154 | ' method is purely an optimization and is never required ' |
| 9155 | 'for\n' |
| 9156 | ' correctness.\n' |
| 9157 | '\n' |
| 9158 | ' New in version 3.4.\n' |
| 9159 | '\n' |
| 9160 | 'Note: Slicing is done exclusively with the following three ' |
| 9161 | 'methods.\n' |
| 9162 | ' A call like\n' |
| 9163 | '\n' |
| 9164 | ' a[1:2] = b\n' |
| 9165 | '\n' |
| 9166 | ' is translated to\n' |
| 9167 | '\n' |
| 9168 | ' a[slice(1, 2, None)] = b\n' |
| 9169 | '\n' |
| 9170 | ' and so forth. Missing slice items are always filled in ' |
| 9171 | 'with "None".\n' |
| 9172 | '\n' |
| 9173 | 'object.__getitem__(self, key)\n' |
| 9174 | '\n' |
| 9175 | ' Called to implement evaluation of "self[key]". For ' |
| 9176 | 'sequence types,\n' |
| 9177 | ' the accepted keys should be integers and slice objects. ' |
| 9178 | 'Note that\n' |
| 9179 | ' the special interpretation of negative indexes (if the ' |
| 9180 | 'class wishes\n' |
| 9181 | ' to emulate a sequence type) is up to the "__getitem__()" ' |
| 9182 | 'method. If\n' |
| 9183 | ' *key* is of an inappropriate type, "TypeError" may be ' |
| 9184 | 'raised; if of\n' |
| 9185 | ' a value outside the set of indexes for the sequence ' |
| 9186 | '(after any\n' |
| 9187 | ' special interpretation of negative values), "IndexError" ' |
| 9188 | 'should be\n' |
| 9189 | ' raised. For mapping types, if *key* is missing (not in ' |
| 9190 | 'the\n' |
| 9191 | ' container), "KeyError" should be raised.\n' |
| 9192 | '\n' |
| 9193 | ' Note: "for" loops expect that an "IndexError" will be ' |
| 9194 | 'raised for\n' |
| 9195 | ' illegal indexes to allow proper detection of the end of ' |
| 9196 | 'the\n' |
| 9197 | ' sequence.\n' |
| 9198 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9199 | 'object.__setitem__(self, key, value)\n' |
| 9200 | '\n' |
| 9201 | ' Called to implement assignment to "self[key]". Same note ' |
| 9202 | 'as for\n' |
| 9203 | ' "__getitem__()". This should only be implemented for ' |
| 9204 | 'mappings if\n' |
| 9205 | ' the objects support changes to the values for keys, or if ' |
| 9206 | 'new keys\n' |
| 9207 | ' can be added, or for sequences if elements can be ' |
| 9208 | 'replaced. The\n' |
| 9209 | ' same exceptions should be raised for improper *key* ' |
| 9210 | 'values as for\n' |
| 9211 | ' the "__getitem__()" method.\n' |
| 9212 | '\n' |
| 9213 | 'object.__delitem__(self, key)\n' |
| 9214 | '\n' |
| 9215 | ' Called to implement deletion of "self[key]". Same note ' |
| 9216 | 'as for\n' |
| 9217 | ' "__getitem__()". This should only be implemented for ' |
| 9218 | 'mappings if\n' |
| 9219 | ' the objects support removal of keys, or for sequences if ' |
| 9220 | 'elements\n' |
| 9221 | ' can be removed from the sequence. The same exceptions ' |
| 9222 | 'should be\n' |
| 9223 | ' raised for improper *key* values as for the ' |
| 9224 | '"__getitem__()" method.\n' |
| 9225 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9226 | 'object.__missing__(self, key)\n' |
| 9227 | '\n' |
| 9228 | ' Called by "dict"."__getitem__()" to implement "self[key]" ' |
| 9229 | 'for dict\n' |
| 9230 | ' subclasses when key is not in the dictionary.\n' |
| 9231 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9232 | 'object.__iter__(self)\n' |
| 9233 | '\n' |
| 9234 | ' This method is called when an iterator is required for a ' |
| 9235 | 'container.\n' |
| 9236 | ' This method should return a new iterator object that can ' |
| 9237 | 'iterate\n' |
| 9238 | ' over all the objects in the container. For mappings, it ' |
| 9239 | 'should\n' |
| 9240 | ' iterate over the keys of the container.\n' |
| 9241 | '\n' |
| 9242 | ' Iterator objects also need to implement this method; they ' |
| 9243 | 'are\n' |
| 9244 | ' required to return themselves. For more information on ' |
| 9245 | 'iterator\n' |
| 9246 | ' objects, see Iterator Types.\n' |
| 9247 | '\n' |
| 9248 | 'object.__reversed__(self)\n' |
| 9249 | '\n' |
| 9250 | ' Called (if present) by the "reversed()" built-in to ' |
| 9251 | 'implement\n' |
| 9252 | ' reverse iteration. It should return a new iterator ' |
| 9253 | 'object that\n' |
| 9254 | ' iterates over all the objects in the container in reverse ' |
| 9255 | 'order.\n' |
| 9256 | '\n' |
| 9257 | ' If the "__reversed__()" method is not provided, the ' |
| 9258 | '"reversed()"\n' |
| 9259 | ' built-in will fall back to using the sequence protocol ' |
| 9260 | '("__len__()"\n' |
| 9261 | ' and "__getitem__()"). Objects that support the sequence ' |
| 9262 | 'protocol\n' |
| 9263 | ' should only provide "__reversed__()" if they can provide ' |
| 9264 | 'an\n' |
| 9265 | ' implementation that is more efficient than the one ' |
| 9266 | 'provided by\n' |
| 9267 | ' "reversed()".\n' |
| 9268 | '\n' |
| 9269 | 'The membership test operators ("in" and "not in") are ' |
| 9270 | 'normally\n' |
| 9271 | 'implemented as an iteration through a sequence. However, ' |
| 9272 | 'container\n' |
| 9273 | 'objects can supply the following special method with a more ' |
| 9274 | 'efficient\n' |
| 9275 | 'implementation, which also does not require the object be a ' |
| 9276 | 'sequence.\n' |
| 9277 | '\n' |
| 9278 | 'object.__contains__(self, item)\n' |
| 9279 | '\n' |
| 9280 | ' Called to implement membership test operators. Should ' |
| 9281 | 'return true\n' |
| 9282 | ' if *item* is in *self*, false otherwise. For mapping ' |
| 9283 | 'objects, this\n' |
| 9284 | ' should consider the keys of the mapping rather than the ' |
| 9285 | 'values or\n' |
| 9286 | ' the key-item pairs.\n' |
| 9287 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9288 | ' For objects that don’t define "__contains__()", the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9289 | 'membership test\n' |
| 9290 | ' first tries iteration via "__iter__()", then the old ' |
| 9291 | 'sequence\n' |
| 9292 | ' iteration protocol via "__getitem__()", see this section ' |
| 9293 | 'in the\n' |
| 9294 | ' language reference.\n' |
| 9295 | '\n' |
| 9296 | '\n' |
| 9297 | 'Emulating numeric types\n' |
| 9298 | '=======================\n' |
| 9299 | '\n' |
| 9300 | 'The following methods can be defined to emulate numeric ' |
| 9301 | 'objects.\n' |
| 9302 | 'Methods corresponding to operations that are not supported ' |
| 9303 | 'by the\n' |
| 9304 | 'particular kind of number implemented (e.g., bitwise ' |
| 9305 | 'operations for\n' |
| 9306 | 'non-integral numbers) should be left undefined.\n' |
| 9307 | '\n' |
| 9308 | 'object.__add__(self, other)\n' |
| 9309 | 'object.__sub__(self, other)\n' |
| 9310 | 'object.__mul__(self, other)\n' |
| 9311 | 'object.__matmul__(self, other)\n' |
| 9312 | 'object.__truediv__(self, other)\n' |
| 9313 | 'object.__floordiv__(self, other)\n' |
| 9314 | 'object.__mod__(self, other)\n' |
| 9315 | 'object.__divmod__(self, other)\n' |
| 9316 | 'object.__pow__(self, other[, modulo])\n' |
| 9317 | 'object.__lshift__(self, other)\n' |
| 9318 | 'object.__rshift__(self, other)\n' |
| 9319 | 'object.__and__(self, other)\n' |
| 9320 | 'object.__xor__(self, other)\n' |
| 9321 | 'object.__or__(self, other)\n' |
| 9322 | '\n' |
| 9323 | ' These methods are called to implement the binary ' |
| 9324 | 'arithmetic\n' |
| 9325 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 9326 | '"divmod()",\n' |
| 9327 | ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, ' |
| 9328 | 'to\n' |
| 9329 | ' evaluate the expression "x + y", where *x* is an instance ' |
| 9330 | 'of a\n' |
| 9331 | ' class that has an "__add__()" method, "x.__add__(y)" is ' |
| 9332 | 'called.\n' |
| 9333 | ' The "__divmod__()" method should be the equivalent to ' |
| 9334 | 'using\n' |
| 9335 | ' "__floordiv__()" and "__mod__()"; it should not be ' |
| 9336 | 'related to\n' |
| 9337 | ' "__truediv__()". Note that "__pow__()" should be defined ' |
| 9338 | 'to accept\n' |
| 9339 | ' an optional third argument if the ternary version of the ' |
| 9340 | 'built-in\n' |
| 9341 | ' "pow()" function is to be supported.\n' |
| 9342 | '\n' |
| 9343 | ' If one of those methods does not support the operation ' |
| 9344 | 'with the\n' |
| 9345 | ' supplied arguments, it should return "NotImplemented".\n' |
| 9346 | '\n' |
| 9347 | 'object.__radd__(self, other)\n' |
| 9348 | 'object.__rsub__(self, other)\n' |
| 9349 | 'object.__rmul__(self, other)\n' |
| 9350 | 'object.__rmatmul__(self, other)\n' |
| 9351 | 'object.__rtruediv__(self, other)\n' |
| 9352 | 'object.__rfloordiv__(self, other)\n' |
| 9353 | 'object.__rmod__(self, other)\n' |
| 9354 | 'object.__rdivmod__(self, other)\n' |
| 9355 | 'object.__rpow__(self, other)\n' |
| 9356 | 'object.__rlshift__(self, other)\n' |
| 9357 | 'object.__rrshift__(self, other)\n' |
| 9358 | 'object.__rand__(self, other)\n' |
| 9359 | 'object.__rxor__(self, other)\n' |
| 9360 | 'object.__ror__(self, other)\n' |
| 9361 | '\n' |
| 9362 | ' These methods are called to implement the binary ' |
| 9363 | 'arithmetic\n' |
| 9364 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 9365 | '"divmod()",\n' |
| 9366 | ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' |
| 9367 | '(swapped)\n' |
| 9368 | ' operands. These functions are only called if the left ' |
| 9369 | 'operand does\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 9370 | ' not support the corresponding operation [3] and the ' |
| 9371 | 'operands are of\n' |
| 9372 | ' different types. [4] For instance, to evaluate the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9373 | 'expression "x -\n' |
| 9374 | ' y", where *y* is an instance of a class that has an ' |
| 9375 | '"__rsub__()"\n' |
| 9376 | ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' |
| 9377 | 'returns\n' |
| 9378 | ' *NotImplemented*.\n' |
| 9379 | '\n' |
| 9380 | ' Note that ternary "pow()" will not try calling ' |
| 9381 | '"__rpow__()" (the\n' |
| 9382 | ' coercion rules would become too complicated).\n' |
| 9383 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9384 | ' Note: If the right operand’s type is a subclass of the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9385 | 'left\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9386 | ' operand’s type and that subclass provides the reflected ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9387 | 'method\n' |
| 9388 | ' for the operation, this method will be called before ' |
| 9389 | 'the left\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9390 | ' operand’s non-reflected method. This behavior allows ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9391 | 'subclasses\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9392 | ' to override their ancestors’ operations.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9393 | '\n' |
| 9394 | 'object.__iadd__(self, other)\n' |
| 9395 | 'object.__isub__(self, other)\n' |
| 9396 | 'object.__imul__(self, other)\n' |
| 9397 | 'object.__imatmul__(self, other)\n' |
| 9398 | 'object.__itruediv__(self, other)\n' |
| 9399 | 'object.__ifloordiv__(self, other)\n' |
| 9400 | 'object.__imod__(self, other)\n' |
| 9401 | 'object.__ipow__(self, other[, modulo])\n' |
| 9402 | 'object.__ilshift__(self, other)\n' |
| 9403 | 'object.__irshift__(self, other)\n' |
| 9404 | 'object.__iand__(self, other)\n' |
| 9405 | 'object.__ixor__(self, other)\n' |
| 9406 | 'object.__ior__(self, other)\n' |
| 9407 | '\n' |
| 9408 | ' These methods are called to implement the augmented ' |
| 9409 | 'arithmetic\n' |
| 9410 | ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' |
| 9411 | '"**=",\n' |
| 9412 | ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' |
| 9413 | 'attempt to\n' |
| 9414 | ' do the operation in-place (modifying *self*) and return ' |
| 9415 | 'the result\n' |
| 9416 | ' (which could be, but does not have to be, *self*). If a ' |
| 9417 | 'specific\n' |
| 9418 | ' method is not defined, the augmented assignment falls ' |
| 9419 | 'back to the\n' |
| 9420 | ' normal methods. For instance, if *x* is an instance of a ' |
| 9421 | 'class\n' |
| 9422 | ' with an "__iadd__()" method, "x += y" is equivalent to "x ' |
| 9423 | '=\n' |
| 9424 | ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' |
| 9425 | '"y.__radd__(x)" are\n' |
| 9426 | ' considered, as with the evaluation of "x + y". In ' |
| 9427 | 'certain\n' |
| 9428 | ' situations, augmented assignment can result in unexpected ' |
| 9429 | 'errors\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9430 | ' (see Why does a_tuple[i] += [‘item’] raise an exception ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9431 | 'when the\n' |
| 9432 | ' addition works?), but this behavior is in fact part of ' |
| 9433 | 'the data\n' |
| 9434 | ' model.\n' |
| 9435 | '\n' |
| 9436 | 'object.__neg__(self)\n' |
| 9437 | 'object.__pos__(self)\n' |
| 9438 | 'object.__abs__(self)\n' |
| 9439 | 'object.__invert__(self)\n' |
| 9440 | '\n' |
| 9441 | ' Called to implement the unary arithmetic operations ("-", ' |
| 9442 | '"+",\n' |
| 9443 | ' "abs()" and "~").\n' |
| 9444 | '\n' |
| 9445 | 'object.__complex__(self)\n' |
| 9446 | 'object.__int__(self)\n' |
| 9447 | 'object.__float__(self)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9448 | '\n' |
| 9449 | ' Called to implement the built-in functions "complex()", ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9450 | '"int()" and\n' |
| 9451 | ' "float()". Should return a value of the appropriate ' |
| 9452 | 'type.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9453 | '\n' |
| 9454 | 'object.__index__(self)\n' |
| 9455 | '\n' |
| 9456 | ' Called to implement "operator.index()", and whenever ' |
| 9457 | 'Python needs\n' |
| 9458 | ' to losslessly convert the numeric object to an integer ' |
| 9459 | 'object (such\n' |
| 9460 | ' as in slicing, or in the built-in "bin()", "hex()" and ' |
| 9461 | '"oct()"\n' |
| 9462 | ' functions). Presence of this method indicates that the ' |
| 9463 | 'numeric\n' |
| 9464 | ' object is an integer type. Must return an integer.\n' |
| 9465 | '\n' |
| 9466 | ' Note: In order to have a coherent integer type class, ' |
| 9467 | 'when\n' |
| 9468 | ' "__index__()" is defined "__int__()" should also be ' |
| 9469 | 'defined, and\n' |
| 9470 | ' both should return the same value.\n' |
| 9471 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9472 | 'object.__round__(self[, ndigits])\n' |
| 9473 | 'object.__trunc__(self)\n' |
| 9474 | 'object.__floor__(self)\n' |
| 9475 | 'object.__ceil__(self)\n' |
| 9476 | '\n' |
| 9477 | ' Called to implement the built-in function "round()" and ' |
| 9478 | '"math"\n' |
| 9479 | ' functions "trunc()", "floor()" and "ceil()". Unless ' |
| 9480 | '*ndigits* is\n' |
| 9481 | ' passed to "__round__()" all these methods should return ' |
| 9482 | 'the value\n' |
| 9483 | ' of the object truncated to an "Integral" (typically an ' |
| 9484 | '"int").\n' |
| 9485 | '\n' |
| 9486 | ' If "__int__()" is not defined then the built-in function ' |
| 9487 | '"int()"\n' |
| 9488 | ' falls back to "__trunc__()".\n' |
| 9489 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9490 | '\n' |
| 9491 | 'With Statement Context Managers\n' |
| 9492 | '===============================\n' |
| 9493 | '\n' |
| 9494 | 'A *context manager* is an object that defines the runtime ' |
| 9495 | 'context to\n' |
| 9496 | 'be established when executing a "with" statement. The ' |
| 9497 | 'context manager\n' |
| 9498 | 'handles the entry into, and the exit from, the desired ' |
| 9499 | 'runtime context\n' |
| 9500 | 'for the execution of the block of code. Context managers ' |
| 9501 | 'are normally\n' |
| 9502 | 'invoked using the "with" statement (described in section The ' |
| 9503 | 'with\n' |
| 9504 | 'statement), but can also be used by directly invoking their ' |
| 9505 | 'methods.\n' |
| 9506 | '\n' |
| 9507 | 'Typical uses of context managers include saving and ' |
| 9508 | 'restoring various\n' |
| 9509 | 'kinds of global state, locking and unlocking resources, ' |
| 9510 | 'closing opened\n' |
| 9511 | 'files, etc.\n' |
| 9512 | '\n' |
| 9513 | 'For more information on context managers, see Context ' |
| 9514 | 'Manager Types.\n' |
| 9515 | '\n' |
| 9516 | 'object.__enter__(self)\n' |
| 9517 | '\n' |
| 9518 | ' Enter the runtime context related to this object. The ' |
| 9519 | '"with"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9520 | ' statement will bind this method’s return value to the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9521 | 'target(s)\n' |
| 9522 | ' specified in the "as" clause of the statement, if any.\n' |
| 9523 | '\n' |
| 9524 | 'object.__exit__(self, exc_type, exc_value, traceback)\n' |
| 9525 | '\n' |
| 9526 | ' Exit the runtime context related to this object. The ' |
| 9527 | 'parameters\n' |
| 9528 | ' describe the exception that caused the context to be ' |
| 9529 | 'exited. If the\n' |
| 9530 | ' context was exited without an exception, all three ' |
| 9531 | 'arguments will\n' |
| 9532 | ' be "None".\n' |
| 9533 | '\n' |
| 9534 | ' If an exception is supplied, and the method wishes to ' |
| 9535 | 'suppress the\n' |
| 9536 | ' exception (i.e., prevent it from being propagated), it ' |
| 9537 | 'should\n' |
| 9538 | ' return a true value. Otherwise, the exception will be ' |
| 9539 | 'processed\n' |
| 9540 | ' normally upon exit from this method.\n' |
| 9541 | '\n' |
| 9542 | ' Note that "__exit__()" methods should not reraise the ' |
| 9543 | 'passed-in\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9544 | ' exception; this is the caller’s responsibility.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9545 | '\n' |
| 9546 | 'See also:\n' |
| 9547 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9548 | ' **PEP 343** - The “with” statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9549 | ' The specification, background, and examples for the ' |
| 9550 | 'Python "with"\n' |
| 9551 | ' statement.\n' |
| 9552 | '\n' |
| 9553 | '\n' |
| 9554 | 'Special method lookup\n' |
| 9555 | '=====================\n' |
| 9556 | '\n' |
| 9557 | 'For custom classes, implicit invocations of special methods ' |
| 9558 | 'are only\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9559 | 'guaranteed to work correctly if defined on an object’s type, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9560 | 'not in\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9561 | 'the object’s instance dictionary. That behaviour is the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9562 | 'reason why\n' |
| 9563 | 'the following code raises an exception:\n' |
| 9564 | '\n' |
| 9565 | ' >>> class C:\n' |
| 9566 | ' ... pass\n' |
| 9567 | ' ...\n' |
| 9568 | ' >>> c = C()\n' |
| 9569 | ' >>> c.__len__ = lambda: 5\n' |
| 9570 | ' >>> len(c)\n' |
| 9571 | ' Traceback (most recent call last):\n' |
| 9572 | ' File "<stdin>", line 1, in <module>\n' |
| 9573 | " TypeError: object of type 'C' has no len()\n" |
| 9574 | '\n' |
| 9575 | 'The rationale behind this behaviour lies with a number of ' |
| 9576 | 'special\n' |
| 9577 | 'methods such as "__hash__()" and "__repr__()" that are ' |
| 9578 | 'implemented by\n' |
| 9579 | 'all objects, including type objects. If the implicit lookup ' |
| 9580 | 'of these\n' |
| 9581 | 'methods used the conventional lookup process, they would ' |
| 9582 | 'fail when\n' |
| 9583 | 'invoked on the type object itself:\n' |
| 9584 | '\n' |
| 9585 | ' >>> 1 .__hash__() == hash(1)\n' |
| 9586 | ' True\n' |
| 9587 | ' >>> int.__hash__() == hash(int)\n' |
| 9588 | ' Traceback (most recent call last):\n' |
| 9589 | ' File "<stdin>", line 1, in <module>\n' |
| 9590 | " TypeError: descriptor '__hash__' of 'int' object needs an " |
| 9591 | 'argument\n' |
| 9592 | '\n' |
| 9593 | 'Incorrectly attempting to invoke an unbound method of a ' |
| 9594 | 'class in this\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9595 | 'way is sometimes referred to as ‘metaclass confusion’, and ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9596 | 'is avoided\n' |
| 9597 | 'by bypassing the instance when looking up special methods:\n' |
| 9598 | '\n' |
| 9599 | ' >>> type(1).__hash__(1) == hash(1)\n' |
| 9600 | ' True\n' |
| 9601 | ' >>> type(int).__hash__(int) == hash(int)\n' |
| 9602 | ' True\n' |
| 9603 | '\n' |
| 9604 | 'In addition to bypassing any instance attributes in the ' |
| 9605 | 'interest of\n' |
| 9606 | 'correctness, implicit special method lookup generally also ' |
| 9607 | 'bypasses\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9608 | 'the "__getattribute__()" method even of the object’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9609 | 'metaclass:\n' |
| 9610 | '\n' |
| 9611 | ' >>> class Meta(type):\n' |
| 9612 | ' ... def __getattribute__(*args):\n' |
| 9613 | ' ... print("Metaclass getattribute invoked")\n' |
| 9614 | ' ... return type.__getattribute__(*args)\n' |
| 9615 | ' ...\n' |
| 9616 | ' >>> class C(object, metaclass=Meta):\n' |
| 9617 | ' ... def __len__(self):\n' |
| 9618 | ' ... return 10\n' |
| 9619 | ' ... def __getattribute__(*args):\n' |
| 9620 | ' ... print("Class getattribute invoked")\n' |
| 9621 | ' ... return object.__getattribute__(*args)\n' |
| 9622 | ' ...\n' |
| 9623 | ' >>> c = C()\n' |
| 9624 | ' >>> c.__len__() # Explicit lookup via ' |
| 9625 | 'instance\n' |
| 9626 | ' Class getattribute invoked\n' |
| 9627 | ' 10\n' |
| 9628 | ' >>> type(c).__len__(c) # Explicit lookup via ' |
| 9629 | 'type\n' |
| 9630 | ' Metaclass getattribute invoked\n' |
| 9631 | ' 10\n' |
| 9632 | ' >>> len(c) # Implicit lookup\n' |
| 9633 | ' 10\n' |
| 9634 | '\n' |
| 9635 | 'Bypassing the "__getattribute__()" machinery in this fashion ' |
| 9636 | 'provides\n' |
| 9637 | 'significant scope for speed optimisations within the ' |
| 9638 | 'interpreter, at\n' |
| 9639 | 'the cost of some flexibility in the handling of special ' |
| 9640 | 'methods (the\n' |
| 9641 | 'special method *must* be set on the class object itself in ' |
| 9642 | 'order to be\n' |
| 9643 | 'consistently invoked by the interpreter).\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9644 | 'string-methods': 'String Methods\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9645 | '**************\n' |
| 9646 | '\n' |
| 9647 | 'Strings implement all of the common sequence operations, ' |
| 9648 | 'along with\n' |
| 9649 | 'the additional methods described below.\n' |
| 9650 | '\n' |
| 9651 | 'Strings also support two styles of string formatting, one ' |
| 9652 | 'providing a\n' |
| 9653 | 'large degree of flexibility and customization (see ' |
| 9654 | '"str.format()",\n' |
| 9655 | 'Format String Syntax and Custom String Formatting) and the ' |
| 9656 | 'other based\n' |
| 9657 | 'on C "printf" style formatting that handles a narrower ' |
| 9658 | 'range of types\n' |
| 9659 | 'and is slightly harder to use correctly, but is often ' |
| 9660 | 'faster for the\n' |
| 9661 | 'cases it can handle (printf-style String Formatting).\n' |
| 9662 | '\n' |
| 9663 | 'The Text Processing Services section of the standard ' |
| 9664 | 'library covers a\n' |
| 9665 | 'number of other modules that provide various text related ' |
| 9666 | 'utilities\n' |
| 9667 | '(including regular expression support in the "re" ' |
| 9668 | 'module).\n' |
| 9669 | '\n' |
| 9670 | 'str.capitalize()\n' |
| 9671 | '\n' |
| 9672 | ' Return a copy of the string with its first character ' |
| 9673 | 'capitalized\n' |
| 9674 | ' and the rest lowercased.\n' |
| 9675 | '\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 9676 | ' Changed in version 3.8: The first character is now put ' |
| 9677 | 'into\n' |
| 9678 | ' titlecase rather than uppercase. This means that ' |
| 9679 | 'characters like\n' |
| 9680 | ' digraphs will only have their first letter capitalized, ' |
| 9681 | 'instead of\n' |
| 9682 | ' the full character.\n' |
| 9683 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9684 | 'str.casefold()\n' |
| 9685 | '\n' |
| 9686 | ' Return a casefolded copy of the string. Casefolded ' |
| 9687 | 'strings may be\n' |
| 9688 | ' used for caseless matching.\n' |
| 9689 | '\n' |
| 9690 | ' Casefolding is similar to lowercasing but more ' |
| 9691 | 'aggressive because\n' |
| 9692 | ' it is intended to remove all case distinctions in a ' |
| 9693 | 'string. For\n' |
| 9694 | ' example, the German lowercase letter "\'ß\'" is ' |
| 9695 | 'equivalent to ""ss"".\n' |
| 9696 | ' Since it is already lowercase, "lower()" would do ' |
| 9697 | 'nothing to "\'ß\'";\n' |
| 9698 | ' "casefold()" converts it to ""ss"".\n' |
| 9699 | '\n' |
| 9700 | ' The casefolding algorithm is described in section 3.13 ' |
| 9701 | 'of the\n' |
| 9702 | ' Unicode Standard.\n' |
| 9703 | '\n' |
| 9704 | ' New in version 3.3.\n' |
| 9705 | '\n' |
| 9706 | 'str.center(width[, fillchar])\n' |
| 9707 | '\n' |
| 9708 | ' Return centered in a string of length *width*. Padding ' |
| 9709 | 'is done\n' |
| 9710 | ' using the specified *fillchar* (default is an ASCII ' |
| 9711 | 'space). The\n' |
| 9712 | ' original string is returned if *width* is less than or ' |
| 9713 | 'equal to\n' |
| 9714 | ' "len(s)".\n' |
| 9715 | '\n' |
| 9716 | 'str.count(sub[, start[, end]])\n' |
| 9717 | '\n' |
| 9718 | ' Return the number of non-overlapping occurrences of ' |
| 9719 | 'substring *sub*\n' |
| 9720 | ' in the range [*start*, *end*]. Optional arguments ' |
| 9721 | '*start* and\n' |
| 9722 | ' *end* are interpreted as in slice notation.\n' |
| 9723 | '\n' |
| 9724 | 'str.encode(encoding="utf-8", errors="strict")\n' |
| 9725 | '\n' |
| 9726 | ' Return an encoded version of the string as a bytes ' |
| 9727 | 'object. Default\n' |
| 9728 | ' encoding is "\'utf-8\'". *errors* may be given to set a ' |
| 9729 | 'different\n' |
| 9730 | ' error handling scheme. The default for *errors* is ' |
| 9731 | '"\'strict\'",\n' |
| 9732 | ' meaning that encoding errors raise a "UnicodeError". ' |
| 9733 | 'Other possible\n' |
| 9734 | ' values are "\'ignore\'", "\'replace\'", ' |
| 9735 | '"\'xmlcharrefreplace\'",\n' |
| 9736 | ' "\'backslashreplace\'" and any other name registered ' |
| 9737 | 'via\n' |
| 9738 | ' "codecs.register_error()", see section Error Handlers. ' |
| 9739 | 'For a list\n' |
| 9740 | ' of possible encodings, see section Standard Encodings.\n' |
| 9741 | '\n' |
| 9742 | ' Changed in version 3.1: Support for keyword arguments ' |
| 9743 | 'added.\n' |
| 9744 | '\n' |
| 9745 | 'str.endswith(suffix[, start[, end]])\n' |
| 9746 | '\n' |
| 9747 | ' Return "True" if the string ends with the specified ' |
| 9748 | '*suffix*,\n' |
| 9749 | ' otherwise return "False". *suffix* can also be a tuple ' |
| 9750 | 'of suffixes\n' |
| 9751 | ' to look for. With optional *start*, test beginning at ' |
| 9752 | 'that\n' |
| 9753 | ' position. With optional *end*, stop comparing at that ' |
| 9754 | 'position.\n' |
| 9755 | '\n' |
| 9756 | 'str.expandtabs(tabsize=8)\n' |
| 9757 | '\n' |
| 9758 | ' Return a copy of the string where all tab characters ' |
| 9759 | 'are replaced\n' |
| 9760 | ' by one or more spaces, depending on the current column ' |
| 9761 | 'and the\n' |
| 9762 | ' given tab size. Tab positions occur every *tabsize* ' |
| 9763 | 'characters\n' |
| 9764 | ' (default is 8, giving tab positions at columns 0, 8, 16 ' |
| 9765 | 'and so on).\n' |
| 9766 | ' To expand the string, the current column is set to zero ' |
| 9767 | 'and the\n' |
| 9768 | ' string is examined character by character. If the ' |
| 9769 | 'character is a\n' |
| 9770 | ' tab ("\\t"), one or more space characters are inserted ' |
| 9771 | 'in the result\n' |
| 9772 | ' until the current column is equal to the next tab ' |
| 9773 | 'position. (The\n' |
| 9774 | ' tab character itself is not copied.) If the character ' |
| 9775 | 'is a newline\n' |
| 9776 | ' ("\\n") or return ("\\r"), it is copied and the current ' |
| 9777 | 'column is\n' |
| 9778 | ' reset to zero. Any other character is copied unchanged ' |
| 9779 | 'and the\n' |
| 9780 | ' current column is incremented by one regardless of how ' |
| 9781 | 'the\n' |
| 9782 | ' character is represented when printed.\n' |
| 9783 | '\n' |
| 9784 | " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" |
| 9785 | " '01 012 0123 01234'\n" |
| 9786 | " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" |
| 9787 | " '01 012 0123 01234'\n" |
| 9788 | '\n' |
| 9789 | 'str.find(sub[, start[, end]])\n' |
| 9790 | '\n' |
| 9791 | ' Return the lowest index in the string where substring ' |
| 9792 | '*sub* is\n' |
| 9793 | ' found within the slice "s[start:end]". Optional ' |
| 9794 | 'arguments *start*\n' |
| 9795 | ' and *end* are interpreted as in slice notation. Return ' |
| 9796 | '"-1" if\n' |
| 9797 | ' *sub* is not found.\n' |
| 9798 | '\n' |
| 9799 | ' Note: The "find()" method should be used only if you ' |
| 9800 | 'need to know\n' |
| 9801 | ' the position of *sub*. To check if *sub* is a ' |
| 9802 | 'substring or not,\n' |
| 9803 | ' use the "in" operator:\n' |
| 9804 | '\n' |
| 9805 | " >>> 'Py' in 'Python'\n" |
| 9806 | ' True\n' |
| 9807 | '\n' |
| 9808 | 'str.format(*args, **kwargs)\n' |
| 9809 | '\n' |
| 9810 | ' Perform a string formatting operation. The string on ' |
| 9811 | 'which this\n' |
| 9812 | ' method is called can contain literal text or ' |
| 9813 | 'replacement fields\n' |
| 9814 | ' delimited by braces "{}". Each replacement field ' |
| 9815 | 'contains either\n' |
| 9816 | ' the numeric index of a positional argument, or the name ' |
| 9817 | 'of a\n' |
| 9818 | ' keyword argument. Returns a copy of the string where ' |
| 9819 | 'each\n' |
| 9820 | ' replacement field is replaced with the string value of ' |
| 9821 | 'the\n' |
| 9822 | ' corresponding argument.\n' |
| 9823 | '\n' |
| 9824 | ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' |
| 9825 | " 'The sum of 1 + 2 is 3'\n" |
| 9826 | '\n' |
| 9827 | ' See Format String Syntax for a description of the ' |
| 9828 | 'various\n' |
| 9829 | ' formatting options that can be specified in format ' |
| 9830 | 'strings.\n' |
| 9831 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9832 | ' Note: When formatting a number ("int", "float", ' |
| 9833 | '"complex",\n' |
| 9834 | ' "decimal.Decimal" and subclasses) with the "n" type ' |
| 9835 | '(ex:\n' |
| 9836 | ' "\'{:n}\'.format(1234)"), the function temporarily ' |
| 9837 | 'sets the\n' |
| 9838 | ' "LC_CTYPE" locale to the "LC_NUMERIC" locale to ' |
| 9839 | 'decode\n' |
| 9840 | ' "decimal_point" and "thousands_sep" fields of ' |
| 9841 | '"localeconv()" if\n' |
| 9842 | ' they are non-ASCII or longer than 1 byte, and the ' |
| 9843 | '"LC_NUMERIC"\n' |
| 9844 | ' locale is different than the "LC_CTYPE" locale. This ' |
| 9845 | 'temporary\n' |
| 9846 | ' change affects other threads.\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 9847 | '\n' |
| 9848 | ' Changed in version 3.7: When formatting a number with ' |
| 9849 | 'the "n" type,\n' |
| 9850 | ' the function sets temporarily the "LC_CTYPE" locale to ' |
| 9851 | 'the\n' |
| 9852 | ' "LC_NUMERIC" locale in some cases.\n' |
| 9853 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9854 | 'str.format_map(mapping)\n' |
| 9855 | '\n' |
| 9856 | ' Similar to "str.format(**mapping)", except that ' |
| 9857 | '"mapping" is used\n' |
| 9858 | ' directly and not copied to a "dict". This is useful if ' |
| 9859 | 'for example\n' |
| 9860 | ' "mapping" is a dict subclass:\n' |
| 9861 | '\n' |
| 9862 | ' >>> class Default(dict):\n' |
| 9863 | ' ... def __missing__(self, key):\n' |
| 9864 | ' ... return key\n' |
| 9865 | ' ...\n' |
| 9866 | " >>> '{name} was born in " |
| 9867 | "{country}'.format_map(Default(name='Guido'))\n" |
| 9868 | " 'Guido was born in country'\n" |
| 9869 | '\n' |
| 9870 | ' New in version 3.2.\n' |
| 9871 | '\n' |
| 9872 | 'str.index(sub[, start[, end]])\n' |
| 9873 | '\n' |
| 9874 | ' Like "find()", but raise "ValueError" when the ' |
| 9875 | 'substring is not\n' |
| 9876 | ' found.\n' |
| 9877 | '\n' |
| 9878 | 'str.isalnum()\n' |
| 9879 | '\n' |
| 9880 | ' Return true if all characters in the string are ' |
| 9881 | 'alphanumeric and\n' |
| 9882 | ' there is at least one character, false otherwise. A ' |
| 9883 | 'character "c"\n' |
| 9884 | ' is alphanumeric if one of the following returns ' |
| 9885 | '"True":\n' |
| 9886 | ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' |
| 9887 | '"c.isnumeric()".\n' |
| 9888 | '\n' |
| 9889 | 'str.isalpha()\n' |
| 9890 | '\n' |
| 9891 | ' Return true if all characters in the string are ' |
| 9892 | 'alphabetic and\n' |
| 9893 | ' there is at least one character, false otherwise. ' |
| 9894 | 'Alphabetic\n' |
| 9895 | ' characters are those characters defined in the Unicode ' |
| 9896 | 'character\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9897 | ' database as “Letter”, i.e., those with general category ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9898 | 'property\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9899 | ' being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9900 | 'that this is\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9901 | ' different from the “Alphabetic” property defined in the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9902 | 'Unicode\n' |
| 9903 | ' Standard.\n' |
| 9904 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 9905 | 'str.isascii()\n' |
| 9906 | '\n' |
| 9907 | ' Return true if the string is empty or all characters in ' |
| 9908 | 'the string\n' |
| 9909 | ' are ASCII, false otherwise. ASCII characters have code ' |
| 9910 | 'points in\n' |
| 9911 | ' the range U+0000-U+007F.\n' |
| 9912 | '\n' |
| 9913 | ' New in version 3.7.\n' |
| 9914 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9915 | 'str.isdecimal()\n' |
| 9916 | '\n' |
| 9917 | ' Return true if all characters in the string are decimal ' |
| 9918 | 'characters\n' |
| 9919 | ' and there is at least one character, false otherwise. ' |
| 9920 | 'Decimal\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9921 | ' characters are those that can be used to form numbers ' |
| 9922 | 'in base 10,\n' |
| 9923 | ' e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a ' |
| 9924 | 'decimal character\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9925 | ' is a character in the Unicode General Category “Nd”.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9926 | '\n' |
| 9927 | 'str.isdigit()\n' |
| 9928 | '\n' |
| 9929 | ' Return true if all characters in the string are digits ' |
| 9930 | 'and there is\n' |
| 9931 | ' at least one character, false otherwise. Digits ' |
| 9932 | 'include decimal\n' |
| 9933 | ' characters and digits that need special handling, such ' |
| 9934 | 'as the\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9935 | ' compatibility superscript digits. This covers digits ' |
| 9936 | 'which cannot\n' |
| 9937 | ' be used to form numbers in base 10, like the Kharosthi ' |
| 9938 | 'numbers.\n' |
| 9939 | ' Formally, a digit is a character that has the property ' |
| 9940 | 'value\n' |
| 9941 | ' Numeric_Type=Digit or Numeric_Type=Decimal.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9942 | '\n' |
| 9943 | 'str.isidentifier()\n' |
| 9944 | '\n' |
| 9945 | ' Return true if the string is a valid identifier ' |
| 9946 | 'according to the\n' |
| 9947 | ' language definition, section Identifiers and keywords.\n' |
| 9948 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9949 | ' Call "keyword.iskeyword()" to test whether string "s" ' |
| 9950 | 'is a reserved\n' |
| 9951 | ' identifier, such as "def" and "class".\n' |
| 9952 | '\n' |
| 9953 | ' Example:\n' |
| 9954 | '\n' |
| 9955 | ' >>> from keyword import iskeyword\n' |
| 9956 | '\n' |
| 9957 | " >>> 'hello'.isidentifier(), iskeyword('hello')\n" |
| 9958 | ' True, False\n' |
| 9959 | " >>> 'def'.isidentifier(), iskeyword('def')\n" |
| 9960 | ' True, True\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9961 | '\n' |
| 9962 | 'str.islower()\n' |
| 9963 | '\n' |
| 9964 | ' Return true if all cased characters [4] in the string ' |
| 9965 | 'are lowercase\n' |
| 9966 | ' and there is at least one cased character, false ' |
| 9967 | 'otherwise.\n' |
| 9968 | '\n' |
| 9969 | 'str.isnumeric()\n' |
| 9970 | '\n' |
| 9971 | ' Return true if all characters in the string are numeric ' |
| 9972 | 'characters,\n' |
| 9973 | ' and there is at least one character, false otherwise. ' |
| 9974 | 'Numeric\n' |
| 9975 | ' characters include digit characters, and all characters ' |
| 9976 | 'that have\n' |
| 9977 | ' the Unicode numeric value property, e.g. U+2155, VULGAR ' |
| 9978 | 'FRACTION\n' |
| 9979 | ' ONE FIFTH. Formally, numeric characters are those with ' |
| 9980 | 'the\n' |
| 9981 | ' property value Numeric_Type=Digit, Numeric_Type=Decimal ' |
| 9982 | 'or\n' |
| 9983 | ' Numeric_Type=Numeric.\n' |
| 9984 | '\n' |
| 9985 | 'str.isprintable()\n' |
| 9986 | '\n' |
| 9987 | ' Return true if all characters in the string are ' |
| 9988 | 'printable or the\n' |
| 9989 | ' string is empty, false otherwise. Nonprintable ' |
| 9990 | 'characters are\n' |
| 9991 | ' those characters defined in the Unicode character ' |
| 9992 | 'database as\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 9993 | ' “Other” or “Separator”, excepting the ASCII space ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9994 | '(0x20) which is\n' |
| 9995 | ' considered printable. (Note that printable characters ' |
| 9996 | 'in this\n' |
| 9997 | ' context are those which should not be escaped when ' |
| 9998 | '"repr()" is\n' |
| 9999 | ' invoked on a string. It has no bearing on the handling ' |
| 10000 | 'of strings\n' |
| 10001 | ' written to "sys.stdout" or "sys.stderr".)\n' |
| 10002 | '\n' |
| 10003 | 'str.isspace()\n' |
| 10004 | '\n' |
| 10005 | ' Return true if there are only whitespace characters in ' |
| 10006 | 'the string\n' |
| 10007 | ' and there is at least one character, false otherwise. ' |
| 10008 | 'Whitespace\n' |
| 10009 | ' characters are those characters defined in the Unicode ' |
| 10010 | 'character\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10011 | ' database as “Other” or “Separator” and those with ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10012 | 'bidirectional\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10013 | ' property being one of “WS”, “B”, or “S”.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10014 | '\n' |
| 10015 | 'str.istitle()\n' |
| 10016 | '\n' |
| 10017 | ' Return true if the string is a titlecased string and ' |
| 10018 | 'there is at\n' |
| 10019 | ' least one character, for example uppercase characters ' |
| 10020 | 'may only\n' |
| 10021 | ' follow uncased characters and lowercase characters only ' |
| 10022 | 'cased ones.\n' |
| 10023 | ' Return false otherwise.\n' |
| 10024 | '\n' |
| 10025 | 'str.isupper()\n' |
| 10026 | '\n' |
| 10027 | ' Return true if all cased characters [4] in the string ' |
| 10028 | 'are uppercase\n' |
| 10029 | ' and there is at least one cased character, false ' |
| 10030 | 'otherwise.\n' |
| 10031 | '\n' |
| 10032 | 'str.join(iterable)\n' |
| 10033 | '\n' |
| 10034 | ' Return a string which is the concatenation of the ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10035 | 'strings in\n' |
| 10036 | ' *iterable*. A "TypeError" will be raised if there are ' |
| 10037 | 'any non-\n' |
| 10038 | ' string values in *iterable*, including "bytes" ' |
| 10039 | 'objects. The\n' |
| 10040 | ' separator between elements is the string providing this ' |
| 10041 | 'method.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10042 | '\n' |
| 10043 | 'str.ljust(width[, fillchar])\n' |
| 10044 | '\n' |
| 10045 | ' Return the string left justified in a string of length ' |
| 10046 | '*width*.\n' |
| 10047 | ' Padding is done using the specified *fillchar* (default ' |
| 10048 | 'is an ASCII\n' |
| 10049 | ' space). The original string is returned if *width* is ' |
| 10050 | 'less than or\n' |
| 10051 | ' equal to "len(s)".\n' |
| 10052 | '\n' |
| 10053 | 'str.lower()\n' |
| 10054 | '\n' |
| 10055 | ' Return a copy of the string with all the cased ' |
| 10056 | 'characters [4]\n' |
| 10057 | ' converted to lowercase.\n' |
| 10058 | '\n' |
| 10059 | ' The lowercasing algorithm used is described in section ' |
| 10060 | '3.13 of the\n' |
| 10061 | ' Unicode Standard.\n' |
| 10062 | '\n' |
| 10063 | 'str.lstrip([chars])\n' |
| 10064 | '\n' |
| 10065 | ' Return a copy of the string with leading characters ' |
| 10066 | 'removed. The\n' |
| 10067 | ' *chars* argument is a string specifying the set of ' |
| 10068 | 'characters to be\n' |
| 10069 | ' removed. If omitted or "None", the *chars* argument ' |
| 10070 | 'defaults to\n' |
| 10071 | ' removing whitespace. The *chars* argument is not a ' |
| 10072 | 'prefix; rather,\n' |
| 10073 | ' all combinations of its values are stripped:\n' |
| 10074 | '\n' |
| 10075 | " >>> ' spacious '.lstrip()\n" |
| 10076 | " 'spacious '\n" |
| 10077 | " >>> 'www.example.com'.lstrip('cmowz.')\n" |
| 10078 | " 'example.com'\n" |
| 10079 | '\n' |
| 10080 | 'static str.maketrans(x[, y[, z]])\n' |
| 10081 | '\n' |
| 10082 | ' This static method returns a translation table usable ' |
| 10083 | 'for\n' |
| 10084 | ' "str.translate()".\n' |
| 10085 | '\n' |
| 10086 | ' If there is only one argument, it must be a dictionary ' |
| 10087 | 'mapping\n' |
| 10088 | ' Unicode ordinals (integers) or characters (strings of ' |
| 10089 | 'length 1) to\n' |
| 10090 | ' Unicode ordinals, strings (of arbitrary lengths) or ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10091 | '"None".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10092 | ' Character keys will then be converted to ordinals.\n' |
| 10093 | '\n' |
| 10094 | ' If there are two arguments, they must be strings of ' |
| 10095 | 'equal length,\n' |
| 10096 | ' and in the resulting dictionary, each character in x ' |
| 10097 | 'will be mapped\n' |
| 10098 | ' to the character at the same position in y. If there ' |
| 10099 | 'is a third\n' |
| 10100 | ' argument, it must be a string, whose characters will be ' |
| 10101 | 'mapped to\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10102 | ' "None" in the result.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10103 | '\n' |
| 10104 | 'str.partition(sep)\n' |
| 10105 | '\n' |
| 10106 | ' Split the string at the first occurrence of *sep*, and ' |
| 10107 | 'return a\n' |
| 10108 | ' 3-tuple containing the part before the separator, the ' |
| 10109 | 'separator\n' |
| 10110 | ' itself, and the part after the separator. If the ' |
| 10111 | 'separator is not\n' |
| 10112 | ' found, return a 3-tuple containing the string itself, ' |
| 10113 | 'followed by\n' |
| 10114 | ' two empty strings.\n' |
| 10115 | '\n' |
| 10116 | 'str.replace(old, new[, count])\n' |
| 10117 | '\n' |
| 10118 | ' Return a copy of the string with all occurrences of ' |
| 10119 | 'substring *old*\n' |
| 10120 | ' replaced by *new*. If the optional argument *count* is ' |
| 10121 | 'given, only\n' |
| 10122 | ' the first *count* occurrences are replaced.\n' |
| 10123 | '\n' |
| 10124 | 'str.rfind(sub[, start[, end]])\n' |
| 10125 | '\n' |
| 10126 | ' Return the highest index in the string where substring ' |
| 10127 | '*sub* is\n' |
| 10128 | ' found, such that *sub* is contained within ' |
| 10129 | '"s[start:end]".\n' |
| 10130 | ' Optional arguments *start* and *end* are interpreted as ' |
| 10131 | 'in slice\n' |
| 10132 | ' notation. Return "-1" on failure.\n' |
| 10133 | '\n' |
| 10134 | 'str.rindex(sub[, start[, end]])\n' |
| 10135 | '\n' |
| 10136 | ' Like "rfind()" but raises "ValueError" when the ' |
| 10137 | 'substring *sub* is\n' |
| 10138 | ' not found.\n' |
| 10139 | '\n' |
| 10140 | 'str.rjust(width[, fillchar])\n' |
| 10141 | '\n' |
| 10142 | ' Return the string right justified in a string of length ' |
| 10143 | '*width*.\n' |
| 10144 | ' Padding is done using the specified *fillchar* (default ' |
| 10145 | 'is an ASCII\n' |
| 10146 | ' space). The original string is returned if *width* is ' |
| 10147 | 'less than or\n' |
| 10148 | ' equal to "len(s)".\n' |
| 10149 | '\n' |
| 10150 | 'str.rpartition(sep)\n' |
| 10151 | '\n' |
| 10152 | ' Split the string at the last occurrence of *sep*, and ' |
| 10153 | 'return a\n' |
| 10154 | ' 3-tuple containing the part before the separator, the ' |
| 10155 | 'separator\n' |
| 10156 | ' itself, and the part after the separator. If the ' |
| 10157 | 'separator is not\n' |
| 10158 | ' found, return a 3-tuple containing two empty strings, ' |
| 10159 | 'followed by\n' |
| 10160 | ' the string itself.\n' |
| 10161 | '\n' |
| 10162 | 'str.rsplit(sep=None, maxsplit=-1)\n' |
| 10163 | '\n' |
| 10164 | ' Return a list of the words in the string, using *sep* ' |
| 10165 | 'as the\n' |
| 10166 | ' delimiter string. If *maxsplit* is given, at most ' |
| 10167 | '*maxsplit* splits\n' |
| 10168 | ' are done, the *rightmost* ones. If *sep* is not ' |
| 10169 | 'specified or\n' |
| 10170 | ' "None", any whitespace string is a separator. Except ' |
| 10171 | 'for splitting\n' |
| 10172 | ' from the right, "rsplit()" behaves like "split()" which ' |
| 10173 | 'is\n' |
| 10174 | ' described in detail below.\n' |
| 10175 | '\n' |
| 10176 | 'str.rstrip([chars])\n' |
| 10177 | '\n' |
| 10178 | ' Return a copy of the string with trailing characters ' |
| 10179 | 'removed. The\n' |
| 10180 | ' *chars* argument is a string specifying the set of ' |
| 10181 | 'characters to be\n' |
| 10182 | ' removed. If omitted or "None", the *chars* argument ' |
| 10183 | 'defaults to\n' |
| 10184 | ' removing whitespace. The *chars* argument is not a ' |
| 10185 | 'suffix; rather,\n' |
| 10186 | ' all combinations of its values are stripped:\n' |
| 10187 | '\n' |
| 10188 | " >>> ' spacious '.rstrip()\n" |
| 10189 | " ' spacious'\n" |
| 10190 | " >>> 'mississippi'.rstrip('ipz')\n" |
| 10191 | " 'mississ'\n" |
| 10192 | '\n' |
| 10193 | 'str.split(sep=None, maxsplit=-1)\n' |
| 10194 | '\n' |
| 10195 | ' Return a list of the words in the string, using *sep* ' |
| 10196 | 'as the\n' |
| 10197 | ' delimiter string. If *maxsplit* is given, at most ' |
| 10198 | '*maxsplit*\n' |
| 10199 | ' splits are done (thus, the list will have at most ' |
| 10200 | '"maxsplit+1"\n' |
| 10201 | ' elements). If *maxsplit* is not specified or "-1", ' |
| 10202 | 'then there is\n' |
| 10203 | ' no limit on the number of splits (all possible splits ' |
| 10204 | 'are made).\n' |
| 10205 | '\n' |
| 10206 | ' If *sep* is given, consecutive delimiters are not ' |
| 10207 | 'grouped together\n' |
| 10208 | ' and are deemed to delimit empty strings (for example,\n' |
| 10209 | ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', ' |
| 10210 | '\'2\']"). The *sep* argument\n' |
| 10211 | ' may consist of multiple characters (for example,\n' |
| 10212 | ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', ' |
| 10213 | '\'3\']"). Splitting an\n' |
| 10214 | ' empty string with a specified separator returns ' |
| 10215 | '"[\'\']".\n' |
| 10216 | '\n' |
| 10217 | ' For example:\n' |
| 10218 | '\n' |
| 10219 | " >>> '1,2,3'.split(',')\n" |
| 10220 | " ['1', '2', '3']\n" |
| 10221 | " >>> '1,2,3'.split(',', maxsplit=1)\n" |
| 10222 | " ['1', '2,3']\n" |
| 10223 | " >>> '1,2,,3,'.split(',')\n" |
| 10224 | " ['1', '2', '', '3', '']\n" |
| 10225 | '\n' |
| 10226 | ' If *sep* is not specified or is "None", a different ' |
| 10227 | 'splitting\n' |
| 10228 | ' algorithm is applied: runs of consecutive whitespace ' |
| 10229 | 'are regarded\n' |
| 10230 | ' as a single separator, and the result will contain no ' |
| 10231 | 'empty strings\n' |
| 10232 | ' at the start or end if the string has leading or ' |
| 10233 | 'trailing\n' |
| 10234 | ' whitespace. Consequently, splitting an empty string or ' |
| 10235 | 'a string\n' |
| 10236 | ' consisting of just whitespace with a "None" separator ' |
| 10237 | 'returns "[]".\n' |
| 10238 | '\n' |
| 10239 | ' For example:\n' |
| 10240 | '\n' |
| 10241 | " >>> '1 2 3'.split()\n" |
| 10242 | " ['1', '2', '3']\n" |
| 10243 | " >>> '1 2 3'.split(maxsplit=1)\n" |
| 10244 | " ['1', '2 3']\n" |
| 10245 | " >>> ' 1 2 3 '.split()\n" |
| 10246 | " ['1', '2', '3']\n" |
| 10247 | '\n' |
| 10248 | 'str.splitlines([keepends])\n' |
| 10249 | '\n' |
| 10250 | ' Return a list of the lines in the string, breaking at ' |
| 10251 | 'line\n' |
| 10252 | ' boundaries. Line breaks are not included in the ' |
| 10253 | 'resulting list\n' |
| 10254 | ' unless *keepends* is given and true.\n' |
| 10255 | '\n' |
| 10256 | ' This method splits on the following line boundaries. ' |
| 10257 | 'In\n' |
| 10258 | ' particular, the boundaries are a superset of *universal ' |
| 10259 | 'newlines*.\n' |
| 10260 | '\n' |
| 10261 | ' ' |
| 10262 | '+-------------------------+-------------------------------+\n' |
| 10263 | ' | Representation | ' |
| 10264 | 'Description |\n' |
| 10265 | ' ' |
| 10266 | '+=========================+===============================+\n' |
| 10267 | ' | "\\n" | Line ' |
| 10268 | 'Feed |\n' |
| 10269 | ' ' |
| 10270 | '+-------------------------+-------------------------------+\n' |
| 10271 | ' | "\\r" | Carriage ' |
| 10272 | 'Return |\n' |
| 10273 | ' ' |
| 10274 | '+-------------------------+-------------------------------+\n' |
| 10275 | ' | "\\r\\n" | Carriage Return + Line ' |
| 10276 | 'Feed |\n' |
| 10277 | ' ' |
| 10278 | '+-------------------------+-------------------------------+\n' |
| 10279 | ' | "\\v" or "\\x0b" | Line ' |
| 10280 | 'Tabulation |\n' |
| 10281 | ' ' |
| 10282 | '+-------------------------+-------------------------------+\n' |
| 10283 | ' | "\\f" or "\\x0c" | Form ' |
| 10284 | 'Feed |\n' |
| 10285 | ' ' |
| 10286 | '+-------------------------+-------------------------------+\n' |
| 10287 | ' | "\\x1c" | File ' |
| 10288 | 'Separator |\n' |
| 10289 | ' ' |
| 10290 | '+-------------------------+-------------------------------+\n' |
| 10291 | ' | "\\x1d" | Group ' |
| 10292 | 'Separator |\n' |
| 10293 | ' ' |
| 10294 | '+-------------------------+-------------------------------+\n' |
| 10295 | ' | "\\x1e" | Record ' |
| 10296 | 'Separator |\n' |
| 10297 | ' ' |
| 10298 | '+-------------------------+-------------------------------+\n' |
| 10299 | ' | "\\x85" | Next Line (C1 Control ' |
| 10300 | 'Code) |\n' |
| 10301 | ' ' |
| 10302 | '+-------------------------+-------------------------------+\n' |
| 10303 | ' | "\\u2028" | Line ' |
| 10304 | 'Separator |\n' |
| 10305 | ' ' |
| 10306 | '+-------------------------+-------------------------------+\n' |
| 10307 | ' | "\\u2029" | Paragraph ' |
| 10308 | 'Separator |\n' |
| 10309 | ' ' |
| 10310 | '+-------------------------+-------------------------------+\n' |
| 10311 | '\n' |
| 10312 | ' Changed in version 3.2: "\\v" and "\\f" added to list ' |
| 10313 | 'of line\n' |
| 10314 | ' boundaries.\n' |
| 10315 | '\n' |
| 10316 | ' For example:\n' |
| 10317 | '\n' |
| 10318 | " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" |
| 10319 | " ['ab c', '', 'de fg', 'kl']\n" |
| 10320 | " >>> 'ab c\\n\\nde " |
| 10321 | "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" |
| 10322 | " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" |
| 10323 | '\n' |
| 10324 | ' Unlike "split()" when a delimiter string *sep* is ' |
| 10325 | 'given, this\n' |
| 10326 | ' method returns an empty list for the empty string, and ' |
| 10327 | 'a terminal\n' |
| 10328 | ' line break does not result in an extra line:\n' |
| 10329 | '\n' |
| 10330 | ' >>> "".splitlines()\n' |
| 10331 | ' []\n' |
| 10332 | ' >>> "One line\\n".splitlines()\n' |
| 10333 | " ['One line']\n" |
| 10334 | '\n' |
| 10335 | ' For comparison, "split(\'\\n\')" gives:\n' |
| 10336 | '\n' |
| 10337 | " >>> ''.split('\\n')\n" |
| 10338 | " ['']\n" |
| 10339 | " >>> 'Two lines\\n'.split('\\n')\n" |
| 10340 | " ['Two lines', '']\n" |
| 10341 | '\n' |
| 10342 | 'str.startswith(prefix[, start[, end]])\n' |
| 10343 | '\n' |
| 10344 | ' Return "True" if string starts with the *prefix*, ' |
| 10345 | 'otherwise return\n' |
| 10346 | ' "False". *prefix* can also be a tuple of prefixes to ' |
| 10347 | 'look for.\n' |
| 10348 | ' With optional *start*, test string beginning at that ' |
| 10349 | 'position.\n' |
| 10350 | ' With optional *end*, stop comparing string at that ' |
| 10351 | 'position.\n' |
| 10352 | '\n' |
| 10353 | 'str.strip([chars])\n' |
| 10354 | '\n' |
| 10355 | ' Return a copy of the string with the leading and ' |
| 10356 | 'trailing\n' |
| 10357 | ' characters removed. The *chars* argument is a string ' |
| 10358 | 'specifying the\n' |
| 10359 | ' set of characters to be removed. If omitted or "None", ' |
| 10360 | 'the *chars*\n' |
| 10361 | ' argument defaults to removing whitespace. The *chars* ' |
| 10362 | 'argument is\n' |
| 10363 | ' not a prefix or suffix; rather, all combinations of its ' |
| 10364 | 'values are\n' |
| 10365 | ' stripped:\n' |
| 10366 | '\n' |
| 10367 | " >>> ' spacious '.strip()\n" |
| 10368 | " 'spacious'\n" |
| 10369 | " >>> 'www.example.com'.strip('cmowz.')\n" |
| 10370 | " 'example'\n" |
| 10371 | '\n' |
| 10372 | ' The outermost leading and trailing *chars* argument ' |
| 10373 | 'values are\n' |
| 10374 | ' stripped from the string. Characters are removed from ' |
| 10375 | 'the leading\n' |
| 10376 | ' end until reaching a string character that is not ' |
| 10377 | 'contained in the\n' |
| 10378 | ' set of characters in *chars*. A similar action takes ' |
| 10379 | 'place on the\n' |
| 10380 | ' trailing end. For example:\n' |
| 10381 | '\n' |
| 10382 | " >>> comment_string = '#....... Section 3.2.1 Issue " |
| 10383 | "#32 .......'\n" |
| 10384 | " >>> comment_string.strip('.#! ')\n" |
| 10385 | " 'Section 3.2.1 Issue #32'\n" |
| 10386 | '\n' |
| 10387 | 'str.swapcase()\n' |
| 10388 | '\n' |
| 10389 | ' Return a copy of the string with uppercase characters ' |
| 10390 | 'converted to\n' |
| 10391 | ' lowercase and vice versa. Note that it is not ' |
| 10392 | 'necessarily true that\n' |
| 10393 | ' "s.swapcase().swapcase() == s".\n' |
| 10394 | '\n' |
| 10395 | 'str.title()\n' |
| 10396 | '\n' |
| 10397 | ' Return a titlecased version of the string where words ' |
| 10398 | 'start with an\n' |
| 10399 | ' uppercase character and the remaining characters are ' |
| 10400 | 'lowercase.\n' |
| 10401 | '\n' |
| 10402 | ' For example:\n' |
| 10403 | '\n' |
| 10404 | " >>> 'Hello world'.title()\n" |
| 10405 | " 'Hello World'\n" |
| 10406 | '\n' |
| 10407 | ' The algorithm uses a simple language-independent ' |
| 10408 | 'definition of a\n' |
| 10409 | ' word as groups of consecutive letters. The definition ' |
| 10410 | 'works in\n' |
| 10411 | ' many contexts but it means that apostrophes in ' |
| 10412 | 'contractions and\n' |
| 10413 | ' possessives form word boundaries, which may not be the ' |
| 10414 | 'desired\n' |
| 10415 | ' result:\n' |
| 10416 | '\n' |
| 10417 | ' >>> "they\'re bill\'s friends from the UK".title()\n' |
| 10418 | ' "They\'Re Bill\'S Friends From The Uk"\n' |
| 10419 | '\n' |
| 10420 | ' A workaround for apostrophes can be constructed using ' |
| 10421 | 'regular\n' |
| 10422 | ' expressions:\n' |
| 10423 | '\n' |
| 10424 | ' >>> import re\n' |
| 10425 | ' >>> def titlecase(s):\n' |
| 10426 | ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' |
| 10427 | ' ... lambda mo: ' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 10428 | 'mo.group(0).capitalize(),\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10429 | ' ... s)\n' |
| 10430 | ' ...\n' |
| 10431 | ' >>> titlecase("they\'re bill\'s friends.")\n' |
| 10432 | ' "They\'re Bill\'s Friends."\n' |
| 10433 | '\n' |
| 10434 | 'str.translate(table)\n' |
| 10435 | '\n' |
| 10436 | ' Return a copy of the string in which each character has ' |
| 10437 | 'been mapped\n' |
| 10438 | ' through the given translation table. The table must be ' |
| 10439 | 'an object\n' |
| 10440 | ' that implements indexing via "__getitem__()", typically ' |
| 10441 | 'a *mapping*\n' |
| 10442 | ' or *sequence*. When indexed by a Unicode ordinal (an ' |
| 10443 | 'integer), the\n' |
| 10444 | ' table object can do any of the following: return a ' |
| 10445 | 'Unicode ordinal\n' |
| 10446 | ' or a string, to map the character to one or more other ' |
| 10447 | 'characters;\n' |
| 10448 | ' return "None", to delete the character from the return ' |
| 10449 | 'string; or\n' |
| 10450 | ' raise a "LookupError" exception, to map the character ' |
| 10451 | 'to itself.\n' |
| 10452 | '\n' |
| 10453 | ' You can use "str.maketrans()" to create a translation ' |
| 10454 | 'map from\n' |
| 10455 | ' character-to-character mappings in different formats.\n' |
| 10456 | '\n' |
| 10457 | ' See also the "codecs" module for a more flexible ' |
| 10458 | 'approach to custom\n' |
| 10459 | ' character mappings.\n' |
| 10460 | '\n' |
| 10461 | 'str.upper()\n' |
| 10462 | '\n' |
| 10463 | ' Return a copy of the string with all the cased ' |
| 10464 | 'characters [4]\n' |
| 10465 | ' converted to uppercase. Note that ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10466 | '"s.upper().isupper()" might be\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10467 | ' "False" if "s" contains uncased characters or if the ' |
| 10468 | 'Unicode\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10469 | ' category of the resulting character(s) is not “Lu” ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10470 | '(Letter,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10471 | ' uppercase), but e.g. “Lt” (Letter, titlecase).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10472 | '\n' |
| 10473 | ' The uppercasing algorithm used is described in section ' |
| 10474 | '3.13 of the\n' |
| 10475 | ' Unicode Standard.\n' |
| 10476 | '\n' |
| 10477 | 'str.zfill(width)\n' |
| 10478 | '\n' |
| 10479 | ' Return a copy of the string left filled with ASCII ' |
| 10480 | '"\'0\'" digits to\n' |
| 10481 | ' make a string of length *width*. A leading sign prefix\n' |
| 10482 | ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' |
| 10483 | '*after* the sign\n' |
| 10484 | ' character rather than before. The original string is ' |
| 10485 | 'returned if\n' |
| 10486 | ' *width* is less than or equal to "len(s)".\n' |
| 10487 | '\n' |
| 10488 | ' For example:\n' |
| 10489 | '\n' |
| 10490 | ' >>> "42".zfill(5)\n' |
| 10491 | " '00042'\n" |
| 10492 | ' >>> "-42".zfill(5)\n' |
| 10493 | " '-0042'\n", |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10494 | 'strings': 'String and Bytes literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10495 | '*************************\n' |
| 10496 | '\n' |
| 10497 | 'String literals are described by the following lexical ' |
| 10498 | 'definitions:\n' |
| 10499 | '\n' |
| 10500 | ' stringliteral ::= [stringprefix](shortstring | longstring)\n' |
| 10501 | ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n' |
| 10502 | ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | ' |
| 10503 | '"Rf" | "RF"\n' |
| 10504 | ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' |
| 10505 | 'shortstringitem* \'"\'\n' |
| 10506 | ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' |
| 10507 | '\'"""\' longstringitem* \'"""\'\n' |
| 10508 | ' shortstringitem ::= shortstringchar | stringescapeseq\n' |
| 10509 | ' longstringitem ::= longstringchar | stringescapeseq\n' |
| 10510 | ' shortstringchar ::= <any source character except "\\" or ' |
| 10511 | 'newline or the quote>\n' |
| 10512 | ' longstringchar ::= <any source character except "\\">\n' |
| 10513 | ' stringescapeseq ::= "\\" <any source character>\n' |
| 10514 | '\n' |
| 10515 | ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' |
| 10516 | ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' |
| 10517 | '"rb" | "rB" | "Rb" | "RB"\n' |
| 10518 | ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' |
| 10519 | 'shortbytesitem* \'"\'\n' |
| 10520 | ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' ' |
| 10521 | 'longbytesitem* \'"""\'\n' |
| 10522 | ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' |
| 10523 | ' longbytesitem ::= longbyteschar | bytesescapeseq\n' |
| 10524 | ' shortbyteschar ::= <any ASCII character except "\\" or newline ' |
| 10525 | 'or the quote>\n' |
| 10526 | ' longbyteschar ::= <any ASCII character except "\\">\n' |
| 10527 | ' bytesescapeseq ::= "\\" <any ASCII character>\n' |
| 10528 | '\n' |
| 10529 | 'One syntactic restriction not indicated by these productions is ' |
| 10530 | 'that\n' |
| 10531 | 'whitespace is not allowed between the "stringprefix" or ' |
| 10532 | '"bytesprefix"\n' |
| 10533 | 'and the rest of the literal. The source character set is defined ' |
| 10534 | 'by\n' |
| 10535 | 'the encoding declaration; it is UTF-8 if no encoding declaration ' |
| 10536 | 'is\n' |
| 10537 | 'given in the source file; see section Encoding declarations.\n' |
| 10538 | '\n' |
| 10539 | 'In plain English: Both types of literals can be enclosed in ' |
| 10540 | 'matching\n' |
| 10541 | 'single quotes ("\'") or double quotes ("""). They can also be ' |
| 10542 | 'enclosed\n' |
| 10543 | 'in matching groups of three single or double quotes (these are\n' |
| 10544 | 'generally referred to as *triple-quoted strings*). The ' |
| 10545 | 'backslash\n' |
| 10546 | '("\\") character is used to escape characters that otherwise have ' |
| 10547 | 'a\n' |
| 10548 | 'special meaning, such as newline, backslash itself, or the quote\n' |
| 10549 | 'character.\n' |
| 10550 | '\n' |
| 10551 | 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they ' |
| 10552 | 'produce\n' |
| 10553 | 'an instance of the "bytes" type instead of the "str" type. They ' |
| 10554 | 'may\n' |
| 10555 | 'only contain ASCII characters; bytes with a numeric value of 128 ' |
| 10556 | 'or\n' |
| 10557 | 'greater must be expressed with escapes.\n' |
| 10558 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10559 | 'Both string and bytes literals may optionally be prefixed with a\n' |
| 10560 | 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* ' |
| 10561 | 'and treat\n' |
| 10562 | 'backslashes as literal characters. As a result, in string ' |
| 10563 | 'literals,\n' |
| 10564 | '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' |
| 10565 | 'specially.\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10566 | 'Given that Python 2.x’s raw unicode literals behave differently ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10567 | 'than\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10568 | 'Python 3.x’s the "\'ur\'" syntax is not supported.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10569 | '\n' |
| 10570 | 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has ' |
| 10571 | 'been\n' |
| 10572 | 'added as a synonym of "\'br\'".\n' |
| 10573 | '\n' |
| 10574 | 'New in version 3.3: Support for the unicode legacy literal\n' |
| 10575 | '("u\'value\'") was reintroduced to simplify the maintenance of ' |
| 10576 | 'dual\n' |
| 10577 | 'Python 2.x and 3.x codebases. See **PEP 414** for more ' |
| 10578 | 'information.\n' |
| 10579 | '\n' |
| 10580 | 'A string literal with "\'f\'" or "\'F\'" in its prefix is a ' |
| 10581 | '*formatted\n' |
| 10582 | 'string literal*; see Formatted string literals. The "\'f\'" may ' |
| 10583 | 'be\n' |
| 10584 | 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore ' |
| 10585 | 'raw\n' |
| 10586 | 'formatted strings are possible, but formatted bytes literals are ' |
| 10587 | 'not.\n' |
| 10588 | '\n' |
| 10589 | 'In triple-quoted literals, unescaped newlines and quotes are ' |
| 10590 | 'allowed\n' |
| 10591 | '(and are retained), except that three unescaped quotes in a row\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10592 | 'terminate the literal. (A “quote” is the character used to open ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10593 | 'the\n' |
| 10594 | 'literal, i.e. either "\'" or """.)\n' |
| 10595 | '\n' |
| 10596 | 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences ' |
| 10597 | 'in string\n' |
| 10598 | 'and bytes literals are interpreted according to rules similar to ' |
| 10599 | 'those\n' |
| 10600 | 'used by Standard C. The recognized escape sequences are:\n' |
| 10601 | '\n' |
| 10602 | '+-------------------+-----------------------------------+---------+\n' |
| 10603 | '| Escape Sequence | Meaning | Notes ' |
| 10604 | '|\n' |
| 10605 | '+===================+===================================+=========+\n' |
| 10606 | '| "\\newline" | Backslash and newline ignored ' |
| 10607 | '| |\n' |
| 10608 | '+-------------------+-----------------------------------+---------+\n' |
| 10609 | '| "\\\\" | Backslash ("\\") ' |
| 10610 | '| |\n' |
| 10611 | '+-------------------+-----------------------------------+---------+\n' |
| 10612 | '| "\\\'" | Single quote ("\'") ' |
| 10613 | '| |\n' |
| 10614 | '+-------------------+-----------------------------------+---------+\n' |
| 10615 | '| "\\"" | Double quote (""") ' |
| 10616 | '| |\n' |
| 10617 | '+-------------------+-----------------------------------+---------+\n' |
| 10618 | '| "\\a" | ASCII Bell (BEL) ' |
| 10619 | '| |\n' |
| 10620 | '+-------------------+-----------------------------------+---------+\n' |
| 10621 | '| "\\b" | ASCII Backspace (BS) ' |
| 10622 | '| |\n' |
| 10623 | '+-------------------+-----------------------------------+---------+\n' |
| 10624 | '| "\\f" | ASCII Formfeed (FF) ' |
| 10625 | '| |\n' |
| 10626 | '+-------------------+-----------------------------------+---------+\n' |
| 10627 | '| "\\n" | ASCII Linefeed (LF) ' |
| 10628 | '| |\n' |
| 10629 | '+-------------------+-----------------------------------+---------+\n' |
| 10630 | '| "\\r" | ASCII Carriage Return (CR) ' |
| 10631 | '| |\n' |
| 10632 | '+-------------------+-----------------------------------+---------+\n' |
| 10633 | '| "\\t" | ASCII Horizontal Tab (TAB) ' |
| 10634 | '| |\n' |
| 10635 | '+-------------------+-----------------------------------+---------+\n' |
| 10636 | '| "\\v" | ASCII Vertical Tab (VT) ' |
| 10637 | '| |\n' |
| 10638 | '+-------------------+-----------------------------------+---------+\n' |
| 10639 | '| "\\ooo" | Character with octal value *ooo* | ' |
| 10640 | '(1,3) |\n' |
| 10641 | '+-------------------+-----------------------------------+---------+\n' |
| 10642 | '| "\\xhh" | Character with hex value *hh* | ' |
| 10643 | '(2,3) |\n' |
| 10644 | '+-------------------+-----------------------------------+---------+\n' |
| 10645 | '\n' |
| 10646 | 'Escape sequences only recognized in string literals are:\n' |
| 10647 | '\n' |
| 10648 | '+-------------------+-----------------------------------+---------+\n' |
| 10649 | '| Escape Sequence | Meaning | Notes ' |
| 10650 | '|\n' |
| 10651 | '+===================+===================================+=========+\n' |
| 10652 | '| "\\N{name}" | Character named *name* in the | ' |
| 10653 | '(4) |\n' |
| 10654 | '| | Unicode database | ' |
| 10655 | '|\n' |
| 10656 | '+-------------------+-----------------------------------+---------+\n' |
| 10657 | '| "\\uxxxx" | Character with 16-bit hex value | ' |
| 10658 | '(5) |\n' |
| 10659 | '| | *xxxx* | ' |
| 10660 | '|\n' |
| 10661 | '+-------------------+-----------------------------------+---------+\n' |
| 10662 | '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' |
| 10663 | '(6) |\n' |
| 10664 | '| | *xxxxxxxx* | ' |
| 10665 | '|\n' |
| 10666 | '+-------------------+-----------------------------------+---------+\n' |
| 10667 | '\n' |
| 10668 | 'Notes:\n' |
| 10669 | '\n' |
| 10670 | '1. As in Standard C, up to three octal digits are accepted.\n' |
| 10671 | '\n' |
| 10672 | '2. Unlike in Standard C, exactly two hex digits are required.\n' |
| 10673 | '\n' |
| 10674 | '3. In a bytes literal, hexadecimal and octal escapes denote the\n' |
| 10675 | ' byte with the given value. In a string literal, these escapes\n' |
| 10676 | ' denote a Unicode character with the given value.\n' |
| 10677 | '\n' |
| 10678 | '4. Changed in version 3.3: Support for name aliases [1] has been\n' |
| 10679 | ' added.\n' |
| 10680 | '\n' |
| 10681 | '5. Exactly four hex digits are required.\n' |
| 10682 | '\n' |
| 10683 | '6. Any Unicode character can be encoded this way. Exactly eight\n' |
| 10684 | ' hex digits are required.\n' |
| 10685 | '\n' |
| 10686 | 'Unlike Standard C, all unrecognized escape sequences are left in ' |
| 10687 | 'the\n' |
| 10688 | 'string unchanged, i.e., *the backslash is left in the result*. ' |
| 10689 | '(This\n' |
| 10690 | 'behavior is useful when debugging: if an escape sequence is ' |
| 10691 | 'mistyped,\n' |
| 10692 | 'the resulting output is more easily recognized as broken.) It is ' |
| 10693 | 'also\n' |
| 10694 | 'important to note that the escape sequences only recognized in ' |
| 10695 | 'string\n' |
| 10696 | 'literals fall into the category of unrecognized escapes for ' |
| 10697 | 'bytes\n' |
| 10698 | 'literals.\n' |
| 10699 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 10700 | ' Changed in version 3.6: Unrecognized escape sequences produce ' |
| 10701 | 'a\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10702 | ' "DeprecationWarning".\n' |
| 10703 | '\n' |
| 10704 | ' Changed in version 3.8: Unrecognized escape sequences produce ' |
| 10705 | 'a\n' |
| 10706 | ' "SyntaxWarning". In some future version of Python they will ' |
| 10707 | 'be a\n' |
| 10708 | ' "SyntaxError".\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 10709 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10710 | 'Even in a raw literal, quotes can be escaped with a backslash, ' |
| 10711 | 'but the\n' |
| 10712 | 'backslash remains in the result; for example, "r"\\""" is a ' |
| 10713 | 'valid\n' |
| 10714 | 'string literal consisting of two characters: a backslash and a ' |
| 10715 | 'double\n' |
| 10716 | 'quote; "r"\\"" is not a valid string literal (even a raw string ' |
| 10717 | 'cannot\n' |
| 10718 | 'end in an odd number of backslashes). Specifically, *a raw ' |
| 10719 | 'literal\n' |
| 10720 | 'cannot end in a single backslash* (since the backslash would ' |
| 10721 | 'escape\n' |
| 10722 | 'the following quote character). Note also that a single ' |
| 10723 | 'backslash\n' |
| 10724 | 'followed by a newline is interpreted as those two characters as ' |
| 10725 | 'part\n' |
| 10726 | 'of the literal, *not* as a line continuation.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10727 | 'subscriptions': 'Subscriptions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10728 | '*************\n' |
| 10729 | '\n' |
| 10730 | 'A subscription selects an item of a sequence (string, tuple ' |
| 10731 | 'or list)\n' |
| 10732 | 'or mapping (dictionary) object:\n' |
| 10733 | '\n' |
| 10734 | ' subscription ::= primary "[" expression_list "]"\n' |
| 10735 | '\n' |
| 10736 | 'The primary must evaluate to an object that supports ' |
| 10737 | 'subscription\n' |
| 10738 | '(lists or dictionaries for example). User-defined objects ' |
| 10739 | 'can support\n' |
| 10740 | 'subscription by defining a "__getitem__()" method.\n' |
| 10741 | '\n' |
| 10742 | 'For built-in objects, there are two types of objects that ' |
| 10743 | 'support\n' |
| 10744 | 'subscription:\n' |
| 10745 | '\n' |
| 10746 | 'If the primary is a mapping, the expression list must ' |
| 10747 | 'evaluate to an\n' |
| 10748 | 'object whose value is one of the keys of the mapping, and ' |
| 10749 | 'the\n' |
| 10750 | 'subscription selects the value in the mapping that ' |
| 10751 | 'corresponds to that\n' |
| 10752 | 'key. (The expression list is a tuple except if it has ' |
| 10753 | 'exactly one\n' |
| 10754 | 'item.)\n' |
| 10755 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10756 | 'If the primary is a sequence, the expression list must ' |
| 10757 | 'evaluate to an\n' |
| 10758 | 'integer or a slice (as discussed in the following ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10759 | 'section).\n' |
| 10760 | '\n' |
| 10761 | 'The formal syntax makes no special provision for negative ' |
| 10762 | 'indices in\n' |
| 10763 | 'sequences; however, built-in sequences all provide a ' |
| 10764 | '"__getitem__()"\n' |
| 10765 | 'method that interprets negative indices by adding the ' |
| 10766 | 'length of the\n' |
| 10767 | 'sequence to the index (so that "x[-1]" selects the last ' |
| 10768 | 'item of "x").\n' |
| 10769 | 'The resulting value must be a nonnegative integer less than ' |
| 10770 | 'the number\n' |
| 10771 | 'of items in the sequence, and the subscription selects the ' |
| 10772 | 'item whose\n' |
| 10773 | 'index is that value (counting from zero). Since the support ' |
| 10774 | 'for\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10775 | 'negative indices and slicing occurs in the object’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10776 | '"__getitem__()"\n' |
| 10777 | 'method, subclasses overriding this method will need to ' |
| 10778 | 'explicitly add\n' |
| 10779 | 'that support.\n' |
| 10780 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10781 | 'A string’s items are characters. A character is not a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10782 | 'separate data\n' |
| 10783 | 'type but a string of exactly one character.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10784 | 'truth': 'Truth Value Testing\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10785 | '*******************\n' |
| 10786 | '\n' |
| 10787 | 'Any object can be tested for truth value, for use in an "if" or\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10788 | '"while" condition or as operand of the Boolean operations below.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10789 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10790 | 'By default, an object is considered true unless its class defines\n' |
| 10791 | 'either a "__bool__()" method that returns "False" or a "__len__()"\n' |
| 10792 | 'method that returns zero, when called with the object. [1] Here ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10793 | 'are\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10794 | 'most of the built-in objects considered false:\n' |
| 10795 | '\n' |
| 10796 | '* constants defined to be false: "None" and "False".\n' |
| 10797 | '\n' |
| 10798 | '* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",\n' |
| 10799 | ' "Fraction(0, 1)"\n' |
| 10800 | '\n' |
| 10801 | '* empty sequences and collections: "\'\'", "()", "[]", "{}", ' |
| 10802 | '"set()",\n' |
| 10803 | ' "range(0)"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10804 | '\n' |
| 10805 | 'Operations and built-in functions that have a Boolean result ' |
| 10806 | 'always\n' |
| 10807 | 'return "0" or "False" for false and "1" or "True" for true, unless\n' |
| 10808 | 'otherwise stated. (Important exception: the Boolean operations ' |
| 10809 | '"or"\n' |
| 10810 | 'and "and" always return one of their operands.)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10811 | 'try': 'The "try" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10812 | '*******************\n' |
| 10813 | '\n' |
| 10814 | 'The "try" statement specifies exception handlers and/or cleanup code\n' |
| 10815 | 'for a group of statements:\n' |
| 10816 | '\n' |
| 10817 | ' try_stmt ::= try1_stmt | try2_stmt\n' |
| 10818 | ' try1_stmt ::= "try" ":" suite\n' |
| 10819 | ' ("except" [expression ["as" identifier]] ":" ' |
| 10820 | 'suite)+\n' |
| 10821 | ' ["else" ":" suite]\n' |
| 10822 | ' ["finally" ":" suite]\n' |
| 10823 | ' try2_stmt ::= "try" ":" suite\n' |
| 10824 | ' "finally" ":" suite\n' |
| 10825 | '\n' |
| 10826 | 'The "except" clause(s) specify one or more exception handlers. When ' |
| 10827 | 'no\n' |
| 10828 | 'exception occurs in the "try" clause, no exception handler is\n' |
| 10829 | 'executed. When an exception occurs in the "try" suite, a search for ' |
| 10830 | 'an\n' |
| 10831 | 'exception handler is started. This search inspects the except ' |
| 10832 | 'clauses\n' |
| 10833 | 'in turn until one is found that matches the exception. An ' |
| 10834 | 'expression-\n' |
| 10835 | 'less except clause, if present, must be last; it matches any\n' |
| 10836 | 'exception. For an except clause with an expression, that expression\n' |
| 10837 | 'is evaluated, and the clause matches the exception if the resulting\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10838 | 'object is “compatible” with the exception. An object is compatible\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10839 | 'with an exception if it is the class or a base class of the ' |
| 10840 | 'exception\n' |
| 10841 | 'object or a tuple containing an item compatible with the exception.\n' |
| 10842 | '\n' |
| 10843 | 'If no except clause matches the exception, the search for an ' |
| 10844 | 'exception\n' |
| 10845 | 'handler continues in the surrounding code and on the invocation ' |
| 10846 | 'stack.\n' |
| 10847 | '[1]\n' |
| 10848 | '\n' |
| 10849 | 'If the evaluation of an expression in the header of an except clause\n' |
| 10850 | 'raises an exception, the original search for a handler is canceled ' |
| 10851 | 'and\n' |
| 10852 | 'a search starts for the new exception in the surrounding code and on\n' |
| 10853 | 'the call stack (it is treated as if the entire "try" statement ' |
| 10854 | 'raised\n' |
| 10855 | 'the exception).\n' |
| 10856 | '\n' |
| 10857 | 'When a matching except clause is found, the exception is assigned to\n' |
| 10858 | 'the target specified after the "as" keyword in that except clause, ' |
| 10859 | 'if\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10860 | 'present, and the except clause’s suite is executed. All except\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10861 | 'clauses must have an executable block. When the end of this block ' |
| 10862 | 'is\n' |
| 10863 | 'reached, execution continues normally after the entire try ' |
| 10864 | 'statement.\n' |
| 10865 | '(This means that if two nested handlers exist for the same ' |
| 10866 | 'exception,\n' |
| 10867 | 'and the exception occurs in the try clause of the inner handler, the\n' |
| 10868 | 'outer handler will not handle the exception.)\n' |
| 10869 | '\n' |
| 10870 | 'When an exception has been assigned using "as target", it is cleared\n' |
| 10871 | 'at the end of the except clause. This is as if\n' |
| 10872 | '\n' |
| 10873 | ' except E as N:\n' |
| 10874 | ' foo\n' |
| 10875 | '\n' |
| 10876 | 'was translated to\n' |
| 10877 | '\n' |
| 10878 | ' except E as N:\n' |
| 10879 | ' try:\n' |
| 10880 | ' foo\n' |
| 10881 | ' finally:\n' |
| 10882 | ' del N\n' |
| 10883 | '\n' |
| 10884 | 'This means the exception must be assigned to a different name to be\n' |
| 10885 | 'able to refer to it after the except clause. Exceptions are cleared\n' |
| 10886 | 'because with the traceback attached to them, they form a reference\n' |
| 10887 | 'cycle with the stack frame, keeping all locals in that frame alive\n' |
| 10888 | 'until the next garbage collection occurs.\n' |
| 10889 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10890 | 'Before an except clause’s suite is executed, details about the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10891 | 'exception are stored in the "sys" module and can be accessed via\n' |
| 10892 | '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' |
| 10893 | 'the\n' |
| 10894 | 'exception class, the exception instance and a traceback object (see\n' |
| 10895 | 'section The standard type hierarchy) identifying the point in the\n' |
| 10896 | 'program where the exception occurred. "sys.exc_info()" values are\n' |
| 10897 | 'restored to their previous values (before the call) when returning\n' |
| 10898 | 'from a function that handled an exception.\n' |
| 10899 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10900 | 'The optional "else" clause is executed if the control flow leaves ' |
| 10901 | 'the\n' |
| 10902 | '"try" suite, no exception was raised, and no "return", "continue", ' |
| 10903 | 'or\n' |
| 10904 | '"break" statement was executed. Exceptions in the "else" clause are\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10905 | 'not handled by the preceding "except" clauses.\n' |
| 10906 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10907 | 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10908 | '"try"\n' |
| 10909 | 'clause is executed, including any "except" and "else" clauses. If ' |
| 10910 | 'an\n' |
| 10911 | 'exception occurs in any of the clauses and is not handled, the\n' |
| 10912 | 'exception is temporarily saved. The "finally" clause is executed. ' |
| 10913 | 'If\n' |
| 10914 | 'there is a saved exception it is re-raised at the end of the ' |
| 10915 | '"finally"\n' |
| 10916 | 'clause. If the "finally" clause raises another exception, the saved\n' |
| 10917 | 'exception is set as the context of the new exception. If the ' |
| 10918 | '"finally"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10919 | 'clause executes a "return", "break" or "continue" statement, the ' |
| 10920 | 'saved\n' |
| 10921 | 'exception is discarded:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10922 | '\n' |
| 10923 | ' >>> def f():\n' |
| 10924 | ' ... try:\n' |
| 10925 | ' ... 1/0\n' |
| 10926 | ' ... finally:\n' |
| 10927 | ' ... return 42\n' |
| 10928 | ' ...\n' |
| 10929 | ' >>> f()\n' |
| 10930 | ' 42\n' |
| 10931 | '\n' |
| 10932 | 'The exception information is not available to the program during\n' |
| 10933 | 'execution of the "finally" clause.\n' |
| 10934 | '\n' |
| 10935 | 'When a "return", "break" or "continue" statement is executed in the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10936 | '"try" suite of a "try"…"finally" statement, the "finally" clause is\n' |
| 10937 | 'also executed ‘on the way out.’\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10938 | '\n' |
| 10939 | 'The return value of a function is determined by the last "return"\n' |
| 10940 | 'statement executed. Since the "finally" clause always executes, a\n' |
| 10941 | '"return" statement executed in the "finally" clause will always be ' |
| 10942 | 'the\n' |
| 10943 | 'last one executed:\n' |
| 10944 | '\n' |
| 10945 | ' >>> def foo():\n' |
| 10946 | ' ... try:\n' |
| 10947 | " ... return 'try'\n" |
| 10948 | ' ... finally:\n' |
| 10949 | " ... return 'finally'\n" |
| 10950 | ' ...\n' |
| 10951 | ' >>> foo()\n' |
| 10952 | " 'finally'\n" |
| 10953 | '\n' |
| 10954 | 'Additional information on exceptions can be found in section\n' |
| 10955 | 'Exceptions, and information on using the "raise" statement to ' |
| 10956 | 'generate\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10957 | 'exceptions may be found in section The raise statement.\n' |
| 10958 | '\n' |
| 10959 | 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n' |
| 10960 | 'was illegal in the "finally" clause due to a problem with the\n' |
| 10961 | 'implementation.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10962 | 'types': 'The standard type hierarchy\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10963 | '***************************\n' |
| 10964 | '\n' |
| 10965 | 'Below is a list of the types that are built into Python. ' |
| 10966 | 'Extension\n' |
| 10967 | 'modules (written in C, Java, or other languages, depending on the\n' |
| 10968 | 'implementation) can define additional types. Future versions of\n' |
| 10969 | 'Python may add types to the type hierarchy (e.g., rational ' |
| 10970 | 'numbers,\n' |
| 10971 | 'efficiently stored arrays of integers, etc.), although such ' |
| 10972 | 'additions\n' |
| 10973 | 'will often be provided via the standard library instead.\n' |
| 10974 | '\n' |
| 10975 | 'Some of the type descriptions below contain a paragraph listing\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10976 | '‘special attributes.’ These are attributes that provide access to ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10977 | 'the\n' |
| 10978 | 'implementation and are not intended for general use. Their ' |
| 10979 | 'definition\n' |
| 10980 | 'may change in the future.\n' |
| 10981 | '\n' |
| 10982 | 'None\n' |
| 10983 | ' This type has a single value. There is a single object with ' |
| 10984 | 'this\n' |
| 10985 | ' value. This object is accessed through the built-in name "None". ' |
| 10986 | 'It\n' |
| 10987 | ' is used to signify the absence of a value in many situations, ' |
| 10988 | 'e.g.,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 10989 | ' it is returned from functions that don’t explicitly return\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10990 | ' anything. Its truth value is false.\n' |
| 10991 | '\n' |
| 10992 | 'NotImplemented\n' |
| 10993 | ' This type has a single value. There is a single object with ' |
| 10994 | 'this\n' |
| 10995 | ' value. This object is accessed through the built-in name\n' |
| 10996 | ' "NotImplemented". Numeric methods and rich comparison methods\n' |
| 10997 | ' should return this value if they do not implement the operation ' |
| 10998 | 'for\n' |
| 10999 | ' the operands provided. (The interpreter will then try the\n' |
| 11000 | ' reflected operation, or some other fallback, depending on the\n' |
| 11001 | ' operator.) Its truth value is true.\n' |
| 11002 | '\n' |
| 11003 | ' See Implementing the arithmetic operations for more details.\n' |
| 11004 | '\n' |
| 11005 | 'Ellipsis\n' |
| 11006 | ' This type has a single value. There is a single object with ' |
| 11007 | 'this\n' |
| 11008 | ' value. This object is accessed through the literal "..." or the\n' |
| 11009 | ' built-in name "Ellipsis". Its truth value is true.\n' |
| 11010 | '\n' |
| 11011 | '"numbers.Number"\n' |
| 11012 | ' These are created by numeric literals and returned as results ' |
| 11013 | 'by\n' |
| 11014 | ' arithmetic operators and arithmetic built-in functions. ' |
| 11015 | 'Numeric\n' |
| 11016 | ' objects are immutable; once created their value never changes.\n' |
| 11017 | ' Python numbers are of course strongly related to mathematical\n' |
| 11018 | ' numbers, but subject to the limitations of numerical ' |
| 11019 | 'representation\n' |
| 11020 | ' in computers.\n' |
| 11021 | '\n' |
| 11022 | ' Python distinguishes between integers, floating point numbers, ' |
| 11023 | 'and\n' |
| 11024 | ' complex numbers:\n' |
| 11025 | '\n' |
| 11026 | ' "numbers.Integral"\n' |
| 11027 | ' These represent elements from the mathematical set of ' |
| 11028 | 'integers\n' |
| 11029 | ' (positive and negative).\n' |
| 11030 | '\n' |
| 11031 | ' There are two types of integers:\n' |
| 11032 | '\n' |
| 11033 | ' Integers ("int")\n' |
| 11034 | '\n' |
| 11035 | ' These represent numbers in an unlimited range, subject to\n' |
| 11036 | ' available (virtual) memory only. For the purpose of ' |
| 11037 | 'shift\n' |
| 11038 | ' and mask operations, a binary representation is assumed, ' |
| 11039 | 'and\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11040 | ' negative numbers are represented in a variant of 2’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11041 | ' complement which gives the illusion of an infinite string ' |
| 11042 | 'of\n' |
| 11043 | ' sign bits extending to the left.\n' |
| 11044 | '\n' |
| 11045 | ' Booleans ("bool")\n' |
| 11046 | ' These represent the truth values False and True. The two\n' |
| 11047 | ' objects representing the values "False" and "True" are ' |
| 11048 | 'the\n' |
| 11049 | ' only Boolean objects. The Boolean type is a subtype of ' |
| 11050 | 'the\n' |
| 11051 | ' integer type, and Boolean values behave like the values 0 ' |
| 11052 | 'and\n' |
| 11053 | ' 1, respectively, in almost all contexts, the exception ' |
| 11054 | 'being\n' |
| 11055 | ' that when converted to a string, the strings ""False"" or\n' |
| 11056 | ' ""True"" are returned, respectively.\n' |
| 11057 | '\n' |
| 11058 | ' The rules for integer representation are intended to give ' |
| 11059 | 'the\n' |
| 11060 | ' most meaningful interpretation of shift and mask operations\n' |
| 11061 | ' involving negative integers.\n' |
| 11062 | '\n' |
| 11063 | ' "numbers.Real" ("float")\n' |
| 11064 | ' These represent machine-level double precision floating ' |
| 11065 | 'point\n' |
| 11066 | ' numbers. You are at the mercy of the underlying machine\n' |
| 11067 | ' architecture (and C or Java implementation) for the accepted\n' |
| 11068 | ' range and handling of overflow. Python does not support ' |
| 11069 | 'single-\n' |
| 11070 | ' precision floating point numbers; the savings in processor ' |
| 11071 | 'and\n' |
| 11072 | ' memory usage that are usually the reason for using these are\n' |
| 11073 | ' dwarfed by the overhead of using objects in Python, so there ' |
| 11074 | 'is\n' |
| 11075 | ' no reason to complicate the language with two kinds of ' |
| 11076 | 'floating\n' |
| 11077 | ' point numbers.\n' |
| 11078 | '\n' |
| 11079 | ' "numbers.Complex" ("complex")\n' |
| 11080 | ' These represent complex numbers as a pair of machine-level\n' |
| 11081 | ' double precision floating point numbers. The same caveats ' |
| 11082 | 'apply\n' |
| 11083 | ' as for floating point numbers. The real and imaginary parts ' |
| 11084 | 'of a\n' |
| 11085 | ' complex number "z" can be retrieved through the read-only\n' |
| 11086 | ' attributes "z.real" and "z.imag".\n' |
| 11087 | '\n' |
| 11088 | 'Sequences\n' |
| 11089 | ' These represent finite ordered sets indexed by non-negative\n' |
| 11090 | ' numbers. The built-in function "len()" returns the number of ' |
| 11091 | 'items\n' |
| 11092 | ' of a sequence. When the length of a sequence is *n*, the index ' |
| 11093 | 'set\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11094 | ' contains the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11095 | 'is\n' |
| 11096 | ' selected by "a[i]".\n' |
| 11097 | '\n' |
| 11098 | ' Sequences also support slicing: "a[i:j]" selects all items with\n' |
| 11099 | ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n' |
| 11100 | ' expression, a slice is a sequence of the same type. This ' |
| 11101 | 'implies\n' |
| 11102 | ' that the index set is renumbered so that it starts at 0.\n' |
| 11103 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11104 | ' Some sequences also support “extended slicing” with a third ' |
| 11105 | '“step”\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11106 | ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' |
| 11107 | 'where\n' |
| 11108 | ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' |
| 11109 | '\n' |
| 11110 | ' Sequences are distinguished according to their mutability:\n' |
| 11111 | '\n' |
| 11112 | ' Immutable sequences\n' |
| 11113 | ' An object of an immutable sequence type cannot change once it ' |
| 11114 | 'is\n' |
| 11115 | ' created. (If the object contains references to other ' |
| 11116 | 'objects,\n' |
| 11117 | ' these other objects may be mutable and may be changed; ' |
| 11118 | 'however,\n' |
| 11119 | ' the collection of objects directly referenced by an ' |
| 11120 | 'immutable\n' |
| 11121 | ' object cannot change.)\n' |
| 11122 | '\n' |
| 11123 | ' The following types are immutable sequences:\n' |
| 11124 | '\n' |
| 11125 | ' Strings\n' |
| 11126 | ' A string is a sequence of values that represent Unicode ' |
| 11127 | 'code\n' |
| 11128 | ' points. All the code points in the range "U+0000 - ' |
| 11129 | 'U+10FFFF"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11130 | ' can be represented in a string. Python doesn’t have a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11131 | '"char"\n' |
| 11132 | ' type; instead, every code point in the string is ' |
| 11133 | 'represented\n' |
| 11134 | ' as a string object with length "1". The built-in ' |
| 11135 | 'function\n' |
| 11136 | ' "ord()" converts a code point from its string form to an\n' |
| 11137 | ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' |
| 11138 | ' integer in the range "0 - 10FFFF" to the corresponding ' |
| 11139 | 'length\n' |
| 11140 | ' "1" string object. "str.encode()" can be used to convert ' |
| 11141 | 'a\n' |
| 11142 | ' "str" to "bytes" using the given text encoding, and\n' |
| 11143 | ' "bytes.decode()" can be used to achieve the opposite.\n' |
| 11144 | '\n' |
| 11145 | ' Tuples\n' |
| 11146 | ' The items of a tuple are arbitrary Python objects. Tuples ' |
| 11147 | 'of\n' |
| 11148 | ' two or more items are formed by comma-separated lists of\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11149 | ' expressions. A tuple of one item (a ‘singleton’) can be\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11150 | ' formed by affixing a comma to an expression (an expression ' |
| 11151 | 'by\n' |
| 11152 | ' itself does not create a tuple, since parentheses must be\n' |
| 11153 | ' usable for grouping of expressions). An empty tuple can ' |
| 11154 | 'be\n' |
| 11155 | ' formed by an empty pair of parentheses.\n' |
| 11156 | '\n' |
| 11157 | ' Bytes\n' |
| 11158 | ' A bytes object is an immutable array. The items are ' |
| 11159 | '8-bit\n' |
| 11160 | ' bytes, represented by integers in the range 0 <= x < 256.\n' |
| 11161 | ' Bytes literals (like "b\'abc\'") and the built-in ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11162 | '"bytes()"\n' |
| 11163 | ' constructor can be used to create bytes objects. Also, ' |
| 11164 | 'bytes\n' |
| 11165 | ' objects can be decoded to strings via the "decode()" ' |
| 11166 | 'method.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11167 | '\n' |
| 11168 | ' Mutable sequences\n' |
| 11169 | ' Mutable sequences can be changed after they are created. ' |
| 11170 | 'The\n' |
| 11171 | ' subscription and slicing notations can be used as the target ' |
| 11172 | 'of\n' |
| 11173 | ' assignment and "del" (delete) statements.\n' |
| 11174 | '\n' |
| 11175 | ' There are currently two intrinsic mutable sequence types:\n' |
| 11176 | '\n' |
| 11177 | ' Lists\n' |
| 11178 | ' The items of a list are arbitrary Python objects. Lists ' |
| 11179 | 'are\n' |
| 11180 | ' formed by placing a comma-separated list of expressions ' |
| 11181 | 'in\n' |
| 11182 | ' square brackets. (Note that there are no special cases ' |
| 11183 | 'needed\n' |
| 11184 | ' to form lists of length 0 or 1.)\n' |
| 11185 | '\n' |
| 11186 | ' Byte Arrays\n' |
| 11187 | ' A bytearray object is a mutable array. They are created ' |
| 11188 | 'by\n' |
| 11189 | ' the built-in "bytearray()" constructor. Aside from being\n' |
| 11190 | ' mutable (and hence unhashable), byte arrays otherwise ' |
| 11191 | 'provide\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11192 | ' the same interface and functionality as immutable "bytes"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11193 | ' objects.\n' |
| 11194 | '\n' |
| 11195 | ' The extension module "array" provides an additional example ' |
| 11196 | 'of a\n' |
| 11197 | ' mutable sequence type, as does the "collections" module.\n' |
| 11198 | '\n' |
| 11199 | 'Set types\n' |
| 11200 | ' These represent unordered, finite sets of unique, immutable\n' |
| 11201 | ' objects. As such, they cannot be indexed by any subscript. ' |
| 11202 | 'However,\n' |
| 11203 | ' they can be iterated over, and the built-in function "len()"\n' |
| 11204 | ' returns the number of items in a set. Common uses for sets are ' |
| 11205 | 'fast\n' |
| 11206 | ' membership testing, removing duplicates from a sequence, and\n' |
| 11207 | ' computing mathematical operations such as intersection, union,\n' |
| 11208 | ' difference, and symmetric difference.\n' |
| 11209 | '\n' |
| 11210 | ' For set elements, the same immutability rules apply as for\n' |
| 11211 | ' dictionary keys. Note that numeric types obey the normal rules ' |
| 11212 | 'for\n' |
| 11213 | ' numeric comparison: if two numbers compare equal (e.g., "1" and\n' |
| 11214 | ' "1.0"), only one of them can be contained in a set.\n' |
| 11215 | '\n' |
| 11216 | ' There are currently two intrinsic set types:\n' |
| 11217 | '\n' |
| 11218 | ' Sets\n' |
| 11219 | ' These represent a mutable set. They are created by the ' |
| 11220 | 'built-in\n' |
| 11221 | ' "set()" constructor and can be modified afterwards by ' |
| 11222 | 'several\n' |
| 11223 | ' methods, such as "add()".\n' |
| 11224 | '\n' |
| 11225 | ' Frozen sets\n' |
| 11226 | ' These represent an immutable set. They are created by the\n' |
| 11227 | ' built-in "frozenset()" constructor. As a frozenset is ' |
| 11228 | 'immutable\n' |
| 11229 | ' and *hashable*, it can be used again as an element of ' |
| 11230 | 'another\n' |
| 11231 | ' set, or as a dictionary key.\n' |
| 11232 | '\n' |
| 11233 | 'Mappings\n' |
| 11234 | ' These represent finite sets of objects indexed by arbitrary ' |
| 11235 | 'index\n' |
| 11236 | ' sets. The subscript notation "a[k]" selects the item indexed by ' |
| 11237 | '"k"\n' |
| 11238 | ' from the mapping "a"; this can be used in expressions and as ' |
| 11239 | 'the\n' |
| 11240 | ' target of assignments or "del" statements. The built-in ' |
| 11241 | 'function\n' |
| 11242 | ' "len()" returns the number of items in a mapping.\n' |
| 11243 | '\n' |
| 11244 | ' There is currently a single intrinsic mapping type:\n' |
| 11245 | '\n' |
| 11246 | ' Dictionaries\n' |
| 11247 | ' These represent finite sets of objects indexed by nearly\n' |
| 11248 | ' arbitrary values. The only types of values not acceptable ' |
| 11249 | 'as\n' |
| 11250 | ' keys are values containing lists or dictionaries or other\n' |
| 11251 | ' mutable types that are compared by value rather than by ' |
| 11252 | 'object\n' |
| 11253 | ' identity, the reason being that the efficient implementation ' |
| 11254 | 'of\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11255 | ' dictionaries requires a key’s hash value to remain constant.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11256 | ' Numeric types used for keys obey the normal rules for ' |
| 11257 | 'numeric\n' |
| 11258 | ' comparison: if two numbers compare equal (e.g., "1" and ' |
| 11259 | '"1.0")\n' |
| 11260 | ' then they can be used interchangeably to index the same\n' |
| 11261 | ' dictionary entry.\n' |
| 11262 | '\n' |
| 11263 | ' Dictionaries are mutable; they can be created by the "{...}"\n' |
| 11264 | ' notation (see section Dictionary displays).\n' |
| 11265 | '\n' |
| 11266 | ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' |
| 11267 | ' additional examples of mapping types, as does the ' |
| 11268 | '"collections"\n' |
| 11269 | ' module.\n' |
| 11270 | '\n' |
| 11271 | 'Callable types\n' |
| 11272 | ' These are the types to which the function call operation (see\n' |
| 11273 | ' section Calls) can be applied:\n' |
| 11274 | '\n' |
| 11275 | ' User-defined functions\n' |
| 11276 | ' A user-defined function object is created by a function\n' |
| 11277 | ' definition (see section Function definitions). It should be\n' |
| 11278 | ' called with an argument list containing the same number of ' |
| 11279 | 'items\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11280 | ' as the function’s formal parameter list.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11281 | '\n' |
| 11282 | ' Special attributes:\n' |
| 11283 | '\n' |
| 11284 | ' ' |
| 11285 | '+---------------------------+---------------------------------+-------------+\n' |
| 11286 | ' | Attribute | Meaning ' |
| 11287 | '| |\n' |
| 11288 | ' ' |
| 11289 | '+===========================+=================================+=============+\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11290 | ' | "__doc__" | The function’s documentation ' |
| 11291 | '| Writable |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11292 | ' | | string, or "None" if ' |
| 11293 | '| |\n' |
| 11294 | ' | | unavailable; not inherited by ' |
| 11295 | '| |\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 11296 | ' | | subclasses. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11297 | '| |\n' |
| 11298 | ' ' |
| 11299 | '+---------------------------+---------------------------------+-------------+\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 11300 | ' | "__name__" | The function’s name. ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11301 | '| Writable |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11302 | ' ' |
| 11303 | '+---------------------------+---------------------------------+-------------+\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 11304 | ' | "__qualname__" | The function’s *qualified ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11305 | '| Writable |\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 11306 | ' | | name*. New in version 3.3. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11307 | '| |\n' |
| 11308 | ' ' |
| 11309 | '+---------------------------+---------------------------------+-------------+\n' |
| 11310 | ' | "__module__" | The name of the module the ' |
| 11311 | '| Writable |\n' |
| 11312 | ' | | function was defined in, or ' |
| 11313 | '| |\n' |
| 11314 | ' | | "None" if unavailable. ' |
| 11315 | '| |\n' |
| 11316 | ' ' |
| 11317 | '+---------------------------+---------------------------------+-------------+\n' |
| 11318 | ' | "__defaults__" | A tuple containing default ' |
| 11319 | '| Writable |\n' |
| 11320 | ' | | argument values for those ' |
| 11321 | '| |\n' |
| 11322 | ' | | arguments that have defaults, ' |
| 11323 | '| |\n' |
| 11324 | ' | | or "None" if no arguments have ' |
| 11325 | '| |\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 11326 | ' | | a default value. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11327 | '| |\n' |
| 11328 | ' ' |
| 11329 | '+---------------------------+---------------------------------+-------------+\n' |
| 11330 | ' | "__code__" | The code object representing ' |
| 11331 | '| Writable |\n' |
| 11332 | ' | | the compiled function body. ' |
| 11333 | '| |\n' |
| 11334 | ' ' |
| 11335 | '+---------------------------+---------------------------------+-------------+\n' |
| 11336 | ' | "__globals__" | A reference to the dictionary ' |
| 11337 | '| Read-only |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11338 | ' | | that holds the function’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11339 | '| |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11340 | ' | | global variables — the global ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11341 | '| |\n' |
| 11342 | ' | | namespace of the module in ' |
| 11343 | '| |\n' |
| 11344 | ' | | which the function was defined. ' |
| 11345 | '| |\n' |
| 11346 | ' ' |
| 11347 | '+---------------------------+---------------------------------+-------------+\n' |
| 11348 | ' | "__dict__" | The namespace supporting ' |
| 11349 | '| Writable |\n' |
| 11350 | ' | | arbitrary function attributes. ' |
| 11351 | '| |\n' |
| 11352 | ' ' |
| 11353 | '+---------------------------+---------------------------------+-------------+\n' |
| 11354 | ' | "__closure__" | "None" or a tuple of cells that ' |
| 11355 | '| Read-only |\n' |
| 11356 | ' | | contain bindings for the ' |
| 11357 | '| |\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11358 | ' | | function’s free variables. See ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11359 | '| |\n' |
| 11360 | ' | | below for information on the ' |
| 11361 | '| |\n' |
| 11362 | ' | | "cell_contents" attribute. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11363 | '| |\n' |
| 11364 | ' ' |
| 11365 | '+---------------------------+---------------------------------+-------------+\n' |
| 11366 | ' | "__annotations__" | A dict containing annotations ' |
| 11367 | '| Writable |\n' |
| 11368 | ' | | of parameters. The keys of the ' |
| 11369 | '| |\n' |
| 11370 | ' | | dict are the parameter names, ' |
| 11371 | '| |\n' |
| 11372 | ' | | and "\'return\'" for the ' |
| 11373 | 'return | |\n' |
| 11374 | ' | | annotation, if provided. ' |
| 11375 | '| |\n' |
| 11376 | ' ' |
| 11377 | '+---------------------------+---------------------------------+-------------+\n' |
| 11378 | ' | "__kwdefaults__" | A dict containing defaults for ' |
| 11379 | '| Writable |\n' |
| 11380 | ' | | keyword-only parameters. ' |
| 11381 | '| |\n' |
| 11382 | ' ' |
| 11383 | '+---------------------------+---------------------------------+-------------+\n' |
| 11384 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11385 | ' Most of the attributes labelled “Writable” check the type of ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11386 | 'the\n' |
| 11387 | ' assigned value.\n' |
| 11388 | '\n' |
| 11389 | ' Function objects also support getting and setting arbitrary\n' |
| 11390 | ' attributes, which can be used, for example, to attach ' |
| 11391 | 'metadata\n' |
| 11392 | ' to functions. Regular attribute dot-notation is used to get ' |
| 11393 | 'and\n' |
| 11394 | ' set such attributes. *Note that the current implementation ' |
| 11395 | 'only\n' |
| 11396 | ' supports function attributes on user-defined functions. ' |
| 11397 | 'Function\n' |
| 11398 | ' attributes on built-in functions may be supported in the\n' |
| 11399 | ' future.*\n' |
| 11400 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11401 | ' A cell object has the attribute "cell_contents". This can be\n' |
| 11402 | ' used to get the value of the cell, as well as set the value.\n' |
| 11403 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11404 | ' Additional information about a function’s definition can be\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11405 | ' retrieved from its code object; see the description of ' |
| 11406 | 'internal\n' |
Łukasz Langa | 23f4589 | 2019-02-25 13:08:32 +0100 | [diff] [blame] | 11407 | ' types below. The "cell" type can be accessed in the "types"\n' |
| 11408 | ' module.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11409 | '\n' |
| 11410 | ' Instance methods\n' |
| 11411 | ' An instance method object combines a class, a class instance ' |
| 11412 | 'and\n' |
| 11413 | ' any callable object (normally a user-defined function).\n' |
| 11414 | '\n' |
| 11415 | ' Special read-only attributes: "__self__" is the class ' |
| 11416 | 'instance\n' |
| 11417 | ' object, "__func__" is the function object; "__doc__" is the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11418 | ' method’s documentation (same as "__func__.__doc__"); ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11419 | '"__name__"\n' |
| 11420 | ' is the method name (same as "__func__.__name__"); ' |
| 11421 | '"__module__"\n' |
| 11422 | ' is the name of the module the method was defined in, or ' |
| 11423 | '"None"\n' |
| 11424 | ' if unavailable.\n' |
| 11425 | '\n' |
| 11426 | ' Methods also support accessing (but not setting) the ' |
| 11427 | 'arbitrary\n' |
| 11428 | ' function attributes on the underlying function object.\n' |
| 11429 | '\n' |
| 11430 | ' User-defined method objects may be created when getting an\n' |
| 11431 | ' attribute of a class (perhaps via an instance of that class), ' |
| 11432 | 'if\n' |
| 11433 | ' that attribute is a user-defined function object or a class\n' |
| 11434 | ' method object.\n' |
| 11435 | '\n' |
| 11436 | ' When an instance method object is created by retrieving a ' |
| 11437 | 'user-\n' |
| 11438 | ' defined function object from a class via one of its ' |
| 11439 | 'instances,\n' |
| 11440 | ' its "__self__" attribute is the instance, and the method ' |
| 11441 | 'object\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11442 | ' is said to be bound. The new method’s "__func__" attribute ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11443 | 'is\n' |
| 11444 | ' the original function object.\n' |
| 11445 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11446 | ' When an instance method object is created by retrieving a ' |
| 11447 | 'class\n' |
| 11448 | ' method object from a class or instance, its "__self__" ' |
| 11449 | 'attribute\n' |
| 11450 | ' is the class itself, and its "__func__" attribute is the\n' |
| 11451 | ' function object underlying the class method.\n' |
| 11452 | '\n' |
| 11453 | ' When an instance method object is called, the underlying\n' |
| 11454 | ' function ("__func__") is called, inserting the class ' |
| 11455 | 'instance\n' |
| 11456 | ' ("__self__") in front of the argument list. For instance, ' |
| 11457 | 'when\n' |
| 11458 | ' "C" is a class which contains a definition for a function ' |
| 11459 | '"f()",\n' |
| 11460 | ' and "x" is an instance of "C", calling "x.f(1)" is equivalent ' |
| 11461 | 'to\n' |
| 11462 | ' calling "C.f(x, 1)".\n' |
| 11463 | '\n' |
| 11464 | ' When an instance method object is derived from a class ' |
| 11465 | 'method\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11466 | ' object, the “class instance” stored in "__self__" will ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11467 | 'actually\n' |
| 11468 | ' be the class itself, so that calling either "x.f(1)" or ' |
| 11469 | '"C.f(1)"\n' |
| 11470 | ' is equivalent to calling "f(C,1)" where "f" is the ' |
| 11471 | 'underlying\n' |
| 11472 | ' function.\n' |
| 11473 | '\n' |
| 11474 | ' Note that the transformation from function object to ' |
| 11475 | 'instance\n' |
| 11476 | ' method object happens each time the attribute is retrieved ' |
| 11477 | 'from\n' |
| 11478 | ' the instance. In some cases, a fruitful optimization is to\n' |
| 11479 | ' assign the attribute to a local variable and call that local\n' |
| 11480 | ' variable. Also notice that this transformation only happens ' |
| 11481 | 'for\n' |
| 11482 | ' user-defined functions; other callable objects (and all non-\n' |
| 11483 | ' callable objects) are retrieved without transformation. It ' |
| 11484 | 'is\n' |
| 11485 | ' also important to note that user-defined functions which are\n' |
| 11486 | ' attributes of a class instance are not converted to bound\n' |
| 11487 | ' methods; this *only* happens when the function is an ' |
| 11488 | 'attribute\n' |
| 11489 | ' of the class.\n' |
| 11490 | '\n' |
| 11491 | ' Generator functions\n' |
| 11492 | ' A function or method which uses the "yield" statement (see\n' |
| 11493 | ' section The yield statement) is called a *generator ' |
| 11494 | 'function*.\n' |
| 11495 | ' Such a function, when called, always returns an iterator ' |
| 11496 | 'object\n' |
| 11497 | ' which can be used to execute the body of the function: ' |
| 11498 | 'calling\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11499 | ' the iterator’s "iterator.__next__()" method will cause the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11500 | ' function to execute until it provides a value using the ' |
| 11501 | '"yield"\n' |
| 11502 | ' statement. When the function executes a "return" statement ' |
| 11503 | 'or\n' |
| 11504 | ' falls off the end, a "StopIteration" exception is raised and ' |
| 11505 | 'the\n' |
| 11506 | ' iterator will have reached the end of the set of values to ' |
| 11507 | 'be\n' |
| 11508 | ' returned.\n' |
| 11509 | '\n' |
| 11510 | ' Coroutine functions\n' |
| 11511 | ' A function or method which is defined using "async def" is\n' |
| 11512 | ' called a *coroutine function*. Such a function, when ' |
| 11513 | 'called,\n' |
| 11514 | ' returns a *coroutine* object. It may contain "await"\n' |
| 11515 | ' expressions, as well as "async with" and "async for" ' |
| 11516 | 'statements.\n' |
| 11517 | ' See also the Coroutine Objects section.\n' |
| 11518 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11519 | ' Asynchronous generator functions\n' |
| 11520 | ' A function or method which is defined using "async def" and\n' |
| 11521 | ' which uses the "yield" statement is called a *asynchronous\n' |
| 11522 | ' generator function*. Such a function, when called, returns ' |
| 11523 | 'an\n' |
| 11524 | ' asynchronous iterator object which can be used in an "async ' |
| 11525 | 'for"\n' |
| 11526 | ' statement to execute the body of the function.\n' |
| 11527 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11528 | ' Calling the asynchronous iterator’s "aiterator.__anext__()"\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11529 | ' method will return an *awaitable* which when awaited will\n' |
| 11530 | ' execute until it provides a value using the "yield" ' |
| 11531 | 'expression.\n' |
| 11532 | ' When the function executes an empty "return" statement or ' |
| 11533 | 'falls\n' |
| 11534 | ' off the end, a "StopAsyncIteration" exception is raised and ' |
| 11535 | 'the\n' |
| 11536 | ' asynchronous iterator will have reached the end of the set ' |
| 11537 | 'of\n' |
| 11538 | ' values to be yielded.\n' |
| 11539 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11540 | ' Built-in functions\n' |
| 11541 | ' A built-in function object is a wrapper around a C function.\n' |
| 11542 | ' Examples of built-in functions are "len()" and "math.sin()"\n' |
| 11543 | ' ("math" is a standard built-in module). The number and type ' |
| 11544 | 'of\n' |
| 11545 | ' the arguments are determined by the C function. Special ' |
| 11546 | 'read-\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11547 | ' only attributes: "__doc__" is the function’s documentation\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11548 | ' string, or "None" if unavailable; "__name__" is the ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11549 | 'function’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11550 | ' name; "__self__" is set to "None" (but see the next item);\n' |
| 11551 | ' "__module__" is the name of the module the function was ' |
| 11552 | 'defined\n' |
| 11553 | ' in or "None" if unavailable.\n' |
| 11554 | '\n' |
| 11555 | ' Built-in methods\n' |
| 11556 | ' This is really a different disguise of a built-in function, ' |
| 11557 | 'this\n' |
| 11558 | ' time containing an object passed to the C function as an\n' |
| 11559 | ' implicit extra argument. An example of a built-in method is\n' |
| 11560 | ' "alist.append()", assuming *alist* is a list object. In this\n' |
| 11561 | ' case, the special read-only attribute "__self__" is set to ' |
| 11562 | 'the\n' |
| 11563 | ' object denoted by *alist*.\n' |
| 11564 | '\n' |
| 11565 | ' Classes\n' |
| 11566 | ' Classes are callable. These objects normally act as ' |
| 11567 | 'factories\n' |
| 11568 | ' for new instances of themselves, but variations are possible ' |
| 11569 | 'for\n' |
| 11570 | ' class types that override "__new__()". The arguments of the\n' |
| 11571 | ' call are passed to "__new__()" and, in the typical case, to\n' |
| 11572 | ' "__init__()" to initialize the new instance.\n' |
| 11573 | '\n' |
| 11574 | ' Class Instances\n' |
| 11575 | ' Instances of arbitrary classes can be made callable by ' |
| 11576 | 'defining\n' |
| 11577 | ' a "__call__()" method in their class.\n' |
| 11578 | '\n' |
| 11579 | 'Modules\n' |
| 11580 | ' Modules are a basic organizational unit of Python code, and are\n' |
| 11581 | ' created by the import system as invoked either by the "import"\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11582 | ' statement, or by calling functions such as\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11583 | ' "importlib.import_module()" and built-in "__import__()". A ' |
| 11584 | 'module\n' |
| 11585 | ' object has a namespace implemented by a dictionary object (this ' |
| 11586 | 'is\n' |
| 11587 | ' the dictionary referenced by the "__globals__" attribute of\n' |
| 11588 | ' functions defined in the module). Attribute references are\n' |
| 11589 | ' translated to lookups in this dictionary, e.g., "m.x" is ' |
| 11590 | 'equivalent\n' |
| 11591 | ' to "m.__dict__["x"]". A module object does not contain the code\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11592 | ' object used to initialize the module (since it isn’t needed ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11593 | 'once\n' |
| 11594 | ' the initialization is done).\n' |
| 11595 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11596 | ' Attribute assignment updates the module’s namespace dictionary,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11597 | ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' |
| 11598 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11599 | ' Predefined (writable) attributes: "__name__" is the module’s ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 11600 | 'name;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11601 | ' "__doc__" is the module’s documentation string, or "None" if\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 11602 | ' unavailable; "__annotations__" (optional) is a dictionary\n' |
| 11603 | ' containing *variable annotations* collected during module body\n' |
| 11604 | ' execution; "__file__" is the pathname of the file from which ' |
| 11605 | 'the\n' |
| 11606 | ' module was loaded, if it was loaded from a file. The "__file__"\n' |
| 11607 | ' attribute may be missing for certain types of modules, such as ' |
| 11608 | 'C\n' |
| 11609 | ' modules that are statically linked into the interpreter; for\n' |
| 11610 | ' extension modules loaded dynamically from a shared library, it ' |
| 11611 | 'is\n' |
| 11612 | ' the pathname of the shared library file.\n' |
| 11613 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11614 | ' Special read-only attribute: "__dict__" is the module’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11615 | 'namespace\n' |
| 11616 | ' as a dictionary object.\n' |
| 11617 | '\n' |
| 11618 | ' **CPython implementation detail:** Because of the way CPython\n' |
| 11619 | ' clears module dictionaries, the module dictionary will be ' |
| 11620 | 'cleared\n' |
| 11621 | ' when the module falls out of scope even if the dictionary still ' |
| 11622 | 'has\n' |
| 11623 | ' live references. To avoid this, copy the dictionary or keep ' |
| 11624 | 'the\n' |
| 11625 | ' module around while using its dictionary directly.\n' |
| 11626 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11627 | 'Custom classes\n' |
| 11628 | ' Custom class types are typically created by class definitions ' |
| 11629 | '(see\n' |
| 11630 | ' section Class definitions). A class has a namespace implemented ' |
| 11631 | 'by\n' |
| 11632 | ' a dictionary object. Class attribute references are translated ' |
| 11633 | 'to\n' |
| 11634 | ' lookups in this dictionary, e.g., "C.x" is translated to\n' |
| 11635 | ' "C.__dict__["x"]" (although there are a number of hooks which ' |
| 11636 | 'allow\n' |
| 11637 | ' for other means of locating attributes). When the attribute name ' |
| 11638 | 'is\n' |
| 11639 | ' not found there, the attribute search continues in the base\n' |
| 11640 | ' classes. This search of the base classes uses the C3 method\n' |
| 11641 | ' resolution order which behaves correctly even in the presence ' |
| 11642 | 'of\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11643 | ' ‘diamond’ inheritance structures where there are multiple\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11644 | ' inheritance paths leading back to a common ancestor. Additional\n' |
| 11645 | ' details on the C3 MRO used by Python can be found in the\n' |
| 11646 | ' documentation accompanying the 2.3 release at\n' |
| 11647 | ' https://www.python.org/download/releases/2.3/mro/.\n' |
| 11648 | '\n' |
| 11649 | ' When a class attribute reference (for class "C", say) would ' |
| 11650 | 'yield a\n' |
| 11651 | ' class method object, it is transformed into an instance method\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11652 | ' object whose "__self__" attribute is "C". When it would yield ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11653 | 'a\n' |
| 11654 | ' static method object, it is transformed into the object wrapped ' |
| 11655 | 'by\n' |
| 11656 | ' the static method object. See section Implementing Descriptors ' |
| 11657 | 'for\n' |
| 11658 | ' another way in which attributes retrieved from a class may ' |
| 11659 | 'differ\n' |
| 11660 | ' from those actually contained in its "__dict__".\n' |
| 11661 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11662 | ' Class attribute assignments update the class’s dictionary, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11663 | 'never\n' |
| 11664 | ' the dictionary of a base class.\n' |
| 11665 | '\n' |
| 11666 | ' A class object can be called (see above) to yield a class ' |
| 11667 | 'instance\n' |
| 11668 | ' (see below).\n' |
| 11669 | '\n' |
| 11670 | ' Special attributes: "__name__" is the class name; "__module__" ' |
| 11671 | 'is\n' |
| 11672 | ' the module name in which the class was defined; "__dict__" is ' |
| 11673 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11674 | ' dictionary containing the class’s namespace; "__bases__" is a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11675 | 'tuple\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11676 | ' containing the base classes, in the order of their occurrence ' |
| 11677 | 'in\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11678 | ' the base class list; "__doc__" is the class’s documentation ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11679 | 'string,\n' |
| 11680 | ' or "None" if undefined; "__annotations__" (optional) is a\n' |
| 11681 | ' dictionary containing *variable annotations* collected during ' |
| 11682 | 'class\n' |
| 11683 | ' body execution.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11684 | '\n' |
| 11685 | 'Class instances\n' |
| 11686 | ' A class instance is created by calling a class object (see ' |
| 11687 | 'above).\n' |
| 11688 | ' A class instance has a namespace implemented as a dictionary ' |
| 11689 | 'which\n' |
| 11690 | ' is the first place in which attribute references are searched.\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11691 | ' When an attribute is not found there, and the instance’s class ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11692 | 'has\n' |
| 11693 | ' an attribute by that name, the search continues with the class\n' |
| 11694 | ' attributes. If a class attribute is found that is a ' |
| 11695 | 'user-defined\n' |
| 11696 | ' function object, it is transformed into an instance method ' |
| 11697 | 'object\n' |
| 11698 | ' whose "__self__" attribute is the instance. Static method and\n' |
| 11699 | ' class method objects are also transformed; see above under\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11700 | ' “Classes”. See section Implementing Descriptors for another way ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11701 | 'in\n' |
| 11702 | ' which attributes of a class retrieved via its instances may ' |
| 11703 | 'differ\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11704 | ' from the objects actually stored in the class’s "__dict__". If ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11705 | 'no\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11706 | ' class attribute is found, and the object’s class has a\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11707 | ' "__getattr__()" method, that is called to satisfy the lookup.\n' |
| 11708 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11709 | ' Attribute assignments and deletions update the instance’s\n' |
| 11710 | ' dictionary, never a class’s dictionary. If the class has a\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11711 | ' "__setattr__()" or "__delattr__()" method, this is called ' |
| 11712 | 'instead\n' |
| 11713 | ' of updating the instance dictionary directly.\n' |
| 11714 | '\n' |
| 11715 | ' Class instances can pretend to be numbers, sequences, or ' |
| 11716 | 'mappings\n' |
| 11717 | ' if they have methods with certain special names. See section\n' |
| 11718 | ' Special method names.\n' |
| 11719 | '\n' |
| 11720 | ' Special attributes: "__dict__" is the attribute dictionary;\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11721 | ' "__class__" is the instance’s class.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11722 | '\n' |
| 11723 | 'I/O objects (also known as file objects)\n' |
| 11724 | ' A *file object* represents an open file. Various shortcuts are\n' |
| 11725 | ' available to create file objects: the "open()" built-in ' |
| 11726 | 'function,\n' |
| 11727 | ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' |
| 11728 | 'method\n' |
| 11729 | ' of socket objects (and perhaps by other functions or methods\n' |
| 11730 | ' provided by extension modules).\n' |
| 11731 | '\n' |
| 11732 | ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11733 | ' initialized to file objects corresponding to the interpreter’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11734 | ' standard input, output and error streams; they are all open in ' |
| 11735 | 'text\n' |
| 11736 | ' mode and therefore follow the interface defined by the\n' |
| 11737 | ' "io.TextIOBase" abstract class.\n' |
| 11738 | '\n' |
| 11739 | 'Internal types\n' |
| 11740 | ' A few types used internally by the interpreter are exposed to ' |
| 11741 | 'the\n' |
| 11742 | ' user. Their definitions may change with future versions of the\n' |
| 11743 | ' interpreter, but they are mentioned here for completeness.\n' |
| 11744 | '\n' |
| 11745 | ' Code objects\n' |
| 11746 | ' Code objects represent *byte-compiled* executable Python ' |
| 11747 | 'code,\n' |
| 11748 | ' or *bytecode*. The difference between a code object and a\n' |
| 11749 | ' function object is that the function object contains an ' |
| 11750 | 'explicit\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11751 | ' reference to the function’s globals (the module in which it ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11752 | 'was\n' |
| 11753 | ' defined), while a code object contains no context; also the\n' |
| 11754 | ' default argument values are stored in the function object, ' |
| 11755 | 'not\n' |
| 11756 | ' in the code object (because they represent values calculated ' |
| 11757 | 'at\n' |
| 11758 | ' run-time). Unlike function objects, code objects are ' |
| 11759 | 'immutable\n' |
| 11760 | ' and contain no references (directly or indirectly) to ' |
| 11761 | 'mutable\n' |
| 11762 | ' objects.\n' |
| 11763 | '\n' |
| 11764 | ' Special read-only attributes: "co_name" gives the function ' |
| 11765 | 'name;\n' |
| 11766 | ' "co_argcount" is the number of positional arguments ' |
| 11767 | '(including\n' |
| 11768 | ' arguments with default values); "co_nlocals" is the number ' |
| 11769 | 'of\n' |
| 11770 | ' local variables used by the function (including arguments);\n' |
| 11771 | ' "co_varnames" is a tuple containing the names of the local\n' |
| 11772 | ' variables (starting with the argument names); "co_cellvars" ' |
| 11773 | 'is a\n' |
| 11774 | ' tuple containing the names of local variables that are\n' |
| 11775 | ' referenced by nested functions; "co_freevars" is a tuple\n' |
| 11776 | ' containing the names of free variables; "co_code" is a ' |
| 11777 | 'string\n' |
| 11778 | ' representing the sequence of bytecode instructions; ' |
| 11779 | '"co_consts"\n' |
| 11780 | ' is a tuple containing the literals used by the bytecode;\n' |
| 11781 | ' "co_names" is a tuple containing the names used by the ' |
| 11782 | 'bytecode;\n' |
| 11783 | ' "co_filename" is the filename from which the code was ' |
| 11784 | 'compiled;\n' |
| 11785 | ' "co_firstlineno" is the first line number of the function;\n' |
| 11786 | ' "co_lnotab" is a string encoding the mapping from bytecode\n' |
| 11787 | ' offsets to line numbers (for details see the source code of ' |
| 11788 | 'the\n' |
| 11789 | ' interpreter); "co_stacksize" is the required stack size\n' |
| 11790 | ' (including local variables); "co_flags" is an integer ' |
| 11791 | 'encoding a\n' |
| 11792 | ' number of flags for the interpreter.\n' |
| 11793 | '\n' |
| 11794 | ' The following flag bits are defined for "co_flags": bit ' |
| 11795 | '"0x04"\n' |
| 11796 | ' is set if the function uses the "*arguments" syntax to accept ' |
| 11797 | 'an\n' |
| 11798 | ' arbitrary number of positional arguments; bit "0x08" is set ' |
| 11799 | 'if\n' |
| 11800 | ' the function uses the "**keywords" syntax to accept ' |
| 11801 | 'arbitrary\n' |
| 11802 | ' keyword arguments; bit "0x20" is set if the function is a\n' |
| 11803 | ' generator.\n' |
| 11804 | '\n' |
| 11805 | ' Future feature declarations ("from __future__ import ' |
| 11806 | 'division")\n' |
| 11807 | ' also use bits in "co_flags" to indicate whether a code ' |
| 11808 | 'object\n' |
| 11809 | ' was compiled with a particular feature enabled: bit "0x2000" ' |
| 11810 | 'is\n' |
| 11811 | ' set if the function was compiled with future division ' |
| 11812 | 'enabled;\n' |
| 11813 | ' bits "0x10" and "0x1000" were used in earlier versions of\n' |
| 11814 | ' Python.\n' |
| 11815 | '\n' |
| 11816 | ' Other bits in "co_flags" are reserved for internal use.\n' |
| 11817 | '\n' |
| 11818 | ' If a code object represents a function, the first item in\n' |
| 11819 | ' "co_consts" is the documentation string of the function, or\n' |
| 11820 | ' "None" if undefined.\n' |
| 11821 | '\n' |
| 11822 | ' Frame objects\n' |
| 11823 | ' Frame objects represent execution frames. They may occur in\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11824 | ' traceback objects (see below), and are also passed to ' |
| 11825 | 'registered\n' |
| 11826 | ' trace functions.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11827 | '\n' |
| 11828 | ' Special read-only attributes: "f_back" is to the previous ' |
| 11829 | 'stack\n' |
| 11830 | ' frame (towards the caller), or "None" if this is the bottom\n' |
| 11831 | ' stack frame; "f_code" is the code object being executed in ' |
| 11832 | 'this\n' |
| 11833 | ' frame; "f_locals" is the dictionary used to look up local\n' |
| 11834 | ' variables; "f_globals" is used for global variables;\n' |
| 11835 | ' "f_builtins" is used for built-in (intrinsic) names; ' |
| 11836 | '"f_lasti"\n' |
| 11837 | ' gives the precise instruction (this is an index into the\n' |
| 11838 | ' bytecode string of the code object).\n' |
| 11839 | '\n' |
| 11840 | ' Special writable attributes: "f_trace", if not "None", is a\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11841 | ' function called for various events during code execution ' |
| 11842 | '(this\n' |
| 11843 | ' is used by the debugger). Normally an event is triggered for\n' |
| 11844 | ' each new source line - this can be disabled by setting\n' |
| 11845 | ' "f_trace_lines" to "False".\n' |
| 11846 | '\n' |
| 11847 | ' Implementations *may* allow per-opcode events to be requested ' |
| 11848 | 'by\n' |
| 11849 | ' setting "f_trace_opcodes" to "True". Note that this may lead ' |
| 11850 | 'to\n' |
| 11851 | ' undefined interpreter behaviour if exceptions raised by the\n' |
| 11852 | ' trace function escape to the function being traced.\n' |
| 11853 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11854 | ' "f_lineno" is the current line number of the frame — writing ' |
| 11855 | 'to\n' |
| 11856 | ' this from within a trace function jumps to the given line ' |
| 11857 | '(only\n' |
| 11858 | ' for the bottom-most frame). A debugger can implement a Jump\n' |
| 11859 | ' command (aka Set Next Statement) by writing to f_lineno.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11860 | '\n' |
| 11861 | ' Frame objects support one method:\n' |
| 11862 | '\n' |
| 11863 | ' frame.clear()\n' |
| 11864 | '\n' |
| 11865 | ' This method clears all references to local variables held ' |
| 11866 | 'by\n' |
| 11867 | ' the frame. Also, if the frame belonged to a generator, ' |
| 11868 | 'the\n' |
| 11869 | ' generator is finalized. This helps break reference ' |
| 11870 | 'cycles\n' |
| 11871 | ' involving frame objects (for example when catching an\n' |
| 11872 | ' exception and storing its traceback for later use).\n' |
| 11873 | '\n' |
| 11874 | ' "RuntimeError" is raised if the frame is currently ' |
| 11875 | 'executing.\n' |
| 11876 | '\n' |
| 11877 | ' New in version 3.4.\n' |
| 11878 | '\n' |
| 11879 | ' Traceback objects\n' |
| 11880 | ' Traceback objects represent a stack trace of an exception. ' |
| 11881 | 'A\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11882 | ' traceback object is implicitly created when an exception ' |
| 11883 | 'occurs,\n' |
| 11884 | ' and may also be explicitly created by calling\n' |
| 11885 | ' "types.TracebackType".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11886 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11887 | ' For implicitly created tracebacks, when the search for an\n' |
| 11888 | ' exception handler unwinds the execution stack, at each ' |
| 11889 | 'unwound\n' |
| 11890 | ' level a traceback object is inserted in front of the current\n' |
| 11891 | ' traceback. When an exception handler is entered, the stack\n' |
| 11892 | ' trace is made available to the program. (See section The try\n' |
| 11893 | ' statement.) It is accessible as the third item of the tuple\n' |
| 11894 | ' returned by "sys.exc_info()", and as the "__traceback__"\n' |
| 11895 | ' attribute of the caught exception.\n' |
| 11896 | '\n' |
| 11897 | ' When the program contains no suitable handler, the stack ' |
| 11898 | 'trace\n' |
| 11899 | ' is written (nicely formatted) to the standard error stream; ' |
| 11900 | 'if\n' |
| 11901 | ' the interpreter is interactive, it is also made available to ' |
| 11902 | 'the\n' |
| 11903 | ' user as "sys.last_traceback".\n' |
| 11904 | '\n' |
| 11905 | ' For explicitly created tracebacks, it is up to the creator ' |
| 11906 | 'of\n' |
| 11907 | ' the traceback to determine how the "tb_next" attributes ' |
| 11908 | 'should\n' |
| 11909 | ' be linked to form a full stack trace.\n' |
| 11910 | '\n' |
| 11911 | ' Special read-only attributes: "tb_frame" points to the ' |
| 11912 | 'execution\n' |
| 11913 | ' frame of the current level; "tb_lineno" gives the line ' |
| 11914 | 'number\n' |
| 11915 | ' where the exception occurred; "tb_lasti" indicates the ' |
| 11916 | 'precise\n' |
| 11917 | ' instruction. The line number and last instruction in the\n' |
| 11918 | ' traceback may differ from the line number of its frame object ' |
| 11919 | 'if\n' |
| 11920 | ' the exception occurred in a "try" statement with no matching\n' |
| 11921 | ' except clause or with a finally clause.\n' |
| 11922 | '\n' |
| 11923 | ' Special writable attribute: "tb_next" is the next level in ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11924 | 'the\n' |
| 11925 | ' stack trace (towards the frame where the exception occurred), ' |
| 11926 | 'or\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11927 | ' "None" if there is no next level.\n' |
| 11928 | '\n' |
| 11929 | ' Changed in version 3.7: Traceback objects can now be ' |
| 11930 | 'explicitly\n' |
| 11931 | ' instantiated from Python code, and the "tb_next" attribute ' |
| 11932 | 'of\n' |
| 11933 | ' existing instances can be updated.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11934 | '\n' |
| 11935 | ' Slice objects\n' |
| 11936 | ' Slice objects are used to represent slices for ' |
| 11937 | '"__getitem__()"\n' |
| 11938 | ' methods. They are also created by the built-in "slice()"\n' |
| 11939 | ' function.\n' |
| 11940 | '\n' |
| 11941 | ' Special read-only attributes: "start" is the lower bound; ' |
| 11942 | '"stop"\n' |
| 11943 | ' is the upper bound; "step" is the step value; each is "None" ' |
| 11944 | 'if\n' |
| 11945 | ' omitted. These attributes can have any type.\n' |
| 11946 | '\n' |
| 11947 | ' Slice objects support one method:\n' |
| 11948 | '\n' |
| 11949 | ' slice.indices(self, length)\n' |
| 11950 | '\n' |
| 11951 | ' This method takes a single integer argument *length* and\n' |
| 11952 | ' computes information about the slice that the slice ' |
| 11953 | 'object\n' |
| 11954 | ' would describe if applied to a sequence of *length* ' |
| 11955 | 'items.\n' |
| 11956 | ' It returns a tuple of three integers; respectively these ' |
| 11957 | 'are\n' |
| 11958 | ' the *start* and *stop* indices and the *step* or stride\n' |
| 11959 | ' length of the slice. Missing or out-of-bounds indices are\n' |
| 11960 | ' handled in a manner consistent with regular slices.\n' |
| 11961 | '\n' |
| 11962 | ' Static method objects\n' |
| 11963 | ' Static method objects provide a way of defeating the\n' |
| 11964 | ' transformation of function objects to method objects ' |
| 11965 | 'described\n' |
| 11966 | ' above. A static method object is a wrapper around any other\n' |
| 11967 | ' object, usually a user-defined method object. When a static\n' |
| 11968 | ' method object is retrieved from a class or a class instance, ' |
| 11969 | 'the\n' |
| 11970 | ' object actually returned is the wrapped object, which is not\n' |
| 11971 | ' subject to any further transformation. Static method objects ' |
| 11972 | 'are\n' |
| 11973 | ' not themselves callable, although the objects they wrap ' |
| 11974 | 'usually\n' |
| 11975 | ' are. Static method objects are created by the built-in\n' |
| 11976 | ' "staticmethod()" constructor.\n' |
| 11977 | '\n' |
| 11978 | ' Class method objects\n' |
| 11979 | ' A class method object, like a static method object, is a ' |
| 11980 | 'wrapper\n' |
| 11981 | ' around another object that alters the way in which that ' |
| 11982 | 'object\n' |
| 11983 | ' is retrieved from classes and class instances. The behaviour ' |
| 11984 | 'of\n' |
| 11985 | ' class method objects upon such retrieval is described above,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 11986 | ' under “User-defined methods”. Class method objects are ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11987 | 'created\n' |
| 11988 | ' by the built-in "classmethod()" constructor.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11989 | 'typesfunctions': 'Functions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11990 | '*********\n' |
| 11991 | '\n' |
| 11992 | 'Function objects are created by function definitions. The ' |
| 11993 | 'only\n' |
| 11994 | 'operation on a function object is to call it: ' |
| 11995 | '"func(argument-list)".\n' |
| 11996 | '\n' |
| 11997 | 'There are really two flavors of function objects: built-in ' |
| 11998 | 'functions\n' |
| 11999 | 'and user-defined functions. Both support the same ' |
| 12000 | 'operation (to call\n' |
| 12001 | 'the function), but the implementation is different, hence ' |
| 12002 | 'the\n' |
| 12003 | 'different object types.\n' |
| 12004 | '\n' |
| 12005 | 'See Function definitions for more information.\n', |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12006 | 'typesmapping': 'Mapping Types — "dict"\n' |
| 12007 | '**********************\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12008 | '\n' |
| 12009 | 'A *mapping* object maps *hashable* values to arbitrary ' |
| 12010 | 'objects.\n' |
| 12011 | 'Mappings are mutable objects. There is currently only one ' |
| 12012 | 'standard\n' |
| 12013 | 'mapping type, the *dictionary*. (For other containers see ' |
| 12014 | 'the built-\n' |
| 12015 | 'in "list", "set", and "tuple" classes, and the "collections" ' |
| 12016 | 'module.)\n' |
| 12017 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12018 | 'A dictionary’s keys are *almost* arbitrary values. Values ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12019 | 'that are\n' |
| 12020 | 'not *hashable*, that is, values containing lists, ' |
| 12021 | 'dictionaries or\n' |
| 12022 | 'other mutable types (that are compared by value rather than ' |
| 12023 | 'by object\n' |
| 12024 | 'identity) may not be used as keys. Numeric types used for ' |
| 12025 | 'keys obey\n' |
| 12026 | 'the normal rules for numeric comparison: if two numbers ' |
| 12027 | 'compare equal\n' |
| 12028 | '(such as "1" and "1.0") then they can be used ' |
| 12029 | 'interchangeably to index\n' |
| 12030 | 'the same dictionary entry. (Note however, that since ' |
| 12031 | 'computers store\n' |
| 12032 | 'floating-point numbers as approximations it is usually ' |
| 12033 | 'unwise to use\n' |
| 12034 | 'them as dictionary keys.)\n' |
| 12035 | '\n' |
| 12036 | 'Dictionaries can be created by placing a comma-separated ' |
| 12037 | 'list of "key:\n' |
| 12038 | 'value" pairs within braces, for example: "{\'jack\': 4098, ' |
| 12039 | "'sjoerd':\n" |
| 12040 | '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' |
| 12041 | '"dict"\n' |
| 12042 | 'constructor.\n' |
| 12043 | '\n' |
| 12044 | 'class dict(**kwarg)\n' |
| 12045 | 'class dict(mapping, **kwarg)\n' |
| 12046 | 'class dict(iterable, **kwarg)\n' |
| 12047 | '\n' |
| 12048 | ' Return a new dictionary initialized from an optional ' |
| 12049 | 'positional\n' |
| 12050 | ' argument and a possibly empty set of keyword arguments.\n' |
| 12051 | '\n' |
| 12052 | ' If no positional argument is given, an empty dictionary ' |
| 12053 | 'is created.\n' |
| 12054 | ' If a positional argument is given and it is a mapping ' |
| 12055 | 'object, a\n' |
| 12056 | ' dictionary is created with the same key-value pairs as ' |
| 12057 | 'the mapping\n' |
| 12058 | ' object. Otherwise, the positional argument must be an ' |
| 12059 | '*iterable*\n' |
| 12060 | ' object. Each item in the iterable must itself be an ' |
| 12061 | 'iterable with\n' |
| 12062 | ' exactly two objects. The first object of each item ' |
| 12063 | 'becomes a key\n' |
| 12064 | ' in the new dictionary, and the second object the ' |
| 12065 | 'corresponding\n' |
| 12066 | ' value. If a key occurs more than once, the last value ' |
| 12067 | 'for that key\n' |
| 12068 | ' becomes the corresponding value in the new dictionary.\n' |
| 12069 | '\n' |
| 12070 | ' If keyword arguments are given, the keyword arguments and ' |
| 12071 | 'their\n' |
| 12072 | ' values are added to the dictionary created from the ' |
| 12073 | 'positional\n' |
| 12074 | ' argument. If a key being added is already present, the ' |
| 12075 | 'value from\n' |
| 12076 | ' the keyword argument replaces the value from the ' |
| 12077 | 'positional\n' |
| 12078 | ' argument.\n' |
| 12079 | '\n' |
| 12080 | ' To illustrate, the following examples all return a ' |
| 12081 | 'dictionary equal\n' |
| 12082 | ' to "{"one": 1, "two": 2, "three": 3}":\n' |
| 12083 | '\n' |
| 12084 | ' >>> a = dict(one=1, two=2, three=3)\n' |
| 12085 | " >>> b = {'one': 1, 'two': 2, 'three': 3}\n" |
| 12086 | " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n" |
| 12087 | " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n" |
| 12088 | " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" |
| 12089 | ' >>> a == b == c == d == e\n' |
| 12090 | ' True\n' |
| 12091 | '\n' |
| 12092 | ' Providing keyword arguments as in the first example only ' |
| 12093 | 'works for\n' |
| 12094 | ' keys that are valid Python identifiers. Otherwise, any ' |
| 12095 | 'valid keys\n' |
| 12096 | ' can be used.\n' |
| 12097 | '\n' |
| 12098 | ' These are the operations that dictionaries support (and ' |
| 12099 | 'therefore,\n' |
| 12100 | ' custom mapping types should support too):\n' |
| 12101 | '\n' |
| 12102 | ' len(d)\n' |
| 12103 | '\n' |
| 12104 | ' Return the number of items in the dictionary *d*.\n' |
| 12105 | '\n' |
| 12106 | ' d[key]\n' |
| 12107 | '\n' |
| 12108 | ' Return the item of *d* with key *key*. Raises a ' |
| 12109 | '"KeyError" if\n' |
| 12110 | ' *key* is not in the map.\n' |
| 12111 | '\n' |
| 12112 | ' If a subclass of dict defines a method "__missing__()" ' |
| 12113 | 'and *key*\n' |
| 12114 | ' is not present, the "d[key]" operation calls that ' |
| 12115 | 'method with\n' |
| 12116 | ' the key *key* as argument. The "d[key]" operation ' |
| 12117 | 'then returns\n' |
| 12118 | ' or raises whatever is returned or raised by the\n' |
| 12119 | ' "__missing__(key)" call. No other operations or ' |
| 12120 | 'methods invoke\n' |
| 12121 | ' "__missing__()". If "__missing__()" is not defined, ' |
| 12122 | '"KeyError"\n' |
| 12123 | ' is raised. "__missing__()" must be a method; it cannot ' |
| 12124 | 'be an\n' |
| 12125 | ' instance variable:\n' |
| 12126 | '\n' |
| 12127 | ' >>> class Counter(dict):\n' |
| 12128 | ' ... def __missing__(self, key):\n' |
| 12129 | ' ... return 0\n' |
| 12130 | ' >>> c = Counter()\n' |
| 12131 | " >>> c['red']\n" |
| 12132 | ' 0\n' |
| 12133 | " >>> c['red'] += 1\n" |
| 12134 | " >>> c['red']\n" |
| 12135 | ' 1\n' |
| 12136 | '\n' |
| 12137 | ' The example above shows part of the implementation of\n' |
| 12138 | ' "collections.Counter". A different "__missing__" ' |
| 12139 | 'method is used\n' |
| 12140 | ' by "collections.defaultdict".\n' |
| 12141 | '\n' |
| 12142 | ' d[key] = value\n' |
| 12143 | '\n' |
| 12144 | ' Set "d[key]" to *value*.\n' |
| 12145 | '\n' |
| 12146 | ' del d[key]\n' |
| 12147 | '\n' |
| 12148 | ' Remove "d[key]" from *d*. Raises a "KeyError" if ' |
| 12149 | '*key* is not\n' |
| 12150 | ' in the map.\n' |
| 12151 | '\n' |
| 12152 | ' key in d\n' |
| 12153 | '\n' |
| 12154 | ' Return "True" if *d* has a key *key*, else "False".\n' |
| 12155 | '\n' |
| 12156 | ' key not in d\n' |
| 12157 | '\n' |
| 12158 | ' Equivalent to "not key in d".\n' |
| 12159 | '\n' |
| 12160 | ' iter(d)\n' |
| 12161 | '\n' |
| 12162 | ' Return an iterator over the keys of the dictionary. ' |
| 12163 | 'This is a\n' |
| 12164 | ' shortcut for "iter(d.keys())".\n' |
| 12165 | '\n' |
| 12166 | ' clear()\n' |
| 12167 | '\n' |
| 12168 | ' Remove all items from the dictionary.\n' |
| 12169 | '\n' |
| 12170 | ' copy()\n' |
| 12171 | '\n' |
| 12172 | ' Return a shallow copy of the dictionary.\n' |
| 12173 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12174 | ' classmethod fromkeys(iterable[, value])\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12175 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12176 | ' Create a new dictionary with keys from *iterable* and ' |
| 12177 | 'values set\n' |
| 12178 | ' to *value*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12179 | '\n' |
| 12180 | ' "fromkeys()" is a class method that returns a new ' |
| 12181 | 'dictionary.\n' |
Łukasz Langa | c1004b8 | 2019-05-06 20:30:25 +0200 | [diff] [blame] | 12182 | ' *value* defaults to "None". All of the values refer ' |
| 12183 | 'to just a\n' |
| 12184 | ' single instance, so it generally doesn’t make sense ' |
| 12185 | 'for *value*\n' |
| 12186 | ' to be a mutable object such as an empty list. To get ' |
| 12187 | 'distinct\n' |
| 12188 | ' values, use a dict comprehension instead.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12189 | '\n' |
| 12190 | ' get(key[, default])\n' |
| 12191 | '\n' |
| 12192 | ' Return the value for *key* if *key* is in the ' |
| 12193 | 'dictionary, else\n' |
| 12194 | ' *default*. If *default* is not given, it defaults to ' |
| 12195 | '"None", so\n' |
| 12196 | ' that this method never raises a "KeyError".\n' |
| 12197 | '\n' |
| 12198 | ' items()\n' |
| 12199 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12200 | ' Return a new view of the dictionary’s items ("(key, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12201 | 'value)"\n' |
| 12202 | ' pairs). See the documentation of view objects.\n' |
| 12203 | '\n' |
| 12204 | ' keys()\n' |
| 12205 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12206 | ' Return a new view of the dictionary’s keys. See the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12207 | ' documentation of view objects.\n' |
| 12208 | '\n' |
| 12209 | ' pop(key[, default])\n' |
| 12210 | '\n' |
| 12211 | ' If *key* is in the dictionary, remove it and return ' |
| 12212 | 'its value,\n' |
| 12213 | ' else return *default*. If *default* is not given and ' |
| 12214 | '*key* is\n' |
| 12215 | ' not in the dictionary, a "KeyError" is raised.\n' |
| 12216 | '\n' |
| 12217 | ' popitem()\n' |
| 12218 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12219 | ' Remove and return a "(key, value)" pair from the ' |
| 12220 | 'dictionary.\n' |
| 12221 | ' Pairs are returned in LIFO (last-in, first-out) ' |
| 12222 | 'order.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12223 | '\n' |
| 12224 | ' "popitem()" is useful to destructively iterate over a\n' |
| 12225 | ' dictionary, as often used in set algorithms. If the ' |
| 12226 | 'dictionary\n' |
| 12227 | ' is empty, calling "popitem()" raises a "KeyError".\n' |
| 12228 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12229 | ' Changed in version 3.7: LIFO order is now guaranteed. ' |
| 12230 | 'In prior\n' |
| 12231 | ' versions, "popitem()" would return an arbitrary ' |
| 12232 | 'key/value pair.\n' |
| 12233 | '\n' |
| 12234 | ' reversed(d)\n' |
| 12235 | '\n' |
| 12236 | ' Return a reverse iterator over the keys of the ' |
| 12237 | 'dictionary. This\n' |
| 12238 | ' is a shortcut for "reversed(d.keys())".\n' |
| 12239 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12240 | ' setdefault(key[, default])\n' |
| 12241 | '\n' |
| 12242 | ' If *key* is in the dictionary, return its value. If ' |
| 12243 | 'not, insert\n' |
| 12244 | ' *key* with a value of *default* and return *default*. ' |
| 12245 | '*default*\n' |
| 12246 | ' defaults to "None".\n' |
| 12247 | '\n' |
| 12248 | ' update([other])\n' |
| 12249 | '\n' |
| 12250 | ' Update the dictionary with the key/value pairs from ' |
| 12251 | '*other*,\n' |
| 12252 | ' overwriting existing keys. Return "None".\n' |
| 12253 | '\n' |
| 12254 | ' "update()" accepts either another dictionary object or ' |
| 12255 | 'an\n' |
| 12256 | ' iterable of key/value pairs (as tuples or other ' |
| 12257 | 'iterables of\n' |
| 12258 | ' length two). If keyword arguments are specified, the ' |
| 12259 | 'dictionary\n' |
| 12260 | ' is then updated with those key/value pairs: ' |
| 12261 | '"d.update(red=1,\n' |
| 12262 | ' blue=2)".\n' |
| 12263 | '\n' |
| 12264 | ' values()\n' |
| 12265 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12266 | ' Return a new view of the dictionary’s values. See ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12267 | 'the\n' |
| 12268 | ' documentation of view objects.\n' |
| 12269 | '\n' |
| 12270 | ' Dictionaries compare equal if and only if they have the ' |
| 12271 | 'same "(key,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12272 | ' value)" pairs. Order comparisons (‘<’, ‘<=’, ‘>=’, ‘>’) ' |
| 12273 | 'raise\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12274 | ' "TypeError".\n' |
| 12275 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12276 | ' Dictionaries preserve insertion order. Note that ' |
| 12277 | 'updating a key\n' |
| 12278 | ' does not affect the order. Keys added after deletion are ' |
| 12279 | 'inserted\n' |
| 12280 | ' at the end.\n' |
| 12281 | '\n' |
| 12282 | ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' |
| 12283 | ' >>> d\n' |
| 12284 | " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" |
| 12285 | ' >>> list(d)\n' |
| 12286 | " ['one', 'two', 'three', 'four']\n" |
| 12287 | ' >>> list(d.values())\n' |
| 12288 | ' [1, 2, 3, 4]\n' |
| 12289 | ' >>> d["one"] = 42\n' |
| 12290 | ' >>> d\n' |
| 12291 | " {'one': 42, 'two': 2, 'three': 3, 'four': 4}\n" |
| 12292 | ' >>> del d["two"]\n' |
| 12293 | ' >>> d["two"] = None\n' |
| 12294 | ' >>> d\n' |
| 12295 | " {'one': 42, 'three': 3, 'four': 4, 'two': None}\n" |
| 12296 | '\n' |
| 12297 | ' Changed in version 3.7: Dictionary order is guaranteed to ' |
| 12298 | 'be\n' |
| 12299 | ' insertion order. This behavior was an implementation ' |
| 12300 | 'detail of\n' |
| 12301 | ' CPython from 3.6.\n' |
| 12302 | '\n' |
| 12303 | ' Dictionaries and dictionary views are reversible.\n' |
| 12304 | '\n' |
| 12305 | ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' |
| 12306 | ' >>> d\n' |
| 12307 | " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" |
| 12308 | ' >>> list(reversed(d))\n' |
| 12309 | " ['four', 'three', 'two', 'one']\n" |
| 12310 | ' >>> list(reversed(d.values()))\n' |
| 12311 | ' [4, 3, 2, 1]\n' |
| 12312 | ' >>> list(reversed(d.items()))\n' |
| 12313 | " [('four', 4), ('three', 3), ('two', 2), ('one', 1)]\n" |
| 12314 | '\n' |
| 12315 | ' Changed in version 3.8: Dictionaries are now reversible.\n' |
| 12316 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12317 | 'See also: "types.MappingProxyType" can be used to create a ' |
| 12318 | 'read-only\n' |
| 12319 | ' view of a "dict".\n' |
| 12320 | '\n' |
| 12321 | '\n' |
| 12322 | 'Dictionary view objects\n' |
| 12323 | '=======================\n' |
| 12324 | '\n' |
| 12325 | 'The objects returned by "dict.keys()", "dict.values()" and\n' |
| 12326 | '"dict.items()" are *view objects*. They provide a dynamic ' |
| 12327 | 'view on the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12328 | 'dictionary’s entries, which means that when the dictionary ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12329 | 'changes,\n' |
| 12330 | 'the view reflects these changes.\n' |
| 12331 | '\n' |
| 12332 | 'Dictionary views can be iterated over to yield their ' |
| 12333 | 'respective data,\n' |
| 12334 | 'and support membership tests:\n' |
| 12335 | '\n' |
| 12336 | 'len(dictview)\n' |
| 12337 | '\n' |
| 12338 | ' Return the number of entries in the dictionary.\n' |
| 12339 | '\n' |
| 12340 | 'iter(dictview)\n' |
| 12341 | '\n' |
| 12342 | ' Return an iterator over the keys, values or items ' |
| 12343 | '(represented as\n' |
| 12344 | ' tuples of "(key, value)") in the dictionary.\n' |
| 12345 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12346 | ' Keys and values are iterated over in insertion order. ' |
| 12347 | 'This allows\n' |
| 12348 | ' the creation of "(value, key)" pairs using "zip()": ' |
| 12349 | '"pairs =\n' |
| 12350 | ' zip(d.values(), d.keys())". Another way to create the ' |
| 12351 | 'same list is\n' |
| 12352 | ' "pairs = [(v, k) for (k, v) in d.items()]".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12353 | '\n' |
| 12354 | ' Iterating views while adding or deleting entries in the ' |
| 12355 | 'dictionary\n' |
| 12356 | ' may raise a "RuntimeError" or fail to iterate over all ' |
| 12357 | 'entries.\n' |
| 12358 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12359 | ' Changed in version 3.7: Dictionary order is guaranteed to ' |
| 12360 | 'be\n' |
| 12361 | ' insertion order.\n' |
| 12362 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12363 | 'x in dictview\n' |
| 12364 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12365 | ' Return "True" if *x* is in the underlying dictionary’s ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12366 | 'keys, values\n' |
| 12367 | ' or items (in the latter case, *x* should be a "(key, ' |
| 12368 | 'value)"\n' |
| 12369 | ' tuple).\n' |
| 12370 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12371 | 'reversed(dictview)\n' |
| 12372 | '\n' |
| 12373 | ' Return a reverse iterator over the keys, values or items ' |
| 12374 | 'of the\n' |
| 12375 | ' dictionary. The view will be iterated in reverse order of ' |
| 12376 | 'the\n' |
| 12377 | ' insertion.\n' |
| 12378 | '\n' |
| 12379 | ' Changed in version 3.8: Dictionary views are now ' |
| 12380 | 'reversible.\n' |
| 12381 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12382 | 'Keys views are set-like since their entries are unique and ' |
| 12383 | 'hashable.\n' |
| 12384 | 'If all values are hashable, so that "(key, value)" pairs are ' |
| 12385 | 'unique\n' |
| 12386 | 'and hashable, then the items view is also set-like. (Values ' |
| 12387 | 'views are\n' |
| 12388 | 'not treated as set-like since the entries are generally not ' |
| 12389 | 'unique.)\n' |
| 12390 | 'For set-like views, all of the operations defined for the ' |
| 12391 | 'abstract\n' |
| 12392 | 'base class "collections.abc.Set" are available (for example, ' |
| 12393 | '"==",\n' |
| 12394 | '"<", or "^").\n' |
| 12395 | '\n' |
| 12396 | 'An example of dictionary view usage:\n' |
| 12397 | '\n' |
| 12398 | " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " |
| 12399 | "'spam': 500}\n" |
| 12400 | ' >>> keys = dishes.keys()\n' |
| 12401 | ' >>> values = dishes.values()\n' |
| 12402 | '\n' |
| 12403 | ' >>> # iteration\n' |
| 12404 | ' >>> n = 0\n' |
| 12405 | ' >>> for val in values:\n' |
| 12406 | ' ... n += val\n' |
| 12407 | ' >>> print(n)\n' |
| 12408 | ' 504\n' |
| 12409 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12410 | ' >>> # keys and values are iterated over in the same order ' |
| 12411 | '(insertion order)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12412 | ' >>> list(keys)\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12413 | " ['eggs', 'sausage', 'bacon', 'spam']\n" |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12414 | ' >>> list(values)\n' |
| 12415 | ' [2, 1, 1, 500]\n' |
| 12416 | '\n' |
| 12417 | ' >>> # view objects are dynamic and reflect dict changes\n' |
| 12418 | " >>> del dishes['eggs']\n" |
| 12419 | " >>> del dishes['sausage']\n" |
| 12420 | ' >>> list(keys)\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12421 | " ['bacon', 'spam']\n" |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12422 | '\n' |
| 12423 | ' >>> # set operations\n' |
| 12424 | " >>> keys & {'eggs', 'bacon', 'salad'}\n" |
| 12425 | " {'bacon'}\n" |
| 12426 | " >>> keys ^ {'sausage', 'juice'}\n" |
| 12427 | " {'juice', 'sausage', 'bacon', 'spam'}\n", |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12428 | 'typesmethods': 'Methods\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12429 | '*******\n' |
| 12430 | '\n' |
| 12431 | 'Methods are functions that are called using the attribute ' |
| 12432 | 'notation.\n' |
| 12433 | 'There are two flavors: built-in methods (such as "append()" ' |
| 12434 | 'on lists)\n' |
| 12435 | 'and class instance methods. Built-in methods are described ' |
| 12436 | 'with the\n' |
| 12437 | 'types that support them.\n' |
| 12438 | '\n' |
| 12439 | 'If you access a method (a function defined in a class ' |
| 12440 | 'namespace)\n' |
| 12441 | 'through an instance, you get a special object: a *bound ' |
| 12442 | 'method* (also\n' |
| 12443 | 'called *instance method*) object. When called, it will add ' |
| 12444 | 'the "self"\n' |
| 12445 | 'argument to the argument list. Bound methods have two ' |
| 12446 | 'special read-\n' |
| 12447 | 'only attributes: "m.__self__" is the object on which the ' |
| 12448 | 'method\n' |
| 12449 | 'operates, and "m.__func__" is the function implementing the ' |
| 12450 | 'method.\n' |
| 12451 | 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' |
| 12452 | 'equivalent to\n' |
| 12453 | 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n' |
| 12454 | '\n' |
| 12455 | 'Like function objects, bound method objects support getting ' |
| 12456 | 'arbitrary\n' |
| 12457 | 'attributes. However, since method attributes are actually ' |
| 12458 | 'stored on\n' |
| 12459 | 'the underlying function object ("meth.__func__"), setting ' |
| 12460 | 'method\n' |
| 12461 | 'attributes on bound methods is disallowed. Attempting to ' |
| 12462 | 'set an\n' |
| 12463 | 'attribute on a method results in an "AttributeError" being ' |
| 12464 | 'raised. In\n' |
| 12465 | 'order to set a method attribute, you need to explicitly set ' |
| 12466 | 'it on the\n' |
| 12467 | 'underlying function object:\n' |
| 12468 | '\n' |
| 12469 | ' >>> class C:\n' |
| 12470 | ' ... def method(self):\n' |
| 12471 | ' ... pass\n' |
| 12472 | ' ...\n' |
| 12473 | ' >>> c = C()\n' |
| 12474 | " >>> c.method.whoami = 'my name is method' # can't set on " |
| 12475 | 'the method\n' |
| 12476 | ' Traceback (most recent call last):\n' |
| 12477 | ' File "<stdin>", line 1, in <module>\n' |
| 12478 | " AttributeError: 'method' object has no attribute " |
| 12479 | "'whoami'\n" |
| 12480 | " >>> c.method.__func__.whoami = 'my name is method'\n" |
| 12481 | ' >>> c.method.whoami\n' |
| 12482 | " 'my name is method'\n" |
| 12483 | '\n' |
| 12484 | 'See The standard type hierarchy for more information.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12485 | 'typesmodules': 'Modules\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12486 | '*******\n' |
| 12487 | '\n' |
| 12488 | 'The only special operation on a module is attribute access: ' |
| 12489 | '"m.name",\n' |
| 12490 | 'where *m* is a module and *name* accesses a name defined in ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12491 | '*m*’s\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12492 | 'symbol table. Module attributes can be assigned to. (Note ' |
| 12493 | 'that the\n' |
| 12494 | '"import" statement is not, strictly speaking, an operation ' |
| 12495 | 'on a module\n' |
| 12496 | 'object; "import foo" does not require a module object named ' |
| 12497 | '*foo* to\n' |
| 12498 | 'exist, rather it requires an (external) *definition* for a ' |
| 12499 | 'module\n' |
| 12500 | 'named *foo* somewhere.)\n' |
| 12501 | '\n' |
| 12502 | 'A special attribute of every module is "__dict__". This is ' |
| 12503 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12504 | 'dictionary containing the module’s symbol table. Modifying ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12505 | 'this\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12506 | 'dictionary will actually change the module’s symbol table, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12507 | 'but direct\n' |
| 12508 | 'assignment to the "__dict__" attribute is not possible (you ' |
| 12509 | 'can write\n' |
| 12510 | '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12511 | 'you can’t\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12512 | 'write "m.__dict__ = {}"). Modifying "__dict__" directly is ' |
| 12513 | 'not\n' |
| 12514 | 'recommended.\n' |
| 12515 | '\n' |
| 12516 | 'Modules built into the interpreter are written like this: ' |
| 12517 | '"<module\n' |
| 12518 | '\'sys\' (built-in)>". If loaded from a file, they are ' |
| 12519 | 'written as\n' |
| 12520 | '"<module \'os\' from ' |
| 12521 | '\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n', |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12522 | 'typesseq': 'Sequence Types — "list", "tuple", "range"\n' |
| 12523 | '*****************************************\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12524 | '\n' |
| 12525 | 'There are three basic sequence types: lists, tuples, and range\n' |
| 12526 | 'objects. Additional sequence types tailored for processing of ' |
| 12527 | 'binary\n' |
| 12528 | 'data and text strings are described in dedicated sections.\n' |
| 12529 | '\n' |
| 12530 | '\n' |
| 12531 | 'Common Sequence Operations\n' |
| 12532 | '==========================\n' |
| 12533 | '\n' |
| 12534 | 'The operations in the following table are supported by most ' |
| 12535 | 'sequence\n' |
| 12536 | 'types, both mutable and immutable. The ' |
| 12537 | '"collections.abc.Sequence" ABC\n' |
| 12538 | 'is provided to make it easier to correctly implement these ' |
| 12539 | 'operations\n' |
| 12540 | 'on custom sequence types.\n' |
| 12541 | '\n' |
| 12542 | 'This table lists the sequence operations sorted in ascending ' |
| 12543 | 'priority.\n' |
| 12544 | 'In the table, *s* and *t* are sequences of the same type, *n*, ' |
| 12545 | '*i*,\n' |
| 12546 | '*j* and *k* are integers and *x* is an arbitrary object that ' |
| 12547 | 'meets any\n' |
| 12548 | 'type and value restrictions imposed by *s*.\n' |
| 12549 | '\n' |
| 12550 | 'The "in" and "not in" operations have the same priorities as ' |
| 12551 | 'the\n' |
| 12552 | 'comparison operations. The "+" (concatenation) and "*" ' |
| 12553 | '(repetition)\n' |
| 12554 | 'operations have the same priority as the corresponding numeric\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12555 | 'operations. [3]\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12556 | '\n' |
| 12557 | '+----------------------------+----------------------------------+------------+\n' |
| 12558 | '| Operation | Result ' |
| 12559 | '| Notes |\n' |
| 12560 | '+============================+==================================+============+\n' |
| 12561 | '| "x in s" | "True" if an item of *s* is ' |
| 12562 | '| (1) |\n' |
| 12563 | '| | equal to *x*, else "False" ' |
| 12564 | '| |\n' |
| 12565 | '+----------------------------+----------------------------------+------------+\n' |
| 12566 | '| "x not in s" | "False" if an item of *s* is ' |
| 12567 | '| (1) |\n' |
| 12568 | '| | equal to *x*, else "True" ' |
| 12569 | '| |\n' |
| 12570 | '+----------------------------+----------------------------------+------------+\n' |
| 12571 | '| "s + t" | the concatenation of *s* and *t* ' |
| 12572 | '| (6)(7) |\n' |
| 12573 | '+----------------------------+----------------------------------+------------+\n' |
| 12574 | '| "s * n" or "n * s" | equivalent to adding *s* to ' |
| 12575 | '| (2)(7) |\n' |
| 12576 | '| | itself *n* times ' |
| 12577 | '| |\n' |
| 12578 | '+----------------------------+----------------------------------+------------+\n' |
| 12579 | '| "s[i]" | *i*th item of *s*, origin 0 ' |
| 12580 | '| (3) |\n' |
| 12581 | '+----------------------------+----------------------------------+------------+\n' |
| 12582 | '| "s[i:j]" | slice of *s* from *i* to *j* ' |
| 12583 | '| (3)(4) |\n' |
| 12584 | '+----------------------------+----------------------------------+------------+\n' |
| 12585 | '| "s[i:j:k]" | slice of *s* from *i* to *j* ' |
| 12586 | '| (3)(5) |\n' |
| 12587 | '| | with step *k* ' |
| 12588 | '| |\n' |
| 12589 | '+----------------------------+----------------------------------+------------+\n' |
| 12590 | '| "len(s)" | length of *s* ' |
| 12591 | '| |\n' |
| 12592 | '+----------------------------+----------------------------------+------------+\n' |
| 12593 | '| "min(s)" | smallest item of *s* ' |
| 12594 | '| |\n' |
| 12595 | '+----------------------------+----------------------------------+------------+\n' |
| 12596 | '| "max(s)" | largest item of *s* ' |
| 12597 | '| |\n' |
| 12598 | '+----------------------------+----------------------------------+------------+\n' |
| 12599 | '| "s.index(x[, i[, j]])" | index of the first occurrence of ' |
| 12600 | '| (8) |\n' |
| 12601 | '| | *x* in *s* (at or after index ' |
| 12602 | '| |\n' |
| 12603 | '| | *i* and before index *j*) ' |
| 12604 | '| |\n' |
| 12605 | '+----------------------------+----------------------------------+------------+\n' |
| 12606 | '| "s.count(x)" | total number of occurrences of ' |
| 12607 | '| |\n' |
| 12608 | '| | *x* in *s* ' |
| 12609 | '| |\n' |
| 12610 | '+----------------------------+----------------------------------+------------+\n' |
| 12611 | '\n' |
| 12612 | 'Sequences of the same type also support comparisons. In ' |
| 12613 | 'particular,\n' |
| 12614 | 'tuples and lists are compared lexicographically by comparing\n' |
| 12615 | 'corresponding elements. This means that to compare equal, every\n' |
| 12616 | 'element must compare equal and the two sequences must be of the ' |
| 12617 | 'same\n' |
| 12618 | 'type and have the same length. (For full details see ' |
| 12619 | 'Comparisons in\n' |
| 12620 | 'the language reference.)\n' |
| 12621 | '\n' |
| 12622 | 'Notes:\n' |
| 12623 | '\n' |
| 12624 | '1. While the "in" and "not in" operations are used only for ' |
| 12625 | 'simple\n' |
| 12626 | ' containment testing in the general case, some specialised ' |
| 12627 | 'sequences\n' |
| 12628 | ' (such as "str", "bytes" and "bytearray") also use them for\n' |
| 12629 | ' subsequence testing:\n' |
| 12630 | '\n' |
| 12631 | ' >>> "gg" in "eggs"\n' |
| 12632 | ' True\n' |
| 12633 | '\n' |
| 12634 | '2. Values of *n* less than "0" are treated as "0" (which yields ' |
| 12635 | 'an\n' |
| 12636 | ' empty sequence of the same type as *s*). Note that items in ' |
| 12637 | 'the\n' |
| 12638 | ' sequence *s* are not copied; they are referenced multiple ' |
| 12639 | 'times.\n' |
| 12640 | ' This often haunts new Python programmers; consider:\n' |
| 12641 | '\n' |
| 12642 | ' >>> lists = [[]] * 3\n' |
| 12643 | ' >>> lists\n' |
| 12644 | ' [[], [], []]\n' |
| 12645 | ' >>> lists[0].append(3)\n' |
| 12646 | ' >>> lists\n' |
| 12647 | ' [[3], [3], [3]]\n' |
| 12648 | '\n' |
| 12649 | ' What has happened is that "[[]]" is a one-element list ' |
| 12650 | 'containing\n' |
| 12651 | ' an empty list, so all three elements of "[[]] * 3" are ' |
| 12652 | 'references\n' |
| 12653 | ' to this single empty list. Modifying any of the elements of\n' |
| 12654 | ' "lists" modifies this single list. You can create a list of\n' |
| 12655 | ' different lists this way:\n' |
| 12656 | '\n' |
| 12657 | ' >>> lists = [[] for i in range(3)]\n' |
| 12658 | ' >>> lists[0].append(3)\n' |
| 12659 | ' >>> lists[1].append(5)\n' |
| 12660 | ' >>> lists[2].append(7)\n' |
| 12661 | ' >>> lists\n' |
| 12662 | ' [[3], [5], [7]]\n' |
| 12663 | '\n' |
| 12664 | ' Further explanation is available in the FAQ entry How do I ' |
| 12665 | 'create a\n' |
| 12666 | ' multidimensional list?.\n' |
| 12667 | '\n' |
| 12668 | '3. If *i* or *j* is negative, the index is relative to the end ' |
| 12669 | 'of\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12670 | ' sequence *s*: "len(s) + i" or "len(s) + j" is substituted. ' |
| 12671 | 'But\n' |
| 12672 | ' note that "-0" is still "0".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12673 | '\n' |
| 12674 | '4. The slice of *s* from *i* to *j* is defined as the sequence ' |
| 12675 | 'of\n' |
| 12676 | ' items with index *k* such that "i <= k < j". If *i* or *j* ' |
| 12677 | 'is\n' |
| 12678 | ' greater than "len(s)", use "len(s)". If *i* is omitted or ' |
| 12679 | '"None",\n' |
| 12680 | ' use "0". If *j* is omitted or "None", use "len(s)". If *i* ' |
| 12681 | 'is\n' |
| 12682 | ' greater than or equal to *j*, the slice is empty.\n' |
| 12683 | '\n' |
| 12684 | '5. The slice of *s* from *i* to *j* with step *k* is defined as ' |
| 12685 | 'the\n' |
| 12686 | ' sequence of items with index "x = i + n*k" such that "0 <= n ' |
| 12687 | '<\n' |
| 12688 | ' (j-i)/k". In other words, the indices are "i", "i+k", ' |
| 12689 | '"i+2*k",\n' |
| 12690 | ' "i+3*k" and so on, stopping when *j* is reached (but never\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12691 | ' including *j*). When *k* is positive, *i* and *j* are ' |
| 12692 | 'reduced to\n' |
| 12693 | ' "len(s)" if they are greater. When *k* is negative, *i* and ' |
| 12694 | '*j* are\n' |
| 12695 | ' reduced to "len(s) - 1" if they are greater. If *i* or *j* ' |
| 12696 | 'are\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12697 | ' omitted or "None", they become “end” values (which end ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12698 | 'depends on\n' |
| 12699 | ' the sign of *k*). Note, *k* cannot be zero. If *k* is ' |
| 12700 | '"None", it\n' |
| 12701 | ' is treated like "1".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12702 | '\n' |
| 12703 | '6. Concatenating immutable sequences always results in a new\n' |
| 12704 | ' object. This means that building up a sequence by repeated\n' |
| 12705 | ' concatenation will have a quadratic runtime cost in the ' |
| 12706 | 'total\n' |
| 12707 | ' sequence length. To get a linear runtime cost, you must ' |
| 12708 | 'switch to\n' |
| 12709 | ' one of the alternatives below:\n' |
| 12710 | '\n' |
| 12711 | ' * if concatenating "str" objects, you can build a list and ' |
| 12712 | 'use\n' |
| 12713 | ' "str.join()" at the end or else write to an "io.StringIO"\n' |
| 12714 | ' instance and retrieve its value when complete\n' |
| 12715 | '\n' |
| 12716 | ' * if concatenating "bytes" objects, you can similarly use\n' |
| 12717 | ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' |
| 12718 | ' concatenation with a "bytearray" object. "bytearray" ' |
| 12719 | 'objects are\n' |
| 12720 | ' mutable and have an efficient overallocation mechanism\n' |
| 12721 | '\n' |
| 12722 | ' * if concatenating "tuple" objects, extend a "list" instead\n' |
| 12723 | '\n' |
| 12724 | ' * for other types, investigate the relevant class ' |
| 12725 | 'documentation\n' |
| 12726 | '\n' |
| 12727 | '7. Some sequence types (such as "range") only support item\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12728 | ' sequences that follow specific patterns, and hence don’t ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12729 | 'support\n' |
| 12730 | ' sequence concatenation or repetition.\n' |
| 12731 | '\n' |
| 12732 | '8. "index" raises "ValueError" when *x* is not found in *s*. ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 12733 | 'Not\n' |
| 12734 | ' all implementations support passing the additional arguments ' |
| 12735 | '*i*\n' |
| 12736 | ' and *j*. These arguments allow efficient searching of ' |
| 12737 | 'subsections\n' |
| 12738 | ' of the sequence. Passing the extra arguments is roughly ' |
| 12739 | 'equivalent\n' |
| 12740 | ' to using "s[i:j].index(x)", only without copying any data and ' |
| 12741 | 'with\n' |
| 12742 | ' the returned index being relative to the start of the ' |
| 12743 | 'sequence\n' |
| 12744 | ' rather than the start of the slice.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12745 | '\n' |
| 12746 | '\n' |
| 12747 | 'Immutable Sequence Types\n' |
| 12748 | '========================\n' |
| 12749 | '\n' |
| 12750 | 'The only operation that immutable sequence types generally ' |
| 12751 | 'implement\n' |
| 12752 | 'that is not also implemented by mutable sequence types is ' |
| 12753 | 'support for\n' |
| 12754 | 'the "hash()" built-in.\n' |
| 12755 | '\n' |
| 12756 | 'This support allows immutable sequences, such as "tuple" ' |
| 12757 | 'instances, to\n' |
| 12758 | 'be used as "dict" keys and stored in "set" and "frozenset" ' |
| 12759 | 'instances.\n' |
| 12760 | '\n' |
| 12761 | 'Attempting to hash an immutable sequence that contains ' |
| 12762 | 'unhashable\n' |
| 12763 | 'values will result in "TypeError".\n' |
| 12764 | '\n' |
| 12765 | '\n' |
| 12766 | 'Mutable Sequence Types\n' |
| 12767 | '======================\n' |
| 12768 | '\n' |
| 12769 | 'The operations in the following table are defined on mutable ' |
| 12770 | 'sequence\n' |
| 12771 | 'types. The "collections.abc.MutableSequence" ABC is provided to ' |
| 12772 | 'make\n' |
| 12773 | 'it easier to correctly implement these operations on custom ' |
| 12774 | 'sequence\n' |
| 12775 | 'types.\n' |
| 12776 | '\n' |
| 12777 | 'In the table *s* is an instance of a mutable sequence type, *t* ' |
| 12778 | 'is any\n' |
| 12779 | 'iterable object and *x* is an arbitrary object that meets any ' |
| 12780 | 'type and\n' |
| 12781 | 'value restrictions imposed by *s* (for example, "bytearray" ' |
| 12782 | 'only\n' |
| 12783 | 'accepts integers that meet the value restriction "0 <= x <= ' |
| 12784 | '255").\n' |
| 12785 | '\n' |
| 12786 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12787 | '| Operation | ' |
| 12788 | 'Result | Notes |\n' |
| 12789 | '+================================+==================================+=======================+\n' |
| 12790 | '| "s[i] = x" | item *i* of *s* is replaced ' |
| 12791 | 'by | |\n' |
| 12792 | '| | ' |
| 12793 | '*x* | |\n' |
| 12794 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12795 | '| "s[i:j] = t" | slice of *s* from *i* to *j* ' |
| 12796 | 'is | |\n' |
| 12797 | '| | replaced by the contents of ' |
| 12798 | 'the | |\n' |
| 12799 | '| | iterable ' |
| 12800 | '*t* | |\n' |
| 12801 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12802 | '| "del s[i:j]" | same as "s[i:j] = ' |
| 12803 | '[]" | |\n' |
| 12804 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12805 | '| "s[i:j:k] = t" | the elements of "s[i:j:k]" ' |
| 12806 | 'are | (1) |\n' |
| 12807 | '| | replaced by those of ' |
| 12808 | '*t* | |\n' |
| 12809 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12810 | '| "del s[i:j:k]" | removes the elements ' |
| 12811 | 'of | |\n' |
| 12812 | '| | "s[i:j:k]" from the ' |
| 12813 | 'list | |\n' |
| 12814 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12815 | '| "s.append(x)" | appends *x* to the end of ' |
| 12816 | 'the | |\n' |
| 12817 | '| | sequence (same ' |
| 12818 | 'as | |\n' |
| 12819 | '| | "s[len(s):len(s)] = ' |
| 12820 | '[x]") | |\n' |
| 12821 | '+--------------------------------+----------------------------------+-----------------------+\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12822 | '| "s.clear()" | removes all items from *s* ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12823 | '(same | (5) |\n' |
| 12824 | '| | as "del ' |
| 12825 | 's[:]") | |\n' |
| 12826 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12827 | '| "s.copy()" | creates a shallow copy of ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12828 | '*s* | (5) |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12829 | '| | (same as ' |
| 12830 | '"s[:]") | |\n' |
| 12831 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12832 | '| "s.extend(t)" or "s += t" | extends *s* with the contents ' |
| 12833 | 'of | |\n' |
| 12834 | '| | *t* (for the most part the ' |
| 12835 | 'same | |\n' |
| 12836 | '| | as "s[len(s):len(s)] = ' |
| 12837 | 't") | |\n' |
| 12838 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12839 | '| "s *= n" | updates *s* with its ' |
| 12840 | 'contents | (6) |\n' |
| 12841 | '| | repeated *n* ' |
| 12842 | 'times | |\n' |
| 12843 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12844 | '| "s.insert(i, x)" | inserts *x* into *s* at ' |
| 12845 | 'the | |\n' |
| 12846 | '| | index given by *i* (same ' |
| 12847 | 'as | |\n' |
| 12848 | '| | "s[i:i] = ' |
| 12849 | '[x]") | |\n' |
| 12850 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12851 | '| "s.pop([i])" | retrieves the item at *i* ' |
| 12852 | 'and | (2) |\n' |
| 12853 | '| | also removes it from ' |
| 12854 | '*s* | |\n' |
| 12855 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12856 | '| "s.remove(x)" | remove the first item from ' |
| 12857 | '*s* | (3) |\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12858 | '| | where "s[i]" is equal to ' |
| 12859 | '*x* | |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12860 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12861 | '| "s.reverse()" | reverses the items of *s* ' |
| 12862 | 'in | (4) |\n' |
| 12863 | '| | ' |
| 12864 | 'place | |\n' |
| 12865 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12866 | '\n' |
| 12867 | 'Notes:\n' |
| 12868 | '\n' |
| 12869 | '1. *t* must have the same length as the slice it is replacing.\n' |
| 12870 | '\n' |
| 12871 | '2. The optional argument *i* defaults to "-1", so that by ' |
| 12872 | 'default\n' |
| 12873 | ' the last item is removed and returned.\n' |
| 12874 | '\n' |
| 12875 | '3. "remove" raises "ValueError" when *x* is not found in *s*.\n' |
| 12876 | '\n' |
| 12877 | '4. The "reverse()" method modifies the sequence in place for\n' |
| 12878 | ' economy of space when reversing a large sequence. To remind ' |
| 12879 | 'users\n' |
| 12880 | ' that it operates by side effect, it does not return the ' |
| 12881 | 'reversed\n' |
| 12882 | ' sequence.\n' |
| 12883 | '\n' |
| 12884 | '5. "clear()" and "copy()" are included for consistency with the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12885 | ' interfaces of mutable containers that don’t support slicing\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12886 | ' operations (such as "dict" and "set")\n' |
| 12887 | '\n' |
| 12888 | ' New in version 3.3: "clear()" and "copy()" methods.\n' |
| 12889 | '\n' |
| 12890 | '6. The value *n* is an integer, or an object implementing\n' |
| 12891 | ' "__index__()". Zero and negative values of *n* clear the ' |
| 12892 | 'sequence.\n' |
| 12893 | ' Items in the sequence are not copied; they are referenced ' |
| 12894 | 'multiple\n' |
| 12895 | ' times, as explained for "s * n" under Common Sequence ' |
| 12896 | 'Operations.\n' |
| 12897 | '\n' |
| 12898 | '\n' |
| 12899 | 'Lists\n' |
| 12900 | '=====\n' |
| 12901 | '\n' |
| 12902 | 'Lists are mutable sequences, typically used to store collections ' |
| 12903 | 'of\n' |
| 12904 | 'homogeneous items (where the precise degree of similarity will ' |
| 12905 | 'vary by\n' |
| 12906 | 'application).\n' |
| 12907 | '\n' |
| 12908 | 'class list([iterable])\n' |
| 12909 | '\n' |
| 12910 | ' Lists may be constructed in several ways:\n' |
| 12911 | '\n' |
| 12912 | ' * Using a pair of square brackets to denote the empty list: ' |
| 12913 | '"[]"\n' |
| 12914 | '\n' |
| 12915 | ' * Using square brackets, separating items with commas: ' |
| 12916 | '"[a]",\n' |
| 12917 | ' "[a, b, c]"\n' |
| 12918 | '\n' |
| 12919 | ' * Using a list comprehension: "[x for x in iterable]"\n' |
| 12920 | '\n' |
| 12921 | ' * Using the type constructor: "list()" or "list(iterable)"\n' |
| 12922 | '\n' |
| 12923 | ' The constructor builds a list whose items are the same and in ' |
| 12924 | 'the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12925 | ' same order as *iterable*’s items. *iterable* may be either ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12926 | 'a\n' |
| 12927 | ' sequence, a container that supports iteration, or an ' |
| 12928 | 'iterator\n' |
| 12929 | ' object. If *iterable* is already a list, a copy is made and\n' |
| 12930 | ' returned, similar to "iterable[:]". For example, ' |
| 12931 | '"list(\'abc\')"\n' |
| 12932 | ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' |
| 12933 | 'returns "[1, 2,\n' |
| 12934 | ' 3]". If no argument is given, the constructor creates a new ' |
| 12935 | 'empty\n' |
| 12936 | ' list, "[]".\n' |
| 12937 | '\n' |
| 12938 | ' Many other operations also produce lists, including the ' |
| 12939 | '"sorted()"\n' |
| 12940 | ' built-in.\n' |
| 12941 | '\n' |
| 12942 | ' Lists implement all of the common and mutable sequence ' |
| 12943 | 'operations.\n' |
| 12944 | ' Lists also provide the following additional method:\n' |
| 12945 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12946 | ' sort(*, key=None, reverse=False)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12947 | '\n' |
| 12948 | ' This method sorts the list in place, using only "<" ' |
| 12949 | 'comparisons\n' |
| 12950 | ' between items. Exceptions are not suppressed - if any ' |
| 12951 | 'comparison\n' |
| 12952 | ' operations fail, the entire sort operation will fail (and ' |
| 12953 | 'the\n' |
| 12954 | ' list will likely be left in a partially modified state).\n' |
| 12955 | '\n' |
| 12956 | ' "sort()" accepts two arguments that can only be passed by\n' |
| 12957 | ' keyword (keyword-only arguments):\n' |
| 12958 | '\n' |
| 12959 | ' *key* specifies a function of one argument that is used ' |
| 12960 | 'to\n' |
| 12961 | ' extract a comparison key from each list element (for ' |
| 12962 | 'example,\n' |
| 12963 | ' "key=str.lower"). The key corresponding to each item in ' |
| 12964 | 'the list\n' |
| 12965 | ' is calculated once and then used for the entire sorting ' |
| 12966 | 'process.\n' |
| 12967 | ' The default value of "None" means that list items are ' |
| 12968 | 'sorted\n' |
| 12969 | ' directly without calculating a separate key value.\n' |
| 12970 | '\n' |
| 12971 | ' The "functools.cmp_to_key()" utility is available to ' |
| 12972 | 'convert a\n' |
| 12973 | ' 2.x style *cmp* function to a *key* function.\n' |
| 12974 | '\n' |
| 12975 | ' *reverse* is a boolean value. If set to "True", then the ' |
| 12976 | 'list\n' |
| 12977 | ' elements are sorted as if each comparison were reversed.\n' |
| 12978 | '\n' |
| 12979 | ' This method modifies the sequence in place for economy of ' |
| 12980 | 'space\n' |
| 12981 | ' when sorting a large sequence. To remind users that it ' |
| 12982 | 'operates\n' |
| 12983 | ' by side effect, it does not return the sorted sequence ' |
| 12984 | '(use\n' |
| 12985 | ' "sorted()" to explicitly request a new sorted list ' |
| 12986 | 'instance).\n' |
| 12987 | '\n' |
| 12988 | ' The "sort()" method is guaranteed to be stable. A sort ' |
| 12989 | 'is\n' |
| 12990 | ' stable if it guarantees not to change the relative order ' |
| 12991 | 'of\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12992 | ' elements that compare equal — this is helpful for sorting ' |
| 12993 | 'in\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12994 | ' multiple passes (for example, sort by department, then by ' |
| 12995 | 'salary\n' |
| 12996 | ' grade).\n' |
| 12997 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 12998 | ' For sorting examples and a brief sorting tutorial, see ' |
| 12999 | 'Sorting\n' |
| 13000 | ' HOW TO.\n' |
| 13001 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13002 | ' **CPython implementation detail:** While a list is being ' |
| 13003 | 'sorted,\n' |
| 13004 | ' the effect of attempting to mutate, or even inspect, the ' |
| 13005 | 'list is\n' |
| 13006 | ' undefined. The C implementation of Python makes the list ' |
| 13007 | 'appear\n' |
| 13008 | ' empty for the duration, and raises "ValueError" if it can ' |
| 13009 | 'detect\n' |
| 13010 | ' that the list has been mutated during a sort.\n' |
| 13011 | '\n' |
| 13012 | '\n' |
| 13013 | 'Tuples\n' |
| 13014 | '======\n' |
| 13015 | '\n' |
| 13016 | 'Tuples are immutable sequences, typically used to store ' |
| 13017 | 'collections of\n' |
| 13018 | 'heterogeneous data (such as the 2-tuples produced by the ' |
| 13019 | '"enumerate()"\n' |
| 13020 | 'built-in). Tuples are also used for cases where an immutable ' |
| 13021 | 'sequence\n' |
| 13022 | 'of homogeneous data is needed (such as allowing storage in a ' |
| 13023 | '"set" or\n' |
| 13024 | '"dict" instance).\n' |
| 13025 | '\n' |
| 13026 | 'class tuple([iterable])\n' |
| 13027 | '\n' |
| 13028 | ' Tuples may be constructed in a number of ways:\n' |
| 13029 | '\n' |
| 13030 | ' * Using a pair of parentheses to denote the empty tuple: ' |
| 13031 | '"()"\n' |
| 13032 | '\n' |
| 13033 | ' * Using a trailing comma for a singleton tuple: "a," or ' |
| 13034 | '"(a,)"\n' |
| 13035 | '\n' |
| 13036 | ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' |
| 13037 | '\n' |
| 13038 | ' * Using the "tuple()" built-in: "tuple()" or ' |
| 13039 | '"tuple(iterable)"\n' |
| 13040 | '\n' |
| 13041 | ' The constructor builds a tuple whose items are the same and ' |
| 13042 | 'in the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13043 | ' same order as *iterable*’s items. *iterable* may be either ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13044 | 'a\n' |
| 13045 | ' sequence, a container that supports iteration, or an ' |
| 13046 | 'iterator\n' |
| 13047 | ' object. If *iterable* is already a tuple, it is returned\n' |
| 13048 | ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' |
| 13049 | '\'b\', \'c\')"\n' |
| 13050 | ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument ' |
| 13051 | 'is\n' |
| 13052 | ' given, the constructor creates a new empty tuple, "()".\n' |
| 13053 | '\n' |
| 13054 | ' Note that it is actually the comma which makes a tuple, not ' |
| 13055 | 'the\n' |
| 13056 | ' parentheses. The parentheses are optional, except in the ' |
| 13057 | 'empty\n' |
| 13058 | ' tuple case, or when they are needed to avoid syntactic ' |
| 13059 | 'ambiguity.\n' |
| 13060 | ' For example, "f(a, b, c)" is a function call with three ' |
| 13061 | 'arguments,\n' |
| 13062 | ' while "f((a, b, c))" is a function call with a 3-tuple as the ' |
| 13063 | 'sole\n' |
| 13064 | ' argument.\n' |
| 13065 | '\n' |
| 13066 | ' Tuples implement all of the common sequence operations.\n' |
| 13067 | '\n' |
| 13068 | 'For heterogeneous collections of data where access by name is ' |
| 13069 | 'clearer\n' |
| 13070 | 'than access by index, "collections.namedtuple()" may be a more\n' |
| 13071 | 'appropriate choice than a simple tuple object.\n' |
| 13072 | '\n' |
| 13073 | '\n' |
| 13074 | 'Ranges\n' |
| 13075 | '======\n' |
| 13076 | '\n' |
| 13077 | 'The "range" type represents an immutable sequence of numbers and ' |
| 13078 | 'is\n' |
| 13079 | 'commonly used for looping a specific number of times in "for" ' |
| 13080 | 'loops.\n' |
| 13081 | '\n' |
| 13082 | 'class range(stop)\n' |
| 13083 | 'class range(start, stop[, step])\n' |
| 13084 | '\n' |
| 13085 | ' The arguments to the range constructor must be integers ' |
| 13086 | '(either\n' |
| 13087 | ' built-in "int" or any object that implements the "__index__"\n' |
| 13088 | ' special method). If the *step* argument is omitted, it ' |
| 13089 | 'defaults to\n' |
| 13090 | ' "1". If the *start* argument is omitted, it defaults to "0". ' |
| 13091 | 'If\n' |
| 13092 | ' *step* is zero, "ValueError" is raised.\n' |
| 13093 | '\n' |
| 13094 | ' For a positive *step*, the contents of a range "r" are ' |
| 13095 | 'determined\n' |
| 13096 | ' by the formula "r[i] = start + step*i" where "i >= 0" and ' |
| 13097 | '"r[i] <\n' |
| 13098 | ' stop".\n' |
| 13099 | '\n' |
| 13100 | ' For a negative *step*, the contents of the range are still\n' |
| 13101 | ' determined by the formula "r[i] = start + step*i", but the\n' |
| 13102 | ' constraints are "i >= 0" and "r[i] > stop".\n' |
| 13103 | '\n' |
| 13104 | ' A range object will be empty if "r[0]" does not meet the ' |
| 13105 | 'value\n' |
| 13106 | ' constraint. Ranges do support negative indices, but these ' |
| 13107 | 'are\n' |
| 13108 | ' interpreted as indexing from the end of the sequence ' |
| 13109 | 'determined by\n' |
| 13110 | ' the positive indices.\n' |
| 13111 | '\n' |
| 13112 | ' Ranges containing absolute values larger than "sys.maxsize" ' |
| 13113 | 'are\n' |
| 13114 | ' permitted but some features (such as "len()") may raise\n' |
| 13115 | ' "OverflowError".\n' |
| 13116 | '\n' |
| 13117 | ' Range examples:\n' |
| 13118 | '\n' |
| 13119 | ' >>> list(range(10))\n' |
| 13120 | ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' |
| 13121 | ' >>> list(range(1, 11))\n' |
| 13122 | ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' |
| 13123 | ' >>> list(range(0, 30, 5))\n' |
| 13124 | ' [0, 5, 10, 15, 20, 25]\n' |
| 13125 | ' >>> list(range(0, 10, 3))\n' |
| 13126 | ' [0, 3, 6, 9]\n' |
| 13127 | ' >>> list(range(0, -10, -1))\n' |
| 13128 | ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' |
| 13129 | ' >>> list(range(0))\n' |
| 13130 | ' []\n' |
| 13131 | ' >>> list(range(1, 0))\n' |
| 13132 | ' []\n' |
| 13133 | '\n' |
| 13134 | ' Ranges implement all of the common sequence operations ' |
| 13135 | 'except\n' |
| 13136 | ' concatenation and repetition (due to the fact that range ' |
| 13137 | 'objects\n' |
| 13138 | ' can only represent sequences that follow a strict pattern ' |
| 13139 | 'and\n' |
| 13140 | ' repetition and concatenation will usually violate that ' |
| 13141 | 'pattern).\n' |
| 13142 | '\n' |
| 13143 | ' start\n' |
| 13144 | '\n' |
| 13145 | ' The value of the *start* parameter (or "0" if the ' |
| 13146 | 'parameter was\n' |
| 13147 | ' not supplied)\n' |
| 13148 | '\n' |
| 13149 | ' stop\n' |
| 13150 | '\n' |
| 13151 | ' The value of the *stop* parameter\n' |
| 13152 | '\n' |
| 13153 | ' step\n' |
| 13154 | '\n' |
| 13155 | ' The value of the *step* parameter (or "1" if the parameter ' |
| 13156 | 'was\n' |
| 13157 | ' not supplied)\n' |
| 13158 | '\n' |
| 13159 | 'The advantage of the "range" type over a regular "list" or ' |
| 13160 | '"tuple" is\n' |
| 13161 | 'that a "range" object will always take the same (small) amount ' |
| 13162 | 'of\n' |
| 13163 | 'memory, no matter the size of the range it represents (as it ' |
| 13164 | 'only\n' |
| 13165 | 'stores the "start", "stop" and "step" values, calculating ' |
| 13166 | 'individual\n' |
| 13167 | 'items and subranges as needed).\n' |
| 13168 | '\n' |
| 13169 | 'Range objects implement the "collections.abc.Sequence" ABC, and\n' |
| 13170 | 'provide features such as containment tests, element index ' |
| 13171 | 'lookup,\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13172 | 'slicing and support for negative indices (see Sequence Types — ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13173 | 'list,\n' |
| 13174 | 'tuple, range):\n' |
| 13175 | '\n' |
| 13176 | '>>> r = range(0, 20, 2)\n' |
| 13177 | '>>> r\n' |
| 13178 | 'range(0, 20, 2)\n' |
| 13179 | '>>> 11 in r\n' |
| 13180 | 'False\n' |
| 13181 | '>>> 10 in r\n' |
| 13182 | 'True\n' |
| 13183 | '>>> r.index(10)\n' |
| 13184 | '5\n' |
| 13185 | '>>> r[5]\n' |
| 13186 | '10\n' |
| 13187 | '>>> r[:5]\n' |
| 13188 | 'range(0, 10, 2)\n' |
| 13189 | '>>> r[-1]\n' |
| 13190 | '18\n' |
| 13191 | '\n' |
| 13192 | 'Testing range objects for equality with "==" and "!=" compares ' |
| 13193 | 'them as\n' |
| 13194 | 'sequences. That is, two range objects are considered equal if ' |
| 13195 | 'they\n' |
| 13196 | 'represent the same sequence of values. (Note that two range ' |
| 13197 | 'objects\n' |
| 13198 | 'that compare equal might have different "start", "stop" and ' |
| 13199 | '"step"\n' |
| 13200 | 'attributes, for example "range(0) == range(2, 1, 3)" or ' |
| 13201 | '"range(0, 3,\n' |
| 13202 | '2) == range(0, 4, 2)".)\n' |
| 13203 | '\n' |
| 13204 | 'Changed in version 3.2: Implement the Sequence ABC. Support ' |
| 13205 | 'slicing\n' |
| 13206 | 'and negative indices. Test "int" objects for membership in ' |
| 13207 | 'constant\n' |
| 13208 | 'time instead of iterating through all items.\n' |
| 13209 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13210 | 'Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13211 | 'objects\n' |
| 13212 | 'based on the sequence of values they define (instead of ' |
| 13213 | 'comparing\n' |
| 13214 | 'based on object identity).\n' |
| 13215 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 13216 | 'New in version 3.3: The "start", "stop" and "step" attributes.\n' |
| 13217 | '\n' |
| 13218 | 'See also:\n' |
| 13219 | '\n' |
| 13220 | ' * The linspace recipe shows how to implement a lazy version ' |
| 13221 | 'of\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13222 | ' range suitable for floating point applications.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13223 | 'typesseq-mutable': 'Mutable Sequence Types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13224 | '**********************\n' |
| 13225 | '\n' |
| 13226 | 'The operations in the following table are defined on ' |
| 13227 | 'mutable sequence\n' |
| 13228 | 'types. The "collections.abc.MutableSequence" ABC is ' |
| 13229 | 'provided to make\n' |
| 13230 | 'it easier to correctly implement these operations on ' |
| 13231 | 'custom sequence\n' |
| 13232 | 'types.\n' |
| 13233 | '\n' |
| 13234 | 'In the table *s* is an instance of a mutable sequence ' |
| 13235 | 'type, *t* is any\n' |
| 13236 | 'iterable object and *x* is an arbitrary object that ' |
| 13237 | 'meets any type and\n' |
| 13238 | 'value restrictions imposed by *s* (for example, ' |
| 13239 | '"bytearray" only\n' |
| 13240 | 'accepts integers that meet the value restriction "0 <= x ' |
| 13241 | '<= 255").\n' |
| 13242 | '\n' |
| 13243 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13244 | '| Operation | ' |
| 13245 | 'Result | Notes ' |
| 13246 | '|\n' |
| 13247 | '+================================+==================================+=======================+\n' |
| 13248 | '| "s[i] = x" | item *i* of *s* is ' |
| 13249 | 'replaced by | |\n' |
| 13250 | '| | ' |
| 13251 | '*x* | ' |
| 13252 | '|\n' |
| 13253 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13254 | '| "s[i:j] = t" | slice of *s* from *i* ' |
| 13255 | 'to *j* is | |\n' |
| 13256 | '| | replaced by the ' |
| 13257 | 'contents of the | |\n' |
| 13258 | '| | iterable ' |
| 13259 | '*t* | |\n' |
| 13260 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13261 | '| "del s[i:j]" | same as "s[i:j] = ' |
| 13262 | '[]" | |\n' |
| 13263 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13264 | '| "s[i:j:k] = t" | the elements of ' |
| 13265 | '"s[i:j:k]" are | (1) |\n' |
| 13266 | '| | replaced by those of ' |
| 13267 | '*t* | |\n' |
| 13268 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13269 | '| "del s[i:j:k]" | removes the elements ' |
| 13270 | 'of | |\n' |
| 13271 | '| | "s[i:j:k]" from the ' |
| 13272 | 'list | |\n' |
| 13273 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13274 | '| "s.append(x)" | appends *x* to the ' |
| 13275 | 'end of the | |\n' |
| 13276 | '| | sequence (same ' |
| 13277 | 'as | |\n' |
| 13278 | '| | "s[len(s):len(s)] = ' |
| 13279 | '[x]") | |\n' |
| 13280 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13281 | '| "s.clear()" | removes all items ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13282 | 'from *s* (same | (5) |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13283 | '| | as "del ' |
| 13284 | 's[:]") | |\n' |
| 13285 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13286 | '| "s.copy()" | creates a shallow ' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13287 | 'copy of *s* | (5) |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13288 | '| | (same as ' |
| 13289 | '"s[:]") | |\n' |
| 13290 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13291 | '| "s.extend(t)" or "s += t" | extends *s* with the ' |
| 13292 | 'contents of | |\n' |
| 13293 | '| | *t* (for the most ' |
| 13294 | 'part the same | |\n' |
| 13295 | '| | as "s[len(s):len(s)] ' |
| 13296 | '= t") | |\n' |
| 13297 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13298 | '| "s *= n" | updates *s* with its ' |
| 13299 | 'contents | (6) |\n' |
| 13300 | '| | repeated *n* ' |
| 13301 | 'times | |\n' |
| 13302 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13303 | '| "s.insert(i, x)" | inserts *x* into *s* ' |
| 13304 | 'at the | |\n' |
| 13305 | '| | index given by *i* ' |
| 13306 | '(same as | |\n' |
| 13307 | '| | "s[i:i] = ' |
| 13308 | '[x]") | |\n' |
| 13309 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13310 | '| "s.pop([i])" | retrieves the item at ' |
| 13311 | '*i* and | (2) |\n' |
| 13312 | '| | also removes it from ' |
| 13313 | '*s* | |\n' |
| 13314 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13315 | '| "s.remove(x)" | remove the first item ' |
| 13316 | 'from *s* | (3) |\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13317 | '| | where "s[i]" is equal ' |
| 13318 | 'to *x* | |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13319 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13320 | '| "s.reverse()" | reverses the items of ' |
| 13321 | '*s* in | (4) |\n' |
| 13322 | '| | ' |
| 13323 | 'place | ' |
| 13324 | '|\n' |
| 13325 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13326 | '\n' |
| 13327 | 'Notes:\n' |
| 13328 | '\n' |
| 13329 | '1. *t* must have the same length as the slice it is ' |
| 13330 | 'replacing.\n' |
| 13331 | '\n' |
| 13332 | '2. The optional argument *i* defaults to "-1", so that ' |
| 13333 | 'by default\n' |
| 13334 | ' the last item is removed and returned.\n' |
| 13335 | '\n' |
| 13336 | '3. "remove" raises "ValueError" when *x* is not found in ' |
| 13337 | '*s*.\n' |
| 13338 | '\n' |
| 13339 | '4. The "reverse()" method modifies the sequence in place ' |
| 13340 | 'for\n' |
| 13341 | ' economy of space when reversing a large sequence. To ' |
| 13342 | 'remind users\n' |
| 13343 | ' that it operates by side effect, it does not return ' |
| 13344 | 'the reversed\n' |
| 13345 | ' sequence.\n' |
| 13346 | '\n' |
| 13347 | '5. "clear()" and "copy()" are included for consistency ' |
| 13348 | 'with the\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13349 | ' interfaces of mutable containers that don’t support ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13350 | 'slicing\n' |
| 13351 | ' operations (such as "dict" and "set")\n' |
| 13352 | '\n' |
| 13353 | ' New in version 3.3: "clear()" and "copy()" methods.\n' |
| 13354 | '\n' |
| 13355 | '6. The value *n* is an integer, or an object ' |
| 13356 | 'implementing\n' |
| 13357 | ' "__index__()". Zero and negative values of *n* clear ' |
| 13358 | 'the sequence.\n' |
| 13359 | ' Items in the sequence are not copied; they are ' |
| 13360 | 'referenced multiple\n' |
| 13361 | ' times, as explained for "s * n" under Common Sequence ' |
| 13362 | 'Operations.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13363 | 'unary': 'Unary arithmetic and bitwise operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13364 | '***************************************\n' |
| 13365 | '\n' |
| 13366 | 'All unary arithmetic and bitwise operations have the same ' |
| 13367 | 'priority:\n' |
| 13368 | '\n' |
| 13369 | ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n' |
| 13370 | '\n' |
| 13371 | 'The unary "-" (minus) operator yields the negation of its numeric\n' |
| 13372 | 'argument.\n' |
| 13373 | '\n' |
| 13374 | 'The unary "+" (plus) operator yields its numeric argument ' |
| 13375 | 'unchanged.\n' |
| 13376 | '\n' |
| 13377 | 'The unary "~" (invert) operator yields the bitwise inversion of ' |
| 13378 | 'its\n' |
| 13379 | 'integer argument. The bitwise inversion of "x" is defined as\n' |
| 13380 | '"-(x+1)". It only applies to integral numbers.\n' |
| 13381 | '\n' |
| 13382 | 'In all three cases, if the argument does not have the proper type, ' |
| 13383 | 'a\n' |
| 13384 | '"TypeError" exception is raised.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13385 | 'while': 'The "while" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13386 | '*********************\n' |
| 13387 | '\n' |
| 13388 | 'The "while" statement is used for repeated execution as long as an\n' |
| 13389 | 'expression is true:\n' |
| 13390 | '\n' |
| 13391 | ' while_stmt ::= "while" expression ":" suite\n' |
| 13392 | ' ["else" ":" suite]\n' |
| 13393 | '\n' |
| 13394 | 'This repeatedly tests the expression and, if it is true, executes ' |
| 13395 | 'the\n' |
| 13396 | 'first suite; if the expression is false (which may be the first ' |
| 13397 | 'time\n' |
| 13398 | 'it is tested) the suite of the "else" clause, if present, is ' |
| 13399 | 'executed\n' |
| 13400 | 'and the loop terminates.\n' |
| 13401 | '\n' |
| 13402 | 'A "break" statement executed in the first suite terminates the ' |
| 13403 | 'loop\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13404 | 'without executing the "else" clause’s suite. A "continue" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13405 | 'statement\n' |
| 13406 | 'executed in the first suite skips the rest of the suite and goes ' |
| 13407 | 'back\n' |
| 13408 | 'to testing the expression.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13409 | 'with': 'The "with" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13410 | '********************\n' |
| 13411 | '\n' |
| 13412 | 'The "with" statement is used to wrap the execution of a block with\n' |
| 13413 | 'methods defined by a context manager (see section With Statement\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13414 | 'Context Managers). This allows common "try"…"except"…"finally" ' |
| 13415 | 'usage\n' |
| 13416 | 'patterns to be encapsulated for convenient reuse.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13417 | '\n' |
| 13418 | ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' |
| 13419 | ' with_item ::= expression ["as" target]\n' |
| 13420 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13421 | 'The execution of the "with" statement with one “item” proceeds as\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13422 | 'follows:\n' |
| 13423 | '\n' |
| 13424 | '1. The context expression (the expression given in the "with_item")\n' |
| 13425 | ' is evaluated to obtain a context manager.\n' |
| 13426 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13427 | '2. The context manager’s "__exit__()" is loaded for later use.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13428 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13429 | '3. The context manager’s "__enter__()" method is invoked.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13430 | '\n' |
| 13431 | '4. If a target was included in the "with" statement, the return\n' |
| 13432 | ' value from "__enter__()" is assigned to it.\n' |
| 13433 | '\n' |
| 13434 | ' Note: The "with" statement guarantees that if the "__enter__()"\n' |
| 13435 | ' method returns without an error, then "__exit__()" will always ' |
| 13436 | 'be\n' |
| 13437 | ' called. Thus, if an error occurs during the assignment to the\n' |
| 13438 | ' target list, it will be treated the same as an error occurring\n' |
| 13439 | ' within the suite would be. See step 6 below.\n' |
| 13440 | '\n' |
| 13441 | '5. The suite is executed.\n' |
| 13442 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13443 | '6. The context manager’s "__exit__()" method is invoked. If an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13444 | ' exception caused the suite to be exited, its type, value, and\n' |
| 13445 | ' traceback are passed as arguments to "__exit__()". Otherwise, ' |
| 13446 | 'three\n' |
| 13447 | ' "None" arguments are supplied.\n' |
| 13448 | '\n' |
| 13449 | ' If the suite was exited due to an exception, and the return ' |
| 13450 | 'value\n' |
| 13451 | ' from the "__exit__()" method was false, the exception is ' |
| 13452 | 'reraised.\n' |
| 13453 | ' If the return value was true, the exception is suppressed, and\n' |
| 13454 | ' execution continues with the statement following the "with"\n' |
| 13455 | ' statement.\n' |
| 13456 | '\n' |
| 13457 | ' If the suite was exited for any reason other than an exception, ' |
| 13458 | 'the\n' |
| 13459 | ' return value from "__exit__()" is ignored, and execution ' |
| 13460 | 'proceeds\n' |
| 13461 | ' at the normal location for the kind of exit that was taken.\n' |
| 13462 | '\n' |
| 13463 | 'With more than one item, the context managers are processed as if\n' |
| 13464 | 'multiple "with" statements were nested:\n' |
| 13465 | '\n' |
| 13466 | ' with A() as a, B() as b:\n' |
| 13467 | ' suite\n' |
| 13468 | '\n' |
| 13469 | 'is equivalent to\n' |
| 13470 | '\n' |
| 13471 | ' with A() as a:\n' |
| 13472 | ' with B() as b:\n' |
| 13473 | ' suite\n' |
| 13474 | '\n' |
| 13475 | 'Changed in version 3.1: Support for multiple context expressions.\n' |
| 13476 | '\n' |
| 13477 | 'See also:\n' |
| 13478 | '\n' |
Łukasz Langa | aab0e57 | 2019-02-03 14:04:12 +0100 | [diff] [blame] | 13479 | ' **PEP 343** - The “with” statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13480 | ' The specification, background, and examples for the Python ' |
| 13481 | '"with"\n' |
| 13482 | ' statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13483 | 'yield': 'The "yield" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13484 | '*********************\n' |
| 13485 | '\n' |
| 13486 | ' yield_stmt ::= yield_expression\n' |
| 13487 | '\n' |
| 13488 | 'A "yield" statement is semantically equivalent to a yield ' |
| 13489 | 'expression.\n' |
| 13490 | 'The yield statement can be used to omit the parentheses that would\n' |
| 13491 | 'otherwise be required in the equivalent yield expression ' |
| 13492 | 'statement.\n' |
| 13493 | 'For example, the yield statements\n' |
| 13494 | '\n' |
| 13495 | ' yield <expr>\n' |
| 13496 | ' yield from <expr>\n' |
| 13497 | '\n' |
| 13498 | 'are equivalent to the yield expression statements\n' |
| 13499 | '\n' |
| 13500 | ' (yield <expr>)\n' |
| 13501 | ' (yield from <expr>)\n' |
| 13502 | '\n' |
| 13503 | 'Yield expressions and statements are only used when defining a\n' |
| 13504 | '*generator* function, and are only used in the body of the ' |
| 13505 | 'generator\n' |
| 13506 | 'function. Using yield in a function definition is sufficient to ' |
| 13507 | 'cause\n' |
| 13508 | 'that definition to create a generator function instead of a normal\n' |
| 13509 | 'function.\n' |
| 13510 | '\n' |
| 13511 | 'For full details of "yield" semantics, refer to the Yield ' |
| 13512 | 'expressions\n' |
| 13513 | 'section.\n'} |